MCP2ANP

MCP ↔ ANP 桥接服务，让支持 MCP 的客户端像调用本地工具一样使用 ANP 智能体。

项目简介

MCP2ANP 面向 Claude 、Cursor 等 MCP 客户端，将 ANP（Agent Network Protocol）的“爬虫式”交互流程映射成 MCP 工具调用，免去客户端改造。 桥接层提供两个工具：anp.fetchDoc 负责探索，anp.invokeOpenRPC 负责执行。

核心特性

• 两个稳定的核心工具，覆盖 ANP 资源发现与操作执行。
• DID 凭证加载与签名能力，支持本地文件或自定义路径。
• 本地 stdio 与远程 HTTP 双模式，适配桌面与服务端部署。
• 结构化日志，方便追踪调用链路与调试。
• 官方示例、单元测试与集成测试辅助验证。

运行模式速览

模式	传输方式	认证方式	典型场景
远程 HTTP	FastMCP HTTP	Header 中的 X-API-Key	多租户服务端、共享实例
本地 stdio	stdin/stdout	环境变量或默认 DID 文件	桌面客户端、单机调试

架构设计

桥接层由 mcp2anp.server（stdio）与 mcp2anp.server_remote（HTTP）两种入口组成，二者都会加载共享的 ANPHandler（定义于 mcp2anp/core/handlers.py）。处理流程包括以下关键阶段：

flowchart LR
    subgraph MCP_Client["MCP 客户端"]
        U["LLM / IDE 前端"] -->|调用工具| F["anp.fetchDoc"]
        U -->|调用工具| I["anp.invokeOpenRPC"]
    end

    subgraph Bridge["MCP2ANP 桥接层"]
        ENV["DID 凭证 (环境变量 / 默认文件)"] --> Loader["Credential Loader (handlers.initialize_anp_crawler)"]
        Loader --> Crawler["ANPCrawler 实例"]
        F --> Handler["ANPHandler.handle_fetch_doc"]
        I --> Handler2["ANPHandler.handle_invoke_openrpc"]
        Handler --> Crawler
        Handler2 --> Crawler
        Crawler --> Signer["agent-connect DID 签名"]
    end

    subgraph ANP_Side["ANP 侧服务"]
        Signer -->|HTTP + DID| Desc["Agent Description 文档"]
        Signer -->|HTTP + DID| Infos["信息资源 (Informations)"]
        Signer -->|HTTP + DID| Specs["OpenRPC 接口定义"]
        Signer -->|JSON-RPC + DID| Endpoint["OpenRPC Endpoint"]
    end

Loading

本地模式将 server.py 通过 stdio 暴露为 MCP 工具；远程模式则由 server_remote.py 基于 FastMCP HTTP 端口化，并在请求头中完成 API Key → DID 凭证映射。无论模式如何，工具调用最终都通过 agent-connect 客户端对接 ANP 网络。

快速上手

1. 使用官方托管端点（推荐，无需安装）

claude mcp add --transport http mcp2anp-remote https://agent-connect.ai/mcp2anp/mcp  \
  --header "X-API-Key: YOUR_API_KEY"

API Key 生成步骤

1. 访问 DID-HOST 并登录账户。
2. 新建 DID Card，在创建流程中勾选“生成 API Key”。 > 注: 将生成的私钥与 API Key 安全保存；它们仅显示一次，丢失后无法恢复。

可选：校验 API Key 是否有效（需 jq）：

curl -sS -H "X-API-Key: YOUR_API_KEY" \
  "https://didhost.cc/api/v1/mcp-sk-api-keys/verify" | jq .

2. 自托管远程 HTTP 服务（推荐用于服务端/多人共享）

• 先安装依赖：

  git clone git@github.com:agent-network-protocol/mcp2anp.git
  cd mcp2anp
  uv venv --python 3.11
  uv sync

• 启动服务：

  uv run python -m mcp2anp.server_remote --host 0.0.0.0 --port 9880

• 在 Claude 中以 HTTP 方式注册（将地址替换为你的部署域名或 IP）：

  claude mcp add --transport http mcp2anp-remote http://localhost:9880/mcp \
    --header "X-API-Key: YOUR_API_KEY"

3. 本地 stdio 模式（用于桌面/单机调试）

确保已完成上文“安装依赖”：

1. DID-HOST 来创建一个新的 DID。
2. 创建成功后，下载生成的压缩包。
3. 解压该压缩包（例如，解压到项目下的 docs/did_public/ 目录），您将得到 public-did-doc.json（DID 文档）和 public-private-key.pem（私钥）两个文件。

• 直接添加到环境变量

  # 设置 DID 文件的路径
  export ANP_DID_DOCUMENT_PATH="docs/did_public/public-did-doc.json"
  export ANP_DID_PRIVATE_KEY_PATH="docs/did_public/public-private-key.pem"
  
  # 使用 uv 启动服务
  uv run python -m mcp2anp.server --log-level INFO

• 在 Claude 中添加：

   # 将仓库根目录赋值给变量（替换为你的实际路径）
   MCP2ANP_DIR=/Users/cs/work/mcp2anp
   
   claude mcp add mcp2anp \
     --env ANP_DID_DOCUMENT_PATH=$MCP2ANP_DIR/docs/did_public/public-did-doc.json \
     --env ANP_DID_PRIVATE_KEY_PATH=$MCP2ANP_DIR/docs/did_public/public-private-key.pem \
     -- uv run --directory $MCP2ANP_DIR python -m mcp2anp.server

4. 运行官方 Demo

uv run python examples/mcp_client_demo.py

Demo 会列出工具、加载示例凭证并演示 anp.fetchDoc 与 anp.invokeOpenRPC 的完整闭环。

使用 uvx 快速体验

如果尚未在系统中安装 uv，也可以使用随发行版提供的 uvx 临时运行本项目：

# 在当前仓库目录下执行，uvx 会读取 pyproject.toml 解析依赖
uvx --from . python -m mcp2anp.server --log-level INFO

# 执行单元测试（示例）
uvx --from . pytest --maxfail=1

uvx 会为每次调用创建并缓存隔离环境，适合快速体验或 CI 场景；若需重复开发，仍推荐使用上文的 uv venv + uv sync 方式。

工具详解

anp.fetchDoc

• 输入：url
• 输出：资源内容（text 或 json），以及待探索的结构化 links
• 用法：递归遍历 ANP 网络，读取描述、接口或下一跳链接

anp.invokeOpenRPC

• 输入：endpoint、method、params
• 输出：OpenRPC 定义的调用结果
• 用法：先用 fetchDoc 获取 OpenRPC 规范，再据此构造参数完成操作执行

常见问题

• 本地模式认证失败：确认 DID 文档和私钥路径无误且具备读取权限。
• 远程模式返回 401：检查 X-API-Key 是否正确并对应到验证服务。
• MCP 客户端未显示工具：确认传输方式（stdio/HTTP）与运行模式一致。
• 需更多日志：运行时增加 --log-level DEBUG，或查看 logs/ 目录。

更多资料

• 远程部署说明：docs/server_remote.md
• 示例载荷：docs/examples/
• 客户端脚本与迁移说明：examples/

参与贡献

开发流程、代码规范、测试要求请参考 CONTRIBUTING.md。

许可证

MIT License