内容
# Recapfy MCP
一个 [MCP](https://modelcontextprotocol.io) 服务器，暴露 Recapfy 的付费 `ask` 端点作为工具。从支持 MCP 的代理（如 Claude Desktop、Cursor、Cline 等）直接询问关于 YouTube 视频的任何问题（或获取摘要）。
每次调用费用为 **0.01 USDC on Solana**，通过 [x402](https://x402.org) 协议自动支付。
## 为什么使用本地 MCP 服务器（以及为什么使用您自己的钱包）
“MCP 服务器”是一种协议角色，而不是托管服务。这是一个 **本地 stdio 服务器**：每个用户运行自己的副本，并使用自己的 **Solana 钱包** 进行配置，因此每个调用者都使用自己的资金支付。这是唯一一种适用于每个代理支付的方式——单个共享托管服务器无法容纳每个人的钱包。它发布到 npm，因此代理主机可以一步添加它，并隐藏整个 x402 调用过程（402 → 签名 → 重试）。
## 工具
### `ask`
| 输入参数 | 类型 | 必需 | 描述 |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------ |
| `videoUrl` | 字符串 | 是 | YouTube 视频的绝对 http(s) URL。 |
| `prompt` | 字符串 | 是 | 提问内容（问题或“总结”）。 |
| `maxOutputTokens` | 整数 | 否 | 答案的最大令牌数（默认为 1024）。**决定动态价格。** |
以文本形式返回代理的答案。在返回答案之前，支付会自动结算。
> 每次调用的价格是 **动态的**：API 根据 `maxOutputTokens` 在 402 挑战中引用 USDC 金额。配置的钱包支付引用的金额，因此请保持 `maxOutputTokens` 在合理范围内。
## 配置
通过环境变量设置（参见 [`.env.example`](./.env.example)）：
| 变量 | 必需 | 描述 |
| ---------------------------- | -------- | --------------------------------------------------------------------------- |
| `RECAPFY_API_BASE_URL` | 是 | Recapfy API 的基本 URL，没有尾部斜杠。 |
| `SVM_PRIVATE_KEY` | 是 | Base58 编码的 Solana **私钥**。每调用一次支付 0.01 USDC。保持资金充足。 |
| `RECAPFY_ALLOW_INSECURE_TLS` | 否 | 设置为 `1` 以接受自签名 TLS（仅本地开发环境使用 https）。 |
## 安装和构建
```bash
npm install
npm run build
```
## 与 Claude Desktop 配合使用
添加到您的 MCP 配置（`claude_desktop_config.json`）：
```jsonc
{
"mcpServers": {
"recapfy": {
"command": "node",
"args": ["C:/Developer/Repositories/Recapfy/recapfy.mcp/dist/index.js"],
"env": {
"RECAPFY_API_BASE_URL": "https://api.recapfy.ai",
"SVM_PRIVATE_KEY": "<您的 Base58 Solana 私钥>"
}
}
}
}
```
发布到 npm 后，此命令变为 `"command": "npx", "args": ["-y", "recapfy-mcp"]`。
## 支付方式
基于官方 Coinbase x402 **v2** 客户端包（`@x402/fetch`、`@x402/svm`、`@x402/core`）和 `@solana/kit` 进行签名。部署的 API 是一个合适的 x402 v2 服务器，因此现成的客户端在连接方面兼容 — 已针对实时端点和 `.well-known/x402` 清单进行确认：
1. 工具向 `${RECAPFY_API_BASE_URL}/api/v1/agents/ask` 发送 POST 请求。
2. API 以 **`PAYMENT-REQUIRED`** 头部回复 `402`，其中包含要求（确切的 SVM 方案、USDC、动态 `amount` 和促进者 `feePayer` 赞助网络费用）。
3. 封装的 fetch 请求使用您的钱包构建并签名一个无 Gas SPL 代币转账，并使用 **`PAYMENT-SIGNATURE`** 头部重试（x402 v2）。
4. API 验证、结算并返回答案以及 **`PAYMENT-RESPONSE`** 结算头部。
已针对实时 API (`api.recapfy.ai`) 进行验证：
- `x402Version: 2`，网络 `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`（主网），资产 USDC，金额 `dynamic`（根据 `maxOutputTokens` 从请求中引用）。
- 字段名为 `amount` — 适用于 x402 **v2**（v1 使用 `maxAmountRequired`）；`@x402/core` 解析两者，按 `x402Version` 键控。
## 状态
- ✅ MCP 服务器通过 stdio 启动并宣传 `ask` 工具（带有 `maxOutputTokens`）。
- ✅ 线上格式已验证与实时 x402 v2 端点兼容。
- ⏳ 真正的*付费*调用仍然需要一个有资金的主网 USDC 钱包；尚未在此处完整测试。
