Vepathos

Vepathos MCP

为 AI Agent 提供大规模配送与车队优化。

Vepathos 可为末端配送车队解决车辆路径问题（VRP）：将停靠点分配给车辆，并为每辆车规划从一个仓库出发的路线，规模从数十个停靠点到数千个停靠点不等。

本仓库是远程 MCP 适配器（mcp.vepathos.com），本身并非独立产品。Web、REST 和 MCP 共用同一个 Vepathos 账户、套餐、功能、限额和每月停靠点配额。

工具	功能	是否更改数据	可用情况
get_account	查看此连接使用的 Vepathos 账户及其套餐权限。	否	始终可用
optimize_routes	规划配送路线（车辆路径问题，VRP）。	是	始终可用
list_plans	列出已连接 Vepathos 账户中的计划（即控制面板中的计划；每次优化都会保存到其中一个计划中）。	否	始终可用
get_optimization_result	根据 optimization_id 获取路线优化的状态和结果。	否	始终可用
import_deliveries	将配送数据导入 Vepathos，使其行数据不会经过此聊天。	是	MCP_IMPORT_TOOLS_ENABLED
get_import_result	获取 import_deliveries 任务的状态和摘要。	否	MCP_IMPORT_TOOLS_ENABLED
update_import_mapping	更正导入的列映射，无需重新上传。	是	MCP_IMPORT_TOOLS_ENABLED
list_datasets	列出本次或之前聊天中的导入数据。	否	MCP_IMPORT_TOOLS_ENABLED
geocode_addresses	使用 Vepathos Smart Import 将街道地址转换为纬度／经度。	是	始终可用
get_geocode_result	获取 geocode_addresses 任务的状态和坐标。	否	始终可用
list_fleet	列出已连接 Vepathos 账户中保存的内容。	否	始终可用
manage_catalog	在账户中添加或更改已保存的车辆、仓库或车队：这些主数据会在本次对话结束后保留。	是	MCP_CATALOG_WRITE_TOOLS_ENABLED
list_automations	列出已连接 Vepathos 账户中的常驻规则。	否	始终可用
create_automation	创建一条按计划安排配送路线的规则。	是	始终可用
create_optimization_map	为已连接账户拥有的已完成优化地图创建临时公开链接。	是	MCP_MAP_SHARES_ENABLED

没有任何工具可以启用自动化：create_automation 始终会将规则创建为关闭状态，只有规则所有者可以在控制面板中将其启用，因为启用的规则会在无人监督的情况下消耗其停靠点配额。

没有取消工具。已提交的优化任务会运行至完成。街道地址必须先通过 geocode_addresses（启用导入工具时，也可通过 import_deliveries）处理；optimize_routes 不会自行生成坐标。

状态

生产环境运行 0.11.1，地址为 https://mcp.vepathos.com/mcp，并发布全部 15 个工具：导入工具、可共享地图和 manage_catalog 均已在生产环境中启用，因此上方“可用”列描述的是代码设置了哪些门控，而不是此部署限制了哪些功能。

manage_catalog 可保存三类内容：车辆、车站，以及由账户已有车辆组成的车队。车队的 units 表示其常备车辆数量，而不是某次运行派出的车辆数；某次运行派出的车辆数由 optimize_routes 中的 vehicles[].count 指定。要使用已保存的车队运行，请通过 list_fleet 读取车队并传入其中的车辆：optimize_routes 不接受 fleet_id。

Vepathos 已列入官方 MCP 注册表，条目为 com.vepathos/vepathos；也已列入 Smithery 和 Glama。目录会在抓取时保存快照，因此条目可能比部署晚一天更新；每次版本号更新时都会重新发布注册表条目。

付费自助服务已关闭。如果账户套餐无法运行某个请求，系统会返回 PLAN_UPGRADE_REQUIRED 和 contact_url，而不是 Stripe Checkout 链接；账户具备运行条件后，用户无需重新连接即可重试。

在生产环境之外运行的两种方式：

• 本地和 CI：使用 模拟 Core 运行此服务；它是一个测试替身，不会实际进行路线规划或地理编码。tests/ 中的所有内容都使用它。
• 使用真实堆栈在本地运行：使用 vepathos-api-doc MCP 通道、优化器和 Smart Import 工作进程。

连接（生产环境目标）

Add Vepathos → Connect → Sign in / Sign up → Authorize

