# https://github.com/blockrunai/blockrun-mcp 项目说明书 生成时间：2026-06-09 09:12:55 UTC ## 目录 - [项目概览与安装指南](#page-1) - [系统架构、x402 支付与钱包管理](#page-2) - [工具目录与数据源](#page-3) - [技能系统、扩展性、运维与故障排查](#page-4) ## 项目概览与安装指南 ### 相关页面 相关主题：[系统架构、x402 支付与钱包管理](#page-2)
相关源码文件 以下源码文件用于生成本页说明： - [AGENTS.md](https://github.com/blockrunai/blockrun-mcp/blob/main/AGENTS.md) - [package.json](https://github.com/blockrunai/blockrun-mcp/blob/main/package.json) - [CONTRIBUTING.md](https://github.com/blockrunai/blockrun-mcp/blob/main/CONTRIBUTING.md) - [skills/search/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/search/SKILL.md) - [skills/exa-research/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/exa-research/SKILL.md) - [src/tools/search.ts](https://github.com/blockrunai/blockrun-mcp/blob/main/src/tools/search.ts) - [skills/surf/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/surf/SKILL.md) - [skills/rpc/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/rpc/SKILL.md)
# 项目概览与安装指南 ## 一、项目定位与核心能力 BlockRun MCP 是一个通过 Model Context Protocol（MCP）暴露给 AI Agent 的工具服务器，将实时数据市场、研究、社交、X/Twitter 与链上数据能力以"按次调用、USDC 即时结算"的形式提供给模型客户端，无需 API Key 即可访问 30+ 个 AI 模型。资料来源：[AGENTS.md:1-9]() 其核心价值在于把原本需要多套凭据、多套计费的实时数据源统一抽象为一组 MCP 工具，配合 `@blockrun/llm` 网关走 x402 协议用 USDC 在链上完成支付结算。资料来源：[AGENTS.md:25-34]() 项目以 MIT 协议开源，包名为 `@blockrun/mcp`，主入口为 `src/index.ts`，运行时基于 Node.js ≥ 18 与 TypeScript + tsup 构建。资料来源：[package.json:4-12]() [package.json:65-70]() 从仓库内置的技能（skill）描述来看，BlockRun 至少提供以下几类能力： | 能力域 | 代表 skill | 典型用途 | |---|---|---| | 实时搜索 | `skills/search/SKILL.md` | Web / News / X 实时检索 + AI 总结与引用 | | 神经语义搜索 | `skills/exa-research/SKILL.md` | 论文检索、竞品发现、网页正文抓取 | | 加密市场与链上 | `skills/surf/SKILL.md`、`skills/rpc/SKILL.md` | 代币价格、钱包画像、多链 RPC | | 图像生成 | `skills/image-prompting/SKILL.md` | Generate / Edit / 多图合成 | 定价模式按"返回结果数 × 单价"计算，例如 Live Search 默认为 `$0.025 × max_results`，`max_results` 上限 50。资料来源：[skills/search/SKILL.md:24-31]() 神经语义搜索与 RPC 等不同域也各自有独立的计费规则，使用前应阅读对应 skill 文档。资料来源：[skills/exa-research/SKILL.md:14-19]() 社区讨论中关注的点也印证了上述定位：Issue #7 提到项目已支持 41+ 模型、零速率限制、按调用付费的 x402 USDC 结算（[https://github.com/blockrunai/blockrun-mcp/issues/7](https://github.com/blockrunai/blockrun-mcp/issues/7)）；Issue #14 则希望在使用前增加"对手方信任度预检"，说明用户普遍关心支付目标地址是否可信。Issue #11 反映出社区希望仓库提供 `SECURITY.md` 以便私下提交漏洞报告，目前官方入口仍以 GitHub Issues 为主。([https://github.com/blockrunai/blockrun-mcp/issues/11](https://github.com/blockrunai/blockrun-mcp/issues/11)) ## 二、安装与首次运行 `AGENTS.md` 给出了在 Codex 中安装最新版本的标准命令： ```bash # 通用安装（以 Codex 为例） Codex mcp add blockrun -s user -- npx -y @blockrun/mcp@latest ``` 资料来源：[AGENTS.md:39-40]() 本地开发流程则在 `CONTRIBUTING.md` 中给出，遵循 clone → install → build → dev 的常规 Node 项目节奏： ```bash git clone https://github.com/blockrunai/blockrun-mcp cd blockrun-mcp npm install npm run typecheck # tsc --noEmit npm run build # tsup → dist/ npm run dev # tsx watch mode ``` 资料来源：[CONTRIBUTING.md:5-12]() `package.json` 中明确声明了构建工具链：`tsup` 用于打包，`tsx` 用于开发态运行，`typescript` ≥ 5.0 用于类型检查，Node 引擎要求 `>=18`。资料来源：[package.json:55-70]() 安装后无需手动配置任何 API Key：所有调用都走 `@blockrun/llm` 网关，由该 SDK 在首次请求时引导用户完成 USDC 钱包的创建与充值，再以 x402 协议在链上完成 402 挑战→签名→结算的闭环。资料来源：[AGENTS.md:25-27]() [package.json:36-46]() ## 三、验证与本地握手 `CONTRIBUTING.md` 提供了一种轻量级的"stdin 握手"冒烟测试方法，绕过客户端直接验证 dist 产物是否正常暴露工具列表： ```bash (printf '{"jsonrpc":"2.0","id":1,"method":"initialize",...}\n...tools/list\n'; sleep 2) \ | node dist/index.js 2>/dev/null ``` 正常情况下该握手应返回 15 个工具，其中包含 `blockrun_surf`、`blockrun_search`、`blockrun_exa`、`blockrun_rpc` 等核心入口。资料来源：[CONTRIBUTING.md:14-25]() 若需在 Claude Code 中连接本地 dev 构建，可使用： ```bash claude mcp add blockrun-dev node /path/to/blockrun-mcp/dist/index.js ``` 资料来源：[CONTRIBUTING.md:27-29]() ## 四、代码组织与开发约定 仓库遵循 TypeScript + ESM 规范，主要目录结构如下（资料来源：[AGENTS.md:11-22]()）： ``` src/ ├── index.ts # MCP server entry point ├── mcp-handler.ts # MCP protocol handler ├── tools/ # 各 MCP 工具实现 ├── types.ts # 类型定义 └── utils/ # 共享工具 skills/ # 供 Agent 阅读的领域知识（SKILL.md） ``` 每个新 API 接入的"是否升级为 MCP 工具"由 `CONTRIBUTING.md` 中的设计原则决定：当接口需要强类型校验、复杂客户端逻辑（例如异步轮询、多步支付、有状态重试），或属于 BlockRun 核心价值（如 chat、image）时，应升级为 `src/tools/` 下的 MCP 工具；其余一次性 passthrough 接口则更适合作为 skill 提供。资料来源：[CONTRIBUTING.md:33-45]() 以 `src/tools/search.ts` 为例，工具实现包含预算检查（`checkBudget`）、请求体规整（`coerceBody`）、x402 客户端获取（`getClient`）与错误格式化（`formatError`）等共用模块，定价常量 `SEARCH_PRICE_PER_SOURCE = 0.025` 与服务端定价保持一致，并在调用前对 `max_results` 做 1–50 区间收口。资料来源：[src/tools/search.ts:18-28]() ## 五、See Also - 项目结构与目录约定：参见 [AGENTS.md](https://github.com/blockrunai/blockrun-mcp/blob/main/AGENTS.md) - 贡献流程与工具 vs Skill 设计原则：参见 [CONTRIBUTING.md](https://github.com/blockrunai/blockrun-mcp/blob/main/CONTRIBUTING.md) - 实时搜索用法与计费：参见 [skills/search/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/search/SKILL.md) - 神经语义研究工作流：参见 [skills/exa-research/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/exa-research/SKILL.md) - 加密市场 / 链上数据：参见 [skills/surf/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/surf/SKILL.md) 与 [skills/rpc/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/rpc/SKILL.md) - 社区诉求：对手方信任预检（[Issue #14](https://github.com/blockrunai/blockrun-mcp/issues/14)）、多链 x402 facilitator（[Issue #13](https://github.com/blockrunai/blockrun-mcp/issues/13)）、Security Advisory 入口（[Issue #11](https://github.com/blockrunai/blockrun-mcp/issues/11)） --- ## 系统架构、x402 支付与钱包管理 ### 相关页面 相关主题：[项目概览与安装指南](#page-1), [工具目录与数据源](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [package.json](https://github.com/blockrunai/blockrun-mcp/blob/main/package.json) - [README.md](https://github.com/blockrunai/blockrun-mcp/blob/main/README.md) - [src/index.ts](https://github.com/blockrunai/blockrun-mcp/blob/main/src/index.ts) - [src/tools/search.ts](https://github.com/blockrunai/blockrun-mcp/blob/main/src/tools/search.ts) - [src/utils/wallet.ts](https://github.com/blockrunai/blockrun-mcp/blob/main/src/utils/wallet.ts) - [src/utils/budget.ts](https://github.com/blockrunai/blockrun-mcp/blob/main/src/utils/budget.ts) - [src/utils/body.ts](https://github.com/blockrunai/blockrun-mcp/blob/main/src/utils/body.ts) - [src/utils/errors.ts](https://github.com/blockrunai/blockrun-mcp/blob/main/src/utils/errors.ts) - [src/types.ts](https://github.com/blockrunai/blockrun-mcp/blob/main/src/types.ts) - [skills/search/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/search/SKILL.md) - [skills/surf/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/surf/SKILL.md) - [skills/exa-research/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/exa-research/SKILL.md)
# 系统架构、x402 支付与钱包管理 ## 概述与项目定位 `blockrun-mcp` 是一个面向 AI Agent 的 MCP（Model Context Protocol）服务器，封装了 40+ 个外部 AI 模型与数据接口（如 Grok Live Search、Exa Research、Surf 等），通过 x402 微支付协议以"按次付费"方式让 Agent 无需 API Key 即可调用。资料来源：[package.json:1-9]()、[README.md:1-30]() 服务器版本号 `0.21.1`，MCP 注册名为 `io.github.BlockRunAI/blockrun-mcp`，以 ESM 模块格式分发，要求 Node `>=18`。资料来源：[package.json:3-3]()、[package.json:47-47]() ## 系统架构与模块划分 入口 `src/index.ts` 通过 `tsup` 构建为 `dist/index.js`，运行时由 `npm start` 加载并向已配置的 MCP 客户端注册工具。资料来源：[package.json:14-22]() 整个代码库呈"工具 + 通用工具层 + 类型"三层结构： | 层级 | 职责 | 代表文件 | |---|---|---| | 入口 | 注册 MCP server、加载工具集合 | `src/index.ts` | | 工具层 | 每个工具一个文件（`chat` / `search` / `exa` / `surf` / `image` / `speech` / `phone` / `wallet` 等） | `src/tools/search.ts` | | 通用工具 | 客户端获取、预算记账、请求体规整、错误格式化 | `src/utils/wallet.ts`、`src/utils/budget.ts`、`src/utils/body.ts`、`src/utils/errors.ts` | 工具层与通用工具层通过 ESM 导入解耦。以 `search.ts` 为例，它从 `../utils/wallet.js` 拉取客户端，从 `../utils/budget.js` 拉取预算与记账函数，从 `../utils/body.js` 拉取请求体规整函数，从 `../utils/errors.ts` 拉取错误格式化函数。资料来源：[src/tools/search.ts:1-12]() 类型集中在 `src/types.ts`，例如 `BudgetState` 被工具层直接引用以携带预算上下文。资料来源：[src/tools/search.ts:14-14]() ```mermaid flowchart LR A[MCP Client] --> B[blockrun-mcp Entry] B --> C[Tool Layer
chat / search / exa / surf ...] C --> D{checkBudget
预算检查} D -- 通过 --> E[getClient
获取钱包客户端] D -- 超限 --> Z[返回预算错误] E --> F[x402 Payment
USDC on Base] F --> G[Upstream API
Grok / Exa / Surf] G --> H[recordSpending
记账] H --> I[格式化结果返回] ``` ## x402 支付流程 BlockRun 的核心创新在于把"按次付费"下沉到协议层：每次工具调用先返回 HTTP 402，由 `@blockrun/llm` 客户端自动签名 USDC 支付并重试，整个过程对 Agent 调用方透明。资料来源：[README.md:18-30]()、`package.json` 中的依赖 `@blockrun/llm`、`viem`（[package.json:31-39]()） 从 `search.ts` 可以看到，工具对外暴露的是 `getWithPaymentRaw` / `requestWithPaymentRaw` 两个底层方法，路径或 body 由工具参数透传给上游；定价采用"按结果计费"：搜索单价 `$0.025 × max_results`，默认 `max_results=10`，封顶 50。资料来源：[src/tools/search.ts:18-25]() 定价策略还体现在 Surf 文档中：其 `chat/completions` 在 v1 阶段固定为 $0.02，按 token 计费将在 Phase 2 上线；不同端点的 cost 字段直接决定 USDC 支付金额。资料来源：[skills/surf/SKILL.md:18-30]() 社区方面，用户曾提议把 `MainStreet preflight` 这样的免费地址信任检查（返回 BLOCK/CAUTION/PROCEED + 0-100 评分）接入到模型路由前的预检环节，目的是在上游 `payTo` 钱包结算前过滤高风险收款方（Issue #14）；另有多链 x402 facilitator 提案（Issue #13，希望在 Base / Solana 之外接入 Algorand / Hedera / Stellar / VOI / Tempo），目前已撤回。这些讨论指向同一底层议题——支付通道的可信度与多链结算。 ## 钱包与预算管理 钱包由 `src/utils/wallet.ts` 中的 `getClient()` 统一获取，对外屏蔽 EOA 私钥、助记词、链选择等细节。从 `surf` 文档可知，BlockRun 钱包原生部署在 Base（默认），同时支持 Solana；Surf 自身的结算则统一落在其 Base 财库。资料来源：[src/utils/wallet.ts]()、`skills/surf/SKILL.md:26-30]() 预算由 `src/utils/budget.ts` 中的 `checkBudget()` 与 `recordSpending()` 共同维护： - `checkBudget`：每次工具调用前判定剩余预算是否覆盖本次预估花费。`search.ts` 中通过 `estimateSearchCost(body)` 按 `max_results` 估算金额。资料来源：[src/tools/search.ts:23-25]()、`src/utils/budget.ts]() - `recordSpending`：调用成功后按实际花费入账，配合 `BudgetState` 实现"父 Agent → 子 Agent"的分级预算委派（参见 README 中"3 个研究 Agent 各设 $0.50 上限"的示例）。资料来源：[README.md:10-15]() 错误处理由 `src/utils/errors.ts` 的 `formatError` / `extractErrorMessage` 统一收敛，再交给 MCP 客户端展示。资料来源：[src/tools/search.ts:11-11]() ## 安全与社区反馈 社区曾请求项目补一份 `SECURITY.md` 并开启 GitHub Security Advisory 以便私下提交漏洞（Issue #11）。当前代码库已经在工具层强制走预算闸门与统一错误出口，但缺少显式的密钥泄露扫描模块（README 与 Issue #11 均未确认 `SECURITY.md` 是否已落地）。 ## See Also - [README.md](https://github.com/blockrunai/blockrun-mcp/blob/main/README.md) - [skills/search/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/search/SKILL.md) - [skills/surf/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/surf/SKILL.md) - [skills/exa-research/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/exa-research/SKILL.md) - [package.json](https://github.com/blockrunai/blockrun-mcp/blob/main/package.json) --- ## 工具目录与数据源 ### 相关页面 相关主题：[系统架构、x402 支付与钱包管理](#page-2), [技能系统、扩展性、运维与故障排查](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [package.json](https://github.com/blockrunai/blockrun-mcp/blob/main/package.json) - [README.md](https://github.com/blockrunai/blockrun-mcp/blob/main/README.md) - [CONTRIBUTING.md](https://github.com/blockrunai/blockrun-mcp/blob/main/CONTRIBUTING.md) - [src/tools/search.ts](https://github.com/blockrunai/blockrun-mcp/blob/main/src/tools/search.ts) - [skills/search/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/search/SKILL.md) - [skills/exa-research/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/exa-research/SKILL.md) - [skills/surf/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/surf/SKILL.md) - [skills/image-prompting/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/image-prompting/SKILL.md)
# 工具目录与数据源 ## 概述 blockrun-mcp 是一个面向 AI 代理的 Model Context Protocol (MCP) 服务器，通过 x402 USDC 链上支付，将 41+ AI 模型、加密市场数据与语音/视频生成能力统一暴露为 LLM 可调用的工具集。仓库核心是约 870 行工具代码加 4 个技能文档（skill），`npm run build` 后的 stdio 握手应返回 15 个工具（含 `blockrun_surf` 及后续新增项） 资料来源：[CONTRIBUTING.md:5-25]()。 每个工具都遵循「按调用付费、无需 API Key」的原则：客户端使用本地或托管的 USDC 钱包（Base 或 Solana 链），由 `@blockrun/llm` SDK 自动完成 402 支付握手 资料来源：[package.json:43-52]()。本页聚焦该工具集的目录结构、所对接的上游数据源与模型清单。 ## 核心工具清单 下表汇总了当前工具集中具备明确实现或文档支持的主要入口。 | 工具名 | 主要能力 | 关键数据源 / 模型 | 引用 | |---|---|---|---| | `blockrun_chat` | 多模型对话补全 | 41+ LLM（OpenAI、Anthropic、xAI、Google、DeepSeek 等） | [README.md:60-80]() | | `blockrun_image` | 文/图生图、编辑、多参考合成 | `openai/gpt-image-2/1`、`dall-e-3`、`google/nano-banana(-pro)`、`black-forest/flux-1.1-pro`、`zai/cogview-4`、`xai/grok-imagine-image(-pro)` | [skills/image-prompting/SKILL.md:30-50]() | | `blockrun_speech` | TTS 语音合成 | 托管 `sarah` 等语音；附 `sound_effect` 动作 | [README.md:65-67]() | | `blockrun_phone` | 语音外呼 | 需先经 `phone/numbers/buy` 申请 `from` 号码 | [README.md:69-71]() | | `blockrun_surf` | 加密市场与链上 SQL（84 端点） | ClickHouse、Polymarket、Kalshi、社交榜单、链上转账 | [skills/surf/SKILL.md:1-60]() | | `blockrun_search` | Grok 实时网页/X/新闻搜索 | xAI Grok Live Search，`$0.025 × max_results` | [skills/search/SKILL.md:14-20]() | | `blockrun_exa` | 神经搜索 / 抓取 / 找相似 | Exa Search/Answer/Contents/Find-similar | [skills/exa-research/SKILL.md:12-20]() | | `blockrun_wallet` | 代理钱包与预算隔离 | x402 USDC on Base / Solana，via `viem` | [README.md:75-77]() | | `blockrun_video` / `blockrun_music` | 异步视频与音乐生成 | Seedance 等 v0.11.0+ 模型 | [README.md:1-20]() | 未在表中单独列出的 `blockrun_markets` 等其他工具可通过 `claude mcp add` 注册后由 `tools/list` 枚举 资料来源：[CONTRIBUTING.md:18-23]()。 ## 数据源与上游服务 工具目录之下是一组异构的上游服务，共同点是：所有调用都按 HTTP 402 协议在链上结算，定价透明、按次计费。 **搜索与研究**。`blockrun_search` 走 xAI Grok Live Search，按 `max_results`（1–50，默认 10）线性计费 资料来源：[src/tools/search.ts:14-22]()，并支持 `web`/`x`/`news` 三类源切换 资料来源：[skills/search/SKILL.md:14-20]()。`blockrun_exa` 走 Exa 的神经搜索，提供 `search`、`answer`、`contents`、`find-similar` 四种动作，按 `path` 参数路由 资料来源：[skills/exa-research/SKILL.md:12-20]()。语义层面，社区多次提及「实时性用 Grok、语义相关性用 Exa」的取舍 资料来源：[skills/exa-research/SKILL.md:1-10]()。 **加密市场**。`blockrun_surf` 是体量最大的数据源，按类别划分为 Token（4）、Wallet（6）、Web（1）、Chat（1）、Social、Prediction Market、Onchain SQL 等 84 个端点 资料来源：[skills/surf/SKILL.md:1-60]()。其中 `onchain/sql` 无服务端行数限制，调用方必须在 SQL 中自带 `LIMIT`，否则会拉取大体积 JSON 产生高额费用 资料来源：[skills/surf/SKILL.md:50-56]()。 **图像与媒体生成**。图像模型覆盖 OpenAI、Black Forest Labs、Google、ZhipuAI 与 xAI 的 9 个版本；GPT Image 2 仅支持 `1024x1024` / `1536x1024` / `1024x1536` 三种合法分辨率 资料来源：[skills/image-prompting/SKILL.md:30-50]()。视频与音乐走异步流程，自 v0.11.0（commit `70684e0d`）起支持 资料来源：[社区问题 #7]()。 **支付与结算**。所有工具共享一个钱包与预算层，使用 `viem` 构造 EIP-3009 签名、SDK `getWithPaymentRaw` 自动重试 402 流程 资料来源：[package.json:46-51]()、资料来源：[src/tools/search.ts:9-12]()。社区已有人提议引入 Algorand、Hedera、Stellar、VOI、Tempo 等多链 x402 facilitator（#13，目前已撤回），表明结算层未来可能扩展。 ## 工具与技能的设计边界 `CONTRIBUTING.md` 明确了「工具 vs 技能」的取舍 资料来源：[CONTRIBUTING.md:30-45]()：当 API 需要强类型参数校验、复杂客户端逻辑（异步轮询、多步支付、有状态重试）或属于 BlockRun 核心价值时，应实现为 MCP 工具（`src/tools/*.ts`）；当调用模式简单、属提示工程范畴时，落地为 `skills/*/SKILL.md` 文档。图像提示工程的 5 段式框架（SCENE / SUBJECT / DETAILS / USE CASE / CONSTRAINTS）即属后者 资料来源：[skills/image-prompting/SKILL.md:60-80]()。 这条边界同样影响 41+ LLM 路由：模型白名单与价格表由后端维护，前端只透传 `model` 字符串，避免在工具层重复实现枚举校验。 ## See Also - [MCP 服务器与 stdio 握手](../mcp-server.md) - [x402 支付与钱包层](../x402-payment.md) - [Surf 数据源详解](../surf-data.md) - [图片提示工程指南](../image-prompting.md) - 社区讨论：[#11 缺失 SECURITY.md](https://github.com/blockrunai/blockrun-mcp/issues/11)、[#14 路由前免费信任检查](https://github.com/blockrunai/blockrun-mcp/issues/14) --- ## 技能系统、扩展性、运维与故障排查 ### 相关页面 相关主题：[系统架构、x402 支付与钱包管理](#page-2), [工具目录与数据源](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [package.json](https://github.com/blockrunai/blockrun-mcp/blob/main/package.json) - [README.md](https://github.com/blockrunai/blockrun-mcp/blob/main/README.md) - [skills/search/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/search/SKILL.md) - [skills/exa-research/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/exa-research/SKILL.md) - [skills/surf/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/surf/SKILL.md) - [skills/image-prompting/SKILL.md](https://github.com/blockrunai/blockrun-mcp/blob/main/skills/image-prompting/SKILL.md) - [src/tools/search.ts](https://github.com/blockrunai/blockrun-mcp/blob/main/src/tools/search.ts)
# 技能系统、扩展性、运维与故障排查 ## 一、技能系统（Skill System）概述 `blockrun-mcp` 采用"技能包 + MCP 工具"的双层抽象。技能包是 `skills//SKILL.md` 一份 Markdown 文档，用来教会智能体**何时**调用哪个 MCP 工具、以何种 `body` 形态发请求。每个 `SKILL.md` 都以 YAML frontmatter 声明元数据，例如 `skills/search/SKILL.md` 在 `triggers` 中列出 `["live search","grok live","what just happened",...]`，告诉智能体在"实时新闻/刚发生了什么"场景下优先选择 `blockrun_search`，其定价为 `$0.025 × max_results`（资料来源：[skills/search/SKILL.md]()）。 MCP 工具的实际实现位于 `src/tools/*.ts`，例如 `src/tools/search.ts` 在调用前后分别执行预算检查与扣减（`checkBudget` / `recordSpending`），并以 `SEARCH_PRICE_PER_SOURCE = 0.025` 为基准预估费用。请求与错误经 `coerceBody` 与 `formatError` 统一包装后返回给客户端（资料来源：[src/tools/search.ts]()）。 技能包之间相互独立、可替换。`skills/surf/SKILL.md` 自带 84 个端点，覆盖交易、钱包、代币、社交、预测市场、Web 抓取、Chat 等多个类目，是一个面向加密数据的复合能力；而 `skills/exa-research/SKILL.md` 自 v0.14.1 起改为 path-based 设计，单一 `blockrun_exa` 工具即可承担搜索、问答、抓取、相似发现四种模式（资料来源：[skills/exa-research/SKILL.md]()）。 ## 二、扩展性：如何新增一个技能 ### 包与运行时依赖 扩展首先在 `package.json` 注册。包名为 `@blockrun/mcp`，`mcpName` 为 `io.github.BlockRunAI/blockrun-mcp`，对外暴露的可执行入口是 `dist/index.js`（通过 `bin.blockrun-mcp` 注册），主类型入口 `dist/index.d.ts`（资料来源：[package.json]()）。`dependencies` 中： - `@blockrun/llm`：提供钱包与 x402 付费客户端； - `viem`：处理链上交互； - `sharp`：图像处理； - `qrcode`：生成支付二维码； - `zod`：参数 schema 校验； - `@modelcontextprotocol/sdk`：MCP 服务端实现； - `@anthropic-ai/sdk`：Anthropic 兼容封装。 大多数技能开发不需要引入新依赖，主要工作是编写 `SKILL.md` 与对应的 `src/tools/*.ts`。 ### 构建与运行脚本 包内置了完整的本地开发回路：`npm run dev` 使用 `tsx watch` 热重载，`npm run build` 用 `tsup` 打包为 ESM 并生成 `.d.ts`，`npm run typecheck` 做静态校验，`prepublishOnly` 在发布前自动执行构建。Node 引擎要求 `>=18`（资料来源：[package.json]()）。 ### 技能模板 新增技能的标准流程是：在 `skills//SKILL.md` 编写 frontmatter（`name` / `description` / `triggers`）+ 正文（使用示例、参数表、注意事项）。`skills/image-prompting/SKILL.md` 给出了五段式提示框架（SCENE / SUBJECT / DETAILS / USE CASE / CONSTRAINTS），适合作为提示工程类技能的写作模板，并明确"视觉事实 > 赞美词"的反 slop 规则（资料来源：[skills/image-prompting/SKILL.md]()）。 ### 工具实现 若需要新增 MCP 工具，应在 `src/tools/` 下新建 TypeScript 文件，使用 `@modelcontextprotocol/sdk` 的 `McpServer` 注册，并在 `src/index.ts` 中挂载。Zod schema 用于参数校验（`zod@^4.3.5`），调用钱包层 `getClient()` 后通过 `getWithPaymentRaw` 或 `requestWithPaymentRaw` 触发 x402 付费流程（资料来源：[src/tools/search.ts]()）。 ## 三、运维要点 ### 部署形态 MCP 进程是一个标准的 Node 可执行文件，可通过 `npx -y @blockrun/mcp` 直接拉起。生产部署建议固定 Node 主版本，并监控 `BLOCKRUN_WALLET_KEY` 等环境变量（钱包密钥由 `@blockrun/llm` 在初始化时读取，缺失将直接导致所有工具报 402）（资料来源：[package.json]() / [src/tools/search.ts]()）。 ### 预算与计费 每个工具调用前都需 `checkBudget`，调用后通过 `recordSpending` 入账。这一机制使多智能体场景下父代理可以为子代理设置硬性 $0.50 上限（README 中的 "Multi-agent research with budget cap" 用例）（资料来源：[README.md]()）。 ### 资源消耗与按量计费陷阱 `skills/surf/SKILL.md` 提示 `onchain/sql` 端点在服务端不限制行数，调用方必须自行添加 `LIMIT` 子句以避免拉取大量 JSON。同样，`blockrun_search` 的 `max_results` 直接驱动价格（默认 10 → $0.25/次，最大 50 → $1.25/次）（资料来源：[skills/surf/SKILL.md]() / [skills/search/SKILL.md]()）。 ## 四、故障排查 | 现象 | 常见原因 | 参考处置 | |---|---|---| | 工具返回 402 | x402 付费挑战未自动签名 | 检查 `BLOCKRUN_WALLET_KEY` 是否配置、`getClient()` 是否成功初始化（资料来源：[src/tools/search.ts]()） | | 工具返回 400 且未扣费 | 必填参数缺失 | `skills/surf/SKILL.md` 中 84 个端点有 56 个要求至少一个参数，错误体中会列出缺失字段（资料来源：[skills/surf/SKILL.md]()） | | 图像提示反复漂移 | 多轮编辑未保留 PRESERVE 列表 | 按 `skills/image-prompting/SKILL.md` 的 Change / Preserve / Constraints 模式，每轮重复 PRESERVE 列表（资料来源：[skills/image-prompting/SKILL.md]()） | | 搜索返回 0 条 | 日期窗口过窄 | `blockrun_search` 的日期过滤是严格的，窗口外的结果被丢弃而非降权；考虑放宽或去掉 `from_date` / `to_date`（资料来源：[skills/search/SKILL.md]()） | | 多链支付失败 | 部分链尚未启用 | Issue #13 提议在 Base / Solana 之外扩展 Algorand、Hedera、Stellar、VOI、Tempo 的 x402 facilitator，目前需等待官方支持（资料来源：[README.md]()） | | 想要先校验收款方 | 信任缺失 | Issue #14 提议在路由前调用免费的 `MainStreet preflight` 获得 BLOCK/CAUTION/PROCEED + 0-100 分（资料来源：[README.md]()） | | 漏洞需要私密上报 | 缺少披露渠道 | Issue #11 反馈项目尚未提供 `SECURITY.md` 与 GitHub Security Advisory，建议先在 issue 中联系维护者再决定是否公开 PoC（资料来源：[README.md]()） | ### 安全与可观测建议 - 在 MCP 客户端侧记录每个工具的 `spend`，避免 `@blockrun/llm` 内部预算超限时才被发现。 - 对高频调用的 `blockrun_surf` / `blockrun_exa`，在调用方做结果缓存可显著降低单任务成本。 - 注意 `skills/surf/SKILL.md` 提到 `chat/completions` 临时为平价 $0.02（Phase 2 将切换为按 token 计费），上线时需重新估算成本（资料来源：[skills/surf/SKILL.md]()）。 --- ## See Also - [README.md](https://github.com/blockrunai/blockrun-mcp/blob/main/README.md) — 项目总览与多智能体/语音通话等高级用例 - [package.json](https://github.com/blockrunai/blockrun-mcp/blob/main/package.json) — 版本、依赖与构建脚本 - [skills/](https://github.com/blockrunai/blockrun-mcp/tree/main/skills) — 各能力技能包目录 - [src/tools/](https://github.com/blockrunai/blockrun-mcp/tree/main/src/tools) — MCP 工具实现源码 --- --- ## Doramagic 踩坑日志 项目：blockrunai/blockrun-mcp 摘要：发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 需要 API Key 或环境变量。 ## 1. 配置坑 · 需要 API Key 或环境变量 - 严重度：high - 证据强度：source_linked - 发现：项目说明中出现 API Key / 环境变量相关需求。 - 对用户的影响：用户必须准备账号、额度或密钥；密钥配置错误会导致运行失败或泄漏风险。 - 建议检查：提取必需 env 列表，确认是否有最小无密钥试用路径。 - 防护动作：页面必须前置密钥/账号依赖，不能把需要密钥的项目包装成零配置。 - 证据：packet_text.keyword_scan | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | matched api key / env var keyword ## 2. 身份坑 · 仓库名和安装名不一致 - 严重度：medium - 证据强度：runtime_trace - 发现：仓库名 `blockrun-mcp` 与安装入口 `@blockrun/mcp` 不完全一致。 - 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 - 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。 - 复现命令：`npm install @blockrun/mcp` - 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。 - 证据：identity.distribution | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | repo=blockrun-mcp; install=@blockrun/mcp ## 3. 安装坑 · 来源证据：Paid ad slot on aibtc.news? - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Paid ad slot on aibtc.news? - 对用户的影响：可能增加新用户试用和生产接入成本。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_810c75b756b9409aae5b8ed474881a07 | https://github.com/BlockRunAI/blockrun-mcp/issues/9 | 来源类型 github_issue 暴露的待验证使用条件。 ## 4. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。 - 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。 - 证据：capability.host_targets | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | host_targets=mcp_host, claude, claude_code, cursor, chatgpt ## 5. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | README/documentation is current enough for a first validation pass. ## 6. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | last_activity_observed missing ## 7. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | no_demo; severity=medium ## 8. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | no_demo; severity=medium ## 9. 安全/权限坑 · 来源证据：aibtc.news classifieds — BlockRun.ai listing, callable agent infra (3,000 sats / 7 days) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：aibtc.news classifieds — BlockRun.ai listing, callable agent infra (3,000 sats / 7 days) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_c46a356b18224401b889a0208002efac | https://github.com/BlockRunAI/blockrun-mcp/issues/7 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。 ## 10. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | issue_or_pr_quality=unknown ## 11. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | art_e028765b20a84b04af53db21f9414116 | https://github.com/punkpeye/awesome-mcp-servers#readme | release_recency=unknown