MCP 服务器

MCP2ANP Bridge Server

Enables MCP clients like Claude Desktop to interact with ANP (Agent Network Protocol) agents through three core tools: authentication setup, document fetching, and OpenRPC method invocation. Converts ANP's crawler-style interaction paradigm into MCP-compatible tools for seamless agent communication.

README

MCP2ANP

MCP to ANP Bridge Server - 让任何支持 MCP 的应用，像"本地工具"一样访问 ANP 智能体

概述

MCP2ANP 是一个 本地 MCP 服务器，将 ANP (Agent Network Protocol) 的"爬虫式"交互范式转换为 MCP (Model Control Protocol) 工具，使 Claude Desktop、Cursor、各类 IDE 等 MCP 客户端无需改造即可访问 ANP 智能体。

核心特性

🔧 三个核心工具: anp.setAuth、anp.fetchDoc、anp.invokeOpenRPC
🔐 DID 认证支持: 本地 DID 文档和私钥管理
🌐 协议适配: ANP 爬虫式交互 ↔ MCP 工具式交互
🚀 本地服务: 无需远程服务器，直接运行在本地
📊 结构化日志: 完整的操作追踪和调试信息
🧪 全面测试: 单元测试和集成测试覆盖

架构设计

flowchart LR
    subgraph MCP Client
      U[LLM / 前端] -->|call tool| T1[anp.fetchDoc]
      U -->|call tool| T2[anp.invokeOpenRPC]
      U -->|optional| T0[anp.setAuth]
    end

    subgraph ANP Bridge
      T1 --> P1[解析/抽链/缓存]
      T2 --> A1[OpenRPC 适配器]
      T0 --> S1[会话级授权上下文]
      P1 --> S1
      A1 --> S1
    end

    subgraph ANP Side
      D1[AgentDescription] -.-> D2[Informations]
      D1 -.-> D3[Interfaces]
      A1 -->|JSON-RPC| E1[OpenRPC Endpoint]
      P1 -->|HTTP GET| D1
      P1 -->|HTTP GET| D2
      P1 -->|HTTP GET| D3
    end

快速开始

安装

# 克隆项目
git clone <repository-url>
cd mcp2anp

# 创建 Python 3.11 虚拟环境
uv venv --python 3.11

# 安装依赖
uv sync

启动服务器

# 开发模式（带热重载）
uv run mcp2anp --reload --log-level DEBUG

# 生产模式
uv run mcp2anp --log-level INFO

基本使用

设置认证（可选）:

{
  "didDocumentPath": "path/to/did-document.json",
  "didPrivateKeyPath": "path/to/private-key.pem"
}

获取 ANP 文档:

{
  "url": "https://grand-hotel.com/agents/hotel-assistant/ad.json"
}

调用 OpenRPC 方法:

{
  "endpoint": "https://grand-hotel.com/api/booking",
  "method": "confirmBooking",
  "params": {
    "checkIn": "2025-10-01",
    "checkOut": "2025-10-03",
    "roomType": "standard"
  }
}

工具说明

anp.setAuth

设置 DID 认证上下文，用于后续的文档获取和 RPC 调用。

输入:

didDocumentPath: DID 文档 JSON 文件路径
didPrivateKeyPath: DID 私钥 PEM 文件路径

输出: {"ok": true} 或错误信息

anp.fetchDoc

获取并解析 ANP 文档，提取可跟进的链接。这是访问 ANP 生态中 URL 的唯一入口。

输入:

url: 要获取的 ANP 文档 URL

输出:

contentType: 内容类型
text: 原始文本内容
json: 解析的 JSON 内容（如适用）
links: 可跟进的链接列表

anp.invokeOpenRPC

调用 OpenRPC 端点的 JSON-RPC 2.0 方法。

输入:

endpoint: OpenRPC 端点 URL
method: 要调用的方法名
params: 方法参数（可选）
id: 请求 ID（可选）

输出:

result: 方法返回结果
raw: 原始 JSON-RPC 响应

项目结构

mcp2anp/
├── src/mcp2anp/          # 源代码
│   ├── server.py         # 主服务器
│   ├── tools/            # MCP 工具实现
│   ├── adapters/         # 协议适配器
│   ├── auth/             # 认证和会话管理
│   └── utils/            # 工具和模型
├── tests/                # 测试代码
│   ├── unit/             # 单元测试
│   ├── integration/      # 集成测试
│   └── fixtures/         # 测试数据
├── docs/                 # 文档
│   ├── examples/         # 示例配置
│   └── usage.md          # 使用指南
└── pyproject.toml        # 项目配置

开发

环境准备

# 安装开发依赖
uv sync --group dev

# 安装 pre-commit hooks
pre-commit install

运行测试

# 运行所有测试
uv run pytest

# 运行特定测试
uv run pytest tests/unit/test_tools.py -v

# 运行测试并生成覆盖率报告
uv run pytest --cov=src/mcp2anp --cov-report=html

代码质量

# 格式化代码
uv run black src/ tests/

# 代码检查
uv run ruff src/ tests/

# 类型检查
uv run mypy src/

使用示例

完整的酒店预订工作流

# 1. 设置认证
await set_auth_tool.execute({
    "didDocumentPath": "docs/examples/did-document.json",
    "didPrivateKeyPath": "docs/examples/private-key.pem"
})

# 2. 获取智能体描述
agent_info = await fetch_doc_tool.execute({
    "url": "https://grand-hotel.com/agents/hotel-assistant/ad.json"
})

# 3. 获取预订接口规范
interface_spec = await fetch_doc_tool.execute({
    "url": agent_info["links"][0]["url"]  # 第一个接口链接
})

# 4. 搜索可用房间
rooms = await invoke_openrpc_tool.execute({
    "endpoint": "https://grand-hotel.com/api/booking",
    "method": "searchRooms",
    "params": {
        "checkIn": "2025-10-01",
        "checkOut": "2025-10-03",
        "guests": 2
    }
})

# 5. 确认预订
booking = await invoke_openrpc_tool.execute({
    "endpoint": "https://grand-hotel.com/api/booking",
    "method": "confirmBooking",
    "params": {
        "checkIn": "2025-10-01",
        "checkOut": "2025-10-03",
        "roomType": "standard",
        "guestInfo": {
            "name": "张三",
            "email": "zhangsan@example.com"
        }
    }
})