@acid-cat/mcp-handshake 0.0.0-stage → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hebilicious
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @acid-cat/mcp-handshake
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The [`initialize` handshake of earlier MCP revisions](../../spec/bindings/mcp.md#earlier-revisions-through-http) in front of an MCP server through HTTP. npm package: `@acid-cat/mcp-handshake`.
+
+An MCP server of the [MCP binding](../../spec/bindings/mcp.md#http) through HTTP serves revision `2026-07-28`. Many MCP clients open the session with the `initialize` handshake of revision `2025-11-25` or `2025-06-18`. `mcpHandshake(handler)` gives a web handler that serves these clients too. It keeps no state.
+
+This package is part of the TypeScript reference implementation. [`@acid-cat/core-ts`](../core-ts) gives it as `mcpHandshake`, and [`@acid-cat/core-effect`](../core-effect) gives it as `Mcp.withHandshake`. It works in front of any web handler that serves MCP revision `2026-07-28`.
+
+```sh
+pnpm add @acid-cat/mcp-handshake
+```
+
+## Use
+
+```ts
+import { mcpHandler, mcpHandshake } from "@acid-cat/core-ts";
+
+const mcp = mcpHandshake(mcpHandler(app, options));
+```
+
+```ts
+import { Mcp } from "@acid-cat/core-effect";
+
+const mcp = Mcp.withHandshake(Mcp.toWebHandler(app, layer, options));
+```
+
+| Option | Default | Use |
+| --- | --- | --- |
+| `maximumBytes` | 1 MiB | The longest body that the wrapper reads. The wrapper sends a longer body to the handler unchanged, and the handler rejects it |
+
+## How it works
+
+- A request of revision `2026-07-28`, and a request that is not `POST`, go to the handler unchanged.
+- The wrapper sends each request of a handshake to the handler as a request of revision `2026-07-28`: `tools/list` and `tools/call` as they are, and each other method as `server/discover`. So the handler screens the origin, the media type and the size of each request.
+- A response that is not 2xx comes back unchanged.
+- `initialize` gives the result of `server/discover` in the form of the handshake. `ping` gives an empty result. A notification gets 202. Another method gets the JSON-RPC error `-32601`.
+- A result has no `_meta`, `resultType`, `ttlMs` or `cacheScope` member. A JSON-RPC error has the HTTP status 200.
+
+The wrapper keeps no session, so it does not send `notifications/tools/list_changed`. Its capabilities are `"tools": { "listChanged": false }`. A client that must see the changes of the tools uses revision `2026-07-28`, or MCP through stdio.

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/** A web request handler. */
+export type WebHandler = (request: Request) => Promise<Response>;
+export interface McpHandshakeOptions {
+    /** The maximum size of a request body, in bytes. Give the limit of the wrapped handler. The default is 1 MiB. */
+    readonly maximumBytes?: number | undefined;
+}
+/**
+ * A web handler that serves the `initialize` handshake of revisions 2025-11-25 and 2025-06-18, and gives all other
+ * requests to `handler` unchanged.
+ */
+export declare function mcpHandshake(handler: WebHandler, options?: McpHandshakeOptions): WebHandler;

package/dist/index.js

@@ -0,0 +1,175 @@
+import { MCP_EVENTS_EXTENSION, MCP_PROTOCOL_VERSION, isJsonObject, readBounded } from "@acid-cat/spec-ts";
+//#region src/index.ts
+/**
+* The `initialize` handshake of earlier MCP revisions through HTTP (spec/bindings/mcp.md#earlier-revisions-through-http).
+* `mcpHandshake` wraps the web handler of an MCP server that serves revision 2026-07-28. Each request of a revision with
+* a handshake goes to that handler as a request of revision 2026-07-28, so the handler screens it. The wrapper keeps no
+* state.
+*/
+const PROTOCOL_VERSION_KEY = "io.modelcontextprotocol/protocolVersion";
+const CLIENT_CAPABILITIES_KEY = "io.modelcontextprotocol/clientCapabilities";
+const SERVER_INFO_KEY = "io.modelcontextprotocol/serverInfo";
+/** The revisions with an `initialize` handshake that the wrapper serves, the latest first. */
+const HANDSHAKE_VERSIONS = ["2025-11-25", "2025-06-18"];
+/** The members of a result that only revision 2026-07-28 has. */
+const CURRENT_ONLY_MEMBERS = /* @__PURE__ */ new Set([
+	"_meta",
+	"resultType",
+	"ttlMs",
+	"cacheScope"
+]);
+/**
+* A web handler that serves the `initialize` handshake of revisions 2025-11-25 and 2025-06-18, and gives all other
+* requests to `handler` unchanged.
+*/
+function mcpHandshake(handler, options = {}) {
+	const maximumBytes = options.maximumBytes ?? 1048576;
+	return async (request) => {
+		const header = request.headers.get("MCP-Protocol-Version");
+		if (request.method !== "POST" || header === MCP_PROTOCOL_VERSION) return handler(request);
+		const message = await readMessage(request.clone(), maximumBytes);
+		if (message === void 0 || !isHandshakeRequest(header, metaOf(message)[PROTOCOL_VERSION_KEY])) return handler(request);
+		return answer(handler, request, message);
+	};
+}
+/**
+* Answer a request of a revision with a handshake. `initialize`, `ping` and notifications go to the handler as
+* `server/discover`, and the other methods go as they are.
+*/
+async function answer(handler, request, message) {
+	const method = typeof message["method"] === "string" ? message["method"] : "";
+	const params = isJsonObject(message["params"]) ? message["params"] : {};
+	const ownMethod = method === "tools/list" || method === "tools/call" ? method : "server/discover";
+	const response = await handler(current(request, ownMethod, ownMethod === "server/discover" ? {} : params));
+	if (!response.ok) return response;
+	const reply = parseObject(await response.text()) ?? {};
+	if (!("id" in message)) return new Response(null, { status: 202 });
+	const id = message["id"];
+	const result = reply["result"];
+	if (!isJsonObject(result)) return json({
+		jsonrpc: "2.0",
+		id,
+		error: reply["error"] ?? {
+			code: -32603,
+			message: "The server gave no result."
+		}
+	});
+	if (method === "initialize") return json({
+		jsonrpc: "2.0",
+		id,
+		result: initializeResult(params["protocolVersion"], result)
+	});
+	if (method === "ping") return json({
+		jsonrpc: "2.0",
+		id,
+		result: {}
+	});
+	if (ownMethod === "server/discover") return json({
+		jsonrpc: "2.0",
+		id,
+		error: {
+			code: -32601,
+			message: `Method not found: ${method}`
+		}
+	});
+	return json({
+		jsonrpc: "2.0",
+		id,
+		result: Object.fromEntries(Object.entries(result).filter(([member]) => !CURRENT_ONLY_MEMBERS.has(member)))
+	});
+}
+/**
+* True if a request is of a revision with a handshake: its header names one, or it has no header and no revision
+* 2026-07-28 in its `params._meta`.
+*/
+function isHandshakeRequest(header, metaVersion) {
+	if (header === null) return metaVersion !== MCP_PROTOCOL_VERSION;
+	return HANDSHAKE_VERSIONS.some((version) => version === header);
+}
+/** The request of revision 2026-07-28 for `method`, with the headers and the metadata that the revision requires. */
+function current(request, method, params) {
+	const headers = new Headers(request.headers);
+	headers.set("MCP-Protocol-Version", MCP_PROTOCOL_VERSION);
+	headers.set("Mcp-Method", method);
+	headers.set("Accept", "application/json, text/event-stream");
+	if (method === "tools/call" && typeof params["name"] === "string") headers.set("Mcp-Name", params["name"]);
+	const meta = {
+		...metaOf({ params }),
+		[PROTOCOL_VERSION_KEY]: MCP_PROTOCOL_VERSION,
+		[CLIENT_CAPABILITIES_KEY]: {}
+	};
+	const body = JSON.stringify({
+		jsonrpc: "2.0",
+		id: 0,
+		method,
+		params: {
+			...params,
+			_meta: meta
+		}
+	});
+	return new Request(request.url, {
+		method: "POST",
+		headers,
+		body,
+		signal: request.signal
+	});
+}
+/**
+* The result of `initialize`, from the result of `server/discover`. The wrapper keeps no session, so it cannot send
+* `notifications/tools/list_changed`. The events extension is only for revision 2026-07-28, so the capabilities do not
+* have it (spec/bindings/mcp.md#events).
+*/
+function initializeResult(offered, discovered) {
+	const info = metaOf({ params: discovered })[SERVER_INFO_KEY];
+	const name = isJsonObject(info) && typeof info["name"] === "string" ? info["name"] : "";
+	const version = isJsonObject(info) && typeof info["version"] === "string" ? info["version"] : "";
+	const instructions = typeof discovered["instructions"] === "string" ? discovered["instructions"] : void 0;
+	const capabilities = isJsonObject(discovered["capabilities"]) ? discovered["capabilities"] : {};
+	return {
+		protocolVersion: HANDSHAKE_VERSIONS.find((each) => each === offered) ?? HANDSHAKE_VERSIONS[0],
+		capabilities: {
+			...withoutEvents(capabilities),
+			tools: { listChanged: false }
+		},
+		serverInfo: {
+			name,
+			version
+		},
+		...instructions === void 0 ? {} : { instructions }
+	};
+}
+/** Capabilities without the events extension. A capability object with no other extension has no `extensions` member. */
+function withoutEvents(capabilities) {
+	const { extensions, ...rest } = capabilities;
+	if (!isJsonObject(extensions)) return capabilities;
+	const { [MCP_EVENTS_EXTENSION]: _, ...others } = extensions;
+	return Object.keys(others).length === 0 ? rest : {
+		...rest,
+		extensions: others
+	};
+}
+/** The `params._meta` of a message, or an empty object. */
+function metaOf(message) {
+	const params = message["params"];
+	const meta = isJsonObject(params) ? params["_meta"] : void 0;
+	return isJsonObject(meta) ? meta : {};
+}
+/** The JSON object in the body of a request, or `undefined` when the body is too large or not a JSON object. */
+async function readMessage(request, maximumBytes) {
+	const body = await readBounded(request, maximumBytes);
+	return "text" in body ? parseObject(body.text) : void 0;
+}
+function parseObject(text) {
+	try {
+		const value = JSON.parse(text);
+		return isJsonObject(value) ? value : void 0;
+	} catch {
+		return;
+	}
+}
+const json = (body) => new Response(JSON.stringify(body), {
+	status: 200,
+	headers: { "Content-Type": "application/json" }
+});
+//#endregion
+export { mcpHandshake };

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@acid-cat/mcp-handshake",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.10.0",
+  "description": "Serve MCP clients of the revisions with an initialize handshake from an AcidCat MCP server through HTTP, with no state. Part of the TypeScript reference implementation.",
+  "keywords": [
+    "acidcat",
+    "mcp"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hebilicious/acidcat.git",
+    "directory": "packages/mcp-handshake"
+  },
+  "homepage": "https://github.com/Hebilicious/acidcat/tree/main/packages/mcp-handshake#readme",
+  "bugs": "https://github.com/Hebilicious/acidcat/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@acid-cat/spec-ts": "0.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.5",
+    "typescript": "7.0.2"
+  }
 }