AI导哈

货运追踪服务器

一个基于MCP协议的DB Schenker货运追踪服务器，通过参考号提供结构化货运信息，包括发件人/收件人详情、包裹信息和完整追踪历史。

  • by digitalxenon98
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 digitalxenon98/sendify-dbschenker-mcp

使用说明

德铁信可货运跟踪MCP服务器

一种MCP（模型上下文协议）服务器，通过参考号跟踪德铁信可的货物，提供结构化的货物信息，包括发件人/收件人详细信息、包裹信息和完整的跟踪历史。

快速开始

  1. 安装依赖项：

    npm install

  2. 构建项目：

    npm run build

  3. MCP检验员测试：

    npx @modelcontextprotocol/inspector

    然后配置：

    • 命令: node
    • 参数: /absolute/path/to/this/project/dist/server.js
    • 运输: stdio

  4. 使用工具：

    • 在MCP检查器中，转到“工具”选项卡
    • 呼叫 track_shipment 带有参考号（例如。， 1806203236)

服务器自动解决验证码挑战-无需手动设置！

验证码通知

德铁信可跟踪端点受 浏览器绑定的挑战响应机制 而不是传统的API密钥流。这意味着：

  • 端点需要 Captcha-Solution 由谜题数据生成的标题
  • 解决方案是 会话和时间相关 -每个请求都需要一个新的解决方案
  • 解决方案很快过期（几秒钟到几分钟），不能重复使用
  • MCP服务器在遇到验证码难题时会自动解决，因此不需要人工干预

错误响应

系统区分不同的验证码相关错误：

  • HTTP 429+ Captcha-Puzzle 头球：丢失或过期 Captcha-Solution 头球
  • HTTP 422“无效解决方案”：The Captcha-Solution 标头被拒绝（过期/无效）
  • HTTP 429无谜题：速率限制（可重试）

有关验证码机制和算法实现的详细信息，请参阅：

安装说明

先决条件

  • Node.js：版本18或更高版本
  • npm：与Node.js捆绑在一起

环境设置

  1. 克隆或下载此存储库

    git clone https://github.com/digitalxenon98/sendify-dbschenker-mcp
cd sendify-dbschenker-mcp

  2. 验证Node.js安装

    node --version  # Should be v18 or higher
npm --version

构建/安装依赖关系

  1. 安装所有依赖项

    npm install

    这将安装：

    • 运行时依赖关系： @modelcontextprotocol/sdk, zod
    • 开发依赖关系： typescript, tsx, @types/node

    注： 服务器使用纯JavaScript验证码解决算法，不需要浏览器自动化。

构建TypeScript项目

npm run build

这将TypeScript编译为JavaScript dist/ 目录。

验证码解决

MCP服务器 自动解决验证码难题 当遇到。当API返回CAPTCHA质询时，服务器：

  1. 从中提取谜题 Captcha-Puzzle 头球
  2. 使用工作量证明算法自动解决该问题
  3. 使用以下命令重试请求 Captcha-Solution 头球
  4. 成功时返回跟踪数据

这个过程是 完全透明 -你不需要手动做任何事情。服务器自动处理所有请求的验证码解决。

如何运行MCP服务器

开发模式

直接使用TypeScript运行服务器（无需构建）：

npm run dev

服务器将通过stdio（标准输入/输出）启动和通信，这是MCP服务器的标准操作方式。

生产模式

  1. 首先，构建项目：

    npm run build

  2. 然后运行编译后的JavaScript：

    npm start

MCP客户端配置

要将此MCP服务器与MCP客户端（如Claude Desktop）一起使用，请将其添加到您的MCP配置中：

生产（建成后）：

{
  "mcpServers": {
    "db-schenker-tracker": {
      "command": "node",
      "args": ["/absolute/path/to/sendify-dbschenker-mcp/dist/server.js"]
    }
  }
}

开发（直接使用TypeScript）：

{
  "mcpServers": {
    "db-schenker-tracker": {
      "command": "npx",
      "args": ["-y", "tsx", "/absolute/path/to/sendify-dbschenker-mcp/src/server.ts"]
    }
  }
}

