mcp-hs-code-query 1.1.0

MCP server for intelligent HS code queries with dual data sources - 智能海关HS编码查询服务(双数据源主备模式)

MCP HS Code Query Server

🚀 智能海关HS编码查询MCP服务器 - 双数据源主备模式 + 嵌入向量相似度匹配

📖 简介

基于 Model Context Protocol (MCP) 的智能海关HS编码查询服务，支持AI智能体平台（Claude Desktop、ChatGPT等）通过 uvx 快速部署和调用。

✨ 核心特性

• ✅ 双数据源: 主备模式，主数据源失败自动切换备用源
  • 主数据源: hsciq.com (支持嵌入向量相似度)
  • 备用数据源: i5a6.com (传统相似度匹配)
• ✅ 嵌入向量匹配: 使用 BGE 模型进行语义相似度计算，准确度更高
• ✅ 智能查询: 中文分词 + 多关键词尝试 + 自动选择最佳结果
• ✅ 完整数据: HS编码、申报要素、监管条件、检验检疫等完整信息
• ✅ 批量支持: 一次查询多个商品
• ✅ 数据来源标识: 每个结果标注数据来源和查询方式
• ✅ 查询统计: 实时统计主备数据源成功率
• ✅ MCP标准: 符合Model Context Protocol规范
• ✅ 一键部署: 使用 uvx 零配置启动
• ✅ AI就绪: 可被Claude Desktop、ChatGPT等AI平台调用

🆕 v1.1.0 新特性

双数据源主备模式

• 主数据源查询失败时自动切换备用数据源
• 每个查询结果包含 data_source 和 query_method 字段
• 提高查询成功率，降低单点故障风险

嵌入向量相似度匹配

• 使用 BAAI/bge-small-zh-v1.5 模型
• 语义级别的商品名称匹配
• 智能缓存机制，避免重复编码
• 查询准确度显著提升

查询统计工具

• 新增 get_query_stats 工具
• 实时监控主备数据源使用情况
• 统计成功率和失败率

🚀 快速开始

方式1: 使用 uvx（推荐）

最简单的使用方式，无需安装：

# 直接运行（uvx会自动下载和运行）
uvx mcp-hs-code-query

# 或者从本地运行
uvx --from . mcp-hs-code-query

方式2: 安装后使用

# 克隆仓库
git clone <repository-url>
cd data_search

# 安装依赖（使用uv）
uv pip install -e .

# 运行服务器
uv run mcp-hs-code-query

方式3: 在Claude Desktop中配置

编辑 Claude Desktop 配置文件:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "hs-code-query": {
      "command": "uvx",
      "args": ["mcp-hs-code-query"]
    }
  }
}

或者从本地路径运行：

{
  "mcpServers": {
    "hs-code-query": {
      "command": "uvx",
      "args": [
        "--from",
        "c:\\Users\\dela1\\Desktop\\data_search",
        "mcp-hs-code-query"
      ]
    }
  }
}

重启 Claude Desktop 后即可使用！

🛠️ 提供的工具

1. query_hs_code

根据商品名称查询HS编码及完整申报信息。

参数:

• product_name (string): 商品名称（中文）

返回: 包含HS编码、申报要素、监管条件等完整信息的字典

示例:

query_hs_code(product_name="苹果")
# 返回:
{
  "hs_code": "08081000.00",
  "product_name": "鲜苹果",
  "description": "鲜苹果",
  "declaration_elements": "1:品名;2:品牌类型;3:出口享惠情况;...",
  "first_unit": "千克",
  "second_unit": "无",
  "customs_supervision_conditions": {...},
  "inspection_quarantine": {...},
  "search_success": true
}

2. batch_query_hs_codes

批量查询多个商品的HS编码。

参数:

• product_names (array): 商品名称列表

返回: 包含查询统计和所有结果的字典

示例:

