{"_id":"@0xtresser/mcpx","_rev":"3-f4e90d31fc4203eac025875aa5e7c78f","name":"@0xtresser/mcpx","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@0xtresser/mcpx","version":"0.1.0","keywords":["mcp","x402","payments","tooling","model-context-protocol"],"author":{"name":"0xtresser"},"license":"MIT","_id":"@0xtresser/mcpx@0.1.0","maintainers":[{"name":"0xtresser","email":"treaserlou@gmail.com"}],"homepage":"https://github.com/0xtresser/mcpx#readme","bugs":{"url":"https://github.com/0xtresser/mcpx/issues"},"dist":{"shasum":"04952da18fb2ef6c37b35ce3aee6aa650a632214","tarball":"https://registry.npmjs.org/@0xtresser/mcpx/-/mcpx-0.1.0.tgz","fileCount":33,"integrity":"sha512-975QMDMitVWzm7I/exgD159SUHUa5BBp8WYX+ub4hJC43fMdB7jVREK9Mm1a3s4l4H+DWZqaQEQU+1HN6ioqdA==","signatures":[{"sig":"MEUCIQCjkGseJ0YM2XHKMBWmTCkYTM3cEBKLRWiicE9p981ZLQIgCqZAH5vwqXrE1qNXzYC1X1MmkbFj0GlGIeDH4td2xlg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":72656},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./client":{"types":"./dist/client/index.d.ts","import":"./dist/client/index.js"},"./server":{"types":"./dist/server/index.d.ts","import":"./dist/server/index.js"}},"gitHead":"f62aa357b6287c1de8b852fdb953d8eef4f19106","scripts":{"lint":"eslint .","test":"vitest run","build":"npm run clean && tsc -p tsconfig.json","check":"npm run lint && npm run test && npm run build","clean":"rimraf dist tsconfig.tsbuildinfo","format":"prettier \"**/*.{ts,js,json,md}\" --write","prepare":"npm run build","lint:fix":"eslint . --fix","test:watch":"vitest","format:check":"prettier \"**/*.{ts,js,json,md}\" --check"},"_npmUser":{"name":"0xtresser","email":"treaserlou@gmail.com"},"repository":{"url":"git+https://github.com/0xtresser/mcpx.git","type":"git"},"_npmVersion":"10.8.1","description":"MCP framework with built-in X402 payment support","directories":{},"sideEffects":false,"_nodeVersion":"18.17.0","dependencies":{"zod":"^3.23.8","viem":"^2.21.26","x402":"^0.7.2","x402-fetch":"^0.7.0","@solana/kit":"^2.1.1","x402-express":"^0.7.1","@modelcontextprotocol/sdk":"^1.9.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.14.0","rimraf":"^5.0.7","vitest":"^2.1.4","prettier":"^3.3.3","@eslint/js":"^9.14.0","typescript":"^5.6.3","@types/node":"^22.9.3","@types/express":"^4.17.21","typescript-eslint":"^8.8.1"},"peerDependencies":{"express":"^4.18.2 || ^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcpx_0.1.0_1764053101162_0.007530312851271148","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@0xtresser/mcpx","version":"0.1.1","keywords":["mcp","x402","payments","tooling","model-context-protocol"],"author":{"name":"0xtresser"},"license":"MIT","_id":"@0xtresser/mcpx@0.1.1","maintainers":[{"name":"0xtresser","email":"treaserlou@gmail.com"}],"homepage":"https://github.com/0xtresser/mcpx#readme","bugs":{"url":"https://github.com/0xtresser/mcpx/issues"},"dist":{"shasum":"8dc33ac0b2bb697d9b828ea18b6117cf1ee9a53b","tarball":"https://registry.npmjs.org/@0xtresser/mcpx/-/mcpx-0.1.1.tgz","fileCount":34,"integrity":"sha512-pc+XlLiZ2riiMov2qb2mejqMVrJMcYO04Nf52zN92z1yxTVdaEde9sy5t6US85LcQo/68ojdZbWNFSSefMY/RQ==","signatures":[{"sig":"MEUCIQCixOWQ2hpVyL7wqbxnG/t0ohg/y64R+6JX10MC7JF6QQIgeEhRXdWoVoSg0V0KVLAyx8jkU0Jqypxpd1plLdRDnLM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":76507},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./client":{"types":"./dist/client/index.d.ts","import":"./dist/client/index.js"},"./server":{"types":"./dist/server/index.d.ts","import":"./dist/server/index.js"}},"gitHead":"f62aa357b6287c1de8b852fdb953d8eef4f19106","scripts":{"lint":"eslint .","test":"vitest run","build":"npm run clean && tsc -p tsconfig.json","check":"npm run lint && npm run test && npm run build","clean":"rimraf dist tsconfig.tsbuildinfo","format":"prettier \"**/*.{ts,js,json,md}\" --write","prepare":"npm run build","lint:fix":"eslint . --fix","test:watch":"vitest","format:check":"prettier \"**/*.{ts,js,json,md}\" --check"},"_npmUser":{"name":"0xtresser","email":"treaserlou@gmail.com"},"repository":{"url":"git+https://github.com/0xtresser/mcpx.git","type":"git"},"_npmVersion":"10.8.1","description":"MCP framework with built-in X402 payment support","directories":{},"sideEffects":false,"_nodeVersion":"18.17.0","dependencies":{"zod":"^3.23.8","viem":"^2.21.26","x402":"^0.7.2","x402-fetch":"^0.7.0","@solana/kit":"^2.1.1","x402-express":"^0.7.1","@modelcontextprotocol/sdk":"^1.9.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.14.0","rimraf":"^5.0.7","vitest":"^2.1.4","prettier":"^3.3.3","@eslint/js":"^9.14.0","typescript":"^5.6.3","@types/node":"^22.9.3","@types/express":"^4.17.21","typescript-eslint":"^8.8.1"},"peerDependencies":{"express":"^4.18.2 || ^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcpx_0.1.1_1764053299695_0.6672404767941591","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@0xtresser/mcpx","version":"0.1.2","description":"MCP framework with built-in X402 payment support","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./server":{"types":"./dist/server/index.d.ts","import":"./dist/server/index.js"},"./client":{"types":"./dist/client/index.d.ts","import":"./dist/client/index.js"}},"sideEffects":false,"engines":{"node":">=18"},"scripts":{"clean":"rimraf dist tsconfig.tsbuildinfo","build":"npm run clean && tsc -p tsconfig.json","lint":"eslint .","lint:fix":"eslint . --fix","format":"prettier \"**/*.{ts,js,json,md}\" --write","format:check":"prettier \"**/*.{ts,js,json,md}\" --check","test":"vitest run","test:watch":"vitest","check":"npm run lint && npm run test && npm run build","prepare":"npm run build"},"keywords":["mcp","x402","payments","tooling","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/0xtresser/mcpx.git"},"bugs":{"url":"https://github.com/0xtresser/mcpx/issues"},"homepage":"https://github.com/0xtresser/mcpx#readme","author":{"name":"0xtresser"},"license":"MIT","publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.9.0","@solana/kit":"^2.1.1","viem":"^2.21.26","x402":"^0.7.2","x402-express":"^0.7.1","x402-fetch":"^0.7.0","zod":"^3.23.8"},"peerDependencies":{"express":"^4.18.2 || ^5.0.0"},"devDependencies":{"@types/express":"^4.17.21","@types/node":"^22.9.3","@eslint/js":"^9.14.0","eslint":"^9.14.0","prettier":"^3.3.3","rimraf":"^5.0.7","typescript":"^5.6.3","typescript-eslint":"^8.8.1","vitest":"^2.1.4"},"_id":"@0xtresser/mcpx@0.1.2","gitHead":"699cda9d6a2a96f9340f0f9e1b24ed63a3db4e72","_nodeVersion":"18.17.0","_npmVersion":"10.8.1","dist":{"integrity":"sha512-qaGg6c8B23VlBwdXL/3t0WtGOrk2oR9p8kVwMDJCgc1dc6DKu4Axzyc8WgGmm8tligirFRJEwFGde4Q70ERwAg==","shasum":"82d593307d93a446b4ec0f25f8edc4cb3e752aad","tarball":"https://registry.npmjs.org/@0xtresser/mcpx/-/mcpx-0.1.2.tgz","fileCount":34,"unpackedSize":74237,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDCVmRYNk0KFUjrrtvnmMILwL4yIqv5E3vNStWjXSCVZwIhAI5cjDbZaXRCua0WhXABF0cPCgFZ0qUdqNIBelc0NfJi"}]},"_npmUser":{"name":"0xtresser","email":"treaserlou@gmail.com"},"directories":{},"maintainers":[{"name":"0xtresser","email":"treaserlou@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcpx_0.1.2_1764062037872_0.18709682855829035"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-25T06:45:01.062Z","modified":"2025-11-25T09:13:58.283Z","0.1.0":"2025-11-25T06:45:01.378Z","0.1.1":"2025-11-25T06:48:19.881Z","0.1.2":"2025-11-25T09:13:58.068Z"},"bugs":{"url":"https://github.com/0xtresser/mcpx/issues"},"author":{"name":"0xtresser"},"license":"MIT","homepage":"https://github.com/0xtresser/mcpx#readme","keywords":["mcp","x402","payments","tooling","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/0xtresser/mcpx.git"},"description":"MCP framework with built-in X402 payment support","maintainers":[{"name":"0xtresser","email":"treaserlou@gmail.com"}],"readme":"# @0xtresser/mcpx\n\n> Model Context Protocol server toolkit with first-class x402 payments\n\n[![npm version](https://img.shields.io/npm/v/%400xtresser%2Fmcpx.svg?color=blue)](https://www.npmjs.com/package/@0xtresser/mcpx) [![CI](https://github.com/0xtresser/mcpx/actions/workflows/ci.yml/badge.svg)](https://github.com/0xtresser/mcpx/actions/workflows/ci.yml)\n\n## Highlights\n\n- ⚡ Drop-in Model Context Protocol server helpers with HTTP streaming transport.\n- 💰 First-class [x402](https://github.com/coinbase/x402) payment middleware for both static and dynamic pricing.\n- 🛠️ Works with any Express-compatible server and exposes a batteries-included MCP client fetch wrapper.\n- ✅ TypeScript-first API surface, strict types, shipped declarations.\n- 🧪 Tested with Vitest, linted with ESLint + Prettier.\n\n## Installation\n\n```bash\nnpm install @0xtresser/mcpx express\n```\n\nThe package ships pure ESM. Ensure your runtime targets Node.js 18+ (or Bun 1.1+).\n\n## Quick Start\n\n### Server\n\n```ts\nimport express from 'express';\nimport { McpXServer, createMcpRequestHandler, createX402Middleware } from '@0xtresser/mcpx';\n\nconst server = new McpXServer({\n  name: 'demo-server',\n  version: '1.0.0',\n  defaultPayTo: '0xYourAddress',\n});\n\nserver.registerTool(\n  'hello_world',\n  { description: 'Greets back' },\n  { price: '$0.001', network: 'base' },\n  async () => ({ content: [{ type: 'text', text: 'Hello from MCP!' }] }),\n);\n\nconst app = express();\napp.use(express.json());\napp.post(\n  '/mcp',\n  createX402Middleware(server),\n  createMcpRequestHandler(() => server),\n);\n\napp.listen(3000, () => console.log('Server ready on http://localhost:3000/mcp'));\n```\n\n### Client Fetch Helper\n\n```ts\nimport { createX402Fetch } from '@0xtresser/mcpx';\n\nconst fetchWithPayments = await createX402Fetch({\n  signer: {\n    evm: {\n      privateKey: process.env.X402_EVM_PRIVATE_KEY!,\n      network: 'base-sepolia',\n    },\n  },\n  onSettlement(info) {\n    console.log('Settlement result:', info.decoded);\n  },\n});\n```\n\n## Payment Modes\n\n| Mode | Flow | When to use |\n| --- | --- | --- |\n| `payBeforeService` | verify ➜ settle ➜ tool executes | Expensive / irreversible workloads |\n| `payThenService` (default) | verify ➜ tool executes ➜ settle | Low-latency flows |\n\n⚠️ **Important**: When using **payThenService**, you must plan for partial failures: verification may succeed while settlement fails (network congestion, balance changes, etc.). Record the tool request ID and replay settlement (or roll back side effects) to keep accounting consistent.\n\n## Scripts\n\n| Command | Description |\n| --- | --- |\n| `npm run lint` | ESLint with TypeScript support |\n| `npm run test` | Vitest unit tests |\n| `npm run build` | Emits ESM output to `dist` |\n| `npm run check` | lint + test + build |\n\n## Examples\n\nThe repository ships ready-to-run samples inside `examples/`:\n\n- `basic-server` – MCP server with free and paid tools (both payment modes)\n- `basic-client` – MCP client with automatic payment handling\n\nEach example README explains prerequisites, commands, and troubleshooting tips.\n\n## FAQ\n\n**Q: Does the middleware handle caching payment config per session?**  \nA: Yes. It stores resolved tool payment requirements per MCP session ID/body payload for 60 seconds to avoid recomputation.\n\n**Q: How do I customize the paywall UI?**  \nA: Pass `customPaywallHtml` through the tool config or provide `options.paywall` when wiring `createX402Middleware`.\n\n**Q: How do I test settlement errors?**  \nA: Mock the facilitator using `useFacilitator` test doubles or inject a fake resolver into `createX402Middleware`.\n\n## Roadmap / TODO\n\n- Multiple facilitator fallbacks per tool.\n- Built-in retry queue for failed settlements.\n- CLI to scaffold new MCP servers.\n\nTrack progress on GitHub Projects or open an issue with suggestions.\n\n## License\n\nMIT © 0xtresser\n","readmeFilename":"README.md"}