@cratis/pi 7.94.0 → 7.95.0

package/README.md

@@ -33,6 +33,20 @@ yields to the managed installation to avoid duplicate resources and hooks. The P
 package manages only Pi; it neither configures other harnesses nor owns a local
 managed corpus.
 
+## MCP servers from the corpus
+
+The packaged `cratis-mcp` extension starts every stdio server declared in
+`mcp-servers.json` whose `profiles` intersect the profiles listed explicitly in
+`.cratis/ai.json` (a profile reached only through another profile's `composes` does
+not start a server; Screenplay keeps its composed selection) (for
+example `codescene` for `cratis/codescene`, `playwright` for `cratis/playwright`).
+Each server gets its own connection, so one failing to start never stops the others,
+and its tools are namespaced by server id (`playwright_browser_navigate`). The
+`command`, `args` and optional literal `env` are used verbatim, without a shell. A
+malformed selected server is skipped with one notice; set
+`mcpServers.<id>.enabled` to `false` in `.cratis/ai.json` to opt a server out.
+`capabilities.json` beside the extension declares this behavior to the Cratis CLI.
+
 ## Screenplay MCP tools
 
 The packaged `cratis-mcp` extension starts the Screenplay MCP server

package/package/corpus/harnesses/pi/extensions/cratis-mcp/CorpusServer.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** A validated stdio server from the corpus descriptor; command, args and env are used verbatim. */
+export interface CorpusServer {
+    id: string;
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+}
+
+/** The servers to start for a project plus the explicit messages for everything skipped. */
+export interface ServerSelection {
+    servers: CorpusServer[];
+    messages: string[];
+}

package/package/corpus/harnesses/pi/extensions/cratis-mcp/ServerBridge.ts

