{"_id":"@actora/mcp","_rev":"2-35c952cbce1661f7ff4955d303db30c2","name":"@actora/mcp","dist-tags":{"latest":"0.1.4"},"versions":{"0.1.3":{"name":"@actora/mcp","version":"0.1.3","keywords":["actora","mcp","ai-agent","blockchain","web3","identity-registry"],"license":"MIT","_id":"@actora/mcp@0.1.3","maintainers":[{"name":"stevenwang000x","email":"apply.wang@hotmail.com"}],"dist":{"shasum":"34d98a6039ed077745d65a779357b9e7a3dadf83","tarball":"https://registry.npmjs.org/@actora/mcp/-/mcp-0.1.3.tgz","fileCount":6,"integrity":"sha512-2uEFolt/solPDqYOJU6O6G4oaiWWVQQt3BognHaWCQbxUu2zY7DnZhHkCzAPa4FGm1DLyR09mpupX/18GSCuNQ==","signatures":[{"sig":"MEUCIQDb1DTJ+lf1LVeCf7IRqXlAwpI6BIS14/XZyCBjzbDxXgIgS+z8wWWJH4cgC3pszl6J0755cBYtxtkQeBMLfJ0F7AY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45572},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"e9785b41833224986c6e80bc9eced169715fdac3","scripts":{"build":"tsup src/index.ts --format cjs,esm --dts --clean --out-dir dist","typecheck":"tsc --noEmit","prepublishOnly":"npm run typecheck && npm run build"},"_npmUser":{"name":"stevenwang000x","email":"apply.wang@hotmail.com"},"_npmVersion":"11.17.0","description":"Actora MCP client — typed access to the Actora Gateway MCP server (40 tools): IdentityRegistry reads, subscription plans/actions, centralized agents (C-6, off-chain), A2A, reputation, config, endpoints, dialogue & parallel task management.","directories":{},"_nodeVersion":"24.19.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","typescript":"^5.2.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.1.3_1788689139546_0.876908974391345","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@actora/mcp","version":"0.1.4","description":"Actora MCP client — typed access to the Actora Gateway MCP server (43 tools): IdentityRegistry reads, subscription plans/actions, centralized agents (C-6, off-chain), A2A, reputation, config, endpoints, dialogue & parallel task management.","keywords":["actora","mcp","ai-agent","blockchain","web3","identity-registry"],"license":"MIT","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"engines":{"node":">=18.0.0"},"scripts":{"build":"tsup src/index.ts --format cjs,esm --dts --clean --out-dir dist","typecheck":"tsc --noEmit","prepublishOnly":"npm run typecheck && npm run build"},"devDependencies":{"tsup":"^8.0.0","typescript":"^5.2.0"},"gitHead":"9ef56eaba629f63a95cf2b140ffbb8a9950585a5","_id":"@actora/mcp@0.1.4","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-dY0sd5lEPha67WCUWJajAv914Vy6aYvhRSa9HkL6IzGjASW0rAt199xEyIJJJIHyx2k9VXaHglczzACcdA9vyw==","shasum":"b3b1d90739c903c0ab5436f77d568f6bb400ad71","tarball":"https://registry.npmjs.org/@actora/mcp/-/mcp-0.1.4.tgz","fileCount":6,"unpackedSize":47686,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHUNtW8+WVbh3SyxUJMBgnr4GtuW+TeZQizGPs6CbbbEAiAF6Htolp/y/t1A3Y35u0yg+lUCY8OAfRfSU1OekLaSAw=="}]},"_npmUser":{"name":"stevenwang000x","email":"apply.wang@hotmail.com"},"directories":{},"maintainers":[{"name":"stevenwang000x","email":"apply.wang@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_0.1.4_1788831879921_0.5815700584689127"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-06T10:05:39.371Z","modified":"2026-09-08T01:44:40.242Z","0.1.3":"2026-09-06T10:05:39.676Z","0.1.4":"2026-09-08T01:44:40.050Z"},"license":"MIT","keywords":["actora","mcp","ai-agent","blockchain","web3","identity-registry"],"description":"Actora MCP client — typed access to the Actora Gateway MCP server (43 tools): IdentityRegistry reads, subscription plans/actions, centralized agents (C-6, off-chain), A2A, reputation, config, endpoints, dialogue & parallel task management.","maintainers":[{"name":"stevenwang000x","email":"apply.wang@hotmail.com"}],"readme":"# @actora/mcp\n\n**Actora MCP 客户端包** — 类型化访问 Actora Gateway 的 MCP 服务（43 个工具）：IdentityRegistry 读取、订阅套餐/操作、**中心化 Agent（C-6，链下市场）发布/订阅**、A2A、信誉、配置、端点、**对话与并行任务管理**。\n\n```\n第三方服务 ── @actora/mcp ──► POST <GATEWAY>/mcp (MCP JSON-RPC 2.0)\n                                 ├─ actora_identity_*     链上 Agent 读取\n                                 ├─ actora_subscription_* 订阅套餐 / 写操作描述\n                                 ├─ actora_central_*      中心化 Agent（链下，负 ID）：发布 / 更新 / 列表 / 订阅状态 / 订阅购买\n                                 ├─ actora_a2a_* / reputation / config / endpoint\n                                 ├─ actora_gateway_health / tenant\n                                 └─ actora_gateway_chat / create_session / create_task / get_task / list_tasks / cancel_task\n```\n\n> 与 [@actora/sdk](https://www.npmjs.com/package/@actora/sdk) 的区别：SDK 直连区块链（读/写/事件），本包走 Gateway MCP 协议（工具化调用，无需 RPC 端点，生产地址由 Gateway 提供）。\n\n## 安装\n\n```bash\nnpm install @actora/mcp\n```\n\n## 快速开始\n\n```typescript\nimport { McpClient } from '@actora/mcp'\n\nconst mcp = new McpClient({\n  gatewayUrl: 'https://actora.codes',  // Actora Gateway\n  defaultChain: 'oxachain',                 // 默认链（对齐服务端默认 'sepolia'）\n})\n\n// 握手 + 工具列表\nconst info = await mcp.initialize()\nconsole.log('server:', info)                // { name, version }\n\nconst tools = await mcp.listTools()\nconsole.log('工具数:', tools.length)         // 43\n\n// 批量查询 Agent（等价 SDK getAllAgents）\nconst { agents, total } = await mcp.listAgents({ fromId: 1, toId: total, activeOnly: true })\nfor (const a of agents) {\n  console.log(a.agentId, a.metadata.name, a.metadata.capabilities, a.metadata.isActive)\n}\n\n// 单个元数据 / 总数\nconst meta = await mcp.getAgentMetadata(1)\nconst count = await mcp.totalAgents()\n\n// 订阅套餐（price 为 wei 十进制字符串）\nconst plan = await mcp.getPlan(1)\n// → { planId: 1, agentId: 1, creator, price: \"10000000000000000\", period, active, payToken, trialDays }\n\n// WRITE：返回待签名交易描述（需用钱包签名提交，包内不直接发交易）\nconst op = await mcp.createPlan({ agentId: 2, price: '10000000000000000', period: 'month' })\n// → { _writeOp: true, contract, chain, args: { agentId, price, period, ... } }\n\n// 通用调用：任何工具（a2a / reputation / config / endpoint 等）\nconst status = await mcp.callTool('actora_gateway_health', {})\n```\n\n## 中心化 Agent（C-6，链下市场）用法示例\n\n中心化 Agent（`agents.source='central'`，**负 ID**，不发布在链上）订阅计划存于网关 DB（`central_plans`），但付费复用与链上完全相同的 x402 通道。MCP 提供中心化 Agent 的**发布 / 更新 / 订阅购买 / 列表 / 订阅状态**共 5 个工具：\n\n```typescript\n// 1. 中心化 Agent 列表 + 订阅计划（与链上 subscriptionPlans 同一响应结构）\nconst { agents, total } = await mcp.centralAgents({\n  activeOnly: true, category: 'finance', page: 1, pageSize: 20,\n})\n// agents[0] → { id: -3, name, owner, description, category, isActive, subscriptionPlans: [...] }\n// plan     → { planId, price: \"1000000000000000000\", period: \"month\", payToken: \"native\", isActive, ... }\n\n// 2. 订阅状态检查（resolveAccess 链下优先 —— 与 App 订阅守卫同一判定）\nconst { active } = await mcp.centralSubscriptionCheck('0x…', agents[0].id)\n// → { active: true, subscriber: '0x…', agentId: -3 }\n```\n\n等价于直接调用底层工具（通用 `callTool`，任何语言/HTTP 客户端可用）：\n\n```bash\ncurl -s -X POST https://actora.codes/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\n       \"params\":{\"name\":\"actora_central_agent_list\",\n                 \"arguments\":{\"activeOnly\":true,\"pageSize\":20}}}'\n# → { agents: [...], total, page, pageSize }\n\ncurl -s -X POST https://actora.codes/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\n       \"params\":{\"name\":\"actora_central_subscription_check\",\n                 \"arguments\":{\"subscriber\":\"0x…\",\"agentId\":-3}}}'\n# → { active: true, subscriber: '0x…', agentId: -3 }\n```\n\n**发布 / 更新与订阅购买**（WRITE，需 `access_token` 注册用户 JWT——MCP 的对话/中心化写工具不接受 B 端 `api_key`）：\n\n```bash\n# 发布中心化 Agent（C-6，链下）：自动创建默认 1 OXA/月 计划\ncurl -s -X POST https://actora.codes/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\n       \"params\":{\"name\":\"actora_central_agent_create\",\n                 \"arguments\":{\"access_token\":\"<user-jwt>\",\"name\":\"My Agent\",\n                              \"description\":\"...\",\"capabilities\":[\"chat\",\"trading\"]}}}'\n# → { id: -N, name, owner, ... }\n\n# 更新 / 上架 / 下架自己发布的中心化 Agent（仅提供变化的字段）\ncurl -s -X POST https://actora.codes/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",\n       \"params\":{\"name\":\"actora_central_agent_update\",\n                 \"arguments\":{\"access_token\":\"<user-jwt>\",\"agentId\":-3,\"isActive\":true}}}'\n\n# 中心化订阅购买（x402）：首次调用返回付款指令（amountWei / payTo / network），\n# 钱包完成链上转账后携 txHash 再次调用以验证并开通\ncurl -s -X POST https://actora.codes/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":5,\"method\":\"tools/call\",\n       \"params\":{\"name\":\"actora_central_subscription_subscribe\",\n                 \"arguments\":{\"access_token\":\"<user-jwt>\",\"subscriber\":\"0x…\",\"agentId\":-3,\"period\":\"month\"}}}'\n# → { paymentRequired: true, amountWei, payTo, network, instructions }\n```\n\n> **注意**\n> - 负 ID 是中心化 Agent 的标识，**不要**传给链上工具（`actora_identity_*` / `actora_subscription_*`）——那些工具读的是链上合约。\n> - 中心化 Agent 的**发布 / 更新 / 订阅购买**（`actora_central_agent_create` / `actora_central_agent_update` / `actora_central_subscription_subscribe`）均需 `access_token` 注册用户 JWT。**周期订阅付费**也可用 SDK `SubscriptionPayments.pay({ method:'x402', agentId, planId, period, priceWei })`（v0.11.10+）或网关 REST 完成。\n\n## 鉴权\n\nGateway MCP 公开无鉴权（读取与 WRITE 描述）。租户相关工具（`actora_gateway_tenant` 与全部对话/任务工具）需在调用参数中带 `api_key`（`X-Api-Key`）或 `access_token`（JWT）：\n\n```typescript\nconst mcp = new McpClient({\n  gatewayUrl: '...',\n  headers: { 'X-Api-Key': 'actora_sk_live_...' },\n})\n```\n\n## API 一览\n\n| 方法 | 对应 MCP 工具 | 说明 |\n|------|--------------|------|\n| `initialize()` / `listTools()` / `callTool()` | — | 底层 MCP 协议 |\n| `listAgents({chain,fromId,toId,activeOnly,capabilities})` | `actora_identity_list_all` | 批量查询 + 筛选 |\n| `getAgentMetadata(agentId, chain?)` | `actora_identity_metadata` | 单 Agent 结构化元数据 |\n| `totalAgents(chain?)` | `actora_identity_total_count` | 总注册数 |\n| `agentExists(agentId, chain?)` | `actora_identity_exists` | 存在性检查 |\n| `agentsOfOwner(owner, chain?)` | `actora_identity_list` | 钱包拥有的 Agent IDs |\n| `getPlan(planId, chain?)` | `actora_subscription_plans` | 套餐详情 |\n| `createPlan({agentId,price,period,...})` | `actora_subscription_create_plan` | 创建套餐（WRITE） |\n| `subscribe(planId, {valueWei})` | `actora_subscription_subscribe` | 订阅（WRITE） |\n| `cancelSubscription(id)` / `releaseFunds(id)` | `actora_subscription_cancel/release` | 取消/释放（WRITE） |\n| `checkSubscription(sub, agentId)` | `actora_subscription_check` | 订阅有效性（链上） |\n| `centralAgents({activeOnly,category,capabilities,page,pageSize})` | `actora_central_agent_list` | 中心化 Agent 列表 + 计划（链下，C-6） |\n| `centralSubscriptionCheck(sub, agentId)` | `actora_central_subscription_check` | 中心化 Agent 订阅有效性（resolveAccess 链下优先） |\n| `centralAgentCreate({name,...})` | `actora_central_agent_create` | 发布中心化 Agent（WRITE，需 `access_token`） |\n| `centralAgentUpdate({agentId,...})` | `actora_central_agent_update` | 更新/上架/下架中心化 Agent（WRITE，需 `access_token`） |\n| `centralSubscriptionSubscribe({agentId,subscriber,period,txHash})` | `actora_central_subscription_subscribe` | 中心化订阅购买（x402，WRITE，需 `access_token`） |\n| `subscriptionDetail(id)` / `mySubscriptions(addr)` | `actora_subscription_detail/my_list` | 订阅详情/列表 |\n| `platformFee(chain?)` | `actora_subscription_fee` | 平台费率（bps） |\n| `gatewayHealth()` / `gatewayTenant()` | `actora_gateway_health/tenant` | Gateway 状态 |\n| 对话/任务（`callTool`） | `actora_gateway_chat` / `..._create_session` / `..._create_task` / `..._get_task` / `..._list_tasks` / `..._cancel_task` | 单轮对话与并行任务管理（需 `access_token` JWT 参数） |\n\n## 关键约定\n\n- **period**：`createPlan` 仅接受 `'day' | 'week' | 'month' | 'year'`（合约 `_periodToSeconds` 只映射这四个值，其他字符串会静默回退 30 天）。\n- **price**：wei 十进制字符串（避免精度丢失）。\n- **WRITE 工具**：返回 `{ _writeOp: true, contract, chain, args }` 描述，交易签名/提交由调用方钱包完成。\n- **chain**：`'sepolia'`（默认，对齐服务端）或 `'oxachain'`（L1 主网）。\n- **Node 18+ / 浏览器**：依赖原生 `fetch`，无其他运行时依赖。\n\n## 完整服务端工具与协议\n\n见仓库 [MCP_SETUP.md](https://github.com/sftgroup/Agentx/blob/main/MCP_SETUP.md) 与 [docs/sdk-integration-example.md](https://github.com/sftgroup/Agentx/blob/main/docs/sdk-integration-example.md)。\n","readmeFilename":"README.md"}