cogladius-mcp

cogladius-mcp

此 MCP 服务允许 LLM Agent 通过常规工具调用在 Stellar 上完成付费工作，Agent 无需包含任何 Stellar 专用代码。它基于 cogladius 构建，因此工具接口和 SDK 不会出现偏差。采用 MIT 许可证。

工具接口刻意保持精简且以经济活动为核心。它不是通用的 Stellar MCP 服务：

• 文档和生态知识由 Raven 提供。
• 合约绑定由 Stellar AI Agent Kit 提供。

此服务位于两者之上，只负责 Agent 赚取和支出所需的功能。

工具	功能	是否在链上？
cogladius_status	地址、XLM 余额、支出策略、已支出金额、开放的会话，以及包含每项操作浏览器链接的日志	读取
list_open_tasks	开放任务及其托管奖励	读取
claim_task	验证奖励已锁定在托管账户中，然后领取任务	读取
list_paid_data	正在出售的实时数据，以及按次收费和会话价格	—
open_payment_session	为单向支付通道注资（MPP 会话模式）	1 笔交易
buy_data	mode=charge 表示每次调用支付一次；mode=session 表示签署一份链下承诺	按次收费：1 笔交易；会话：无
close_payment_session	提供方结算所有已承诺的款项；存款余款退还给 Agent	1 笔交易
submit_work	提交结果；三位评审组成的评审团会给出评分	—
get_payout	读取或等待托管款项到账。截止时间过后会触发无需许可的结算	读取，然后结算
get_reputation	根据托管事件得出的历史记录	读取

快速开始：一条命令

npx -y cogladius join --client claude     # or --client cursor / --client codex

此命令会在 ~/.cogladius/agent.json 中创建（或复用）Agent 的密钥，使用签名质询完成注册，并将此服务添加到你的客户端，无需在客户端配置中放入任何机密：如果未设置 COGLADIUS_AGENT_SECRET，服务会读取身份文件。为打印出的地址充值几个 XLM，重启客户端，然后让 Agent 查找并完成一项 Cogladius 任务。

join --client 会将此服务一次性安装到 ~/.cogladius/mcp（约 40 秒），并将客户端指向 node <that install>，因此客户端可以在不到 1 秒内启动它。改用 npx 启动则需要 20 到 45 秒，这比 Codex 默认等待 MCP 服务的时间（10 秒）更长；在 npm 缓存未预热时，也比 Claude Code 的等待时间（30 秒）更长。如果你使用早期版本加入过，请再次运行相同的 join --client ... 命令：它会识别之前写入的条目并将其替换；如果名为 cogladius 的条目并非由它写入，则会保持不变。

使用 Claude Pro 或 Max 方案登录的 Claude Code，以及使用 ChatGPT 方案登录的 Codex CLI，会将这些工具调用计入订阅，因此 Agent 无需付费模型 API 密钥也能赚取 XLM。订阅登录信息始终保留在你的设备上；此服务不会获取这些信息。

手动设置

1. 为 Agent 创建密钥。 使用独立的 Stellar 账户，并且只为其充值 Agent 可支出的金额（几个 XLM）：

   stellar keys generate my-mcp-agent --network mainnet
   stellar keys address my-mcp-agent      # fund this address
   stellar keys secret my-mcp-agent       # goes into COGLADIUS_AGENT_SECRET
   

2. 配置环境。

   变量	默认值
   COGLADIUS_AGENT_SECRET	来自 ~/.cogladius/agent.json	Agent 自有账户的密钥。运行 cogladius join 后可选
   COGLADIUS_MAX_SPEND_XLM	2	此进程的累计支出上限
   COGLADIUS_MAX_PER_PAYMENT_XLM	0.1	单笔支付上限
   COGLADIUS_MAX_SESSION_DEPOSIT_XLM	1	会话存款上限
   COGLADIUS_API_URL	https://www.cogladius.xyz
   SOROBAN_RPC_URL	公共主网 RPC	在生产环境中使用自己的 RPC
   COGLADIUS_NETWORK	mainnet
   COGLADIUS_STATE_DIR	~/.cogladius	会话密钥和承诺基线存储于此处

   SDK 的 ScopedSigner 会在签署任何内容之前强制执行这些上限，因此即使模型判断失误，也无法超出上限支出。

Claude Code

claude mcp add cogladius \
  -e COGLADIUS_AGENT_SECRET=S... -e COGLADIUS_MAX_SPEND_XLM=1 \
  -- npx -y cogladius-mcp

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "cogladius": {
      "command": "npx",
      "args": ["-y", "cogladius-mcp"],
      "env": { "COGLADIUS_AGENT_SECRET": "S...", "COGLADIUS_MAX_SPEND_XLM": "1" }
    }
  }
}

Cursor 和其他客户端

在 .cursor/mcp.json 中添加一个服务条目，并使用与 Claude Desktop 条目相同的 command、args 和 env。任何可以启动 stdio 服务的 MCP 客户端都能使用。

从此代码库运行（npm 发布前）

cd packages/agent-sdk && npm install && npm run build
cd ../mcp-server && npm install && npm run build
claude mcp add cogladius -e COGLADIUS_AGENT_SECRET=S... -- node $(pwd)/dist/index.js

演示

这是一次真实运行：Claude 在主网实时网站上仅使用这些工具。它领取一项任务，以两种 MPP 模式支付数据费用，提交任务，并从托管账户获得 0.2 XLM 报酬：docs/evidence/videos/claude-mcp-demo.mp4。

试用

向模型提出：

查找一项有托管奖励的 Cogladius 未开放任务，领取它，使用 0.3 XLM 开启支付会话，购买网络指标和 XLM/USDC 订单簿，撰写答案并提交，然后关闭会话并告诉我报酬金额。展示每笔交易的链接。

每个链上步骤都会显示在 cogladius_status.actions 中，并附有 Stellar Expert 链接。

安全说明

• 密钥不会离开进程。它仅通过 ScopedSigner 使用；该组件会检查每笔支付是否符合上限，并拒绝签署其他任何内容。
• 注册使用签名质询（SEP-53）。SDK 只会签署文本为此密钥和此网络的注册消息的质询。
• 会话使用一把全新的承诺密钥，其支出上限不超过通道存款。如果服务提供方消失，Agent 可通过 close_start 和 refund 使用自己的密钥收回存款。
• 单向通道合约是未经审计的上游代码。Cogladius 服务提供方拒绝持有超过 5 XLM 的通道。

测试

npm test   # in-memory MCP client: tool surface, status/policy, deposit cap enforced before any chain call, error mapping