@gjsify/mcp 0.53.0

package/README.md

@@ -0,0 +1,28 @@
+# @gjsify/mcp
+
+Server-side runtime for [MCP](https://modelcontextprotocol.io) servers that run on GJS and Node. It wraps `@modelcontextprotocol/sdk` (a peer dependency) with the lifecycle pieces every stdio server ends up re-writing.
+
+```ts
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { applyReadOnlyGate, serveStdio, mcpSuccess } from '@gjsify/mcp';
+
+const server = new McpServer({ name: 'demo', version: '1.0.0' });
+applyReadOnlyGate(server, process.env.ALLOW_WRITE === '1'); // BEFORE any registerTool
+server.registerTool('ping', { annotations: { readOnlyHint: true } }, async () => mcpSuccess({ pong: true }));
+await serveStdio(server, 'demo');
+```
+
+## API
+
+| Export | Purpose |
+|---|---|
+| `applyReadOnlyGate(server, allowWrite)` | Default-deny: without `allowWrite`, only tools with `annotations.readOnlyHint === true` are registered. A forgotten annotation drops the tool (visible), it never exposes a mutation (silent). Call it before registering tools. |
+| `serveUntilClosed(server, { label?, stdin?, stdout? })` | Connect over stdio and resolve when the client goes away (stdin `end`/`close` or transport close). The SDK does not report stdin EOF itself, so a server without this outlives its client. Streams are injectable for tests. |
+| `serveStdio(server, label?)` | `serveUntilClosed`, then `process.exit(0)` — needed under GJS, where the GLib main loop keeps an idle process alive. |
+| `mcpSuccess(data)` / `mcpError(msg)` / `mcpErrorFrom(err)` | One result shape: a single JSON text block. Errors carry the message only, never a stack. |
+
+Logs go to stderr; stdout is the protocol channel.
+
+## License
+
+MIT

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import{applyReadOnlyGate as e}from"./read-only-gate.js";import{serveStdio as t,serveUntilClosed as n}from"./serve-stdio.js";import{mcpError as r,mcpErrorFrom as i,mcpSuccess as a}from"./tool-result.js";export{e as applyReadOnlyGate,r as mcpError,i as mcpErrorFrom,a as mcpSuccess,t as serveStdio,n as serveUntilClosed};

package/lib/esm/read-only-gate.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";function applyReadOnlyGate(e,t){if(t)return;let n=e.registerTool.bind(e);e.registerTool=((e,t,...r)=>t?.annotations?.readOnlyHint===!0?n(e,t,...r):void 0)}export{applyReadOnlyGate};

package/lib/esm/serve-stdio.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{StdioServerTransport as e}from"@modelcontextprotocol/sdk/server/stdio.js";async function serveUntilClosed(t,n={}){let r=n.stdin??process.stdin,i=new e(r,n.stdout??process.stdout);await t.connect(i),await new Promise(e=>{let t=i.onclose;i.onclose=()=>{t?.(),e()},r.once(`end`,e),r.once(`close`,e)}),console.error(`[${n.label??`mcp`}] client disconnected (stdin closed) — exiting`)}async function serveStdio(e,t=`mcp`){return await serveUntilClosed(e,{label:t}),process.exit(0)}export{serveStdio,serveUntilClosed};

package/lib/esm/tool-result.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";function mcpSuccess(e){return{content:[{type:`text`,text:JSON.stringify(e,null,2)}]}}function mcpError(e){return{content:[{type:`text`,text:JSON.stringify({error:e})}],isError:!0}}function mcpErrorFrom(e){return mcpError(e instanceof Error?e.message:String(e))}export{mcpError,mcpErrorFrom,mcpSuccess};

package/lib/types/index.d.ts

@@ -0,0 +1,3 @@
+export { applyReadOnlyGate } from './read-only-gate.js';
+export { serveStdio, serveUntilClosed, type ServeOptions } from './serve-stdio.js';
+export { mcpSuccess, mcpError, mcpErrorFrom, type McpTextResult } from './tool-result.js';

package/lib/types/mcp.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/read-only-gate.d.ts

@@ -0,0 +1,18 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Gate mutating tools, DEFAULT-DENY.
+ *
+ * Unless writes are explicitly allowed, a tool is registered ONLY if it proves it is read-only
+ * (`annotations.readOnlyHint === true`). A tool that omits the annotation, or mis-sets it, is
+ * DROPPED.
+ *
+ * The direction is the whole point: the obvious spelling — drop only when `readOnlyHint === false`
+ * — fails OPEN, silently exposing every tool whose author forgot the annotation. This one fails
+ * CLOSED: the failure mode is a tool missing from `tools/list`, which gets noticed and fixed,
+ * instead of a mutation quietly reachable. Tools identify themselves by their own annotation, so
+ * there is no second name list to drift.
+ *
+ * Call this BEFORE registering anything — it wraps `registerTool`, so tools registered earlier
+ * are already through.
+ */
+export declare function applyReadOnlyGate(server: McpServer, allowWrite: boolean): void;

package/lib/types/serve-stdio.d.ts

@@ -0,0 +1,34 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Readable, Writable } from 'node:stream';
+export interface ServeOptions {
+    /** Prefix of the stderr line printed on disconnect. Default `mcp`. */
+    label?: string;
+    /** Input stream. Default `process.stdin`. */
+    stdin?: Readable;
+    /** Output stream. Default `process.stdout`. */
+    stdout?: Writable;
+}
+/**
+ * Serve over stdio until the client goes away, then resolve (the process is left alone — see
+ * {@link serveStdio} for the variant that exits).
+ *
+ * Park until EOF — NOT forever. `await new Promise<never>(() => {})` is unsettleable, so a server
+ * whose client died keeps running; such processes have been found REPARENTED TO `systemd --user`,
+ * which only happens once the spawning process is gone. stdin EOF is the signal: for a stdio
+ * child, the parent closing the pipe IS "you are done". The MCP SDK will not report it — its
+ * `StdioServerTransport` attaches only `data` and `error` to stdin and calls `close()` solely on
+ * explicit shutdown, so EOF is left to the server author.
+ *
+ * Several concurrently running servers are NOT leaks: each editor session legitimately owns one.
+ * The liveness test is a live client ancestor, not membership in the session doing the counting.
+ */
+export declare function serveUntilClosed(server: McpServer, options?: ServeOptions): Promise<void>;
+/**
+ * {@link serveUntilClosed}, then `process.exit(0)`.
+ *
+ * The explicit exit is needed because returning is not enough: the GLib main loop a gjsify CLI arms
+ * keeps the process parked at 0 % CPU with nothing left to serve, and only `process.exit()` tears
+ * it down. `return` in front is the house rule — a bare `process.exit()` under GJS schedules the
+ * exit and keeps running, which double-exits.
+ */
+export declare function serveStdio(server: McpServer, label?: string): Promise<never>;

