模型上下文协议服务器工具包

一个提供模型上下文协议服务器助手和x402支付中间件的工具包,适用于需要支付集成的开发场景。

  • by 0xtresser
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 0xtresser/mcpx

使用说明

@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