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 許可證。