{"_id":"@airo-js/mcp","_rev":"3-ae7ddac95c944718d0017529050dc1b2","name":"@airo-js/mcp","dist-tags":{"latest":"0.11.0"},"versions":{"0.10.0":{"name":"@airo-js/mcp","version":"0.10.0","keywords":["airo","mcp","model-context-protocol","agent","tools","framework"],"author":{"name":"AI/RO contributors"},"license":"Apache-2.0","_id":"@airo-js/mcp@0.10.0","maintainers":[{"name":"ben.smith","email":"ben.smith@dotter.me"}],"homepage":"https://github.com/airo-studio/airo-js/tree/main/packages/mcp#readme","bugs":{"url":"https://github.com/airo-studio/airo-js/issues"},"dist":{"shasum":"19ccccfa6d3e359fb1f3434288401db61408c51b","tarball":"https://registry.npmjs.org/@airo-js/mcp/-/mcp-0.10.0.tgz","fileCount":18,"integrity":"sha512-v/clcJ/QXz23ZCztC2bJzb8/NAGtqfPlCwH7/hKjDIppD17O4Dxv722L11Wyrt1oj60hdLDkHkOcuVxMe7tq7w==","signatures":[{"sig":"MEYCIQC+Awpay1L4euV/o5BPn4gE7WTHIorBYSBBwNSLqdVQxAIhAMBZr8jmkFOSDDvqTGkKd+BS58jEWVCrt50pIh+MdL31","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":59691},"main":"./dist/index.js","type":"module","_from":"file:airo-js-mcp-0.10.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist *.tsbuildinfo","typecheck":"tsc -p tsconfig.json --noEmit","test:watch":"vitest"},"_npmUser":{"name":"ben.smith","email":"ben.smith@dotter.me"},"_resolved":"/private/var/folders/c5/n9tshghx1rn9q47jkjlw9q4m0000gp/T/4d053265439277773d02fc7c24b8dd42/airo-js-mcp-0.10.0.tgz","_integrity":"sha512-v/clcJ/QXz23ZCztC2bJzb8/NAGtqfPlCwH7/hKjDIppD17O4Dxv722L11Wyrt1oj60hdLDkHkOcuVxMe7tq7w==","repository":{"url":"git+https://github.com/airo-studio/airo-js.git","type":"git","directory":"packages/mcp"},"_npmVersion":"11.4.2","description":"Airo MCP — tool manifest emission + dispatch. Cartridges declare MCP tools via @airo-js/cartridge-kit; this package advertises and invokes them against the same post-Transformer snapshot the views render.","directories":{},"sideEffects":false,"_nodeVersion":"24.3.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.0"},"peerDependencies":{"@airo-js/cartridge-kit":"^0.10.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.10.0_1788612226127_0.9210760599964434","host":"s3://npm-registry-packages-npm-production"}},"0.10.1":{"name":"@airo-js/mcp","version":"0.10.1","keywords":["airo","mcp","model-context-protocol","agent","tools","framework"],"author":{"name":"AI/RO contributors"},"license":"Apache-2.0","_id":"@airo-js/mcp@0.10.1","maintainers":[{"name":"ben.smith","email":"ben.smith@dotter.me"}],"homepage":"https://github.com/airo-studio/airo-js/tree/main/packages/mcp#readme","bugs":{"url":"https://github.com/airo-studio/airo-js/issues"},"dist":{"shasum":"244949ee39a3978545786b10c09b60c9fa85b631","tarball":"https://registry.npmjs.org/@airo-js/mcp/-/mcp-0.10.1.tgz","fileCount":18,"integrity":"sha512-7lW2OCDn1E82B/25kFnJ61HX+mTAo+r7j9LNV1VrtXtQRMNnZG2QSivm5k6q/0KJxYoH0GgvON2LKG8ch24e5A==","signatures":[{"sig":"MEUCIFpNUkz3bXerN0DGfsJfRN/3nxYZ+XPpnG5xnFrXb+WTAiEAmizn3rieN5Iy4J2q1HPpV3hzHr7yg+DOXFy9QSqWVq8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":59691},"main":"./dist/index.js","type":"module","_from":"file:airo-js-mcp-0.10.1.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","clean":"rm -rf dist *.tsbuildinfo","typecheck":"tsc -p tsconfig.json --noEmit","test:watch":"vitest"},"_npmUser":{"name":"ben.smith","email":"ben.smith@dotter.me"},"_resolved":"/private/var/folders/c5/n9tshghx1rn9q47jkjlw9q4m0000gp/T/90edd62e7dc6b9c1f13be0807bfccd71/airo-js-mcp-0.10.1.tgz","_integrity":"sha512-7lW2OCDn1E82B/25kFnJ61HX+mTAo+r7j9LNV1VrtXtQRMNnZG2QSivm5k6q/0KJxYoH0GgvON2LKG8ch24e5A==","repository":{"url":"git+https://github.com/airo-studio/airo-js.git","type":"git","directory":"packages/mcp"},"_npmVersion":"11.4.2","description":"Airo MCP — tool manifest emission + dispatch. Cartridges declare MCP tools via @airo-js/cartridge-kit; this package advertises and invokes them against the same post-Transformer snapshot the views render.","directories":{},"sideEffects":false,"_nodeVersion":"24.3.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.1.0"},"peerDependencies":{"@airo-js/cartridge-kit":"^0.10.1"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.10.1_1788884743353_0.1651963605503619","host":"s3://npm-registry-packages-npm-production"}},"0.11.0":{"name":"@airo-js/mcp","version":"0.11.0","description":"Airo MCP — tool manifest emission + dispatch. Cartridges declare MCP tools via @airo-js/cartridge-kit; this package advertises and invokes them against the same post-Transformer snapshot the views render.","keywords":["airo","mcp","model-context-protocol","agent","tools","framework"],"author":{"name":"AI/RO contributors"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/airo-studio/airo-js.git","directory":"packages/mcp"},"homepage":"https://github.com/airo-studio/airo-js/tree/main/packages/mcp#readme","bugs":{"url":"https://github.com/airo-studio/airo-js/issues"},"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"}},"sideEffects":false,"peerDependencies":{"@airo-js/cartridge-kit":"^0.11.0"},"devDependencies":{"vitest":"^2.1.0"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","test":"vitest run","test:watch":"vitest","clean":"rm -rf dist *.tsbuildinfo"},"_id":"@airo-js/mcp@0.11.0","_integrity":"sha512-T8HfYteQ94ZKFUFL6lg24riT6M8XwYvttIet7Rs/+UJBc5Rf/uMHbSd5kEncyyvUVpSp2v/4QqU3r7vTXzg4IA==","_resolved":"/private/var/folders/c5/n9tshghx1rn9q47jkjlw9q4m0000gp/T/700b5e4554ad7a3eae2c12880d474004/airo-js-mcp-0.11.0.tgz","_from":"file:airo-js-mcp-0.11.0.tgz","_nodeVersion":"24.3.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-T8HfYteQ94ZKFUFL6lg24riT6M8XwYvttIet7Rs/+UJBc5Rf/uMHbSd5kEncyyvUVpSp2v/4QqU3r7vTXzg4IA==","shasum":"4e2e8d45a6cef2b7018b4c95a4cbb207497aaa4e","tarball":"https://registry.npmjs.org/@airo-js/mcp/-/mcp-0.11.0.tgz","fileCount":18,"unpackedSize":59691,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC1JUvl3wl3MzVVCbvav5mlGYQApAA9HXPdThsivPjLggIgJS496t0HG4oshxuT221wl4bGiK6LXRlHuYcYOdb1ARE="}]},"_npmUser":{"name":"ben.smith","email":"ben.smith@dotter.me"},"directories":{},"maintainers":[{"name":"ben.smith","email":"ben.smith@dotter.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_0.11.0_1789137542711_0.5176220040423658"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-05T12:43:45.964Z","modified":"2026-09-11T14:39:03.034Z","0.10.0":"2026-09-05T12:43:46.248Z","0.10.1":"2026-09-08T16:25:43.494Z","0.11.0":"2026-09-11T14:39:02.847Z"},"bugs":{"url":"https://github.com/airo-studio/airo-js/issues"},"author":{"name":"AI/RO contributors"},"license":"Apache-2.0","homepage":"https://github.com/airo-studio/airo-js/tree/main/packages/mcp#readme","keywords":["airo","mcp","model-context-protocol","agent","tools","framework"],"repository":{"type":"git","url":"git+https://github.com/airo-studio/airo-js.git","directory":"packages/mcp"},"description":"Airo MCP — tool manifest emission + dispatch. Cartridges declare MCP tools via @airo-js/cartridge-kit; this package advertises and invokes them against the same post-Transformer snapshot the views render.","maintainers":[{"name":"ben.smith","email":"ben.smith@dotter.me"}],"readme":"# `@airo-js/mcp`\n\nMCP tool manifest emission and dispatch for airo-js cartridges.\n\nCartridges declare agent-facing tools as `McpToolDefinition` entries in\n`@airo-js/cartridge-kit`. This package turns those declarations into the two\noperations an MCP server performs: advertise the tools, and invoke one.\n\n## The guarantee\n\nTools answer from the **same post-Transformer snapshot** the views rendered and\nthe publication adapters published. Three readers, one source of truth — so the\nrendered page, the indexed feed and the agent's answer cannot disagree.\n\n`dispatchTool` takes the snapshot as a parameter rather than fetching one,\nbecause a host that renders from one snapshot and dispatches against a fresher\none has already broken the guarantee, whatever this package does.\n\n## What's in here\n\n### `buildToolManifest(cartridge, opts?)`\n\nReturns MCP's `tools/list` payload — `{ tools: [{ name, description,\ninputSchema }] }` — and nothing else. `handler` is not serialisable and\n`requires` is coverage metadata a client cannot act on.\n\nPure and synchronous. A cartridge with no `mcpTools` yields `{ tools: [] }`\nrather than throwing.\n\n`opts.toolNames` restricts the set. `opts.snapshot` additionally omits tools\nwhose `required: 'always'` paths that snapshot cannot cover — **off by\ndefault**, because MCP clients cache tool lists and a tool that appears and\ndisappears as data changes is worse for an agent than one that is always\nlisted and sometimes answers `missing-required-fields`, which at least names\nwhat is missing.\n\n### `dispatchTool(cartridge, toolName, input, snapshot, opts)`\n\nResolves the tool, gates it on coverage, optionally validates the input, then\ninvokes it. Returns a discriminated union:\n\n```ts\n{ ok: true,  toolName, result }\n{ ok: false, toolName, error: { code, message, missing?, validationErrors?, cause? } }\n```\n\n`code` is one of `'unknown-tool'`, `'missing-required-fields'`,\n`'invalid-input'`, `'handler-threw'`.\n\n**It never throws.** Every outcome becomes a protocol response, and an agent\ncalling a stale tool name is ordinary rather than exceptional — throwing would\nturn that into a crashed request handler and make the common failure\nindistinguishable from a bug in the host.\n\n`ctx.schema` is taken from `cartridge.schema`, so callers never construct one.\n\n## Scope\n\nEmission and dispatch. **Not** transport, auth, rate limiting, tenancy or\nsession state — those are host concerns, and none of them is rendering or\ndispatch. `ToolContext.scope` carries a host's tenancy through opaquely; the\nframework never reads it.\n\nInput validation is a **seam**, not a dependency. `inputSchema` is JSON Schema,\nand validating it needs a validator — a choice with real weight that belongs to\nthe host, which already has one if it serves an API. Pass `validateInput` to\nenable it; omit it and inputs reach handlers unvalidated, which is documented\nrather than silent.\n\n## Install\n\n```bash\nnpm install @airo-js/mcp @airo-js/cartridge-kit\n```\n\n`@airo-js/cartridge-kit` is a peer dependency.\n\n**Server-only.** Ship MCP tools from a cartridge's `full.ts` envelope, never\nfrom `runtime.ts` — see best-practices §2.5. A handler closing over server\ncredentials is the normal case.\n\n## Example\n\n```ts\nimport { buildToolManifest, dispatchTool } from '@airo-js/mcp';\n\napp.get('/mcp/tools', (_req, res) => {\n  res.json(buildToolManifest(cartridge));\n});\n\napp.post('/mcp/call', async (req, res) => {\n  const snapshot = await snapshotFor(req.body.slug);\n  const out = await dispatchTool(\n    cartridge, req.body.name, req.body.arguments, snapshot, { config },\n  );\n  res.status(out.ok ? 200 : 400).json(out);\n});\n```\n\nWorking versions in [`examples/full-site`](../../examples/full-site) (Express,\none cartridge serving HTML, JSON-LD, `llms.txt` and MCP off one snapshot) and\n[`examples/shopify-edge-worker`](../../examples/shopify-edge-worker) (two\ncartridges on one Cloudflare Worker).\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md"}