@@ -0,0 +1,113 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { object } from './configuration.ts';
+import type { CorpusServer } from './CorpusServer.ts';
+import { startServer } from './process.ts';
+import { discoverServer, mapServerResult, type ServerCatalog } from './serverProtocol.ts';
+import { selectedCorpusServers } from './servers.ts';
+import type { StdioConnection } from './StdioConnection.ts';
+
+function withDeadline<T>(work: Promise<T>, milliseconds: number, id: string): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const expired = new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`MCP server '${id}' did not become ready within ${milliseconds} ms.`)), milliseconds);
+        timer.unref();
+    });
+    work.catch(() => { /* The deadline already reported the outcome; the disposed connection rejects the abandoned request. */ });
+    return Promise.race([work, expired]).finally(() => clearTimeout(timer));
+}
+
+/** Bridge every selected corpus server except Screenplay: one connection each, isolated failures, tools namespaced by server id. */
+export interface ServerBridge {
+    refresh(context: ExtensionContext, newSession: boolean): Promise<void>;
+    dispose(): void;
+}
+
+export function createServerBridge(pi: ExtensionAPI, corpus: string, connect: (project: string, server: CorpusServer) => StdioConnection = startServer, deadlineMilliseconds = 15_000): ServerBridge {
+    const connections = new Map<string, StdioConnection>();
+    const registered = new Set<string>();
+    const paused = new Set<string>();
+    let selectionKey: string | undefined;
+
+    const notify = (context: ExtensionContext, messages: string[]): void => {
+        if (context.hasUI) messages.forEach(message => context.ui.notify(message, 'warning'));
+    };
+    const deactivate = (): void => {
+        const active = pi.getActiveTools();
+        active.filter(name => registered.has(name)).forEach(name => paused.add(name));
+        if (active.some(name => registered.has(name))) pi.setActiveTools(active.filter(name => !registered.has(name)));
+    };
+    const dispose = (): void => {
+        connections.forEach(connection => connection.dispose());
+        connections.clear();
+        deactivate();
+    };
+    interface Started { server: CorpusServer; connection: StdioConnection; catalog?: ServerCatalog; messages: string[] }
+    /** Connect and discover only; registration happens afterwards in selection order so name claims are deterministic. */
+    const start = async (context: ExtensionContext, server: CorpusServer): Promise<Started> => {
+        const connection = connect(context.cwd, server);
+        connections.set(server.id, connection);
+        try {
+            const catalog = await withDeadline(discoverServer(connection, server.id), deadlineMilliseconds, server.id);
+            if (connections.get(server.id) !== connection || connection.stopped) throw new Error(`MCP server '${server.id}' session ended during discovery.`);
+            return { server, connection, catalog, messages: [...catalog.messages] };
+        } catch (error) {
+            connection.dispose();
+            if (connections.get(server.id) === connection) connections.delete(server.id);
+            return { server, connection, messages: [`MCP server '${server.id}' is unavailable: ${error instanceof Error ? error.message : String(error)}`] };
+        }
+    };
+    const register = ({ server, connection, catalog, messages }: Started, claimed: Set<string>): void => {
+        const existing = new Set(pi.getAllTools().map(tool => tool.name));
+        for (const tool of catalog?.tools ?? []) {
+            if (claimed.has(tool.nativeName) || (existing.has(tool.nativeName) && !registered.has(tool.nativeName))) {
+                messages.push(`MCP server '${server.id}' tool '${tool.name}' was skipped: '${tool.nativeName}' conflicts with another tool.`);
+                continue;
+            }
+            claimed.add(tool.nativeName);
+            pi.registerTool({
+                name: tool.nativeName,
+                label: `${server.id} ${tool.name}`,
+                description: tool.description,
+                parameters: tool.parameters,
+                executionMode: 'sequential',
+                async execute(_toolCallId, parameters, signal) {
+                    if (connections.get(server.id) !== connection || connection.stopped || !pi.getActiveTools().includes(tool.nativeName)) {
+                        throw new Error(`MCP server '${server.id}' is unavailable in this session.`);
+                    }
+                    if (!object(parameters)) throw new Error('MCP arguments must be an object.');
+                    const result = mapServerResult(await connection.request('tools/call', { name: tool.name, arguments: parameters }, signal), server.id);
+                    if (result.details.isError) throw new Error(result.content.map(part => part.type === 'text' ? part.text : '').join('\n') || `MCP server '${server.id}' reported a failed tool call.`);
+                    return result;
+                },
+            });
+        }
+    };
+    const refresh = async (context: ExtensionContext, newSession: boolean): Promise<void> => {
+        let selection: ReturnType<typeof selectedCorpusServers>;
+        try { selection = selectedCorpusServers(context.cwd, corpus); }
+        catch (error) { dispose(); selectionKey = undefined; throw error; }
+        const key = JSON.stringify(selection);
+        if (!newSession && key === selectionKey) return;
+        const previouslyActive = new Set([...pi.getActiveTools(), ...paused]);
+        const oldNames = new Set(registered);
+        dispose();
+        selectionKey = key;
+        const messages = [...selection.messages];
+        const claimed = new Set<string>();
+        // Servers start in parallel; a slow or hung one is abandoned at its own deadline and never delays the others.
+        const outcomes = await Promise.all(selection.servers.map(server => start(context, server)));
+        for (const outcome of outcomes) { register(outcome, claimed); messages.push(...outcome.messages); }
+        claimed.forEach(name => registered.add(name));
+        // Never re-enable a user-disabled tool. SDK allow/exclude restrictions still filter registration.
+        const next = pi.getActiveTools().filter(name => !registered.has(name) || (claimed.has(name) && (!oldNames.has(name) || previouslyActive.has(name))));
+        for (const name of claimed) if (oldNames.has(name) && previouslyActive.has(name)) next.push(name);
+        pi.setActiveTools([...new Set(next)]);
+        paused.clear();
+        notify(context, messages);
+    };
+
+    return { refresh, dispose: () => { dispose(); selectionKey = undefined; } };
+}

package/package/corpus/harnesses/pi/extensions/cratis-mcp/StdioConnection.ts

