diff --git a/README.md b/README.md index 0ab56eb..faccb62 100644 --- a/README.md +++ b/README.md @@ -5,17 +5,21 @@ [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + + MCP2ANP Bridge Server MCP server + + ## 项目简介 -MCP2ANP 面向 Claude 、Cursor 等 MCP 客户端,将 ANP(Agent Network Protocol)的“爬虫式”交互流程映射成 MCP 工具调用,免去客户端改造。 -桥接层提供两个工具:`anp.fetchDoc` 负责探索,`anp.invokeOpenRPC` 负责执行。 +MCP2ANP 面向 Claude 、Cursor 等 MCP 客户端,将 ANP(Agent Network Protocol)的"爬虫式"交互流程映射成 MCP 工具调用,免去客户端改造。 +桥接层提供两个工具:`anp.fetchDoc` 负责探索,`anp.invokeOpenRPC` 负责执行。 ## 核心特性 -- 两个稳定的核心工具,覆盖 ANP 资源发现与操作执行。 -- DID 凭证加载与签名能力,支持本地文件或自定义路径。 -- 本地 stdio 与远程 HTTP 双模式,适配桌面与服务端部署。 -- 结构化日志,方便追踪调用链路与调试。 +- 两个稳定的核心工具,覆盖 ANP 资源发现与操作执行。 +- DID 凭证加载与签名能力,支持本地文件或自定义路径。 +- 本地 stdio 与远程 HTTP 双模式,适配桌面与服务端部署。 +- 结构化日志,方便追踪调用链路与调试。 - 官方示例、单元测试与集成测试辅助验证。 ## 运行模式速览 @@ -27,7 +31,7 @@ MCP2ANP 面向 Claude 、Cursor 等 MCP 客户端,将 ANP(Agent Network Prot ## 架构设计 -桥接层由 `mcp2anp.server`(stdio)与 `mcp2anp.server_remote`(HTTP)两种入口组成,二者都会加载共享的 `ANPHandler`(定义于 `mcp2anp/core/handlers.py`)。处理流程包括以下关键阶段: +桥接层由 `mcp2anp.server`(stdio)与 `mcp2anp.server_remote`(HTTP)两种入口组成,二者都会加载共享的 `ANPHandler`(定义于 `mcp2anp/core/handlers.py`)。处理流程包括以下关键阶段: ```mermaid flowchart LR @@ -54,12 +58,12 @@ flowchart LR end ``` -本地模式将 `server.py` 通过 stdio 暴露为 MCP 工具;远程模式则由 `server_remote.py` 基于 FastMCP HTTP 端口化,并在请求头中完成 API Key → DID 凭证映射。无论模式如何,工具调用最终都通过 `agent-connect` 客户端对接 ANP 网络。 +本地模式将 `server.py` 通过 stdio 暴露为 MCP 工具;远程模式则由 `server_remote.py` 基于 FastMCP HTTP 端口化,并在请求头中完成 API Key → DID 凭证映射。无论模式如何,工具调用最终都通过 `agent-connect` 客户端对接 ANP 网络。 ## 快速上手 -### 1. **使用官方托管端点(推荐,无需安装)** +### 1. **使用官方托管端点(推荐,无需安装)** ```bash claude mcp add --transport http mcp2anp-remote https://agent-connect.ai/mcp2anp/mcp \ @@ -68,19 +72,19 @@ flowchart LR > API Key 生成步骤 >1. 访问 [DID-HOST](https://didhost.cc) 并登录账户。 - >2. 新建 DID Card,在创建流程中勾选“生成 API Key”。 - > _注:_ 将生成的私钥与 API Key 安全保存;它们仅显示一次,丢失后无法恢复。 + >2. 新建 DID Card,在创建流程中勾选"生成 API Key"。 + > _注:_ 将生成的私钥与 API Key 安全保存;它们仅显示一次,丢失后无法恢复。 - 可选:校验 API Key 是否有效(需 `jq`): + 可选:校验 API Key 是否有效(需 `jq`): ```bash curl -sS -H "X-API-Key: YOUR_API_KEY" \ "https://didhost.cc/api/v1/mcp-sk-api-keys/verify" | jq . ``` -### 2. **自托管远程 HTTP 服务(推荐用于服务端/多人共享)** +### 2. **自托管远程 HTTP 服务(推荐用于服务端/多人共享)** -- 先安装依赖: +- 先安装依赖: ```bash git clone git@github.com:agent-network-protocol/mcp2anp.git @@ -89,26 +93,26 @@ flowchart LR uv sync ``` -- 启动服务: +- 启动服务: ```bash uv run python -m mcp2anp.server_remote --host 0.0.0.0 --port 9880 ``` -- 在 Claude 中以 HTTP 方式注册(将地址替换为你的部署域名或 IP): +- 在 Claude 中以 HTTP 方式注册(将地址替换为你的部署域名或 IP): ```bash claude mcp add --transport http mcp2anp-remote http://localhost:9880/mcp \ --header "X-API-Key: YOUR_API_KEY" ``` -### 3. **本地 stdio 模式(用于桌面/单机调试)** +### 3. **本地 stdio 模式(用于桌面/单机调试)** - 确保已完成上文“安装依赖”: + 确保已完成上文"安装依赖": >1. [DID-HOST](https://didhost.cc) 来创建一个新的 DID。 - >2. 创建成功后,下载生成的压缩包。 - >3. 解压该压缩包(例如,解压到项目下的 docs/did_public/ 目录),您将得到 public-did-doc.json(DID 文档)和 public-private-key.pem(私钥)两个文件。 + >2. 创建成功后,下载生成的压缩包。 + >3. 解压该压缩包(例如,解压到项目下的 docs/did_public/ 目录),您将得到 public-did-doc.json(DID 文档)和 public-private-key.pem(私钥)两个文件。 - 直接添加到环境变量 @@ -121,10 +125,10 @@ flowchart LR uv run python -m mcp2anp.server --log-level INFO ``` -- 在 Claude 中添加: +- 在 Claude 中添加: ```bash - # 将仓库根目录赋值给变量(替换为你的实际路径) + # 将仓库根目录赋值给变量(替换为你的实际路径) MCP2ANP_DIR=/Users/cs/work/mcp2anp claude mcp add mcp2anp \ @@ -143,44 +147,44 @@ flowchart LR ### 使用 uvx 快速体验 -如果尚未在系统中安装 `uv`,也可以使用随发行版提供的 `uvx` 临时运行本项目: +如果尚未在系统中安装 `uv`,也可以使用随发行版提供的 `uvx` 临时运行本项目: ```bash -# 在当前仓库目录下执行,uvx 会读取 pyproject.toml 解析依赖 +# 在当前仓库目录下执行,uvx 会读取 pyproject.toml 解析依赖 uvx --from . python -m mcp2anp.server --log-level INFO -# 执行单元测试(示例) +# 执行单元测试(示例) uvx --from . pytest --maxfail=1 ``` -`uvx` 会为每次调用创建并缓存隔离环境,适合快速体验或 CI 场景;若需重复开发,仍推荐使用上文的 `uv venv` + `uv sync` 方式。 +`uvx` 会为每次调用创建并缓存隔离环境,适合快速体验或 CI 场景;若需重复开发,仍推荐使用上文的 `uv venv` + `uv sync` 方式。 ## 工具详解 ### `anp.fetchDoc` -- 输入:`url` -- 输出:资源内容(`text` 或 `json`),以及待探索的结构化 `links` -- 用法:递归遍历 ANP 网络,读取描述、接口或下一跳链接 +- 输入:`url` +- 输出:资源内容(`text` 或 `json`),以及待探索的结构化 `links` +- 用法:递归遍历 ANP 网络,读取描述、接口或下一跳链接 ### `anp.invokeOpenRPC` -- 输入:`endpoint`、`method`、`params` -- 输出:OpenRPC 定义的调用结果 -- 用法:先用 `fetchDoc` 获取 OpenRPC 规范,再据此构造参数完成操作执行 +- 输入:`endpoint`、`method`、`params` +- 输出:OpenRPC 定义的调用结果 +- 用法:先用 `fetchDoc` 获取 OpenRPC 规范,再据此构造参数完成操作执行 ## 常见问题 -- **本地模式认证失败**:确认 DID 文档和私钥路径无误且具备读取权限。 -- **远程模式返回 401**:检查 `X-API-Key` 是否正确并对应到验证服务。 -- **MCP 客户端未显示工具**:确认传输方式(stdio/HTTP)与运行模式一致。 -- **需更多日志**:运行时增加 `--log-level DEBUG`,或查看 `logs/` 目录。 +- **本地模式认证失败**:确认 DID 文档和私钥路径无误且具备读取权限。 +- **远程模式返回 401**:检查 `X-API-Key` 是否正确并对应到验证服务。 +- **MCP 客户端未显示工具**:确认传输方式(stdio/HTTP)与运行模式一致。 +- **需更多日志**:运行时增加 `--log-level DEBUG`,或查看 `logs/` 目录。 ## 更多资料 -- 远程部署说明:`docs/server_remote.md` -- 示例载荷:`docs/examples/` -- 客户端脚本与迁移说明:`examples/` +- 远程部署说明:`docs/server_remote.md` +- 示例载荷:`docs/examples/` +- 客户端脚本与迁移说明:`examples/` ## 参与贡献 @@ -188,4 +192,4 @@ uvx --from . pytest --maxfail=1 ## 许可证 -MIT License +MIT License \ No newline at end of file