货运查询中间件

发货MCP

人工智能中间件服务器，通过OpenRouter（LLM，带功能调用）调用现有的发货后端API，回答有关发货的自然语言问题。将其用作前端或MCP客户端的聊天后端。

建筑

客户端向该服务器发送消息；服务器使用工具定义调用OpenRouter。OpenRouter可能会通过工具调用从您的发货后端请求数据；此服务器执行这些调用并将结果返回给OpenRouter，直到模型生成最终的文本响应。

flowchart LR
  Client[Client] -->|POST /api/chat| Middleware[Middleware]
  Middleware -->|chat + tools| OpenRouter[OpenRouter]
  Middleware -->|GET /api/shipments etc.| Backend[Shipments Backend]
  OpenRouter -->|tool results| Middleware
  Middleware -->|response| Client

先决条件

• Node.js >= 18
• 一 OpenRouter API密钥 （例如来自 OpenRouter密钥)
• 跑步 发货后端 公开预期的API（例如。 /api/shipments, /api/shipment-details, /api/reference/* --看 src/services/backendApi.ts)

安装

git clone <repo-url>
cd shipmentsMCP
npm install

配置

1. 复制 .env.example 到 .env.
2. 设置以下变量：

安全： 不要承诺 .env 或将真正的API密钥放入 .env.example。在示例中使用占位符，并在中添加您自己的密钥 .env.

运行服务器

• 发展： npm run dev （tsx观看 src/index.ts)
• 构建： npm run build （TypeScript→ dist/)
• 生产： npm start （跑步 dist/index.js)

服务器正在监听 http://localhost:<PORT> （默认值为3001）。

API 参考

GET/api/健康

• 没有身份验证。
• 答复： { "status": "ok" }

POST/api/聊天

• 身份验证： Authorization: Bearer <CHAT_PASSWORD>
• 主体： { "message": string, "conversationHistory"?: Array<{ role, content }> } （参见 src/types.ts ChatRequest)
• 答复： { "response": string } （参见 ChatResponse)
• 错误： 400如果 message 缺失或无效，如果身份验证失败，则为401，OpenRouter或后端错误为500

运作原理

1. 服务器使用 系统提示 （装运助理）和 工具定义 从 src/tools/definitions.ts （列出/获取装运、装运详细信息、参考表：国家、服务代码、状态等）。
2. OpenRouter可能会返回 工具调用。服务器通过以下方式运行它们 src/tools/executor.ts，它调用 src/services/backendApi.ts。参考查找（国家、状态等）缓存在内存中。
3. 工具结果将发送回OpenRouter。循环将继续，直到模型返回最终的文本响应，该响应将作为 response 给客户。

项目结构