1. 通过 Claude 或其他 MCP 客户端发现 Vepathos。
2. 连接。客户端会在 api.vepathos.com 登录（或创建 Free / Duck 账户）。
3. 授权客户端使用该账户优化路线。
4. 调用 optimize_routes。如果套餐无法运行此请求，工具会返回 PLAN_UPGRADE_REQUIRED，以及 upgrade_url（启用付费套餐时）或 contact_url（仅提供 Free 套餐、Stripe 尚未配置时）。启用付款后，付款完全由 Stripe 处理。账户具备运行条件后，无需重新连接即可重试作业。

此流程无需 API 密钥和 JSON 配置。请参阅 docs/onboarding.md。

开发者和无头 Agent

创建一个具有 mcp:optimize 范围的 Vepathos 仪表板凭证，并将

Authorization: Bearer <client_id>:<client_secret>

发送到 https://mcp.vepathos.com/mcp。用量计入与 Web 应用和 REST API 相同的账户套餐。

示例（3,200 次配送）

{
  "depot": { "latitude": 40.7128, "longitude": -74.0060 },
  "vehicles": [
    { "vehicle_id": "van", "count": 35, "max_weight_kg": 900, "max_volume_m3": 8.0 }
  ],
  "stops": [
    {
      "stop_id": "ORD-10045",
      "latitude": 40.7306,
      "longitude": -73.9352,
      "weight_kg": 18.5,
      "volume_m3": 0.04,
      "time_window": { "start": "09:00", "end": "12:00" }
    }
  ],
  "schedule": {
    "date": "2026-10-01",
    "route_start_time": "07:30",
    "time_zone": "America/New_York",
    "service_time_minutes": 4
  }
}

每个停靠点都必须包含纬度和经度。地址不会进行地理编码。重量、体积和时间窗均为可选项；如果为任一车辆设置了容量，则每辆车和每个停靠点都必须包含该字段。时间窗需要 schedule.route_start_time。

结果会保留 24 小时。detail=summary 返回精简结果（总计和一页路线）。detail=stops 返回按顺序排列的 stop_id 和到达时间，不会重复返回坐标。

完整的架构和错误说明：请参阅 docs/tools.md。

本地运行

需要 Python 3.12+。

python3.12 -m venv .venv && .venv/bin/pip install -e ".[dev]"
cp .env.example .env
docker compose up --build

MCP 端点为 http://127.0.0.1:8080/mcp，使用 Authorization: Bearer dev-bearer-token-change-me。该 compose 堆栈连接的是模拟 Core，而非优化器。

.venv/bin/pytest -m "not integration"
.venv/bin/mypy
.venv/bin/ruff check src tests devtools

MCP Inspector 和针对真实本地堆栈的集成测试： docs/testing.md。

隐私

这些工具接受坐标、可选的重量／体积／时间窗，以及你自己的停靠点和车辆 ID。街道地址会通过 geocode_addresses 和 import_deliveries 传给 Smart Import，不会在响应中返回。结果不会重复包含坐标；日志会省略令牌、载荷和坐标；托管结果会保留 24 小时。

账户和物流数据遵循公开隐私政策，其中包含 MCP 相关章节。另请参阅 docs/security.md 和 SECURITY.md。

研究与基准测试

Vepathos 末端优化器的介绍见公开技术报告： doi:10.5281/zenodo.19859531。该存档并非经同行评审的出版物。

文档

文档	主题
docs/architecture.md	ADR：独立适配器、信任模型、身份验证、试用
docs/core-changes.md	Core（vepathos-api-doc）所需的更改
docs/core-channel-contract.md	HTTP 契约 /api/mcp/v1
docs/auth.md	OAuth、API 密钥、服务模式
docs/onboarding.md	连接、注册、升级
docs/tools.md	工具的工作方式：计划、确认、主数据、错误
docs/tools-reference.md	自动生成的参考文档：每个工具、输入、注释、工作流
docs/agent-test-plan.md	使用真实 Agent 运行的所有场景，从健康检查到连接商店，以及待解决的问题
docs/chatgpt-test-battery.md	只有 ChatGPT 能告诉我们的内容：512 字符窗口、附件、缓存的架构
docs/async.md	optimization_id + 轮询；稍后支持 Tasks
docs/deployment.md	运维索引（容器、Caddy、健康检查）
docs/deploy-api-prod.md	在 api-prod 上首次部署到生产环境（2026-09-14）：所有步骤和注意事项
docs/publish-marketplaces.md	Claude、MCP Registry、ChatGPT、Cursor——发布顺序和阻碍因素
docs/directory-listing.md	可直接粘贴的目录简介（免费版 + 联系方式）
docs/publication-checklist.md	Registry 和目录审核关卡
docs/privacy-mcp.md	公开隐私政策中的 MCP 部分
docs/public-mcp-page.md	vepathos.com/mcp 页面的文案

许可证

Apache License 2.0