MCP Server Example for Indonesian Customs Tariff & Hascode API

印度尼西亚关税与 Hascode API 的 MCP 服务示例

本仓库提供了 Model Context Protocol (MCP) 服务的示例实现，针对印度尼西亚关税数据和 Hascode API 集成场景进行了定制，仅供教育用途。本项目展示了如何构建可运行的 MCP 服务，连接 Hascode 等 API，为 AI 模型获取关税和 HS 编码信息。

什么是 MCP？

MCP（Model Context Protocol）是一项旨在为大语言模型（LLM）提供结构化上下文的开放标准。你可以把 MCP 想成 AI 的 USB-C 接口——它提供了一种标准化方式，可将模型连接到各种外部数据源，例如关税 API、HS 编码查询服务或物流数据库。

主要优势

• 为 Hascode API 等服务提供预构建集成，可实时提供 HS 编码和关税税率信息
• 灵活适配不同的大模型提供商（OpenAI、Anthropic 等）
• 提供简洁的抽象层，安全访问进出口关税结构等受监管数据

架构概览

MCP 采用客户端-服务端架构，支持多个数据访问点：

• MCP 宿主：Claude Desktop 或企业助手等 AI 工具，用于请求结构化海关数据
• MCP 客户端：负责与服务端进行一对一通信的协议中介
• MCP 服务：用于公开数据和功能的轻量级组件，例如通过 API 获取印度尼西亚关税
• 数据源：包括本地文件（例如 PDF 税则表）以及 Hascode 等远程 API 或海关机构数据库

MCP 核心概念

MCP 服务通常会公开三类功能：

• 资源：HS 编码数据集、关税表或 API 响应（例如特定商品的关税税率）
• 工具：大模型可调用以获取最新海关信息的 API 函数
• 提示词：预先配置的模板（例如：“HS 编码 8703.23.91.00 在印度尼西亚的进口关税是多少？”）

系统要求

• Python 3.10 或更高版本
• MCP SDK 1.2.0 或更高版本
• uv 包管理器

入门

安装 uv 包管理器

在 MacOS/Linux 上：

curl -LsSf https://astral.sh/uv/install.sh | sh

然后重新启动终端，以启用 uv 命令。

项目设置

1. 初始化 MCP 项目：

uv init mcp-server
cd mcp-server

uv venv
source .venv/bin/activate  # Use .venv\Scripts\activate on Windows

uv add "mcp[cli]" httpx

2. 创建主服务文件：

touch main.py

示例：集成 Hascode API

在 main.py 中，你可以定义一个资源，通过 Hascode 获取关税数据：

import httpx
from mcp import Resource

class HsCodeTariffResource(Resource):
    def read(self, hs_code: str):
        response = httpx.get(f"https://api.hascode.id/tariff?code={hs_code}")
        return response.json()

运行服务

启动服务：

uv run main.py

连接到 Claude Desktop

1. 安装 Claude Desktop
2. 编辑此路径下的配置文件： ~/Library/Application Support/Claude/claude_desktop_config.json

{
    "mcpServers": {
        "mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/YOUR/mcp-server",
                "run",
                "main.py"
            ]
        }
    }
}

3. 重启 Claude Desktop

故障排查

如果 Claude Desktop 无法检测到你的服务：

1. 检查配置文件路径和语法
2. 所有目录均使用绝对路径
3. 确保已安装 uv 且运行正常
4. 查看 Claude 日志，排查连接问题

许可证

本项目采用 MIT 许可证。更多详情请参阅 LICENSE 文件。

---