@gjsify/mcp 0.59.0 → 0.60.0

package/README.md

@@ -17,6 +17,7 @@ await serveStdio(server, 'demo');
 | 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. |
+| `applyGrantGate(server, grants)` + `requiresCapability(config, { capability, targetOf })` | Per-capability successor ([ADR 0106](../../../docs/adr/0106-mcp-tools-register-per-granted-capability.md)). `grants` is the app's `{ capability, target }[]`. A tool registers if read-only, or if it declares a capability with ≥1 grant. The gate's wrapper also checks each call: the handler runs only when `targetOf(args)` equals a grant's target exactly; otherwise an MCP error names the capability. No capability names live here; no wildcards; empty targets are refused. `applyReadOnlyGate` is unchanged. |
 | `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. |

package/lib/esm/grant-gate.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{mcpError as e}from"./tool-result.js";const t=new WeakMap;function requiresCapability(e,n){return t.set(e,n),e}function applyGrantGate(n,r){let i=new Map;for(let e of r){if(typeof e.capability!=`string`||e.capability===``)throw Error(`grant: empty capability`);if(typeof e.target!=`string`||e.target===``)throw Error(`grant for ${e.capability}: empty target`);let t=i.get(e.capability);t||i.set(e.capability,t=new Set),t.add(e.target)}let a=n.registerTool.bind(n);n.registerTool=((n,r,o)=>{let s=r&&typeof r==`object`?t.get(r):void 0,c=r?.annotations?.readOnlyHint===!0;if(!s)return c?a(n,r,o):void 0;let l=i.get(s.capability);if(!c&&!l)return;let u=r?.inputSchema!==void 0,checked=async(...t)=>{let n=u?t[0]:{},r;try{r=s.targetOf(n)}catch{r=void 0}return typeof r!=`string`||r===``||!l?.has(r)?e(`capability ${s.capability} is not granted for this call`):o(...t)};return a(n,r,checked)})}export{applyGrantGate,requiresCapability};

package/lib/esm/index.js

@@ -1 +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};
+import{mcpError as e,mcpErrorFrom as t,mcpSuccess as n}from"./tool-result.js";import{applyGrantGate as r,requiresCapability as i}from"./grant-gate.js";import{applyReadOnlyGate as a}from"./read-only-gate.js";import{serveStdio as o,serveUntilClosed as s}from"./serve-stdio.js";export{r as applyGrantGate,a as applyReadOnlyGate,e as mcpError,t as mcpErrorFrom,n as mcpSuccess,i as requiresCapability,o as serveStdio,s as serveUntilClosed};

package/lib/types/grant-gate.d.ts

@@ -0,0 +1,37 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** One permission the app holds: a capability name the APP defines, bound to exactly one target. */
+export interface Grant {
+    capability: string;
+    target: string;
+}
+/** How a tool declares the write it performs and where the call aims it. */
+export interface CapabilitySpec<Args = Record<string, unknown>> {
+    capability: string;
+    /** Derive the target from the call's arguments. Empty, non-string or a throw refuses the call. */
+    targetOf(args: Args): string;
+}
+/** Declare the capability a tool needs. Returns `config` itself, so it composes inline. */
+export declare function requiresCapability<C extends object, Args = Record<string, unknown>>(config: C, spec: CapabilitySpec<Args>): C;
+/**
+ * Gate tools by grant, DEFAULT-DENY — the successor to {@link applyReadOnlyGate} for apps whose
+ * writes are permitted per capability.
+ *
+ * Registration: a tool registers if `annotations.readOnlyHint === true`, or if it declared a
+ * capability (via {@link requiresCapability}) and at least one grant for that capability exists.
+ * Anything else — no annotations, `readOnlyHint: false` without a capability, an ungranted
+ * capability — is DROPPED, so a forgotten declaration shows up as a missing tool, never as a
+ * reachable mutation.
+ *
+ * Call: THIS wrapper, not the tool, performs the check. A capability tool's handler is reached only
+ * after `targetOf(args)` returned a non-empty target that equals a grant's target for that
+ * capability, EXACTLY (no wildcards, no prefixes). Otherwise the call answers with an MCP error
+ * naming the capability. Because the check lives in the registration path, a tool cannot be
+ * registered with the check left out — and a forgotten check is the one failure that looks exactly
+ * like a working gate.
+ *
+ * gjsify holds no capability names: they, and the grants, belong to the app. The grant set is
+ * copied at call time of this function; later edits to the caller's array do not apply.
+ *
+ * Call this BEFORE registering anything — it wraps `registerTool`.
+ */
+export declare function applyGrantGate(server: McpServer, grants: readonly Grant[]): void;

package/lib/types/index.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/mcp",
-    "version": "0.59.0",
+    "version": "0.60.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",
@@ -36,15 +36,16 @@
     ],
     "dependencies": {},
     "peerDependencies": {
-        "@modelcontextprotocol/sdk": "^1.29.0"
+        "@modelcontextprotocol/sdk": "^1.32.1"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.59.0",
-        "@gjsify/stream": "^0.59.0",
-        "@gjsify/unit": "^0.59.0",
-        "@modelcontextprotocol/sdk": "^1.29.0",
+        "@gjsify/cli": "^0.60.0",
+        "@gjsify/stream": "^0.60.0",
+        "@gjsify/unit": "^0.60.0",
+        "@modelcontextprotocol/sdk": "^1.32.1",
         "@types/node": "^25.9.2",
-        "typescript": "^6.0.3"
+        "typescript": "^6.0.3",
+        "zod": "^4.4.3"
     },
     "gjsify": {
         "runtimes": {