@@ -15,7 +15,7 @@ export class StdioConnection {
     private _termination?: ReturnType<typeof setTimeout>;
     private readonly _maximumBytes = 8 * 1024 * 1024;
 
-    constructor(private readonly _child: ChildProcessWithoutNullStreams, private readonly _timeout = 30_000) {
+    constructor(private readonly _child: ChildProcessWithoutNullStreams, private readonly _timeout = 30_000, private readonly _label = 'Screenplay', private readonly _tolerant = false) {
         _child.stdout.on('data', this.receive);
         _child.stdout.on('end', this.ended);
         _child.stdout.on('error', this.streamFailed);
@@ -32,22 +32,22 @@ export class StdioConnection {
 
     async request(method: string, params: Record<string, unknown>, signal?: AbortSignal, mutation = false): Promise<unknown> {
         if (this._failure) throw this._failure;
-        if (signal?.aborted) throw new ConnectionFailure('Screenplay request cancelled before sending.');
-        if (this._pending) throw new ConnectionFailure('Screenplay is busy; parallel requests are not queued.');
+        if (signal?.aborted) throw new ConnectionFailure(`${this._label} request cancelled before sending.`);
+        if (this._pending) throw new ConnectionFailure(`${this._label} is busy; parallel requests are not queued.`);
         const id = ++this._sequence;
         const line = this.encode({ jsonrpc: '2.0', id, method, params });
         return new Promise((resolve, reject) => {
-            const abort = () => this.stop('Screenplay request cancelled after sending.');
-            const timer = setTimeout(() => this.stop('Screenplay request timed out.'), this._timeout);
+            const abort = () => this.stop(`${this._label} request cancelled after sending.`);
+            const timer = setTimeout(() => this.stop(`${this._label} request timed out.`), this._timeout);
             this._pending = {
                 id, mutation, resolve, reject,
                 cleanup: () => { clearTimeout(timer); signal?.removeEventListener('abort', abort); },
             };
             signal?.addEventListener('abort', abort, { once: true });
             try {
-                this._child.stdin.write(line, error => { if (error) this.stop('Screenplay input pipe failed.'); });
+                this._child.stdin.write(line, error => { if (error) this.stop(`${this._label} input pipe failed.`); });
             } catch {
-                this.stop('Screenplay input pipe failed.');
+                this.stop(`${this._label} input pipe failed.`);
             }
         });
     }
@@ -55,18 +55,18 @@ export class StdioConnection {
     notify(method: string): void {
         if (this._failure) throw this._failure;
         try {
-            this._child.stdin.write(this.encode({ jsonrpc: '2.0', method }), error => { if (error) this.stop('Screenplay notification failed.'); });
+            this._child.stdin.write(this.encode({ jsonrpc: '2.0', method }), error => { if (error) this.stop(`${this._label} notification failed.`); });
         } catch {
-            this.stop('Screenplay notification failed.');
+            this.stop(`${this._label} notification failed.`);
             throw this._failure;
         }
     }
 
-    dispose(): void { this.stop('Screenplay session closed.'); }
+    dispose(): void { this.stop(`${this._label} session closed.`); }
 
     private encode(value: unknown): string {
         const line = `${JSON.stringify(value)}\n`;
-        if (Buffer.byteLength(line) > this._maximumBytes) throw new ConnectionFailure('Screenplay request exceeds the 8 MiB transport limit.');
+        if (Buffer.byteLength(line) > this._maximumBytes) throw new ConnectionFailure(`${this._label} request exceeds the 8 MiB transport limit.`);
         return line;
     }
 
@@ -82,7 +82,7 @@ export class StdioConnection {
                 this._buffer = Buffer.alloc(0);
                 this.accept(line);
             } catch {
-                this.stop('Screenplay returned invalid UTF-8 protocol data.');
+                this.stop(`${this._label} returned invalid UTF-8 protocol data.`);
             }
             if (this.stopped) return;
             start = index + 1;
@@ -92,7 +92,7 @@ export class StdioConnection {
 
     private append(chunk: Buffer): boolean {
         if (this._buffer.length + chunk.length > this._maximumBytes) {
-            this.stop('Screenplay response exceeds the 8 MiB transport limit.');
+            this.stop(`${this._label} response exceeds the 8 MiB transport limit.`);
             return false;
         }
         this._buffer = Buffer.concat([this._buffer, chunk]);
@@ -103,6 +103,13 @@ export class StdioConnection {
         try {
             const message: unknown = JSON.parse(line);
             if (!object(message) || message.jsonrpc !== '2.0') throw new Error();
+            if ('method' in message && this._tolerant) {
+                // Third-party servers may notify or ask; this client offers no capabilities, so refuse requests and ignore notifications.
+                if ('id' in message && typeof message.method === 'string') {
+                    this._child.stdin.write(this.encode({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: 'Method not found' } }));
+                }
+                return;
+            }
             if ('method' in message) {
                 // This pinned server does not send requests or changing tool lists.
                 throw new Error();
@@ -113,14 +120,14 @@ export class StdioConnection {
             this._pending = undefined;
             pending.cleanup();
             if (object(message.error)) {
-                pending.reject(new ConnectionFailure(`Screenplay protocol error ${message.error.code}: ${message.error.message}`, pending.mutation));
+                pending.reject(new ConnectionFailure(`${this._label} protocol error ${message.error.code}: ${message.error.message}`, pending.mutation));
                 // A server failure during mutation is not evidence that nothing was written.
-                if (pending.mutation) this.stop('Screenplay mutation failed with a protocol error.', true);
+                if (pending.mutation) this.stop(`${this._label} mutation failed with a protocol error.`, true);
             } else {
                 pending.resolve(message.result);
             }
         } catch {
-            this.stop('Screenplay returned malformed or unexpected JSON-RPC.');
+            this.stop(`${this._label} returned malformed or unexpected JSON-RPC.`);
         }
     }
 
@@ -145,11 +152,13 @@ export class StdioConnection {
     }
 
     private readonly drain = (): void => { /* Drain server stderr without exposing it as a protocol result. */ };
-    private readonly ended = (): void => this.stop('Screenplay output closed before session shutdown.');
-    private readonly streamFailed = (): void => this.stop('Screenplay stdio failed.');
-    private readonly spawnFailed = (): void => this.stop('Cannot launch native cratis screenplay mcp. Install/update the Cratis CLI through its normal channel; this extension never downloads a runtime.');
+    private readonly ended = (): void => this.stop(`${this._label} output closed before session shutdown.`);
+    private readonly streamFailed = (): void => this.stop(`${this._label} stdio failed.`);
+    private readonly spawnFailed = (): void => this.stop(this._label !== 'Screenplay'
+        ? `Cannot launch the ${this._label} MCP server command. Check that it is installed; this extension never downloads a runtime.`
+        : 'Cannot launch native cratis screenplay mcp. Install/update the Cratis CLI through its normal channel; this extension never downloads a runtime.');
     private readonly closed = (): void => {
-        this.stop('Screenplay process exited. Check that the installed Cratis CLI includes the embedded Screenplay runtime; no runtime is downloaded by this extension.');
+        this.stop(this._label !== 'Screenplay' ? `${this._label} process exited.` : 'Screenplay process exited. Check that the installed Cratis CLI includes the embedded Screenplay runtime; no runtime is downloaded by this extension.');
         clearTimeout(this._termination);
         this._child.stdout.removeListener('error', this.streamFailed);
         this._child.stdin.removeListener('error', this.streamFailed);

package/package/corpus/harnesses/pi/extensions/cratis-mcp/capabilities.json

@@ -0,0 +1 @@
+{ "servers": "selected-profiles" }

package/package/corpus/harnesses/pi/extensions/cratis-mcp/configuration.ts

@@ -8,7 +8,7 @@ export function object(value: unknown): value is Record<string, unknown> {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
-function readJson(path: string): Record<string, unknown> {
+export function readJson(path: string): Record<string, unknown> {
     if (lstatSync(path).size > 1024 * 1024) throw new Error(`Cratis configuration is too large: ${path}`);
     const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
     if (!object(value)) throw new Error(`Expected a JSON object: ${path}`);
@@ -21,6 +21,10 @@ function strings(value: unknown): string[] {
     return value;
 }
 
+export function supportedSchema(version: unknown): boolean {
+    return typeof version === 'string' && /^1\.\d+$/.test(version);
+}
+
 /** Resolve through existing directories only, refusing every source-root symlink. Never creates a directory. */
 export function physicalRoot(project: string, root: string): string {
     if (!root || isAbsolute(root) || root.includes('\0')) throw new Error('Screenplay root must be a nonempty project-relative directory.');
@@ -45,8 +49,16 @@ export function physicalRoot(project: string, root: string): string {
     return current;
 }
 
-/** Select only the shipped Screenplay descriptor, never project-supplied commands or environments. */
-export function selectedServer(project: string, corpus: string) {
+export interface ProfileResolution {
+    configuration: Record<string, unknown>;
+    selected: Set<string>;
+    /** Profiles listed directly in `.cratis/ai.json`, before any `composes` expansion. */
+    explicit: Set<string>;
+    nonApplicationSelection: boolean;
+}
+
+/** Resolve the selected profiles (after `composes` expansion) from the project's `.cratis/ai.json`. */
+export function resolveProfiles(project: string, corpus: string): ProfileResolution | undefined {
     let configuration: Record<string, unknown>;
     try {
         configuration = readJson(join(project, '.cratis', 'ai.json'));
@@ -86,7 +98,14 @@ export function selectedServer(project: string, corpus: string) {
         strings(profile.composes).forEach(child => select(child, false, applicationPath));
     };
     requested.forEach(id => select(id, true));
-    if (!selected.has('cratis/screenplay')) return undefined;
+    return { configuration, selected, explicit: new Set(requested), nonApplicationSelection };
+}
+
+/** Select only the shipped Screenplay descriptor, never project-supplied commands or environments. */
+export function selectedServer(project: string, corpus: string) {
+    const resolution = resolveProfiles(project, corpus);
+    if (!resolution?.selected.has('cratis/screenplay')) return undefined;
+    const { configuration, nonApplicationSelection } = resolution;
     const overrides = configuration.mcpServers;
     if (overrides !== undefined && !object(overrides)) throw new Error('Invalid mcpServers configuration.');
     const screenplay = object(overrides) ? overrides.screenplay : undefined;
@@ -94,7 +113,9 @@ export function selectedServer(project: string, corpus: string) {
     if (object(screenplay) && screenplay.enabled === false) return undefined;
     if (object(screenplay) && screenplay.enabled !== undefined && screenplay.enabled !== true) throw new Error('Screenplay MCP enabled must be a boolean.');
     const descriptor = readJson(join(corpus, 'mcp-servers.json'));
-    if (descriptor.schemaVersion !== '1.0' || !Array.isArray(descriptor.servers)) throw new Error('Unsupported Cratis MCP descriptor.');
+    // Any 1.x descriptor is accepted; another major loads no corpus MCP servers (the generic bridge reports it once).
+    if (!supportedSchema(descriptor.schemaVersion)) return undefined;
+    if (!Array.isArray(descriptor.servers)) throw new Error('Unsupported Cratis MCP descriptor.');
     const servers = descriptor.servers.filter(server => object(server) && server.id === 'screenplay');
     if (servers.length !== 1 || !object(servers[0])) throw new Error('Expected exactly one Screenplay MCP descriptor.');
     const server = servers[0];

package/package/corpus/harnesses/pi/extensions/cratis-mcp/index.ts

@@ -7,8 +7,10 @@ import { fileURLToPath } from 'node:url';
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { ConnectionFailure } from './ConnectionFailure.ts';
 import { object, selectedServer } from './configuration.ts';
-import { startConnection, supportsNoModelStartup } from './process.ts';
+import type { CorpusServer } from './CorpusServer.ts';
+import { startConnection, startServer, supportsNoModelStartup } from './process.ts';
 import { discover, failedResult, mapResult } from './protocol.ts';
+import { createServerBridge } from './ServerBridge.ts';
 import type { DiscoveredTool } from './DiscoveredTool.ts';
 import type { StdioConnection } from './StdioConnection.ts';
 
@@ -16,7 +18,8 @@ const extensionDirectory = dirname(fileURLToPath(import.meta.url));
 const bundledCorpus = resolve(extensionDirectory, '..', '..', '..', '..');
 
 /** Native tools go through Pi's tool_call restrictions and normal execution/result pipeline. */
-export function registerBridge(pi: ExtensionAPI, corpus: string, connect = startConnection, checkVersion = supportsNoModelStartup): void {
+export function registerBridge(pi: ExtensionAPI, corpus: string, connect = startConnection, checkVersion = supportsNoModelStartup, connectServer: (project: string, server: CorpusServer) => StdioConnection = startServer): void {
+    const servers = createServerBridge(pi, corpus, connectServer);
     let connection: StdioConnection | undefined;
     let selectionKey: string | undefined;
     let attempted = false;
@@ -149,9 +152,15 @@ export function registerBridge(pi: ExtensionAPI, corpus: string, connect = start
         }
     };
 
-    pi.on('session_start', (_event, context) => refresh(context, true));
-    pi.on('before_agent_start', async (_event, context) => { await refresh(context); });
-    pi.on('session_shutdown', () => { dispose(); failures.clear(); });
+    // Screenplay and the other corpus servers fail independently; the first failure is surfaced after both ran.
+    const refreshAll = async (context: ExtensionContext, newSession: boolean): Promise<void> => {
+        const outcomes = await Promise.allSettled([refresh(context, newSession), servers.refresh(context, newSession)]);
+        const failed = outcomes.find(outcome => outcome.status === 'rejected');
+        if (failed) throw failed.reason;
+    };
+    pi.on('session_start', (_event, context) => refreshAll(context, true));
+    pi.on('before_agent_start', async (_event, context) => { await refreshAll(context, false); });
+    pi.on('session_shutdown', () => { dispose(); servers.dispose(); failures.clear(); });
     pi.on('tool_result', event => {
         if (!registered.has(event.toolName)) return;
         const failure = failures.get(event.toolCallId);

package/package/corpus/harnesses/pi/extensions/cratis-mcp/process.ts

@@ -2,6 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { execFile, spawn } from 'node:child_process';
+import type { CorpusServer } from './CorpusServer.ts';
 import { StdioConnection } from './StdioConnection.ts';
 
 /** Preserve OS/runtime lookup only; never copy arbitrary credentials or descriptor environment values. */
@@ -43,3 +44,14 @@ export function startConnection(project: string, launch: typeof spawn = spawn):
         windowsHide: true,
     }));
 }
+
+/** Launch a corpus server verbatim (no shell, no interpolation): the default environment plus its declared literal env only. */
+export function startServer(project: string, server: CorpusServer, launch: typeof spawn = spawn): StdioConnection {
+    return new StdioConnection(launch(server.command, server.args, {
+        cwd: project,
+        env: { ...childEnvironment(), ...server.env },
+        shell: false,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+    }), 30_000, server.id, true);
+}

package/package/corpus/harnesses/pi/extensions/cratis-mcp/serverProtocol.ts

@@ -0,0 +1,92 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { TSchema } from 'typebox';
+import { object } from './configuration.ts';
+import type { StdioConnection } from './StdioConnection.ts';
+
+/** A tool of a corpus server other than Screenplay, exposed under a name namespaced by the server id. */
+export interface ServerTool {
+    name: string;
+    nativeName: string;
+    description: string;
+    parameters: TSchema;
+}
+
+export interface ServerCatalog {
+    tools: ServerTool[];
+    messages: string[];
+}
+
+const maximumTools = 128;
+const maximumPages = 8;
+const maximumNativeNameLength = 64;
+const maximumDescriptionLength = 4 * 1024;
+const maximumSchemaLength = 64 * 1024;
+const maximumImageLength = 2 * 1024 * 1024;
+const imageTypes = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+
+/** Initialize and list tools; tools that cannot be exposed safely are skipped with a message rather than failing the server. */
+export async function discoverServer(connection: StdioConnection, id: string): Promise<ServerCatalog> {
+    const initialized = await connection.request('initialize', {
+        protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'cratis.pi', version: '1.0.0' },
+    });
+    if (!object(initialized) || !object(initialized.capabilities) || !object(initialized.capabilities.tools)) {
+        throw new Error(`MCP server '${id}' did not advertise tool support.`);
+    }
+    connection.notify('notifications/initialized');
+    const listed: unknown[] = [];
+    let cursor: unknown;
+    for (let page = 0; page < maximumPages; page++) {
+        const response = await connection.request('tools/list', cursor === undefined ? {} : { cursor });
+        if (!object(response) || !Array.isArray(response.tools)) throw new Error(`MCP server '${id}' returned an invalid tool list.`);
+        listed.push(...response.tools);
+        if (listed.length > maximumTools) throw new Error(`MCP server '${id}' exposes more than ${maximumTools} tools.`);
+        cursor = response.nextCursor;
+        if (cursor === undefined) break;
+        if (typeof cursor !== 'string') throw new Error(`MCP server '${id}' returned an invalid pagination cursor.`);
+    }
+    const catalog: ServerCatalog = { tools: [], messages: [] };
+    const names = new Set<string>();
+    for (const tool of listed) {
+        const name = object(tool) ? tool.name : undefined;
+        if (!object(tool) || typeof name !== 'string' || !name || !object(tool.inputSchema) || tool.inputSchema.type !== 'object' ||
+            (tool.description !== undefined && typeof tool.description !== 'string')) {
+            catalog.messages.push(`MCP server '${id}' has a tool with an invalid name or input schema; it was skipped.`);
+            continue;
+        }
+        if (JSON.stringify(tool.inputSchema).length > maximumSchemaLength || ((tool.description as string | undefined)?.length ?? 0) > maximumDescriptionLength) {
+            catalog.messages.push(`MCP server '${id}' tool '${name}' was skipped: its description or input schema is too large.`);
+            continue;
+        }
+        const nativeName = `${id}_${name.replace(/[^A-Za-z0-9_]/g, '_')}`;
+        if (nativeName.length > maximumNativeNameLength || names.has(nativeName)) {
+            catalog.messages.push(`MCP server '${id}' tool '${name}' was skipped: its namespaced name is too long or not unique.`);
+            continue;
+        }
+        names.add(nativeName);
+        catalog.tools.push({ name, nativeName, description: (tool.description as string | undefined) ?? '', parameters: tool.inputSchema as TSchema });
+    }
+    if (!catalog.tools.length) throw new Error(`MCP server '${id}' exposes no usable tools.`);
+    return catalog;
+}
+
+/** Map an MCP result to Pi content. Server-reported errors throw so Pi marks the call failed. */
+export function mapServerResult(result: unknown, id: string) {
+    if (!object(result) || !Array.isArray(result.content) || (result.isError !== undefined && typeof result.isError !== 'boolean')) {
+        throw new Error(`Malformed MCP result from '${id}'.`);
+    }
+    const content = result.content.map((part: unknown) => {
+        if (object(part) && part.type === 'text' && typeof part.text === 'string') return { type: 'text' as const, text: part.text };
+        if (object(part) && part.type === 'image' && typeof part.data === 'string' && typeof part.mimeType === 'string') {
+            if (!imageTypes.has(part.mimeType) || part.data.length > maximumImageLength) return { type: 'text' as const, text: `[image omitted: unsupported type or larger than ${maximumImageLength / 1024 / 1024} MiB]` };
+            return { type: 'image' as const, data: part.data, mimeType: part.mimeType };
+        }
+        return { type: 'text' as const, text: `[unsupported ${object(part) ? String(part.type) : 'unknown'} content omitted]` };
+    });
+    const maximumCharacters = 32 * 1024;
+    const bounded = content.map(part => part.type === 'text' && part.text.length > maximumCharacters
+        ? { ...part, text: `${part.text.slice(0, maximumCharacters)}\n[display truncated]` }
+        : part);
+    return { content: bounded, details: { isError: result.isError === true, structuredContent: result.structuredContent } };
+}

package/package/corpus/harnesses/pi/extensions/cratis-mcp/servers.ts

@@ -0,0 +1,76 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { join } from 'node:path';
+import { object, readJson, resolveProfiles, supportedSchema } from './configuration.ts';
+import type { CorpusServer, ServerSelection } from './CorpusServer.ts';
+
+const validId = /^[A-Za-z0-9_-]+$/;
+
+function isSelected(entry: Record<string, unknown>, selected: Set<string>): boolean {
+    return Array.isArray(entry.profiles) && entry.profiles.some(profile => typeof profile === 'string' && selected.has(profile));
+}
+
+function problem(entry: Record<string, unknown>): string | undefined {
+    if (typeof entry.id !== 'string' || !validId.test(entry.id)) return 'the id must match ^[A-Za-z0-9_-]+$';
+    if (entry.transport !== 'stdio') return 'only the stdio transport is supported';
+    if (typeof entry.command !== 'string' || !entry.command) return 'the command is missing or empty';
+    if (!Array.isArray(entry.args) || !entry.args.every(argument => typeof argument === 'string')) return 'args must be an array of strings';
+    if (entry.env !== undefined && (!object(entry.env) || !Object.values(entry.env).every(value => typeof value === 'string'))) {
+        return 'env must be an object of literal string values';
+    }
+    return undefined;
+}
+
+/** `mcpServers.<id>.enabled`: false opts out, a non-boolean is an error for that server only. */
+function optOut(overrides: Record<string, unknown>, id: string): 'enabled' | 'disabled' | string {
+    const override = overrides[id];
+    if (override === undefined) return 'enabled';
+    if (!object(override)) return 'the mcpServers configuration must be an object';
+    if (override.enabled === undefined || override.enabled === true) return 'enabled';
+    return override.enabled === false ? 'disabled' : 'mcpServers enabled must be a boolean';
+}
+
+/** Select every stdio server whose profiles intersect the explicitly listed profiles (never composed ones), except Screenplay which keeps its own path. */
+export function selectedCorpusServers(project: string, corpus: string): ServerSelection {
+    const selection: ServerSelection = { servers: [], messages: [] };
+    const resolution = resolveProfiles(project, corpus);
+    if (!resolution) return selection;
+    const descriptor = readJson(join(corpus, 'mcp-servers.json'));
+    if (!supportedSchema(descriptor.schemaVersion)) {
+        selection.messages.push(`Cratis MCP descriptor schemaVersion '${String(descriptor.schemaVersion)}' is not supported; no corpus MCP servers were loaded.`);
+        return selection;
+    }
+    if (!Array.isArray(descriptor.servers)) {
+        selection.messages.push('Cratis MCP descriptor has no servers list; no corpus MCP servers were loaded.');
+        return selection;
+    }
+    const overrides = resolution.configuration.mcpServers;
+    if (overrides !== undefined && !object(overrides)) {
+        selection.messages.push('Invalid mcpServers configuration; no corpus MCP servers were loaded.');
+        return selection;
+    }
+    const entries = descriptor.servers.filter(object);
+    const counts = new Map<unknown, number>();
+    entries.forEach(entry => counts.set(entry.id, (counts.get(entry.id) ?? 0) + 1));
+    const reported = new Set<unknown>();
+    for (const entry of entries) {
+        if (entry.id === 'screenplay') continue;
+        // An entry without profiles can never be selected, so it is ignored like any other unselected entry.
+        if (!isSelected(entry, resolution.explicit)) continue;
+        const label = `MCP server '${String(entry.id)}'`;
+        if (counts.get(entry.id)! > 1) {
+            if (!reported.has(entry.id)) selection.messages.push(`${label} was skipped: the descriptor declares the id more than once.`);
+            reported.add(entry.id);
+            continue;
+        }
+        const invalid = problem(entry);
+        if (invalid) { selection.messages.push(`${label} was skipped: ${invalid}.`); continue; }
+        const id = entry.id as string;
+        const state = object(overrides) ? optOut(overrides, id) : 'enabled';
+        if (state === 'disabled') continue;
+        if (state !== 'enabled') { selection.messages.push(`${label} was skipped: ${state}.`); continue; }
+        selection.servers.push({ id, command: entry.command as string, args: entry.args as string[], env: { ...(entry.env as Record<string, string> | undefined) } });
+    }
+    return selection;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.94.0",
+  "version": "7.95.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [