内容
# agtp-mcp
AGTP至MCP的翻译网关。任何基于标准输入输出的[模型上下文协议（MCP）][mcp]服务器都可以通过该网关添加AGTP和TLS，增加代理身份、权限范围执行、预算限制执行和签名的归因记录。在后台的MCP服务器上无需任何更改。
在`@modelcontextprotocol/server-filesystem`、`@modelcontextprotocol/server-brave-search`或您自己的MCP服务器前面运行它，AGTP客户端可以像调用其他AGTP方法一样调用它，并在其上层叠加所有AGTP保证。
## 动词映射
| AGTP 动词 + 路径 | MCP JSON-RPC |
|----------------------|--------------------|
| `DESCRIBE` + 工具 | `tools/list` |
| `EXECUTE` + 工具 | `tools/call` |
| `DISCOVER` + 资源 | `resources/list` |
| `QUERY` + 资源 | `resources/read` |
| `DISCOVER` + 提示 | `prompts/list` |
| `QUERY` + 提示 | `prompts/get` |
## 架构
```
AGTP 客户端 ──TLS──▶ agtp-mcp 网关 ──stdio──▶ MCP 服务器
│ （文件系统，
▼ 勇敢搜索，
registry.agtp.io 您自己的…）
（代理身份）
```
该网关是一个单独的Python进程。它：
1. 在其公共端口（默认为4480，可通过`AGTP_MCP_PORT`配置）终止TLS。
2. 解析传入的AGTP请求，验证代理身份并执行权限范围和预算。
3. 将配置的MCP服务器作为子进程启动，并通过stdio与其进行JSON-RPC通信（按照MCP规范）。
4. 将响应翻译回AGTP帧，签署归因记录，并将其发送到线路和归因日志中。
## 安装
```bash
git clone https://github.com/nomoticai/agtp-mcp
cd agtp-mcp
pip install -r requirements.txt
```
推荐使用Python 3.11+。
## 配置
所有配置均通过环境变量驱动，因此相同的网关镜像可以在开发、预发布和生产环境中运行。
| 变量 | 默认值 | 功能 |
|---------------------------|------------------------------------------------------|-----------------------------------------------|
| `AGTP_MCP_HOST` | `0.0.0.0` | TCP绑定主机 |
| `AGTP_MCP_PORT` | `4481` | TCP绑定端口（生产环境：4480标准AGTP）|
| `AGTP_MCP_CERT` | Let's Encrypt路径 | TLS完整链 |
| `AGTP_MCP_KEY` | Let's Encrypt路径 | TLS私钥 |
| `AGTP_REGISTRY` | `https://registry.agtp.io` | AGTP代理注册中心 |
| `AGTP_MCP_BACKEND` | 模拟MCP服务器 | 启动后台MCP服务器的命令 |
| `AGTP_GATEWAY_KEY` | `/var/lib/agtp/gateway_signing_key.pem` | 用于签署归因记录的Ed25519密钥 |
| `AGTP_ATTRIBUTION_LOG` | `/var/log/agtp/attribution.log` | 追加式归因日志路径 |
| `AGTP_REQUIRE_SIGNATURE` | `0` | 当为`1`时，拒绝没有有效代理签名的请求 |
### 直接运行
```bash
export AGTP_MCP_BACKEND="npx -y @modelcontextprotocol/server-filesystem /var/lib/agtp/mcp-sandbox"
export AGTP_MCP_CERT=/etc/letsencrypt/live/mcp.example.com/fullchain.pem
export AGTP_MCP_KEY=/etc/letsencrypt/live/mcp.example.com/privkey.pem
python gateway.py
```
### 通过systemd运行
该存储库中提供了一个单元文件：
```bash
sudo cp agtp-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now agtp-mcp
```
编辑单元文件，将`AGTP_MCP_BACKEND`指向您要公开的MCP服务器。
## 本地测试
`mock_mcp_server.py`是一个小型stdio MCP服务器，暴露了一个工具（`echo`）——在不安装真正的MCP后端的情况下，用于对网关进行烟雾测试：
```bash
# 终端 1：网关 + 模拟后端
AGTP_MCP_BACKEND="python mock_mcp_server.py" \
AGTP_MCP_CERT=server.crt \
AGTP_MCP_KEY=server.key \
python gateway.py
# 终端 2：客户端演示
python client_demo.py
```
## 为什么选择桥接而不是替换
MCP客户端（Claude Desktop、Cline等）已经通过stdio或HTTP使用JSON-RPC风格。如果替换它们，则意味着需要重写每个MCP客户端。桥接意味着：
- 现有的MCP服务器在无需代码更改的情况下获得代理身份、范围、预算和加密归因。
- 学习使用AGTP的MCP客户端可以获得完整的AGTP功能集（基于注册中心的发现、跨代理预算、通过代理证书的相互身份验证）。
- AGTP和MCP社区可以独立发展。AGTP不试图定义工具调用模式；MCP不试图定义跨代理传输。
## 相关
- [AGTP规范存储库][agtp] — 协议草案（IETF）、`agtpd`守护进程、一致性测试
- [模型上下文协议][mcp] — 来自Anthropic的上游MCP规范
- [`agtp-a2a`][a2a] — 兄弟跨协议桥接（目前在规范存储库中，随着表面稳定而独立）
## 历史
该软件包最初名为`mcp-on-agtp/`。为了与一致的连接器软件包（`agtp-drupal`、`agtp-symfony`、`agtp-laravel`、`agtp-wordpress`）保持一致，更名为`agtp-mcp/`。后来提取到其自己的存储库中，以便MCP用户无需克隆整个AGTP堆栈即可运行单个桥接。
[mcp]: https://modelcontextprotocol.io/
[agtp]: https://github.com/nomoticai/agtp
[a2a]: https://github.com/nomoticai/agtp/tree/main/connectors/agtp-a2a
