玄瞳AI MCP服务器

English | 简体中文

封装玄瞳AI平台接口的MCP（Model Context Protocol）服务器，提供41个AI工具，可直接在Claude Code中使用。

快速开始

1. 安装

# 克隆仓库
git clone <repository-url>
cd xtai-single-mcp-server

# 安装依赖
npm install

# 构建
npm run build

2. 配置

复制配置示例并创建配置文件：

cp config.example.yml config.yml

编辑 config.yml，填入你的玄瞳AI平台信息：

server:
  port: 3000
  apiKey: "your-api-key-here"

api:
  baseUrl: "https://ai.xtion.net"
  username: "your-username"
  password: "your-password"

3. 启动服务

# 方式一：直接启动MCP服务器
npm start

# 方式二：使用全局命令（发布到npm后）
npm install -g xtai-single-mcp-server
xtai-mcp-server

4. 在Claude Code中配置

在Claude Code的配置文件中添加MCP服务器：

Windows配置文件位置： %APPDATA%\Claude\claude_desktop_config.json

配置内容：

{
  "mcpServers": {
    "xtai": {
      "command": "node",
      "args": ["D:\\code\\xtai-single-mcp-server\\dist\\index.js"],
      "env": {
        "XTAI_CONFIG_PATH": "D:\\code\\xtai-single-mcp-server\\config.yml"
      }
    }
  }
}

注意： 请将路径替换为你实际的项目路径。

5. 重启Claude Code

配置完成后，重启Claude Code，即可在对话中使用所有AI工具。

可用工具

服务器提供 41个AI工具，分为11个分类：

📦 辅助工具（1个）

• helper_get_tool_list - 获取可用工具列表

🛒 货架识别（4个）

• shelf_shelf_sync_detect - 货架同步识别
• shelf_shelf_async_detect - 货架异步识别
• shelf_shelf_async_poll - 货架异步识别（自动轮询）
• shelf_shelf_result - 查询货架识别结果

🤖 超级模型（4个）

• supermodel_sync_detect - 超级模型同步识别
• supermodel_async_detect - 超级模型异步识别
• supermodel_async_poll - 超级模型异步识别（自动轮询）
• supermodel_fetch_result - 查询超级模型结果

🏪 场景检测（2个）

• scene_store_header_detect - 店招检测
• scene_display_detect - 陈列检测

📸 翻拍识别（9个）

• fake_sync_detect - 翻拍实时识别
• fake_async_detect - 翻拍异步识别
• fake_async_poll - 翻拍异步识别（自动轮询）
• fake_fetch_result - 查询翻拍检测结果
• fake_lvmo_sync_detect - 铝膜码翻拍检测（奶粉行业）
• fake_tbc_sync_detect - 罐底码翻拍检测（奶粉行业）
• fake_accurate_sync_detect - 箱码翻拍检测（奶粉行业）
• fake_accurate_async_detect - 箱码异步检测
• fake_accurate_async_poll - 箱码异步轮询

🖼️ 图片质量（1个）

• imagequality_blur_detect - 图片模糊识别

🔗 图片合成（5个）

• imagemerge_merge_prediction - 图片拼接预测
• imagemerge_image_splice - 图片拼接
• imagemerge_find_splice_result - 查询拼接结果
• imagemerge_deduplication - AI拼接去重
• imagemerge_find_deduplication_result - 查询去重结果

🔍 其他检测（2个）

• otherdetect_num_person - 人数识别
• otherdetect_shelf_section - 货架节识别

📐 地堆区域（3个）

• area_detect - 地堆面积识别
• area_carton_estimation - 地堆箱体预估
• area_carton_fullness - 地堆饱满度预估

🔁 重复检测（6个）

• dupcheck_picture_check - 实时分组查重
• dupcheck_hist_picture_check - 相似度同步查询
• dupcheck_async_similarity_search - 相似度异步查询
• dupcheck_fetch_similarity_result - 查询相似度结果
• dupcheck_similarity_collect - 相似度图片采集
• dupcheck_delete_history_image - 删除历史图片库

📦 SKU组合（4个）

• combined_async_detect - SKU组合异步识别
• combined_async_poll - SKU组合异步识别（自动轮询）
• combined_fetch_result - 查询组合识别结果
• combined_sku_sync_detect - SKU组合同步识别（新接口）

使用示例

在Claude Code对话中，你可以直接调用这些工具：

示例1：货架检测

请帮我检测这张货架图片：https://example.com/shelf.jpg

Claude会自动调用 shelf_shelf_sync_detect 工具进行分析。

示例2：翻拍检测

检测这张图片是否为翻拍：https://example.com/photo.jpg

示例3：地堆面积计算

计算这个地堆的面积：
正面图：https://example.com/front.jpg
侧面图：https://example.com/side.jpg

示例4：批量检测

检测这几张图片的SKU组合：
- https://example.com/img1.jpg
- https://example.com/img2.jpg

Claude会自动选择合适的工具并返回结果。

高级配置

启用/禁用工具分类

在 config.yml 中可以控制哪些分类的工具可用：

categories:
  shelf:
    enabled: true    # 启用货架识别
  fake:
    enabled: false   # 禁用翻拍识别

只启用特定工具

categories:
  shelf:
    enabled: true
    tools:
      - shelf_shelf_sync_detect    # 只启用同步检测
      - shelf_shelf_async_poll     # 和自动轮询

调整日志级别

logging:
  level: "debug"     # debug | info | warn | error
  enableCallLog: true
  enableErrorLog: true

配置重试机制

retry:
  maxRetries: 3              # 最大重试次数
  retryDelay: 1000           # 重试延迟（毫秒）
  retryableStatusCodes:      # 需要重试的状态码
    - 401
    - 429
    - 500
    - 502
    - 503
    - 504

故障排查

服务无法启动

1. 检查Node.js版本（需要 >= 18）
2. 确认已运行 npm install 和 npm run build
3. 检查配置文件路径是否正确

Token认证失败

1. 确认 config.yml 中的用户名和密码正确
2. 检查网络连接
3. 确认baseUrl配置正确

Claude Code无法识别工具

1. 确认MCP服务正在运行
2. 检查Claude Code配置文件中的路径是否正确
3. 重启Claude Code

查看日志

服务器会输出详细的运行日志，包括：

• 每个API调用的详情
• Token获取和刷新状态
• 错误信息和堆栈跟踪

配置文件参考

完整的配置选项请参考 config.example.yml 文件。

许可证

MIT

支持

如有问题或建议，请提交Issue。