package/lib/types/tool-result.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Every tool answers with a single JSON text block, so a client never has to guess. Errors carry
+ * the message only: the underlying failures are protocol errors whose stack traces contain
+ * hostnames and paths, and an MCP error string ends up in a transcript that outlives the request.
+ */
+export interface McpTextResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+    [key: string]: unknown;
+}
+export declare function mcpSuccess(data: unknown): McpTextResult;
+export declare function mcpError(message: string): McpTextResult;
+/** Error result from a caught value (the common `catch` handler). */
+export declare function mcpErrorFrom(err: unknown): McpTextResult;

package/package.json

@@ -0,0 +1,68 @@
+{
+    "name": "@gjsify/mcp",
+    "version": "0.53.0",
+    "description": "MCP server runtime for GJS and Node — default-deny read-only gate, stdio serve loop that ends on client EOF, uniform tool results",
+    "type": "module",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        }
+    },
+    "files": [
+        "lib"
+    ],
+    "scripts": {
+        "clear": "gjsify clear lib tmp tsconfig.tsbuildinfo test.gjs.mjs test.node.mjs",
+        "check": "gjsify tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+        "build:types": "gjsify tsc",
+        "build:test": "gjsify run build:test:gjs && gjsify run build:test:node",
+        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:node && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs",
+        "build:test:node": "gjsify build src/test.mts --app node --outfile test.node.mjs",
+        "test:node": "node test.node.mjs"
+    },
+    "keywords": [
+        "gjs",
+        "mcp",
+        "stdio",
+        "model-context-protocol",
+        "agent"
+    ],
+    "dependencies": {},
+    "peerDependencies": {
+        "@modelcontextprotocol/sdk": "^1.29.0"
+    },
+    "devDependencies": {
+        "@gjsify/cli": "^0.53.0",
+        "@gjsify/stream": "^0.53.0",
+        "@gjsify/unit": "^0.53.0",
+        "@modelcontextprotocol/sdk": "^1.29.0",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "gjsify": {
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "none",
+            "browser": "none",
+            "nativescript": "none"
+        },
+        "tier": 2
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/framework/mcp"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/framework/mcp#readme"
+}