From 0b94b9e7eb72591f21b46056b53d100924f3b926 Mon Sep 17 00:00:00 2001 From: Vensin Date: Fri, 13 Nov 2026 08:30:02 +0100 Subject: [PATCH] docs: MCP (inkan 0.10), the CLI's mcp and check --mcp, and a draft post --- content/blog/inkan-0-10.mdx | 75 +++++++++++++++++ content/docs/cli.mdx | 9 +- content/docs/mcp.mdx | 164 ++++++++++++++++++++++++++++++++++++ content/docs/meta.json | 1 + 4 files changed, 247 insertions(+), 2 deletions(-) create mode 100644 content/blog/inkan-0-10.mdx create mode 100644 content/docs/mcp.mdx diff --git a/content/blog/inkan-0-10.mdx b/content/blog/inkan-0-10.mdx new file mode 100644 index 0000000..cf43256 --- /dev/null +++ b/content/blog/inkan-0-10.mdx @@ -0,0 +1,75 @@ +--- +title: "Your API, as tools a model can call" +description: "inkan 0.10 serves every route as an MCP tool, made from the contract the route already has, and checks that what a model gets is what the docs say." +date: "2026-11-13" +author: "Vensin" +draft: true +--- + +Every inkan route carries its contract: what goes in, what comes out, and a few examples of +a call. Until now three readers used it: the validation, the docs page, and `inkan check`. In +0.10 there is a fourth. AI clients like Claude, Cursor or VS Code call tools over the +[Model Context Protocol](https://modelcontextprotocol.io), and a tool is, again, a name, a +description, an input schema and an output schema. inkan had all of that already. + +```ts +const app = inkan({ title: "Tea Shop", version: "1.0.0", mcp: true }); +``` + +That is the whole change to an app. Every documented route is a tool on `/mcp`. + +## Nothing written twice + +The tool's name is the route's `operationId`, the one `openapi.json` already has. Its +description is the summary, the description, and the examples, written as calls a model can +copy: `found: {"id":1} → 200`. The input schema is the params, query and body, the output +schema the 2xx answer. GET says it only reads; DELETE says it destroys. A route can rename or +reword its tool, or stay out with `mcp: false`, but it does not have to say anything. + +Most ways of turning an API into MCP tools generate them from an OpenAPI file and then ask +you to curate the result. Here there is nothing to generate, so nothing goes stale. + +## A tool call is a request + +The part I care about most: a tool call does not have a way of its own into the app. A call +to `getTeasById` with `{ "id": 1 }` becomes `GET /teas/1`, with the caller's Authorization +header and cookies, and runs through the route's security, the hooks, the input checks, +middleware, `rateLimit` and the log like any request. Whatever the route would not let that +caller do, the tool cannot do either. + +A problem comes back as a tool error with the problem as its text. When a model sends +`"id": "abc"`, it reads the same 400 a person would: which field, and what it should be. And +it can try again. + +## Proven, not promised + +`inkan check --mcp` runs every example a second time, as a tool call, and holds the answer to +the same contract. If the tool and the route ever disagree, the check says so before anyone +asks a model to use it. + +I also tested the endpoint with the official MCP SDK and the new 2.x client, both the older +way (`initialize`) and the new stateless revision from July, 2026-07-28. That paid off right +away: the new client refused my first tool list because it had no cache hints, which the new +revision requires. It has them now. + +## Locally too + +`inkan mcp src/app.ts` serves the same tools on stdin and stdout, for clients that start a +server as a process. `-H "authorization: Bearer …"` hands it a token. The docs page got an +**mcp** button that copies the config a client needs. + +## About speed + +Without `mcp` nothing changes on the request path. While measuring I found that +`app.inject` had picked up an extra turn per request, and fixed it: the in-process bench is now +about 4 % faster than 0.9.4, almost all of it in `inject`, which only your tests use. The +numbers over the network are in the release notes. + +## Next + +MCP is experimental in 0.10, as WebSockets and jobs were at first. What comes after it is +still open: llms.txt next to the docs page, Standard Schema so a contract can be written in +Zod or Valibot, or `inkan mock`, a server made from the examples. Tell me which one you would +use first. + +See you next time ✨ diff --git a/content/docs/cli.mdx b/content/docs/cli.mdx index 4dbc4d0..d59930f 100644 --- a/content/docs/cli.mdx +++ b/content/docs/cli.mdx @@ -1,10 +1,11 @@ --- title: "CLI" -description: "inkan check, diff, openapi, create, examples, hanko and seal." +description: "inkan check, diff, openapi, mcp, create, examples, hanko and seal." --- ```sh -npx inkan check src/app.ts [--only ] [--strict] [--format terminal|json|markdown] +npx inkan check src/app.ts [--only ] [--strict] [--mcp] [--format terminal|json|markdown] +npx inkan mcp src/app.ts [-H "name: value"]... npx inkan openapi src/app.ts [-o openapi.json] npx inkan routes src/app.ts npx inkan diff openapi.json src/app.ts [--format terminal|json|markdown] @@ -25,6 +26,10 @@ field that is required now, a value a request may no longer send, a value an ans send now. Requests may only get looser and answers only stricter; it exits with `1` when something breaks, so CI can ask for a major version. +`inkan mcp` serves the app as an [MCP](/docs/mcp) server on stdin and stdout, for clients +that start it as a process; `-H` sends a header with every tool call. `inkan check --mcp` runs +every example of a tool a second time, as a tool call. + `inkan create app` is what `npm create inkan` runs; its options are on [Installation](/docs/installation#start-a-project). `inkan create plugin` writes a package for a plugin of your own, see [Publish a plugin](/docs/publish-a-plugin). diff --git a/content/docs/mcp.mdx b/content/docs/mcp.mdx new file mode 100644 index 0000000..f34bb79 --- /dev/null +++ b/content/docs/mcp.mdx @@ -0,0 +1,164 @@ +--- +title: "MCP" +description: "mcp: true: every route a tool for Claude, Cursor and other AI clients, made from the contract it already has." +--- + + +The option, the tool shapes and the CLI may change in a minor release, named in the changelog. + + +The [Model Context Protocol](https://modelcontextprotocol.io) is how AI clients (Claude, Cursor, +VS Code and others) call tools. An inkan app already says, for every route, what goes in, what +comes out and what a call looks like. With `mcp: true` it says the same to those clients: + +```ts +const app = inkan({ title: "Tea Shop", version: "1.0.0", mcp: true }); +``` + +Every documented route is now a tool on `/mcp`, with nothing written twice. The tool is made +from the contract, and a tool call is a request to the route, so what a model gets is what the +docs page shows and `inkan check` tested. + +## What a route becomes + +```ts +app.get( + "/teas/:id", + { + summary: "One tea by its id", + params: t.object({ id: t.int() }), + response: { 200: Tea, 404: t.problem() }, + examples: [ + { name: "found", params: { id: 1 } }, + { name: "missing", params: { id: 99 }, status: 404 }, + ], + }, + handler, +); +``` + +```json +{ + "name": "getTeasById", + "title": "One tea by its id", + "description": "One tea by its id\n\nExamples:\n- found: {\"id\":1} → 200\n- missing: {\"id\":99} → 404", + "inputSchema": { "type": "object", "properties": { "id": { "type": "integer" } }, "required": ["id"], "additionalProperties": false }, + "outputSchema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": ["id", "name"] }, + "annotations": { "title": "One tea by its id", "readOnlyHint": true } +} +``` + +| | comes from | +| --- | --- | +| `name` | `mcp.name`, else the `operationId`, the same one `openapi.json` has | +| `description` | the summary, the description, and up to three examples written as calls | +| `inputSchema` | params and query side by side, declared `headers`, and `body`. Where a name is in both params and query, they go as `params` and `query` | +| `outputSchema` | the one 2xx answer, when it is a JSON object | +| `annotations` | the method: GET is read-only, DELETE destructive, PUT and DELETE idempotent | + +`app.mcp()` hands back the tools and the routes that are none, with the reason: + +```ts +const { tools, skipped } = app.mcp(); +// skipped: [{ method: "GET", path: "/feed", reason: "answers with server-sent events" }] +``` + +WebSocket routes, event streams, raw, streamed and file bodies are no tools, and neither are +`hidden` routes. Two routes with the same tool name, or a name MCP cannot carry, throw when the +tools are made. + +## A route's say + +```ts +app.delete("/teas/:id", { /* … */ mcp: { name: "remove_tea", description: "Takes a tea off the shelf for good." } }, handler); +app.post("/admin/reset", { /* … */ mcp: false }, handler); // never a tool +``` + +`mcp: { name, description, annotations }` changes what the client is told; `annotations` is +merged over what the method says. `mcp: false` keeps a route out. + +## A tool call is a request + +A call to `getTeasById` with `{ "id": 1 }` is `GET /teas/1`, sent into the app as any other +request: + +- **With the caller's credentials.** The Authorization header, cookies and an API key header the + MCP client sends go with it, and an API key a route reads from the query comes from the + endpoint's own URL. The route's `security`, your auth hooks and `@inkanjs/auth` decide, as + they would over HTTP. +- **Through everything.** Hooks, input checks, middleware, `bodyLimit`, `rateLimit` (once per + call) and the log, where it shows as `via MCP tool getTeasById`. The endpoint itself runs no + hooks: only the routes' requests do. +- **An answer is a result.** A 2xx is the tool's result, as JSON text and, with an + `outputSchema`, as `structuredContent` too. A problem is a tool error (`isError`) with the + problem as its text, so a model reads that `id` should have been an integer and tries again. + The status is in `_meta["dev.inkan/status"]`. + +There is no second way into your app, and nothing a tool can do that the route would not let +the same caller do. + +## Connecting a client + +Over HTTP, give the client the endpoint. The docs page has an **mcp** button that copies this: + +```json +{ "mcpServers": { "tea-shop": { "type": "http", "url": "http://localhost:3000/mcp" } } } +``` + +Or let the client start the app as a process and talk to it on stdin and stdout, with no +server running: + +```sh +inkan mcp src/app.ts +inkan mcp src/app.ts -H "authorization: Bearer $TEA_TOKEN" +``` + +```json +{ "mcpServers": { "tea-shop": { "command": "npx", "args": ["inkan", "mcp", "src/app.ts"] } } } +``` + +`-H` sends a header with every call, such as the token a route asks for. What the app logs +goes to stderr, so stdout carries only the protocol. + +## Proven by check + +```sh +inkan check src/app.ts --mcp +``` + +Every example of a route that is a tool runs twice, once as a request and once as a +`tools/call`, and both answers are held to the same contract. `app.check({ mcp: true })` does +the same in a test. + +```text + GET /teas/:id + ✓ found 200 1.3ms + ✓ missing 404 0.4ms + ✓ found via MCP 200 0.3ms + ✓ missing via MCP 404 0.2ms +``` + +## The endpoint + +```ts +inkan({ mcp: { path: "/mcp", origins: ["https://claude.ai"], instructions: "Teas, their kinds and stock." } }); +``` + +| option | | +| --- | --- | +| `path` | where it lives. Default `/mcp` | +| `origins` | the pages that may call it from a browser: by default the app's own origin, and clients without an Origin header, which are not browsers. Another origin is a 403. Same shape as `cors` and `ws.origins` | +| `instructions` | what a model is told about the server as a whole. Default: the app's `description` | + +It speaks MCP **2026-07-28**, stateless, with every request's `MCP-Protocol-Version`, +`Mcp-Method` and `Mcp-Name` headers checked against its body, `server/discover`, and cache hints +on the tool list (`cacheScope: "public"`, `ttlMs` 0 in development, five minutes otherwise). +For older clients it answers `initialize` for 2025-11-25 back to 2025-03-26, without a session +either way. It takes POST only and one message per request. It is tested against the official +SDK 1.32 and `@modelcontextprotocol/client` 2.4, both the legacy way and pinned to 2026-07-28. + +Without `mcp` there is no endpoint, and the request path does no more work than before. + +Not there yet: resources and prompts, OAuth protected resource metadata (RFC 9728) for +clients that sign in by themselves, and `ctx.mcp`, for a handler to know it was called as a +tool. That name is reserved and arrives in a later release. diff --git a/content/docs/meta.json b/content/docs/meta.json index c34af88..8e284de 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -24,6 +24,7 @@ "storage", "runtime", "client", + "mcp", "middleware", "hooks", "plugins",