HimiTrace

HimiTrace MCP 服务 — 面向 AI Agent 的区块链产品溯源（TypeScript 移植版）

HimiTrace 是一个模型上下文协议（MCP）服务，可将 AI Agent 直接连接到 Polygon 主网区块链，以检查产品真伪、验证产地并查看供应链事件谱系。该服务由 HimiTek（himitek.com）开发，可将不可篡改的链上可信数据与面向 AI Agent 的自然语言查询连接起来。

这样，任何兼容 MCP 的 AI Agent（例如 Claude Desktop、Cursor、Windsurf 或 ChatGPT）都可以通过自然语言查询、追踪和审计链上的实体商品。

---

主要功能

• 链上验证： 验证产品或批次 ID 是否已在 Polygon 区块链上注册（防篡改、不可变）。
• 供应链时间线（兼容 GS1 EPCIS）： 直接从 Polygon 获取产品的完整时间顺序事件日志（采收、加工、包装、运输）。
• 证书验证： 获取存储在 IPFS 上、其哈希锚定在链上的质量证书（USDA Organic、VietGAP、Fair Trade 等）。
• BOM（物料清单）谱系： 追踪原材料批次的父子合并／拆分关系。
• 零 Gas 费用： 智能合约的所有读取操作均完全免费，AI Agent 无需花费任何加密代币（POL）。

---

技术规格

• 合约地址： 0xFF7A3429427aFda56b2994B2F3eeF4464b851EE0
• 网络： Polygon 主网（Chain ID：137）
• 框架： 使用 TypeScript 和 ethers.js（v6）基于 Anthropic 的模型上下文协议（MCP）SDK 构建。

---

安装与设置

1. 先决条件

• Node.js v20 或更高版本
• npm

2. 安装依赖项

克隆仓库并安装软件包：

npm install

3. 构建项目

将 TypeScript 编译为 Javascript：

npm run build

4. 测试连接

确保服务可以连接到 Polygon 合约，并在本地查询工具：

npm run test:local

如果看到 ALL TESTS PASSED，则说明环境配置正确。

---

连接到 AI 客户端

1. Claude Desktop

将 HimiTrace MCP 添加到 Claude Desktop 配置文件中。

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

将以下内容添加到 mcpServers 对象中：

{
  "mcpServers": {
    "himitrace-mcp": {
      "command": "node",
      "args": [
        "C:/path/to/your/himitrace-mcp/dist/index.js"
      ]
    }
  }
}

注意：请务必将 C:/path/to/your/himitrace-mcp/dist/index.js 替换为已编译入口点的实际绝对路径。

2. Cursor 或 Windsurf IDE

在 Cursor 设置中：

1. 前往 Settings > Features > MCP。
2. 点击 + Add New MCP Server。
3. 填写以下字段：
   • Name： HimiTrace
   • Type： command
   • Command： node "C:/path/to/your/himitrace-mcp/dist/index.js"

---

可用工具

AI Agent 可以执行以下工具：

1. verify_product

检查产品是否存在于链上，并获取其注册参数。

• 参数： product_id（字符串，例如 LOT-20260315-A1B2C3）
• 返回： JSON，包含验证状态、名称、产地、所有者、注册日期和区块浏览器链接。

2. get_trace_history

获取产品完整的供应链历史（时间线）。

• 参数： product_id（字符串）
• 返回： 按时间顺序排列的事件数组，包含事件类型、时间戳、自定义负载数据（GS1 EPCIS 标准）以及记录者的区块链钱包地址。

3. get_certificates

获取与产品关联的证书。

• 参数： product_id（字符串）
• 返回： 证书类型、颁发方、颁发/到期日期，以及安全的 IPFS 网关链接。

4. get_batch_lineage

追踪物料清单（BOM）的溯源信息（批次的拆分与合并）。

• 参数： batch_id（字符串）
• 返回： 原材料输入的父子关系、数量和单位。

5. check_product_exists

快速检查产品是否存在。

• 参数： product_id（字符串）
• 返回： True/False 状态。

6. get_system_stats

提供系统总体统计信息。

• 返回： 已注册产品数量、合约详情和钱包余额。

---

可用资源

AI Agent 可以参考以下静态资源：

• himitrace://info：系统概览文档、适用行业和标准。
• himitrace://contract：区块链元数据（chain_id、RPC 节点、合约代码版本）。
• himitrace://pricing：API 限额的定价等级（Free、Pro、Enterprise）。

---

许可证与支持

由 HimiTek Joint Stock Company 开发和维护。

• 网站：himitek.com
• 支持邮箱：[email protected]
• 门户：trace.himitek.vn