ITEM Knowledge Base MCP Server

这是一个 MCP (Model Context Protocol) 服务器，用于查询 ITEM 公司的产品知识库，包括 YMS、WMS、Carrier Portal 等产品的信息和 SOP 流程。

功能特性

• 🔍 查询 ITEM 产品知识库（YMS、WMS、Carrier Portal 等）
• 🎯 支持语义搜索和智能排序
• 📚 返回相关文档来源和引用
• 💬 支持会话上下文管理
• ⚡ 快速响应，自动格式化结果

快速开始

详细的快速开始指南请查看 QUICKSTART.md

1. 配置 Kiro

编辑 ~/.kiro/settings/mcp.json：

{
  "mcpServers": {
    "item-knowledge": {
      "command": "npx",
      "args": ["-y", "@item/knowledge-mcp-server"],
      "env": {
        "ITEM_API_KEY": "your_api_key_here"
      },
      "disabled": false,
      "autoApprove": ["query_knowledge"]
    }
  }
}

2. 重新连接 MCP 服务器

在 Kiro 中按 Ctrl+Shift+P → 搜索 "MCP" → 选择 "Reconnect MCP Servers"

3. 开始使用

请帮我查询 YMS 的 SOP 流程

配置

获取 API Key

1. 访问 ITEM 知识库管理后台
2. 进入 "API Access" 页面
3. 生成或复制您的 Personal API Key

在 Kiro 中配置

方式一：全局配置（推荐，适用于所有项目）

编辑 ~/.kiro/settings/mcp.json：

{
  "mcpServers": {
    "item-knowledge": {
      "command": "npx",
      "args": ["-y", "@item/knowledge-mcp-server"],
      "env": {
        "ITEM_API_KEY": "your_api_key_here"
      },
      "disabled": false,
      "autoApprove": ["query_knowledge"]
    }
  }
}

方式二：工作区配置（仅当前项目）

在项目根目录创建 .kiro/settings/mcp.json：

{
  "mcpServers": {
    "item-knowledge": {
      "command": "npx",
      "args": ["-y", "@item/knowledge-mcp-server"],
      "env": {
        "ITEM_API_KEY": "your_api_key_here"
      },
      "disabled": false,
      "autoApprove": ["query_knowledge"]
    }
  }
}

方式三：本地开发配置

如果你是从源码运行：

{
  "mcpServers": {
    "item-knowledge": {
      "command": "node",
      "args": ["index.js"],
      "env": {
        "ITEM_API_KEY": "your_api_key_here"
      },
      "disabled": false,
      "autoApprove": ["query_knowledge"]
    }
  }
}

重要： 请将 your_api_key_here 替换为您的实际 API Key

重新连接 MCP 服务器

配置完成后：

1. 在 Kiro 中按 Ctrl+Shift+P 打开命令面板
2. 搜索 "MCP"
3. 选择 "Reconnect MCP Servers"

使用方法

配置完成后，MCP 服务器会自动启动。AI 会在检测到相关问题时自动调用知识库。

自动触发场景

AI 会在以下情况自动查询知识库：

产品查询：

• "YMS 的签到流程是什么？"
• "WMS 如何配置库位？"
• "Carrier Portal 的预约功能"

业务流程：

• "物流调度的 SOP 流程"
• "财务对账操作指南"
• "订单履行的最佳实践"

技术文档：

• "YMS API 接口文档"
• "如何集成电商平台"
• "权限配置说明"

故障排查：

• "WMS 异常处理流程"
• "如何解决库存不一致"
• "系统错误代码说明"

详细的触发机制请查看 TRIGGERS.md

query_knowledge 工具

参数：

• query (必需): 要查询的问题
• topK (可选): 返回的最大相关文档数量（1-20），默认 10
• useSemanticRanker (可选): 是否启用语义排序，默认 true
• sessionId (可选): 会话标识符，用于保持对话上下文

示例对话：

用户：请帮我查询 YMS 的 SOP 流程
AI：[自动调用 query_knowledge，返回详细的 YMS SOP 文档]

用户：查询 Carrier Portal 如何创建预约
AI：[自动调用 query_knowledge，返回预约创建指南]

用户：WMS 的装货流程是怎样的？
AI：[自动调用 query_knowledge，返回装货流程说明]

API 说明

本 MCP 服务器调用 ITEM 知识库 API：

• 端点： https://api-base.item.com/api/knowledgebase/v1/knowledgebase/chatViaApi
• 认证： 通过 X-API-KEY 请求头
• 方法： POST

开发

测试 API 连接

npm test
# 或
node test-api.js

本地运行

npm start

故障排除

未配置 API Key 错误

确保在 MCP 配置中正确设置了 ITEM_API_KEY 环境变量

服务器无法启动

• 检查 Node.js 版本：node --version（需要 v18+）
• 如果使用 npx，确保网络连接正常
• 尝试清除 npx 缓存：npx clear-npx-cache

查看服务器日志

在 Kiro 中打开 MCP Server 视图查看连接状态和日志

API 调用失败

• 验证 API Key 是否有效
• 检查网络连接
• 运行 npm test 测试 API 连接

支持的产品

• YMS (Yard Management System)
• WMS (Warehouse Management System)
• Carrier Portal
• Cubework

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License - 详见 LICENSE 文件

相关链接

• Model Context Protocol
• Kiro IDE
• ITEM 官网