batch_query_hs_codes(product_names=["苹果", "香蕉", "橙子"])
# 返回:
{
  "total": 3,
  "successful": 3,
  "failed": 0,
  "results": [...]
}

3. query_by_code

根据已知HS编码查询详细信息。

参数:

• hs_code (string): HS编码

示例:

query_by_code(hs_code="08081000.00")

📋 在AI助手中使用

配置完成后，你可以在Claude Desktop中这样使用：

示例对话:

用户: 帮我查询"苹果"的HS编码

Claude: 我来帮你查询... [调用 query_hs_code 工具]

查询结果：

• HS编码：08081000.00
• 商品名称：鲜苹果
• 申报要素：1:品名;2:品牌类型;3:出口享惠情况;...
• 监管条件：AB（入境/出境货物通关单）
• ...

用户: 批量查询"苹果、香蕉、橙子"的HS编码

Claude: [调用 batch_query_hs_codes 工具]

已查询3个商品，全部成功！

1. 苹果 - 08081000.00
2. 香蕉 - 08030012.00
3. 橙子 - 08051000.10

🔧 开发和测试

使用MCP Inspector测试

# 启动Inspector进行交互式测试
uv run mcp dev mcp_hs_code_query/server.py

单元测试

# 运行测试
uv run pytest tests/

调试

在VS Code中配置 .vscode/mcp.json:

{
  "servers": {
    "hs-code-query": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "mcp-hs-code-query"]
    }
  }
}

📦 依赖

核心依赖：

• mcp>=1.0.0 - Model Context Protocol SDK
• requests>=2.31.0 - HTTP请求
• beautifulsoup4>=4.12.0 - HTML解析
• lxml>=4.9.3 - XML/HTML处理
• jieba>=0.42.1 - 中文分词
• rapidfuzz>=3.0.0 - 相似度匹配

所有依赖在 pyproject.toml 中定义。

🏗️ 项目结构

data_search/
├── mcp_hs_code_query/        # MCP服务器包
│   ├── __init__.py           # 包初始化
│   ├── __main__.py           # 命令行入口
│   └── server.py             # MCP服务器实现
├── src/                      # 核心业务逻辑
│   ├── scraper.py           # 爬虫引擎
│   ├── parser.py            # HTML解析
│   ├── search_optimizer.py # 搜索优化
│   ├── storage.py           # 数据存储
│   └── utils.py             # 工具函数
├── config/                   # 配置文件
│   └── settings.py
├── pyproject.toml           # 项目配置和依赖
└── README_MCP.md            # 本文档

🌐 与REST API的区别

特性	MCP服务器	REST API
使用场景	AI智能体集成	Web应用、微服务
通信方式	stdio / SSE	HTTP
部署方式	uvx一键启动	需要Web服务器
调用方式	AI自动调用	手动HTTP请求
文档	自动生成	需要编写

两者可以共存！ 你可以同时提供MCP服务和REST API，满足不同场景的需求。

🔐 安全性

• ✅ 请求延迟控制（避免过载）
• ✅ 重试机制（网络容错）
• ✅ 错误处理（详细日志）
• ⚠️ 建议在生产环境中添加速率限制
• ⚠️ 建议配置代理池（避免IP封禁）

📄 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📚 相关文档

• Model Context Protocol 官方文档
• MCP Python SDK
• Claude Desktop MCP 集成
• 项目完整文档
• REST API 文档

💡 常见问题

Q: 如何在ChatGPT中使用？

A: ChatGPT目前不直接支持MCP，但你可以使用REST API（见 API_README.md）

Q: 如何提高查询速度？

A: 1) 使用批量查询 2) 添加缓存机制 3) 使用代理池

Q: 如何自定义目标网站？

A: 修改 config/settings.py 中的 BASE_URL

Q: 如何调试MCP服务器？

A: 使用 uv run mcp dev 或在VS Code中配置断点调试

---

维护者: HS Code Query Team
最后更新: 2025-11-25