recapfy

Recapfy MCP

一个 MCP 服务，将 Recapfy 的付费端点作为工具提供，可直接通过支持 MCP 的 Agent（如 Claude Desktop、Cursor 或 Cline）询问任何与 YouTube 视频相关的问题，并获取视频的完整文字稿。 它在本地运行——没有托管的 Recapfy MCP 端点；你需要启动自己的副本。

每次调用都需使用 Solana 上的 USDC 付费（价格动态变化，并随 maxOutputTokens 调整），通过 x402 协议自动结算。你需要自备钱包；只为调用的内容付费。

📦 npm：recapfy-mcp

前置条件

• Node.js ≥ 20。
• 一个**在主网上有 USDC 余额的 Solana 钱包。**你不需要 SOL 来支付手续费 ——API 的结算方会代付网络手续费。
• 该钱包的Base58 编码私钥（即 Phantom 的“Export Private Key”导出的 64 字节格式，或通过 solana-keygen 获取）。

⚠️ 该密钥会签署真实付款。请使用余额较低的专用钱包，绝不要分享密钥， 也绝不要将其提交到代码库。

安装

无需克隆或构建。将以下内容添加到 MCP 客户端配置中（Claude Desktop： claude_desktop_config.json），然后重启客户端：

{
  "mcpServers": {
    "recapfy": {
      "command": "npx",
      "args": ["-y", "recapfy-mcp@latest"],
      "env": {
        "SVM_PRIVATE_KEY": "<your base58 Solana secret key>"
      }
    }
  }
}

**始终使用 recapfy-mcp@latest。**直接运行 npx -y recapfy-mcp 会重复使用 npx 缓存中的内容，且不会重新检查注册表，因此可能会一直停留在旧版本（并错过新工具）。 @latest 标签会强制 npx 在每次启动时解析最新发布的版本。

更新

新版本（包括新工具/端点）会在以下两件事都发生后自动启用，因为这里有两个相互独立的缓存：

1. npx 软件包缓存——使用 recapfy-mcp@latest（如上所述）会让 npx 在每次启动时获取 最新发布的版本。不使用 @latest 时，npx 会提供缓存副本，你会一直停留在旧版本。
2. MCP 客户端工具列表——客户端每个会话只读取一次服务端的工具列表。只有在你完全重启 MCP 客户端 （Claude Desktop、Cursor、Cline 等）后，新工具才会出现；重启会重新启动服务端并重新读取工具列表。

因此，发布新版本后：保留 @latest 并重启客户端。如果仍然看不到全新的 工具，请强制清除缓存并重新获取：

npx clear-npx-cache    # or: rm -rf "$(npm config get cache)/_npx"

然后再次重启客户端。

配置

变量	必填	说明
SVM_PRIVATE_KEY	是	Base58 编码的 Solana 私钥。用于支付每次调用的费用。请确保余额充足。
RECAPFY_API_BASE_URL	否	覆盖 API 基础 URL（默认为 https://api.recapfy.ai）。用于本地开发。
RECAPFY_ALLOW_INSECURE_TLS	否	设置为 1 以接受自签名 TLS（仅用于通过 https 进行本地开发）。

工具：ask

输入	类型	必填	说明
videoUrl	string	是	YouTube 视频的绝对 http(s) URL。
prompt	string	是	关于视频的问题。
maxOutputTokens	integer	否	答案中的最大 token 数（默认为 1024）。决定动态价格。

返回 Agent 的文本回答。付款会在返回答案前结算。 每次调用的价格动态变化：API 会根据 maxOutputTokens 在 402 质询中报价 USDC 金额，你的钱包会支付报价金额——因此请合理设置 maxOutputTokens。

工具：get_transcript

输入	类型	必填	描述
videoUrl	string	是	YouTube 视频的绝对 http(s) URL。

返回视频的完整转录文本，按带时间戳的片段呈现，并附带其 title、 channelName 和 durationSeconds。文本内容是易读的带时间戳转录文本；结构化内容包含原始 transcript 数组（每个 片段都是 { timestampInSeconds, text }）。每次调用按固定金额收取 USDC，具体金额会在 402 挑战中列出，并自动支付。

付款方式

基于 Coinbase 官方 x402 v2 客户端包（@x402/fetch、 @x402/svm、@x402/core），并使用 @solana/kit 进行签名：

1. 工具向 ${RECAPFY_API_BASE_URL} 下对应的端点发送 POST 请求 （/api/v1/agents/ask 或 /api/v1/agents/get-transcript）。
2. API 返回 402，并在 PAYMENT-REQUIRED 标头中提供要求 （exact SVM 方案、USDC、动态金额，以及为网络费用提供支持的中介 feePayer）。
3. 封装的 fetch 使用你的钱包签署免 gas 的 SPL 代币转账，并通过 PAYMENT-SIGNATURE 标头重试。
4. API 验证并结算付款，然后返回答案及 PAYMENT-RESPONSE 结算标头。

验证是否正常工作

使用 MCP Inspector 检查工具，不会产生任何费用（只有在实际调用工具时才会签署付款，因此浏览工具时使用任意密钥即可）：

SVM_PRIVATE_KEY=<key> npx @modelcontextprotocol/inspector npx -y recapfy-mcp@latest

打开打印出的 URL → Tools → ask / get_transcript。使用已充值的钱包调用工具会产生真实付费请求；请在 Solana 区块浏览器上核实支出。

故障排除

现象	原因 / 解决方法
Missing required environment variable ...	未设置 SVM_PRIVATE_KEY。
SVM_PRIVATE_KEY is not valid base58	需要 64 字节密钥的 base58 编码。
400 ... maxOutputTokens must be greater than 0	请传入正数 maxOutputTokens（工具默认值为 1024）。
400 ... prompt	必须提供非空的 prompt。
更新后缺少新工具/端点	固定使用 recapfy-mcp@latest，重启客户端，然后清除 npx 缓存（参见更新）。
402 循环 / "Failed to create payment payload"	钱包在主网上没有 USDC，或网络不正确。请为钱包充值。
通过 https 访问本地 API 时出现 TLS 错误	设置 RECAPFY_ALLOW_INSECURE_TLS=1（仅限 localhost 开发环境）。

许可证

MIT