重要提示： 在配置中使用绝对路径。替换 /absolute/path/to/sendify-dbschenker-mcp 带有项目目录的实际路径。

如何测试工具

使用MCP检查员（建议用于测试）

MCP Inspector是一个基于网络的工具，用于测试MCP服务器。这是在将服务器与其他客户端集成之前测试服务器的最简单方法。

  1. 构建项目 （如果尚未建成）：

    npm run build

  2. 启动MCP检查器:

    npx @modelcontextprotocol/inspector

  3. 在MCP检查器中配置服务器:

    • 在浏览器中打开MCP检查器（通常自动打开）
    • 在连接设置中：
      • 命令: node
      • 参数: /absolute/path/to/sendify-dbschenker-mcp/dist/server.js
      • 运输: stdio （默认）
    • 点击“连接”

  4. 测试工具:

    • 导航到“工具”选项卡
    • 找到 track_shipment 在列表中
    • 输入参考号（例如。， 1806203236)
    • 点击“呼叫工具”
    • 查看回复

注： 替换 /absolute/path/to/sendify-dbschenker-mcp 使用项目目录的实际绝对路径。你可以通过跑步得到绝对路径 pwd 在您的项目目录中。

使用MCP客户端（克劳德桌面等）

  1. 配置您的MCP客户端 使用服务器（请参见 MCP客户端配置 以上）
  2. 启动您的MCP客户端 （例如，克劳德桌面）
  3. 调用工具 带有参考号：
    track_shipment(reference: "1806203236")

示例参考号

您可以使用这些参考号进行测试：

  • 1806203236
  • 1806290829
  • 1806273700
  • 1806272330
  • 1806271886

预期响应格式

成功响应：

{
  "ok": true,
  "reference": "1806203236",
  "shipment": {
    "id": "...",
    "stt": "...",
    "transportMode": "LAND",
    ...
  },
  "sender": {...},
  "receiver": {...},
  "packageDetails": {...},
  "trackingHistory": [...],
  ...
}

错误响应（未找到）：

{
  "ok": false,
  "error": "NOT_FOUND",
  "message": "No shipment found for that reference number.",
  "reference": "1806203236"
}

错误响应（API错误）：

{
  "ok": false,
  "error": "API_ERROR",
  "message": "Failed to fetch shipment data from DB Schenker API.",
  "reference": "1806203236",
  "details": "HTTP 429 Too Many Requests...",
  "hint": "The upstream service rejected the request. Retry behavior depends on the failure type."
}

错误响应（验证码解决方案无效-422）：

{
  "ok": false,
  "error": "CAPTCHA_SOLUTION_INVALID",
  "message": "The Captcha-Solution header was rejected by the server. The solution may have expired.",
  "reference": "1806203236",
  "details": "HTTP 422 Unprocessable Entity :: Invalid solution",
  "hint": "The Captcha-Solution header is time-sensitive and expires quickly. The server will automatically retry with a fresh solution.",
  "retryable": true
}

错误响应（验证码被阻止-429）：

{
  "status": "blocked",
  "retryable": false,
  "reason": "Upstream service requires browser CAPTCHA",
  "details": "This endpoint is protected by anti-bot measures and cannot be accessed server-side.",
  "upstream": {
    "url": "...",
    "status": 429,
    "hasCaptchaPuzzleHeader": true
  }
}

验证码解决测试

要验证验证码解决是否正常工作，您可以使用测试脚本：

npm run test-captcha-flow

这将：

  1. 向德铁信可提出真正的API请求
  2. 自动解决遇到的任何验证码挑战
  3. 显示有关解决过程的调试信息（自动启用）
  4. 显示请求是否成功

预期产量：

  • [CAPTCHA] Puzzle solved in Xms -显示验证码已成功解决
  • Request succeeded! -显示已工作的解决方案和已检索的数据

注： 调试输出由测试脚本自动启用。你不需要设置 DEBUG_CAPTCHA=1 手动。

手动测试（高级）

您还可以通过stdio发送MCP协议消息来手动测试服务器，尽管这需要了解MCP协议格式。对于大多数用户来说，MCP Inspector（上图）是推荐的测试方法。

相关 MCP