使用说明（Markdown 格式）

• 项目简介

  • 本仓库实现一个基于 MCP（Model Context Protocol）的后端服务器，面向 LLM 客户端，提供对快递100 API 的访问能力。核心能力包括：资源管理、工具注册与执行、以及 Prompt 模板的定义与渲染。服务器通过 JSON-RPC 与客户端通信，支持多种传输方式，提供会话管理与能力声明。

• 主要功能点

  • 工具集成：query_trace、estimate_time、estimate_time_with_logistic、estimate_price 等工具，封装对快递100 的不同 API 调用。
  • API Key 获取与安全性：从请求头或环境变量中读取 KUAIDI100_API_KEY，用于授权访问快递100 接口。
  • 数据格式灵活返回：支持返回文本、markdown 等数据格式，便于在 LLM 场景中直接使用。
  • 传输模式支持：STDIO、Streamable/SSE/WebSocket 等传输方式，方便在不同环境中部署。
  • 自包含执行入口：通过 api_mcp.py 实现 FastMCP 服务实例化，具备完整的服务端逻辑。

• 安装步骤

  • 环境要求：需要 Python 3.x，安装所需依赖（如 mcp、httpx、pydantic 等）。
  • 获取代码：将仓库克隆到本地或服务器。
  • 安装依赖：根据项目要求安装所需 Python 包（例如使用 pip 安装 mcp、httpx、pydantic 等）。
  • 启动服务器的常用方式（示例，具体以实际运行方式为准）：
    • 使用 STDIO 方式启动（Python 环境下的示例）：
      • 通过 UVicorn/uvx 等工具执行，传递环境变量 KUAIDI100_API_KEY。
      • 配置示例（客户端需要的最小字段，JSON 形式，非代码块）： { "server_name": "kuaidi100_mcp", "transport": "stdio", "command": "uvx", "args": ["kuaidi100-mcp"], "env": { "KUAIDI100_API_KEY": "YOUR_API_KEY" } } 说明：该配置用于 STDIO 连接方式，需在启动时设置 API Key。
    • 或使用 Node.js 相关方式（如果选择 STDIO 的 Node 入口）：
      • 客户端示例配置同样适用，命令及参数按实际执行命令填写。
    • Streamable/SSE/WebSocket 等传输方式：按仓库 README 的说明，使用对应的 transport 选择进行启动与连接。

• 服务器配置（MCP 客户端需要的最小字段，JSON 形式，便于快速对接） 配置示例（仅供参考，具体使用时请根据环境和部署方式调整；MCP 客户端只需要 server 信息、启动命令及参数）： { "server_name": "kuaidi100_mcp", "transport": "stdio", "command": "uvx", "args": [ "kuaidi100-mcp" ], "env": { "KUAIDI100_API_KEY": "YOUR_API_KEY" } } 备注：

  • 以上示例使用 STDIO 启动方式，需在环境变量中提供 KUAIDI100_API_KEY（若以环境变量传入会覆盖请求头中的同名参数）。
  • 另外一种常见启动方式是通过 npx 或 Node.js 入口执行（如 npm 包为 @kuaidi100-mcp/kuaidi100-mcp-server），配置中的 command 和 args 相应调整即可。

• 基本使用方法

  • 获取 API Key：在快递100开放平台获取并配置到服务器启动环境变量或请求头中。
  • 启动服务后，客户端通过 MCP JSON-RPC 请求调用已注册的工具（如 query_trace、estimate_time 等），服务器会调用快递100 的接口并返回结果。
  • 运行后可通过提供的传输通道（STDIO、Streamable/SSE、WebSocket 等）进行后续的交互与数据获取。

• 其他注意

  • 本实现的核心逻辑包括从请求头或环境变量获取 API Key、按请求组装参数、调用快递100 的 API，并返回统一的 JSON-RPC 风格响应。
  • 针对不同的调用场景，接口参数通过 Field 描述进行输入约束，方便在 LLM 调用时给出清晰的参数提示。