{"_id":"@agentwares/mcp-kit","_rev":"2-547fbef1b439e7bbf54ec4555bac430b","name":"@agentwares/mcp-kit","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@agentwares/mcp-kit","version":"0.1.0","keywords":["mcp","model-context-protocol","mcp-server","streamable-http","stdio","ai-agents","tools","zod","llms-txt","x402"],"license":"MIT","_id":"@agentwares/mcp-kit@0.1.0","maintainers":[{"name":"umerbukhari","email":"umer.bukhari@gmail.com"}],"homepage":"https://github.com/agentwares/libs/tree/main/packages/mcp-kit#readme","bugs":{"url":"https://github.com/agentwares/libs/issues"},"dist":{"shasum":"8d3809f37761dcbaf221a3ed0668147fbc23da91","tarball":"https://registry.npmjs.org/@agentwares/mcp-kit/-/mcp-kit-0.1.0.tgz","fileCount":11,"integrity":"sha512-/rtGXOcyxXSzYbRQlD3HLKvZSkYKe9JH/QoNfJJq2bLmOCQfuHYo4t1f2A2N5B0bay+xeDE234OBvpcjP4u4BA==","signatures":[{"sig":"MEUCIAFbBdDV4Csl3Z32VTrbab9ND1GZh/KDUtfHru/C1uNZAiEA0/mBqiggsH9ExGMgb9dysN/xkudRYZETCq2srVLtYTI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":190692},"main":"./dist/index.js","type":"module","_from":"file:agentwares-mcp-kit-0.1.0.tgz","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"lint":"eslint src","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","conformance":"node scripts/conformance.mjs","example:http":"pnpm build && node dist/example-http.js"},"_npmUser":{"name":"umerbukhari","email":"umer.bukhari@gmail.com"},"_resolved":"/private/var/folders/2p/2j2wcvfs4wz6v0nfr4h455k40000gn/T/11ad8a766ac41abc1823951612dc516f/agentwares-mcp-kit-0.1.0.tgz","_integrity":"sha512-/rtGXOcyxXSzYbRQlD3HLKvZSkYKe9JH/QoNfJJq2bLmOCQfuHYo4t1f2A2N5B0bay+xeDE234OBvpcjP4u4BA==","repository":{"url":"git+https://github.com/agentwares/libs.git","type":"git","directory":"packages/mcp-kit"},"_npmVersion":"10.9.8","description":"Expose any package as an MCP server: one defineTool definition served over stdio and Streamable HTTP, errors that always carry code/cause/fix/retryable, 402 payment gating, and generators for server.json, llms.txt and pricing.json.","directories":{},"sideEffects":false,"_nodeVersion":"22.23.2","dependencies":{"zod":"^4.5.4","@agentwares/x402":"^0.1.0","@modelcontextprotocol/sdk":"^1.30.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp-kit_0.1.0_1788805238737_0.4272672674173943","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@agentwares/mcp-kit","version":"0.2.0","description":"Expose any package as an MCP server: one defineTool definition served over stdio and Streamable HTTP, errors that always carry code/cause/fix/retryable, 402 payment gating, and generators for server.json, llms.txt and pricing.json.","license":"MIT","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/agentwares/libs.git","directory":"packages/mcp-kit"},"homepage":"https://github.com/agentwares/libs/tree/main/packages/mcp-kit#readme","bugs":{"url":"https://github.com/agentwares/libs/issues"},"keywords":["mcp","model-context-protocol","mcp-server","streamable-http","stdio","ai-agents","tools","zod","llms-txt","x402"],"sideEffects":false,"engines":{"node":">=20"},"dependencies":{"@modelcontextprotocol/sdk":"^1.30.0","zod":"^4.5.4","@agentwares/x402":"^0.2.0"},"scripts":{"build":"tsup","typecheck":"tsc --noEmit","lint":"eslint src","test":"vitest run","example:http":"pnpm build && node dist/example-http.js","conformance":"node scripts/conformance.mjs"},"_id":"@agentwares/mcp-kit@0.2.0","_integrity":"sha512-wN7TRk0ORw4i3Nt7OKZBnJAQ3TdB4rxKsG12e1krme66w7FoMSTiSUU6Srm3bZVHF2Xl5Aev5OEXsrF6G9hCLQ==","_resolved":"/private/var/folders/2p/2j2wcvfs4wz6v0nfr4h455k40000gn/T/4e6abe67c94dc14f58dc6974df4c8485/agentwares-mcp-kit-0.2.0.tgz","_from":"file:agentwares-mcp-kit-0.2.0.tgz","_nodeVersion":"22.23.2","_npmVersion":"10.9.8","dist":{"integrity":"sha512-wN7TRk0ORw4i3Nt7OKZBnJAQ3TdB4rxKsG12e1krme66w7FoMSTiSUU6Srm3bZVHF2Xl5Aev5OEXsrF6G9hCLQ==","shasum":"629f936b86978e8e83c5787e513297afd31e953a","tarball":"https://registry.npmjs.org/@agentwares/mcp-kit/-/mcp-kit-0.2.0.tgz","fileCount":11,"unpackedSize":195963,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGluoYFv3L7QoELiB9mncSEV8ns54FmUYD3rVA+xayf4AiEA6QRwAAnqriVY8w41fvZdDOsjhYY1ip1rOP5VGJYs78M="}]},"_npmUser":{"name":"umerbukhari","email":"umer.bukhari@gmail.com"},"directories":{},"maintainers":[{"name":"umerbukhari","email":"umer.bukhari@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-kit_0.2.0_1788820508386_0.9241154466673591"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-07T18:20:38.441Z","modified":"2026-09-07T22:35:08.711Z","0.1.0":"2026-09-07T18:20:38.884Z","0.2.0":"2026-09-07T22:35:08.537Z"},"bugs":{"url":"https://github.com/agentwares/libs/issues"},"license":"MIT","homepage":"https://github.com/agentwares/libs/tree/main/packages/mcp-kit#readme","keywords":["mcp","model-context-protocol","mcp-server","streamable-http","stdio","ai-agents","tools","zod","llms-txt","x402"],"repository":{"type":"git","url":"git+https://github.com/agentwares/libs.git","directory":"packages/mcp-kit"},"description":"Expose any package as an MCP server: one defineTool definition served over stdio and Streamable HTTP, errors that always carry code/cause/fix/retryable, 402 payment gating, and generators for server.json, llms.txt and pricing.json.","maintainers":[{"name":"umerbukhari","email":"umer.bukhari@gmail.com"}],"readme":"# @agentwares/mcp-kit\n\nExpose any package as an MCP server. One `defineTool` definition is served over **stdio** and\n**Streamable HTTP** from the same code; the HTTP handler is Web-standard (`Request → Response`)\nso it runs unchanged in Next.js route handlers, Vercel Functions and Cloudflare Workers.\n\n- `defineTool` — zod input/output, naming lint (`<namespace>_<verb>_<object>`), descriptions written for a new teammate\n- errors always carry `{ code, cause, fix, retryable }` (in the result text and, where the client can take it, `structuredContent`)\n- `withPayment` — 402 with x402 + Stripe MPP payment options (Wave 0 stub: `comingSoon: true`, free `sample` mode)\n- `generateServerJson` + `registryPublishWorkflow` — official MCP registry `server.json` and a tag-triggered OIDC publish workflow\n- `renderLlmsTxt`, `pricingJson`, `listToolManifest` — the machine-readable docs every product ships\n\n```sh\nnpm install @agentwares/mcp-kit\n```\n\n## Define a tool, serve both transports\n\n```ts\nimport { z } from \"zod\";\nimport { createHttpHandler, defineTool, serveStdio, toolError } from \"@agentwares/mcp-kit\";\n\nconst createMonitor = defineTool({\n  name: \"agentcheck_create_monitor\", // namespaced or it throws at boot\n  description:\n    \"Create an uptime monitor for an MCP endpoint. Returns the monitor id and when it is first checked.\",\n  input: z.object({ url: z.url(), intervalMinutes: z.number().int().min(5).default(5) }),\n  output: z.object({ id: z.string(), nextCheckAt: z.string() }),\n  annotations: { readOnlyHint: false, idempotentHint: false },\n  async handler({ url, intervalMinutes }, ctx) {\n    if (!ctx.headers.get(\"authorization\"))\n      throw toolError(\"UNAUTHORIZED\", \"no API key sent\", \"retry with Authorization: Bearer <key>\");\n    return {\n      id: await createMonitorRow(url, intervalMinutes),\n      nextCheckAt: new Date().toISOString(),\n    };\n  },\n});\n\nconst server = { name: \"agentcheck\", version: \"1.0.0\", tools: [createMonitor] };\nexport const POST = createHttpHandler(server); // Next.js app/mcp/route.ts (also Workers: `fetch: handler`)\nif (process.argv.includes(\"--stdio\")) await serveStdio(server); // npx entry for Claude Desktop / Cursor\n```\n\n`ctx` carries `headers` (empty over stdio), `requestId`, `signal`, `sessionId`, `log()`, `progress()` and\n`extra` (the raw SDK context: `sendRequest` for sampling/elicitation).\n`createMcpServer(opts)` returns the SDK `McpServer` if you need resources or prompts too; pass a factory\n`createHttpHandler(() => server)` in that case.\n\nThe HTTP handler is stateless by default (fresh server + transport per request, one JSON body per\nPOST, `GET` → 405) — right for Vercel/Workers. Pass `jsonResponse: false` to stream SSE so\n`ctx.log`/`ctx.progress` reach the client mid-call. Pass `sessions: true` on a long-lived process to\nkeep `Mcp-Session-Id` sessions in memory (SSE by default): that enables sampling/elicitation via\n`ctx.extra.sendRequest` and the standalone GET stream. `OPTIONS` handles CORS when `cors: true`;\n`handleHealth({ name, version, tools })` gives you a `/health` JSON response.\n\n`tools/list` is served from `listToolManifest(tools)` — JSON Schema 2020-12 with\n`additionalProperties: false` for plain `z.object`s (use `z.looseObject` to allow extra keys) — so\nwhat `llms.txt` documents is exactly what the server advertises.\n\n## Errors\n\n```ts\nthrow toolError(\"NOT_FOUND\", \"no monitor mon_1\", \"list monitors and use an existing id\");\nthrow toolError({\n  code: \"RATE_LIMITED\",\n  cause: \"10 req/min exceeded\",\n  fix: \"wait 30s\",\n  retryable: true,\n  details: { resetAt },\n});\n```\n\nEvery failure — thrown `toolError`, plain `Error` (→ `INTERNAL`), invalid arguments (→ `INVALID_INPUT`\nnaming the fields, zod issues in `details`) — becomes a result with `isError: true`, the JSON body in\n`content[0].text` and `_meta.httpStatus`. Codes: `INVALID_INPUT` `NOT_FOUND` `UNAUTHORIZED`\n`PAYMENT_REQUIRED` `RATE_LIMITED` `UPSTREAM_ERROR` `INTERNAL` (plus your own). `structuredContent`\nalso carries the body unless the tool declares an `output` schema, because the official SDK client\nvalidates any `structuredContent` against `outputSchema` even on errors.\n\n## Payment stub (Wave 0)\n\n```ts\nconst paidLookup = withPayment(lookup, {\n  priceUsd: 0.05,\n  authorize: async (ctx) => entitlementFor(ctx.headers),\n});\n```\n\nAdds an optional `sample: boolean` input (\"return an example response at no charge\"). Flow per call:\n`sample` → handler with `ctx.sample = true`; else `authorize` ok → handler with `ctx.userId`; else the\nverifier checks the request's payment headers (default `StubVerifier`, never accepts); else a\n`PAYMENT_REQUIRED` result whose body is `@agentwares/x402`'s `PaymentRequiredBody` — both rails in\n`accepts`, `comingSoon: true` until the wallet ships, `_meta.httpStatus: 402`. For plain HTTP endpoints\nuse `paymentRequiredHttpResponse({ resource, priceUsd })`.\n\n## Registry: server.json + publish on tag\n\n```ts\nconst serverJson = generateServerJson({\n  name: \"io.github.acme/deal-memo\", // io.github.<owner>/ is required for OIDC publishing\n  description: \"Turn a pitch deck into a scored deal memo.\", // ≤ 100 chars\n  version: \"0.1.0\",\n  repository: {\n    url: \"https://github.com/acme/deal-memo\",\n    source: \"github\",\n  },\n  remoteUrl: \"https://deal-memo.example.com/mcp\",\n  npmPackage: { identifier: \"@acme/deal-memo-mcp\", version: \"0.1.0\" }, // package.json needs `mcpName`\n});\nwriteFileSync(\n  \".github/workflows/publish-mcp.yml\",\n  registryPublishWorkflow({ serverJsonPath: \"server.json\" }),\n);\n```\n\nSchema: `https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json`. The workflow\nruns on tags matching `mcp-*`, installs `mcp-publisher`, `login github-oidc`, `publish` — no secrets.\n\n## Docs\n\n`renderLlmsTxt({ name, summary, links, tools })` → `llms.txt`; `pricingJson({ product, tiers, meters, updatedAt })`\n→ `{ schema: \"agentwares.pricing/v1\", ... }`; `listToolManifest(tools)` → `[{ name, description, inputSchema, annotations }]`.\n\n## Example + conformance\n\n```sh\npnpm example:http        # serves example_echo / example_add / example_paid_lookup at http://127.0.0.1:8765/mcp\npnpm conformance         # builds, starts the example (stateful + SSE) with the suite's fixture tools/resources/prompts,\n                         # runs npx -y @modelcontextprotocol/conformance@0.1.16 server --url http://127.0.0.1:<port>/mcp\npnpm conformance --stateless   # the serverless default: everything but sampling/elicitation passes\npnpm conformance --json        # JSON responses: additionally no mid-call log/progress notifications\n```\n\n`dist/example-http.js` flags: `--port= --host= --path= --sse --stateful --conformance --dns-protection`.\n`conformanceTools` / `registerConformanceFixtures(server)` are exported so any product server can run the suite.\n\nMIT © agentwares contributors — part of the [agentwares](https://agentwares.vercel.app) portfolio.\n","readmeFilename":"README.md"}