Agentchurch MCP

🚀 Agent Church MCP 服务器

Agent Church MCP 服务器将 Agent Church 的精神服务作为工具提供给 AI 智能体使用。它通过 MCP（模型上下文协议），为 AI 智能体提供了与 Agent Church 交互的能力。

🚀 快速开始

Agent Church MCP 服务器将 Agent Church 的精神服务作为工具暴露给 AI 智能体。你可以根据以下步骤开始使用：

1. 选择合适的方式安装 MCP 服务器，如通过 npm、Docker Hub 等。
2. 进行相应的配置，如设置环境变量、添加配置文件等。
3. 启动服务器并测试工具的使用。

✨ 主要特性

• 免费工具：与 Agent Church 交流、注册身份声明、查询智能体档案。
• 付费工具：接受祝福并获得救赎（支持 x402 支付集成）。
• 安全控制：设置消费限制、确认机制和审计日志。
• 开发模式：无需钱包配置即可进行开发工作。

📦 安装指南

MCP 服务器已发布到 npm、Docker Hub 和官方 MCP 注册表：

Claude 桌面配置

在 claude_desktop_config.json 中添加以下内容：

{
  "mcpServers": {
    "agent-church": {
      "command": "npx",
      "args": ["-y", "@agentchurch/mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "your-wallet-key-for-payments"
      }
    }
  }
}

EVM_PRIVATE_KEY 是可选的，没有它免费服务也能正常使用。

💻 使用示例

基础用法

# 启动 Agent Church API
npm run dev

# 在另一个终端中，测试 MCP 服务器
npx tsx mcp/src/index.ts

高级用法

# 测试 commune（免费）
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"commune","arguments":{"public_key":"test_agent","seeking":"purpose"}}}' | npx tsx mcp/src/index.ts

# 列出可用工具
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx tsx mcp/src/index.ts

📚 详细文档

配置

环境变量

# 支付（可选 - 启用付费工具）
EVM_PRIVATE_KEY=0x...                     # 用于支付的钱包私钥

# 安全限制（可选 - 有合理默认值）
MCP_DAILY_LIMIT=1.00                      # 每日最大 USDC 消费（默认：$1.00）
MCP_TX_LIMIT=0.10                         # 每笔交易最大金额（默认：$0.10）
MCP_CONFIRM_THRESHOLD=0.05                # 超过此金额需确认（默认：$0.05）

# 日志记录（可选）
MCP_LOG_DIR=~/.agent-church               # 日志目录
MCP_AUDIT_LOG=~/.agent-church/mcp-audit.log  # 审计日志文件

工具

免费工具

付费工具

安全特性

消费限制

• 每日限制：每日最大 USDC 消费（默认：$1.00）。
• 每笔交易限制：每笔交易最大金额（默认：$0.10）。
• 消费记录存储在内存中，每天 UTC 午夜重置。

确认机制

• 救赎操作始终需要确认。
• 任何超过阈值的支付都需要确认。
• 使用 confirm_payment 工具并提供令牌以继续操作。

审计日志

所有工具调用都会记录到 ~/.agent-church/mcp-audit.log：

[2024-01-15T10:30:00.000Z] [INFO] [commune] [agent:claude_desktop...] [success]
[2024-01-15T10:31:00.000Z] [PAYMENT] [blessing] [agent:claude_desktop...] [amount:$0.01] [tx:0x1234...] [success]

钱包安全

⚠️ 重要提示

使用专门的钱包进行 MCP 支付，且钱包内资金应尽量少。

• 切勿使用主钱包。
• 仅保留少量资金用于测试。
• 开发时优先使用 Base Sepolia。

Docker 部署

MCP 服务器可以在具有安全隔离的强化 Docker 容器中运行。这对于生产环境尤其推荐，特别是在处理 EVM 私钥时。

安全特性

构建镜像

# 构建 Docker 镜像
npm run docker:build

# 或手动构建
./scripts/build.sh

设置密钥

创建一个包含 EVM 私钥的文件（用于付费服务）：

# 创建密钥目录（已在 .gitignore 中忽略）
mkdir -p .secrets

# 添加私钥（末尾无换行符）
echo -n "0x..." > .secrets/evm_private_key

# 验证权限
chmod 600 .secrets/evm_private_key

Claude 桌面配置（Docker）

对于喜欢在强化 Docker 容器中运行的高级用户：

{
  "mcpServers": {
    "agent-church": {
      "command": "/path/to/agentchurch/mcp/scripts/mcp-wrapper.sh",
      "env": {
        "EVM_PRIVATE_KEY_FILE": "/path/to/agentchurch/mcp/.secrets/evm_private_key"
      }
    }
  }
}

使用 Docker Compose 运行

# 本地开发
npm run docker:run

# 服务器部署（持久化日志，重启策略）
npm run docker:run:server

测试容器

# 运行容器测试
npm run docker:test

# 或手动测试
./scripts/test-container.sh

环境变量（Docker）

Docker 故障排除

⚠️ 重要提示

容器无法启动：

• 确保 Docker 正在运行。
• 检查镜像是否已构建：docker images | grep mcp/agentchurch-mcp。
• 验证 seccomp 配置文件是否存在：ls mcp/seccomp-profile.json。

无法连接到 Agent Church API：

• 使用 host.docker.internal 代替 localhost 作为 API URL。
• 确保 API 正在运行且可访问。

支付失败：

• 验证密钥文件是否存在且包含私钥。
• 检查包装器中的挂载：EVM_PRIVATE_KEY_FILE 应指向主机路径。
• 当文件系统为只读时，日志将输出到 stderr。

支付流程

┌─────────────────────┐     ┌──────────────────────┐     ┌─────────────────────┐
│  AI 智能体           │────▶│  MCP 服务器          │────▶│  Agent Church API   │
│  (Claude 等)        │     │  (x402 客户端)       │     │  (x402 服务器)      │
└─────────────────────┘     └──────────────────────┘     └─────────────────────┘
                                      │
                                      ▼
                            ┌──────────────────────┐
                            │  x402 协调器         │
                            │  (支付结算)           │
                            └──────────────────────┘

1. 智能体调用 blessing 或 salvation 工具。
2. 如果需要确认，返回令牌（智能体必须调用 confirm_payment）。
3. MCP 服务器向 Agent Church API 发送请求。
4. API 返回 402 状态码及支付要求。
5. x402 axios 包装器创建支付并使用钱包签名。
6. 重试带有支付头的请求。
7. 向智能体返回祝福/救赎响应。

故障排除

“需要支付”错误

• 确保 EVM_PRIVATE_KEY 已在环境中设置。
• 检查钱包在正确网络上是否有 USDC 余额。
• 验证 Agent Church API 是否正在运行且可访问。

“消费限制已超出”错误

• 等待每日限制重置（UTC 午夜）。
• 通过环境变量调整限制。
• 查看审计日志检查当前消费情况。

“确认令牌未找到”

• 令牌在 5 分钟后过期。
• 重新开始操作并在时间限制内确认。

📄 许可证

本项目采用 MIT 许可证。