内容
# Molpha MCP
[](https://github.com/molpha/mcp/actions/workflows/ci.yml)
[](LICENSE)
[](package.json)
一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器，允许 AI 代理创建、获取、验证和发布 [Molpha](https://docs.molpha.io/) 神谕数据。
Molpha 将 HTTP API 响应转换为阈值签名有效载荷，可以在 Solana、EVM 和 Starknet 上验证。该服务器将工作流程公开为一组小型 MCP 工具，并将签名保留在本地、Privy 或 Turnkey 支持的钱包中。
> [!WARNING]
> 此版本针对 Solana Devnet 和 Sepolia 验证器网络。请将其视为测试网络软件，而不是生产安全边界。编写工具会花费 SOL，并可能消耗订阅配额，除非启用 dry-run 模式。
## 功能
- 发现活动注册表、神谕节点、网关和验证器部署。
- 在本地从声明性 API 规范中派生 feedId - 无需交易，无需订阅。Feed 会在首次结算时延迟创建。
- 请求阈值签名结果，并为多个链构建验证器参数，支付方式为活动 USDC 订阅或自筹 [x402](#x402-pay-per-request) 轮。
- 构建 EVM/Starknet 验证器调用参数，或向 Solana feed 提交验证更新。
- 使用本地密钥对、Privy 服务器钱包或 Turnkey 钱包，无需更改 MCP 工具表面。
- 对代理发起的写入和 x402 支出设置每日上限和全局 dry-run 默认值。
## MCP 工具
| 工具 | 访问 | 描述 |
| --- | --- | --- |
| `molpha_get_capabilities` | 读取 | 返回注册表版本、节点集、网关、链、验证器元数据和 x402上限。 |
| `molpha_describe_feed` | 读取 | 读取 feed 的链上状态和订阅状态。传递 `feedId`，或 `apiConfig` + `signaturesRequired` 以派生它。 |
| `molpha_derive_feed` | 读取 | 从 `apiConfig` + `signaturesRequired` 在本地派生 feedId。无需交易。 |
| `molpha_agent_status` | 读取 | 读取 x402 代理托管账户（USDC 余额、已承诺金额、报价下一个价格）当前签名者。 |
| `molpha_fetch_verified` | 读取/配额/支出 | 运行签名轮并返回签名工件和验证器参数。`payment: "subscription" \| "x402" \| "auto"` 选择如何支付轮；`autoSubmit: true` 在同一调用中结算 Solana 腿。 |
| `molpha_get_latest` | 读取 | 读取 Solana feed 账户中存储的最新值。 |
| `molpha_verify` | 读取 | 构建 EVM/Starknet 验证器地址和调用参数（仅限 calldata）。 |
| `molpha_execute` | 写入 | 向 Solana 提交签名数据更新。接受 `molpha_fetch_verified` 输出不变。 |
`molpha_verify` **按设计** 在 calldata 处停止：Molpha 验证器是无状态的，因此代理执行 `verify()` 自身，服务器从未提交 EVM/Starknet 交易或担保其未在链上验证的结果。Solana 是此服务器结算的唯一链 - 通过 `molpha_execute` 或 `molpha_fetch_verified` 的 `autoSubmit` - 并且没有独立的 Solana 验证模拟路径；提交，然后使用 `molpha_get_latest` 读取结果。
`molpha_execute` 和 `molpha_verify` 采用 `molpha_fetch_verified` 响应原样：调用之间没有字段重映射，短十六进制字段（网关发出一个签名者的 `signersBitmap` 为 `"4"`）在服务器端填充为其规范宽度。
## 快速入门
### 要求
- Node.js 20 或更高版本
- 一个包含 Devnet SOL 的 Solana 钱包
- 如果您计划使用活动订阅或按需付费路径，则需要 Devnet USDC
- 一个 MCP 客户端，例如 Cursor、Claude Desktop 或 Codex
### 1. 安装和构建
```bash
git clone https://github.com/molpha/mcp.git
cd mcp
npm ci
cp .env.example .env
npm run build
```
### 2. 配置签名者
对于本地开发，将 `OWNER_KEYPAIR` 指向 Solana JSON 密钥对。在 MCP 客户端启动时使用绝对路径。
```dotenv
SIGNER_BACKEND=memory
OWNER_KEYPAIR=/absolute/path/to/owner-keypair.json
SOLANA_RPC=https://api.devnet.solana.com
GATEWAY_ENDPOINTS=
```
同一个钱包拥有 feed 和任何 x402 托管账户，验证网关请求，并签署 Solana 交易。不要提交 `.env`、钱包文件或凭证。
其他支持的签名者配置：
| 后端 | 所需配置 |
| --- | --- |
| 本地密钥对 | `SIGNER_BACKEND=memory`，`OWNER_KEYPAIR` |
| Privy | `SIGNER_BACKEND=keychain`，`KEYCHAIN_BACKEND=privy`，`PRIVY_APP_ID`，`PRIVY_APP_SECRET`，`PRIVY_WALLET_ID`，`PRIVY_WALLET_ADDRESS` |
| Turnkey | `SIGNER_BACKEND=keychain`，`KEYCHAIN_BACKEND=turnkey`，`TURNKEY_API_PUBLIC_KEY`，`TURNKEY_API_PRIVATE_KEY`，`TURNKEY_ORGANIZATION_ID`，`TURNKEY_WALLET_ADDRESS` |
参见 [.env.example](.env.example) 和 [examples](examples) 目录中的即用文件。
### 3. 检查设置
```bash
npm run doctor
```
医生检查编译后的入口点、签名者配置、钱包可用性和 Solana RPC。它还会打印具有解析的绝对路径的配置片段。
### 4. 引导订阅
订阅操作扣除 USDC，因此它们故意不包含在 MCP 工具表面中。使用与服务器相同的签名者配置运行配置 CLI：
```bash
# 预览而不发送交易
npm run provision -- subscribe --plan Basic --max-price-usdc 20000000 --dry-run
# 订阅，最大批准价格为 20 USDC（6 个小数位）
npm run provision -- subscribe --plan Basic --max-price-usdc 20000000
```
使用以下命令扩展现有订阅：
```bash
npm run provision -- extend --max-price-usdc 20000000
```
`--max-price-usdc` 是一个安全上限，以原始 USDC 基本单位表示，而不是报价计划价格。如果实时链上价格超过上限，则交易中止。
### 5. 连接 MCP 客户端
选择以下安装路径之一。在两种情况下，服务器都通过 stdio JSON-RPC 进行通信，并且需要与步骤 2 中的相同签名者设置。
#### Claude Desktop (MCPB)
将构建树打包成 [MCP 包](https://github.com/modelcontextprotocol/mcpb)，并将其安装为桌面扩展。存储库中已经包含一个 [`manifest.json`](manifest.json)，声明了 Node 入口点、工具和用户配置字段。
```bash
npm run build
npx @anthropic-ai/mcpb pack . molpha-mcp.mcpb
```
这会在存储库根目录中写入 `molpha-mcp.mcpb`。可以通过以下方式在 Claude Desktop 中安装：
- 双击 `.mcpb` 文件
- 将其拖入 Claude Desktop 窗口
- 设置 → 扩展 → 高级设置 → 安装扩展 → 选择 `.mcpb` 文件
在安装过程中，设置签名者后端和相关字段（本地密钥对路径、Privy 或 Turnkey）。这些映射到与 `.env.example` 相同的环境变量。
#### Cursor、Codex 或手动 Claude Desktop 配置
将客户端指向构建的服务器（`dist/src/server.js`），而不是 `src/server.ts`:
```json
{
"mcpServers": {
"molpha": {
"command": "node",
"args": ["/absolute/path/to/mcp/dist/src/server.js"],
"env": {
"SIGNER_BACKEND": "memory",
"OWNER_KEYPAIR": "/absolute/path/to/owner-keypair.json",
"SOLANA_RPC": "https://api.devnet.solana.com"
}
}
}
}
```
- Cursor：在 `.cursor/mcp.json` 或 `~/.cursor/mcp.json` 下保存 JSON。可以在 [examples](examples) 目录中找到现成的副本（`cursor-memory.mcp.json`、`cursor-privy.mcp.json`、`cursor-turnkey.mcp.json`）。
- Claude Desktop：将相同的块添加到 `claude_desktop_config.json` 并重启，或更喜欢上面的 MCPB 路径。
- Codex：使用 [Codex TOML 示例](examples/codex-memory.toml) 之一，或运行 `codex mcp add molpha -- node /absolute/path/to/mcp/dist/src/server.js`，然后将签名者变量添加到 `config.toml`。
在更改配置或重新构建后重启客户端。直接 `node dist/src/server.js` 调用会在 stdin 上等待 JSON-RPC；这是 stdio 服务器所预期的。
## 示例提示
一旦服务器连接，这些提示将演练主要工作流程。
### 发现网络
> 使用 Molpha 检查当前的神谕功能。总结注册表版本、节点数量、支持的链、网关端点和验证器地址。不要进行任何写入。
### 预览 feed
> 为 `https://api.example.com/v1/finalized/price` 从 JSON 路径 `$.price` 和 3 个所需签名派生 Molpha feedId。显示 API 配置哈希、派生的 feedId 和任何确定性警告。不要发送交易。
用返回稳定、独立可复制数据的公共端点替换示例 URL。实时行情端点可能会产生不同的值，并且可能无法达到法定人数。
### 获取和验证结果
> 对于同一个 feed，使用 `payment: "auto"` 和 60 秒的最大年龄，为 EVM 链获取签名结果。总结签名值、时间戳、注册表版本、法定人数和 EVM 验证器调用，并告诉我它是否通过订阅或 x402 支付。信任签名工件；不要信任值本身。
### 在支付之前检查 x402 支出
> 为 3 个所需签名调用 `molpha_agent_status`。告诉我托管账户的 USDC 余额、已承诺金额和给定法定人数的报价价格，然后再授权任何 x402 支出。
### 发布审批检查点
> 读取 Molpha feed `<FEED_ID>` 的最新值。如果我提供更新的签名结果，请使用 `dryRun: true` 预览 `molpha_execute`，解释支付钱包和确切写入，并在我确认后将其提交到 Solana。
## 架构
```mermaid
flowchart LR
Client["MCP 客户端<br/>Cursor · Claude · Codex"] <-->|"stdio / JSON-RPC"| Server["Molpha MCP 服务器"]
Server --> Guardrails["写入防护<br/>dry-run · 每日上限 · x402 支出上限"]
Server --> Signer["签名者适配器"]
Signer --> Memory["本地密钥对"]
Signer --> Keychain["Privy 或 Turnkey"]
Server --> SDK["Molpha SDK"]
Server --> X402["x402 客户端<br/>托管资金 · AgentRequestAuth"]
SDK --> Gateway["Molpha 网关<br/>订阅轮"]
X402 --> Gateway2["Molpha 网关<br/>x402 代理轮"]
Gateway <--> Nodes["神谕节点法定人数"]
Gateway2 <--> Nodes
SDK <--> Solana["Solana 程序<br/>feed · 订阅 · 代理托管账户"]
X402 <--> Solana
Gateway --> Artifact["阈值签名<br/>数据更新"]
Gateway2 --> Artifact
Artifact --> Server
Server --> Args["EVM / Starknet 验证器参数，<br/>或在 Solana 上提交数据更新"]
```
服务器是一个适配器和策略边界，而不是新的事实来源：
1. MCP 客户端通过 stdio 调用一个类型化的工具。
2. 签名者验证网关请求和所有者交易。
3. 神谕节点独立获取已提交的 API 配置并在达到法定人数后生成一个聚合签名。
4. 服务器返回自包含的签名工件。Solana 可以验证或存储它；EVM 和 Starknet 消费者接收合约准备好的验证器参数。
5. 消费者只有在验证签名有效载荷与其注册表版本后才信任一个值。
配置是一个单独的 CLI 路径，因为订阅或扩展会扣除 USDC。它在自主 MCP 工具调用中永远不可用。
## 配置
| 变量 | 默认值 | 目的 |
| --- | --- | --- |
| `SIGNER_BACKEND` | `memory` | `memory` 或 `keychain` |
| `KEYCHAIN_BACKEND` | — | `privy` 或 `turnkey` 表示密钥链签名者 |
| `OWNER_KEYPAIR` | — | 本地 Solana JSON 密钥对路径 |
| `SOLANA_RPC` | `https://api.devnet.solana.com` | Solana RPC 端点 |
| `GATEWAY_ENDPOINTS` | `https://dev-gateway.molpha.io` | 用逗号分隔的 **Molpha 网关** 基本 URL（不是您的 Solana RPC）。必须公开 `/v1/nodes` 和签名路由（用于 x402 的 `/v1/agent/execute`，用于订阅的 `/v1/round/execute`）。运行 `npm run doctor` 进行验证。 |
| `MOLPHA_EVM_NETWORKS` | `evm-sepolia` | 用逗号分隔的 EVM 验证器网络 |
| `MOLPHA_STARKNET_NETWORKS` | `starknet-sepolia` | 用逗号分隔的 Starknet 验证器网络 |
| `MOLPHA_MAX_EXECUTES_PER_DAY` | `100` | 进程本地每日 Solana 提交上限 |
| `MOLPHA_DRY_RUN` | `false` | 当设置为 `true` 时，预览所有写入 |
| `MOLPHA_X402_MAX_PRICE_USDC` | `1` | 拒绝为此价格以上的 x402 轮融资（小数 USDC） |
| `MOLPHA_X402_MAX_SPEND_PER_DAY_USDC` | `10` | 进程本地每日 x402 支出上限（小数 USDC） |
| `MOLPHA_X402_GATEWAY_PDA` | — | 可选：跳过 x402 发现往返，当网关的 PDA 已通过其他方式得知时 |
每日计数器是进程本地的，并在服务器重启时重置。它们是安全防护措施，而不是持久的速率限制。
## x402 按需付费
`molpha_fetch_verified` 接受一个 `payment` 参数：
- `"subscription"` — 使用调用者的活动 USDC 订阅（参见 [引导订阅](#4-bootstrap-a-subscription)）。如果订阅不活动或超出配额，则失败。
- `"x402"` — 从每个签名者的托管账户中自筹资金，无需订阅。如果托管账户资金不足，MCP 服务器会用签名者的 USDC 余额为其提供资金（如果需要，创建托管账户的关联代币账户），每个轮次最高可达 `MOLPHA_X402_MAX_PRICE_USDC`，每天最高可达 `MOLPHA_X402_MAX_SPEND_PER_DAY_USDC`，然后超过这些上限时拒绝并显示明确的错误。
- `"auto"`（默认）— 在活动时使用订阅，否则回落到 `"x402"`。
调用 `molpha_agent_status` 以检查托管账户（USDC 余额、已承诺金额和给定法定人数的报价价格）在支出之前，或确认已结算的轮次。`encryptSecrets`（私有 API 机密）当前不支持 x402 路径 — 对具有加密机密的 feed 使用 `payment: "subscription"`。
## 开发
```bash
npm run dev # 从 TypeScript 开始本地开发
npm run typecheck # 在不生成文件的情况下验证类型
npm test # 运行 Vitest 套件
npm run build # 将 src/、cli/ 和测试编译到 dist/
```
在打开拉取请求之前，运行：
```bash
npm run typecheck && npm test && npm run build
```
欢迎提交错误报告和有针对性的拉取请求。对于安全问题，请使用 [GitHub 的私有漏洞报告](https://github.com/molpha/mcp/security/advisories/new)，而不是公开的问题。
## 发布
版本控制和发布自动化 [Changesets](https://github.com/changesets/changesets)。如果您的拉取请求更改了已发布的行为，请添加一个变更集：
```bash
npx changeset
```
这记录了版本号（补丁/小版本/大版本）和更改日志条目。在合并到 `main` 后，[.github/workflows/release.yml](.github/workflows/release.yml)：
1. 打开或更新一个“版本包”拉取请求，同步更新 `package.json`、`manifest.json` 和 `server.json`，并更新 `CHANGELOG.md`。
2. 当该拉取请求合并时，使用 [trusted publishing](https://docs.npmjs.com/trusted-publishers)（GitHub Actions OIDC - 不需要 npm token 在 CI 中）将 `@molpha/mcp` 发布到 npm，然后使用 GitHub OIDC 登录将 `server.json` 发布到 [MCP 注册表](https://registry.modelcontextprotocol.io/)。
发布步骤不需要任何机密；两者都依赖于工作流的 `id-token: write` 权限，并通过每个注册表与此存储库的信任关系授权。
## 文档
- [Molpha 协议文档](https://docs.molpha.io/)
- [客户端配置示例](examples)
- [MCPB 清单](manifest.json) 用于 Claude Desktop / `.mcpb` 打包
## 许可证
在 [MIT 许可证](LICENSE) 下发布。
