Sendify Dbschenker MCP

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

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

快速开始

1. 安装依赖项：

   npm install

1. 构建项目：

   npm run build

1. MCP检验员测试：

   npx @modelcontextprotocol/inspector

然后配置：

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

1. 使用工具：

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

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

验证码通知

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

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

错误响应

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

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

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

• CAPTCHA算法：背景与实现
• 测试验证码流程

安装说明

先决条件

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

环境设置

1. 克隆或下载此存储库

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

1. 验证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

1. 然后运行编译后的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

1. 启动MCP检查器:

   npx @modelcontextprotocol/inspector

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

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

1. 测试工具:

- 导航到“工具”选项卡 - 找到 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（上图）是推荐的测试方法。