@cogenta/mcp 0.1.4 → 0.3.0

package/README.md

@@ -0,0 +1,123 @@
+# `@cogenta/mcp` — connecting an MCP client to a Cogenta site
+
+This package is the MCP (Model Context Protocol) server and client primitives
+(`createMcpServer`, `serveMcpOverStdio`, `createMcpStdioClient`). The thing you
+actually run against a site is the CLI command built on top of it:
+
+```sh
+cogenta mcp
+```
+
+It starts a real MCP server on the process's own `stdin`/`stdout` — no HTTP
+port, no network listener — exposing this site's content tools (and, for an
+authenticated actor, its media and site-config tools) to whatever process
+spawned it: Claude Desktop, Claude Code, Cursor, or any other MCP client that
+speaks stdio.
+
+## Who the server runs as (R4)
+
+`cogenta mcp` never runs with an implicit admin identity. Pick one:
+
+```sh
+cogenta mcp --email you@example.com   # a real user, looked up in the site's own user store
+cogenta mcp --role viewer             # a synthetic actor for local testing, no real account
+cogenta mcp --api-key cogenta_sk_…    # a key minted from the admin's "MCP" or "Clés API" screen
+cogenta mcp                           # anonymous ("public") — the default, no flag needed
+```
+
+- **`--email`** resolves the account's real roles from the user store the
+  admin and REST API already share. The account must already exist —
+  `cogenta users create --email you@example.com --roles editor` first if it
+  doesn't. Every tool call this server makes then runs with exactly that
+  user's permissions, checked by the same `PermissionLayer` REST and GraphQL
+  use — a role that cannot publish over the admin UI cannot publish through
+  this server either.
+- **`--role`** hands a synthetic actor with the given role(s)
+  (comma-separated: `--role editor,reviewer`) and no real account behind it.
+  Meant for local testing against a scratch site, not for pointing a real
+  client at a real site.
+- **`--api-key`** resolves an actor from a machine-to-machine bearer key,
+  through the exact same `ApiKeyStore` (`@cogenta/auth`) and "roles = scope"
+  mapping REST's own `resolveActor` uses for a `cogenta_sk_…` bearer token —
+  one store, two callers. Mint one from the admin's dedicated **MCP** screen
+  (which also shows the client configuration below, pre-filled with the raw
+  key), or from the general-purpose **Clés API** screen — either works, since
+  a key is a key regardless of which screen minted it. A revoked, expired, or
+  unknown key refuses to start the server at all (`MCP_ACTOR_API_KEY_INVALID`)
+  rather than silently falling back to anonymous.
+- **With none of these flags**, the server runs as the anonymous `public`
+  actor —
+  the same actor an unauthenticated REST request gets. Content tools
+  (`content.read`, `content.write_draft`, `content.publish`,
+  `content.delete`) are still on the manifest and still permission-checked
+  per call, so a public actor can read what a public actor may read and
+  nothing else. Media, site-config and HTTP-fetch tools are left off the
+  manifest entirely in this mode — see "What's on the manifest" below for
+  why.
+
+## What's on the manifest
+
+Content tools are always on the manifest, authenticated or not, because their
+actual permission gate lives one layer down: they call into the site's real
+`ContentService`, which asserts against `PermissionLayer` on every read and
+write, exactly as `/api/content/*` does. There is nothing extra this server
+needs to enforce for them.
+
+Media (`media.read`, `media.write`) and site-config (`site.config_read`)
+tools have no such check of their own — by design, per their own doc
+comments in `@cogenta/agents`, *the manifest itself* is the permission gate
+for these three. `cogenta mcp` therefore only puts them on the manifest for
+an authenticated actor (`--email`, `--role`, or `--api-key`); the anonymous
+default never sees them at all, so there is no way to reach one without
+first naming who you are running as.
+
+## Connecting a client
+
+Every MCP client that supports a stdio server wants roughly the same three
+things: a command, its arguments, and the working directory to run it in
+(your site's root, next to `cogenta.config.mjs`).
+
+**Claude Desktop** (`claude_desktop_config.json`) / **Claude Code**
+(`.mcp.json` in your project, or `claude mcp add`) / **Cursor** (MCP settings)
+all accept this shape:
+
+```json
+{
+  "mcpServers": {
+    "cogenta": {
+      "command": "npx",
+      "args": ["cogenta", "mcp", "--email", "you@example.com"],
+      "cwd": "/absolute/path/to/my-site"
+    }
+  }
+}
+```
+
+Drop `--email …` for the anonymous default, swap it for `--role viewer`
+while testing locally, or swap it for `--api-key cogenta_sk_…` to connect
+with a key minted from the admin — the admin's **MCP** screen generates this
+exact JSON block for you, with the key already filled in, right after you
+create one. If `cogenta` is installed as a project dependency rather than
+globally, point `command` at the local binary instead of `npx` (for example
+`"command": "./node_modules/.bin/cogenta"`).
+
+`COGENTA_AUTH_SIGNING_KEY` and any other environment variables your site's
+`cogenta.config.mjs` needs must be visible to the spawned process — most
+clients accept an `"env"` block alongside `"command"`/`"args"` for exactly
+this; check your client's own MCP configuration docs for the exact key.
+
+## Known limitation
+
+Content written or published through `cogenta mcp` goes through the same
+`ContentStore` as `cogenta serve`'s REST and GraphQL routes, but **not**
+through the same decorated stores `assembleSite` builds — the full-text
+search index, the vector (semantic search) index, redirect tracking on a
+slug rename, and scheduled-publish enqueueing are all decorators applied at
+`cogenta serve` startup, and `cogenta mcp` does not currently wire them in.
+An entry an MCP client creates or edits is real, permission-checked content,
+immediately visible to `cogenta serve` on its next read — but it will not
+appear in full-text or semantic search results, and a slug rename will not
+leave a redirect, until the next full reindex (`cogenta`'s "Outils" admin
+screen, or a restart that touches the entry again). See `BLOCKERS.md`,
+"MCP actor scoping", for the fuller account and the reasoning behind not
+gold-plating this in the first pass.

package/dist/client/sandbox.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Fiche 58 task 1bis: "`cwd`: <répertoire dédié à la connexion, vidé avant/
+ * après>". A third-party `stdio` MCP server is spawned with this as its
+ * working directory instead of `process.cwd()` (which, for `cogenta serve`,
+ * is the site's own project root — secrets in `.env`, the schema, the
+ * database file for the `sqlite` driver) — a relative-path read/write the
+ * remote binary attempts lands in an empty scratch directory, not the site.
+ *
+ * Created fresh on connect and removed on close/dispose: nothing the remote
+ * process wrote there survives past the connection it belongs to.
+ */
+export interface SandboxWorkDir {
+    readonly path: string;
+    cleanup(): Promise<void>;
+}
+export declare function createSandboxWorkDir(prefix?: string): Promise<SandboxWorkDir>;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/client/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/client/sandbox.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB;AAED,wBAAsB,oBAAoB,CACxC,MAAM,SAAyB,GAC9B,OAAO,CAAC,cAAc,CAAC,CAmBzB"}

package/dist/client/sandbox.js

@@ -0,0 +1,24 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+export async function createSandboxWorkDir(prefix = 'cogenta-mcp-sandbox-') {
+    const path = await mkdtemp(join(tmpdir(), prefix));
+    return {
+        path,
+        async cleanup() {
+            // `McpClient.close()` kills the child process but does not wait for
+            // it to actually exit — on Windows specifically, the OS keeps a
+            // spawned process's working directory locked for a short window
+            // after `kill()` is issued, until the process has actually finished
+            // tearing down. A bare `rm` right after `close()` can race that and
+            // fail with `EBUSY`/`EPERM` — found for real running this package's
+            // own end-to-end test against a genuinely spawned process (never
+            // reproduced against the fake `spawnFn` this package's unit tests
+            // use, which never holds a real OS handle on `path` at all).
+            // `maxRetries`/`retryDelay` are `fs.rm`'s own documented answer to
+            // exactly this Windows race, not a bespoke retry loop.
+            await rm(path, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+        },
+    };
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/client/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../src/client/sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAmBhC,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAAM,GAAG,sBAAsB;IAE/B,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,CAAA;IAClD,OAAO;QACL,IAAI;QACJ,KAAK,CAAC,OAAO;YACX,oEAAoE;YACpE,gEAAgE;YAChE,gEAAgE;YAChE,oEAAoE;YACpE,oEAAoE;YACpE,oEAAoE;YACpE,iEAAiE;YACjE,kEAAkE;YAClE,6DAA6D;YAC7D,mEAAmE;YACnE,uDAAuD;YACvD,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAA;QAClF,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/client/stdio-client.d.ts

@@ -1,9 +1,58 @@
+import { type Logger } from '@cogenta/core';
 import type { ChildProcessLike, McpClient } from './types.js';
+import { type ReadPidUsage } from './watchdog.js';
+/**
+ * The exact options `child_process.spawn` receives for one connection —
+ * pulled out so `spawnFn` (real spawn in production, a fake in tests) sees
+ * precisely what this client decided to hand the OS, nothing implicit.
+ */
+export interface SpawnOptionsForClient {
+    readonly env: Readonly<Record<string, string>>;
+    readonly cwd: string;
+}
 export interface McpStdioClientOptions {
     readonly command: string;
     readonly args?: readonly string[];
-    /** Injectable for tests — defaults to `node:child_process.spawn`, piping stdio. */
-    readonly spawnFn?: (command: string, args: readonly string[]) => ChildProcessLike;
+    /**
+     * The exact environment the spawned process receives. **Never**
+     * `process.env`, and never merged with it — the previous default (no
+     * `env` at all, which `child_process.spawn` resolves to "inherit the
+     * host's environment") handed a third-party binary every secret this
+     * process had, including `COGENTA_AUTH_SIGNING_KEY`, before the server
+     * had even been asked to `initialize()`. Omit this option (or pass `{}`)
+     * for a process that receives no environment variables at all; list
+     * exactly what it needs otherwise.
+     */
+    readonly env?: Readonly<Record<string, string>>;
+    /**
+     * A dedicated working directory for this one connection — see
+     * `./sandbox.js`'s `createSandboxWorkDir`. Required, deliberately: there
+     * is no safe implicit default (`process.cwd()` for `cogenta serve` is the
+     * site's own project root).
+     */
+    readonly cwd: string;
+    /**
+     * Where captured stderr is logged, structured, through this project's own
+     * redaction-aware logger — never `stdio: [...,...,'inherit']`, which
+     * would both bypass that logger's secret-redaction policy and let a
+     * hostile server inject arbitrary bytes into the host's own log stream.
+     * Defaults to a silent logger (still captured, just not emitted) so a
+     * caller that has no logger handy yet does not need to build one.
+     */
+    readonly logger?: Logger;
+    /** Hard ceiling on one JSON-RPC round trip (`initialize`, `tools/list`, or `tools/call`) — exceeded, the child process is killed and every pending call (this one included) rejects. A server that never responds cannot block a run indefinitely. */
+    readonly callTimeoutMs?: number;
+    /** Caps how many bytes of stderr are buffered/logged for this connection — a hostile or merely buggy server flooding stderr cannot exhaust host memory or log storage. */
+    readonly maxStderrBytes?: number;
+    /** `undefined` disables the memory ceiling. Defaults to 512 MiB — generous for a tool server, small enough to catch a runaway process. */
+    readonly maxRssBytes?: number;
+    /** `undefined` disables the CPU ceiling. Defaults to 200 (i.e. 200%, two full cores) — see `./watchdog.js`'s own module comment on why this is a floor, not a guarantee. */
+    readonly maxCpuPercent?: number;
+    readonly watchdogPollMs?: number;
+    /** Injectable for tests — defaults to the real `ps`/PowerShell probe (`./watchdog.js`). */
+    readonly readPidUsage?: ReadPidUsage;
+    /** Injectable for tests — defaults to `node:child_process.spawn`, always piping all three streams. */
+    readonly spawnFn?: (command: string, args: readonly string[], spawnOptions: SpawnOptionsForClient) => ChildProcessLike;
 }
 /**
  * The same JSON-RPC-per-line protocol `serveMcpOverStdio` (task 17) speaks,
@@ -12,6 +61,14 @@ export interface McpStdioClientOptions {
  * des serveurs tiers" — this is that consumption; `wrapMcpTool` is what
  * turns what it discovers into something the runtime can actually grant to
  * an agent, with permissions declared exactly like an internal tool.
+ *
+ * Fiche 58 task 1bis's plancher de sandboxing lives here: no implicit
+ * environment inheritance, no `inherit` stdio, a hard per-call timeout that
+ * kills the process, and a best-effort memory/CPU watchdog. None of this
+ * makes running an arbitrary third-party binary safe — it runs with the
+ * full OS privileges of the Cogenta process, always (see the registry
+ * layer's mandatory confirmation, `../registry/store.js`) — it only removes
+ * the specific, structural leaks a naive `spawn()` would otherwise have.
  */
 export declare function createMcpStdioClient(options: McpStdioClientOptions): McpClient;
 //# sourceMappingURL=stdio-client.d.ts.map

package/dist/client/stdio-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stdio-client.d.ts","sourceRoot":"","sources":["../../src/client/stdio-client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,gBAAgB,EAChB,SAAS,EAIV,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,gBAAgB,CAAA;CAClF;AAOD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,SAAS,CA+D9E"}
+{"version":3,"file":"stdio-client.d.ts","sourceRoot":"","sources":["../../src/client/stdio-client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,eAAe,CAAA;AAEzD,OAAO,KAAK,EACV,gBAAgB,EAEhB,SAAS,EAIV,MAAM,YAAY,CAAA;AACnB,OAAO,EAAoB,KAAK,YAAY,EAAoB,MAAM,eAAe,CAAA;AAErF;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC;;;;;;;;;OASG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC/C;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,sPAAsP;IACtP,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,0KAA0K;IAC1K,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,0IAA0I;IAC1I,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,4KAA4K;IAC5K,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,2FAA2F;IAC3F,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAA;IACpC,sGAAsG;IACtG,QAAQ,CAAC,OAAO,CAAC,EAAE,CACjB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,YAAY,EAAE,qBAAqB,KAChC,gBAAgB,CAAA;CACtB;AAsCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,SAAS,CA0O9E"}

package/dist/client/stdio-client.js

@@ -1,9 +1,35 @@
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
 import { CogentaError } from '@cogenta/core';
-function defaultSpawn(command, args) {
-    const child = spawn(command, [...args], { stdio: ['pipe', 'pipe', 'inherit'] });
-    return { stdin: child.stdin, stdout: child.stdout, kill: () => child.kill() };
+import { startPidWatchdog } from './watchdog.js';
+const DEFAULT_CALL_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_STDERR_BYTES = 64 * 1024;
+const DEFAULT_MAX_RSS_BYTES = 512 * 1024 * 1024;
+const DEFAULT_MAX_CPU_PERCENT = 200;
+function defaultSpawn(command, args, options) {
+    // stdio is always fully piped — never `inherit` on stdout or stderr (fiche 58
+    // task 1bis): `inherit` on stderr would both bypass the structured
+    // logger's secret-redaction policy and let a hostile server write
+    // arbitrary bytes straight into the host process's own log stream.
+    const child = spawn(command, [...args], {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        cwd: options.cwd,
+        env: options.env,
+    });
+    return child;
+}
+function silentLogger() {
+    const noop = () => undefined;
+    const logger = {
+        level: 'silent',
+        debug: noop,
+        info: noop,
+        warn: noop,
+        error: noop,
+        child: () => logger,
+        isLevelEnabled: () => false,
+    };
+    return logger;
 }
 /**
  * The same JSON-RPC-per-line protocol `serveMcpOverStdio` (task 17) speaks,
@@ -12,13 +38,105 @@ function defaultSpawn(command, args) {
  * des serveurs tiers" — this is that consumption; `wrapMcpTool` is what
  * turns what it discovers into something the runtime can actually grant to
  * an agent, with permissions declared exactly like an internal tool.
+ *
+ * Fiche 58 task 1bis's plancher de sandboxing lives here: no implicit
+ * environment inheritance, no `inherit` stdio, a hard per-call timeout that
+ * kills the process, and a best-effort memory/CPU watchdog. None of this
+ * makes running an arbitrary third-party binary safe — it runs with the
+ * full OS privileges of the Cogenta process, always (see the registry
+ * layer's mandatory confirmation, `../registry/store.js`) — it only removes
+ * the specific, structural leaks a naive `spawn()` would otherwise have.
  */
 export function createMcpStdioClient(options) {
     const spawnFn = options.spawnFn ?? defaultSpawn;
-    const child = spawnFn(options.command, options.args ?? []);
+    const env = options.env ?? {};
+    const callTimeoutMs = options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+    const maxStderrBytes = options.maxStderrBytes ?? DEFAULT_MAX_STDERR_BYTES;
+    const maxRssBytes = options.maxRssBytes ?? DEFAULT_MAX_RSS_BYTES;
+    const maxCpuPercent = options.maxCpuPercent ?? DEFAULT_MAX_CPU_PERCENT;
+    const logger = options.logger ?? silentLogger();
+    const child = spawnFn(options.command, options.args ?? [], { env, cwd: options.cwd });
     const rl = createInterface({ input: child.stdout });
     const pending = new Map();
     let nextId = 1;
+    let closed = false;
+    let stderrBytesLogged = 0;
+    let stderrTruncated = false;
+    let watchdog;
+    function rejectAllPending(error) {
+        for (const [, entry] of pending)
+            entry.reject(error);
+        pending.clear();
+    }
+    function killAndRejectAll(error) {
+        try {
+            child.kill();
+        }
+        catch {
+            // already gone
+        }
+        rejectAllPending(error);
+    }
+    // stderr is always captured, never left to `inherit` — logged through the
+    // structured logger (which owns secret redaction), capped so a flood
+    // cannot exhaust memory or log storage.
+    if (child.stderr !== undefined) {
+        const stderrRl = createInterface({ input: child.stderr });
+        stderrRl.on('line', (line) => {
+            if (stderrBytesLogged >= maxStderrBytes) {
+                if (!stderrTruncated) {
+                    stderrTruncated = true;
+                    logger.warn('mcp client: remote stderr truncated (cap reached)', {
+                        command: options.command,
+                        maxStderrBytes,
+                    });
+                }
+                return;
+            }
+            stderrBytesLogged += Buffer.byteLength(line, 'utf8');
+            logger.warn('mcp client: remote stderr', { command: options.command, line });
+        });
+    }
+    child.once?.('exit', () => {
+        if (closed)
+            return;
+        killAndRejectAll(new CogentaError({
+            code: 'MCP_CLIENT_PROCESS_EXITED',
+            message: 'The MCP server process exited before responding.',
+            hint: "Check this connection's captured stderr for why it exited.",
+        }));
+    });
+    child.once?.('error', (error) => {
+        killAndRejectAll(new CogentaError({
+            code: 'MCP_CLIENT_SPAWN_FAILED',
+            message: `Could not start the MCP server process: ${error instanceof Error ? error.message : String(error)}`,
+            hint: 'Check the command and arguments configured for this connection.',
+            cause: error,
+        }));
+    });
+    if (child.pid !== undefined && (maxRssBytes !== undefined || maxCpuPercent !== undefined)) {
+        watchdog = startPidWatchdog({
+            pid: child.pid,
+            ...(options.watchdogPollMs === undefined ? {} : { pollMs: options.watchdogPollMs }),
+            ...(maxRssBytes === undefined ? {} : { maxRssBytes }),
+            ...(maxCpuPercent === undefined ? {} : { maxCpuPercent }),
+            ...(options.readPidUsage === undefined ? {} : { readUsage: options.readPidUsage }),
+            onExceeded: (usage, reason) => {
+                logger.error('mcp client: resource ceiling exceeded, killing the process', {
+                    command: options.command,
+                    reason,
+                    rssBytes: usage.rssBytes,
+                    cpuPercent: usage.cpuPercent,
+                });
+                killAndRejectAll(new CogentaError({
+                    code: 'MCP_CLIENT_RESOURCE_EXCEEDED',
+                    message: `The MCP server process exceeded its ${reason} ceiling and was killed.`,
+                    hint: 'This is a best-effort floor (see docs/05-securite.md) — a repeatedly misbehaving server should be disabled from the admin\'s "MCP Clients" screen.',
+                    details: { reason, rssBytes: usage.rssBytes, cpuPercent: usage.cpuPercent },
+                }));
+            },
+        });
+    }
     rl.on('line', (line) => {
         const trimmed = line.trim();
         if (trimmed === '')
@@ -32,45 +150,103 @@ export function createMcpStdioClient(options) {
         }
         if (typeof response.id !== 'number')
             return;
-        const resolve = pending.get(response.id);
-        if (resolve === undefined)
+        const entry = pending.get(response.id);
+        if (entry === undefined)
             return;
         pending.delete(response.id);
-        resolve(response);
+        entry.resolve(response);
     });
-    function send(method, params) {
+    function send(method, params, callOptions) {
         const id = nextId++;
         return new Promise((resolve, reject) => {
-            pending.set(id, (response) => {
-                if ('error' in response) {
-                    reject(new CogentaError({
-                        code: 'MCP_CLIENT_REMOTE_ERROR',
-                        message: response.error.message,
-                        hint: 'The remote MCP server reported a protocol-level error, not a tool failure.',
-                        details: { code: response.error.code, data: response.error.data },
-                    }));
+            let settled = false;
+            // Deliberately does not touch `settled`/`pending` itself: `resolve`
+            // already clears this timer on a real response, so if this fires the
+            // call is genuinely still outstanding. `killAndRejectAll` rejects
+            // through this call's own `pending` entry below (whose `reject`
+            // closure is what actually settles this promise), and every other
+            // still-outstanding call on the same connection with it — a server
+            // that stops answering is presumed dead for all of them, not just
+            // the one that happened to hit the timeout first.
+            const timer = setTimeout(() => {
+                killAndRejectAll(new CogentaError({
+                    code: 'MCP_CLIENT_CALL_TIMEOUT',
+                    message: `"${method}" on the MCP server did not respond within ${callTimeoutMs}ms.`,
+                    hint: 'The server process has been killed and every pending call on this connection has been rejected. Raise callTimeoutMs only for a server known to be legitimately slow — never to mask a hang.',
+                }));
+            }, callTimeoutMs);
+            timer.unref?.();
+            const onAbort = () => {
+                if (settled)
                     return;
-                }
-                resolve(response.result);
+                settled = true;
+                clearTimeout(timer);
+                pending.delete(id);
+                reject(new CogentaError({
+                    code: 'MCP_CLIENT_CALL_ABORTED',
+                    message: `"${method}" was cancelled before the MCP server responded.`,
+                    hint: "The caller's own signal was aborted — this is not a server failure.",
+                }));
+            };
+            callOptions?.signal?.addEventListener('abort', onAbort, { once: true });
+            pending.set(id, {
+                resolve: (response) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    callOptions?.signal?.removeEventListener('abort', onAbort);
+                    if ('error' in response) {
+                        reject(new CogentaError({
+                            code: 'MCP_CLIENT_REMOTE_ERROR',
+                            message: response.error.message,
+                            hint: 'The remote MCP server reported a protocol-level error, not a tool failure.',
+                            details: { code: response.error.code, data: response.error.data },
+                        }));
+                        return;
+                    }
+                    resolve(response.result);
+                },
+                reject: (error) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    callOptions?.signal?.removeEventListener('abort', onAbort);
+                    reject(error);
+                },
             });
             child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, ...(params === undefined ? {} : { params }) })}\n`);
         });
     }
     return {
-        async initialize() {
-            const result = (await send('initialize'));
+        pid: child.pid,
+        async initialize(callOptions) {
+            const result = (await send('initialize', undefined, callOptions));
             return result.serverInfo;
         },
-        async listTools() {
-            const result = (await send('tools/list'));
+        async listTools(callOptions) {
+            const result = (await send('tools/list', undefined, callOptions));
             return result.tools;
         },
-        async callTool(name, args) {
-            return (await send('tools/call', { name, arguments: args }));
+        async callTool(name, args, callOptions) {
+            return (await send('tools/call', { name, arguments: args }, callOptions));
         },
         close() {
+            closed = true;
+            watchdog?.stop();
             rl.close();
-            child.kill();
+            rejectAllPending(new CogentaError({
+                code: 'MCP_CLIENT_CLOSED',
+                message: 'This MCP connection was closed.',
+                hint: 'Reconnect if you still need this server.',
+            }));
+            try {
+                child.kill();
+            }
+            catch {
+                // already gone
+            }
         },
     };
 }

package/dist/client/stdio-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"stdio-client.js","sourceRoot":"","sources":["../../src/client/stdio-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stdio-client.js","sourceRoot":"","sources":["../../src/client/stdio-client.ts"],"names":[],"mappings":"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"}

package/dist/client/types.d.ts

@@ -16,16 +16,33 @@ export interface McpServerInfo {
     readonly name: string;
     readonly version: string;
 }
+/** Per-call cancellation — distinct from the connection-wide hard timeout every call already has (fiche 58 task 1bis): a caller can cancel one in-flight call early (e.g. the agent run's own `ctx.signal`), which — like the timeout — kills the underlying process rather than leaving it running unobserved. */
+export interface McpCallOptions {
+    readonly signal?: AbortSignal;
+}
 export interface McpClient {
-    initialize(): Promise<McpServerInfo>;
-    listTools(): Promise<readonly McpToolSpec[]>;
-    callTool(name: string, args: Readonly<Record<string, unknown>>): Promise<McpToolCallResult>;
+    initialize(options?: McpCallOptions): Promise<McpServerInfo>;
+    listTools(options?: McpCallOptions): Promise<readonly McpToolSpec[]>;
+    callTool(name: string, args: Readonly<Record<string, unknown>>, options?: McpCallOptions): Promise<McpToolCallResult>;
+    /** The OS process id backing this connection, when known — `undefined` for a fake used in a test. Exposed so a caller can run its own external supervision (a cgroup, a Job Object) against the real process, on top of this client's own best-effort watchdog. */
+    readonly pid: number | undefined;
     close(): void;
 }
-/** The minimal shape a spawned MCP server process needs — real `child_process.spawn()` already satisfies this; tests inject a fake. */
+/**
+ * The minimal shape a spawned MCP server process needs — real
+ * `child_process.spawn()` already satisfies this structurally; tests inject
+ * a fake. `stderr`/`pid`/`once` are new since fiche 58 task 1bis: stdio is
+ * always `['pipe', 'pipe', 'pipe']` now (never `inherit`), so stderr must be
+ * readable from here, `pid` backs the memory/CPU watchdog, and `once` lets
+ * the client notice the process dying on its own (crash, kill from outside)
+ * instead of leaving pending calls hanging forever.
+ */
 export interface ChildProcessLike {
     readonly stdin: Writable;
     readonly stdout: Readable;
+    readonly stderr?: Readable;
+    readonly pid?: number;
     kill(): void;
+    once?(event: 'exit' | 'error', listener: (...args: unknown[]) => void): void;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/client/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAErD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACxD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAA;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,IAAI,OAAO,CAAC,aAAa,CAAC,CAAA;IACpC,SAAS,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAA;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAC3F,KAAK,IAAI,IAAI,CAAA;CACd;AAED,uIAAuI;AACvI,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;IACzB,IAAI,IAAI,IAAI,CAAA;CACb"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAErD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACxD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAA;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,mTAAmT;AACnT,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAC5D,SAAS,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAA;IACpE,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAC7B,mQAAmQ;IACnQ,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,KAAK,IAAI,IAAI,CAAA;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAA;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,IAAI,IAAI,IAAI,CAAA;IACZ,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAA;CAC7E"}