使用说明
@0xtresser/mcpx
具有一流x402支付的模型上下文协议服务器工具包
亮点
- ⚡ 使用HTTP流传输的插入式模型上下文协议服务器帮助程序。
- 💰 头等舱 x402 用于静态和动态定价的支付中间件。
- 🛠️ 可与任何Express兼容的服务器配合使用,并公开包含电池的MCP客户端获取包装。
- ✅ TypeScript-first API表面,严格类型,附带声明。
- 🧪 用Vitest测试,用ESLint+Prettier测试。
安装
npm install @0xtresser/mcpx express
该包裹运送纯ESM。确保你的运行时目标是Node.js 18+(或Bun 1.1+)。
快速开始
服务器
import express from 'express';
import { McpXServer, createMcpRequestHandler, createX402Middleware } from '@0xtresser/mcpx';
const server = new McpXServer({
name: 'demo-server',
version: '1.0.0',
defaultPayTo: '0xYourAddress',
});
server.registerTool(
'hello_world',
{ description: 'Greets back' },
{ price: '$0.001', network: 'base' },
async () => ({ content: [{ type: 'text', text: 'Hello from MCP!' }] }),
);
const app = express();
app.use(express.json());
app.post(
'/mcp',
createX402Middleware(server),
createMcpRequestHandler(() => server),
);
app.listen(3000, () => console.log('Server ready on http://localhost:3000/mcp'));
客户端获取助手
import { createX402Fetch } from '@0xtresser/mcpx';
const fetchWithPayments = await createX402Fetch({
signer: {
evm: {
privateKey: process.env.X402_EVM_PRIVATE_KEY!,
network: 'base-sepolia',
},
},
onSettlement(info) {
console.log('Settlement result:', info.decoded);
},
});
支付方式
| 模式 | 流量 | 何时使用 |
|---|---|---|
payBeforeService |
验证➜ 解决➜ 工具执行 | 昂贵/不可逆的工作负载 |
payThenService (默认) |
验证➜ 工具执行➜ 结算 | 低延迟流 |
⚠️ 重要:使用时 payThenService,您必须为部分失败做好计划:验证可能会成功,而结算失败(网络拥塞、余额变化等)。记录工具请求ID并回放结算(或回滚副作用),以保持会计一致。
脚本
| 命令 | 描述 |
|---|---|
npm run lint |
支持TypeScript的ESLint |
npm run test |
Vitest单元测试 |
npm run build |
向发射ESM输出 dist |
npm run check |
lint+测试+构建 |
示例
存储库中附带了可运行的样本 examples/:
basic-server–MCP服务器,提供免费和付费工具(两种支付模式)basic-client–具有自动支付处理功能的MCP客户端
每个示例README都解释了先决条件、命令和故障排除提示。
常见问题解答
Q: 中间件是否处理每个会话的缓存支付配置?
A: 是的。它将每个MCP会话ID/主体有效载荷的已解决工具付款要求存储60秒,以避免重新计算。
Q: 如何自定义付费墙UI?
A: 通行证 customPaywallHtml 通过工具配置或提供 options.paywall 接线时 createX402Middleware.
Q: 如何测试结算错误?
A: 使用以下方式模拟主持人 useFacilitator 测试加倍或注入假解析器 createX402Middleware.
路线图/TODO
- 每个工具有多个引导者回退。
- 内置重试队列,用于失败的结算。
- CLI用于构建新的MCP服务器。
跟踪GitHub项目的进度或提出建议。
许可证
麻省理工学院© 0xtresser
