@shardworks/claude-code-apparatus 0.1.101

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Sean Boots
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Claude Code Session Provider
+ *
+ * Apparatus plugin that implements AnimatorSessionProvider for the
+ * Claude Code CLI. The Animator discovers this via guild config:
+ *
+ *   guild.json["animator"]["sessionProvider"] = "claude-code"
+ *
+ * Launches sessions via the `claude` CLI in autonomous mode (--print)
+ * with --output-format stream-json for structured telemetry.
+ *
+ * Key design choice: uses async spawn() instead of spawnSync().
+ * This is required for stream-json transcript parsing, timeout enforcement,
+ * and future concurrent session support.
+ */
+import type { Plugin } from '@shardworks/nexus-core';
+import type { SessionChunk } from '@shardworks/animator-apparatus';
+/**
+ * Create the Claude Code session provider apparatus.
+ *
+ * The apparatus has no startup logic — it just provides the
+ * AnimatorSessionProvider implementation. The Animator looks it up
+ * via guild().apparatus('claude-code').
+ */
+export declare function createClaudeCodeProvider(): Plugin;
+declare const _default: Plugin;
+export default _default;
+export { createMcpServer, startMcpHttpServer } from './mcp-server.ts';
+export type { McpHttpHandle } from './mcp-server.ts';
+/** Parsed result from stream-json output. @internal */
+export interface StreamJsonResult {
+    exitCode: number;
+    transcript: Record<string, unknown>[];
+    costUsd?: number;
+    tokenUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+    };
+    providerSessionId?: string;
+}
+/**
+ * Parse a single NDJSON message from stream-json output.
+ *
+ * Returns parsed chunks for streaming and accumulates data into the
+ * provided accumulators (transcript, metrics).
+ *
+ * @internal Exported for testing only.
+ */
+export declare function parseStreamJsonMessage(msg: Record<string, unknown>, acc: {
+    transcript: Record<string, unknown>[];
+    costUsd?: number;
+    tokenUsage?: StreamJsonResult['tokenUsage'];
+    providerSessionId?: string;
+}): SessionChunk[];
+/**
+ * Process NDJSON buffer, calling handler for each complete line.
+ * Returns the remaining incomplete buffer.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function processNdjsonBuffer(buffer: string, handler: (msg: Record<string, unknown>) => void): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,EAIV,YAAY,EACb,MAAM,gCAAgC,CAAC;AAwLxC;;;;;;GAMG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAWjD;;AAED,wBAA0C;AAO1C,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACtE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAIrD,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,GAAG,EAAE;IACH,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAC;IAC5C,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,GACA,YAAY,EAAE,CAiDhB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAC9C,MAAM,CAgBR"}

package/dist/index.js

@@ -0,0 +1,384 @@
+/**
+ * Claude Code Session Provider
+ *
+ * Apparatus plugin that implements AnimatorSessionProvider for the
+ * Claude Code CLI. The Animator discovers this via guild config:
+ *
+ *   guild.json["animator"]["sessionProvider"] = "claude-code"
+ *
+ * Launches sessions via the `claude` CLI in autonomous mode (--print)
+ * with --output-format stream-json for structured telemetry.
+ *
+ * Key design choice: uses async spawn() instead of spawnSync().
+ * This is required for stream-json transcript parsing, timeout enforcement,
+ * and future concurrent session support.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { startMcpHttpServer } from "./mcp-server.js";
+/**
+ * Prepare session files and build base CLI args.
+ *
+ * Writes system prompt to a temp directory. Builds the base args array
+ * including --resume support. When tools are provided, starts an
+ * in-process MCP HTTP server and writes --mcp-config.
+ *
+ * Caller is responsible for cleaning up tmpDir and calling mcpHandle.close().
+ */
+async function prepareSession(config) {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nsg-session-'));
+    const args = [
+        '--setting-sources', 'user',
+        '--dangerously-skip-permissions',
+        '--model', config.model,
+    ];
+    if (config.systemPrompt) {
+        const systemPromptPath = path.join(tmpDir, 'system-prompt.md');
+        fs.writeFileSync(systemPromptPath, config.systemPrompt);
+        args.push('--system-prompt-file', systemPromptPath);
+    }
+    // Resume an existing conversation
+    if (config.conversationId) {
+        args.push('--resume', config.conversationId);
+    }
+    // Tool-equipped session: start MCP HTTP server, write --mcp-config
+    let mcpHandle;
+    if (config.tools && config.tools.length > 0) {
+        const tools = config.tools.map((rt) => rt.definition);
+        mcpHandle = await startMcpHttpServer(tools);
+        const mcpConfig = {
+            mcpServers: {
+                'nexus-guild': {
+                    type: 'sse',
+                    url: mcpHandle.url,
+                },
+            },
+        };
+        const mcpConfigPath = path.join(tmpDir, 'mcp-config.json');
+        fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig));
+        args.push('--mcp-config', mcpConfigPath, '--strict-mcp-config');
+    }
+    return { tmpDir, args, mcpHandle };
+}
+// ── Result builder ──────────────────────────────────────────────────
+function buildResult(raw) {
+    const status = raw.exitCode === 0 ? 'completed' : 'failed';
+    return {
+        status,
+        exitCode: raw.exitCode,
+        error: status === 'failed' ? `claude exited with code ${raw.exitCode}` : undefined,
+        costUsd: raw.costUsd,
+        tokenUsage: raw.tokenUsage,
+        providerSessionId: raw.providerSessionId,
+    };
+}
+// ── Provider implementation ──────────────────────────────────────────
+const provider = {
+    name: 'claude-code',
+    launch(config) {
+        // prepareSession is async (MCP server start), so we wrap the launch
+        // in a promise. The chunks iterable bridges the async gap — it waits
+        // for prep to complete before yielding.
+        let chunkResolve = null;
+        let innerChunks = null;
+        let innerIterator = null;
+        let prepDone = false;
+        let prepError = null;
+        let done = false;
+        const result = prepareSession(config).then(async ({ tmpDir, args, mcpHandle }) => {
+            // Autonomous mode: initial prompt via --print, stream-json for telemetry
+            args.push('--print', config.initialPrompt ?? '', '--output-format', 'stream-json', '--verbose');
+            const cleanup = async () => {
+                await mcpHandle?.close().catch(() => { });
+                fs.rmSync(tmpDir, { recursive: true, force: true });
+            };
+            try {
+                if (config.streaming) {
+                    const spawned = spawnClaudeStreamingJson(args, config.cwd);
+                    innerChunks = spawned.chunks;
+                    prepDone = true;
+                    if (chunkResolve) {
+                        chunkResolve();
+                        chunkResolve = null;
+                    }
+                    const raw = await spawned.result;
+                    await cleanup();
+                    return buildResult(raw);
+                }
+                // Non-streaming
+                prepDone = true;
+                done = true;
+                if (chunkResolve) {
+                    chunkResolve();
+                    chunkResolve = null;
+                }
+                const raw = await spawnClaudeStreamJson(args, config.cwd);
+                await cleanup();
+                return buildResult(raw);
+            }
+            catch (err) {
+                await cleanup();
+                throw err;
+            }
+        }).catch((err) => {
+            // If prep itself failed, unblock the chunk iterator
+            prepError = err instanceof Error ? err : new Error(String(err));
+            prepDone = true;
+            done = true;
+            if (chunkResolve) {
+                chunkResolve();
+                chunkResolve = null;
+            }
+            throw err;
+        });
+        // Chunks iterable that bridges the async prep gap. In non-streaming
+        // mode or on error, it completes immediately with no items.
+        const chunks = {
+            [Symbol.asyncIterator]() {
+                return {
+                    async next() {
+                        // Wait for prep to complete
+                        while (!prepDone) {
+                            await new Promise((resolve) => { chunkResolve = resolve; });
+                        }
+                        if (prepError || done) {
+                            return { value: undefined, done: true };
+                        }
+                        // Delegate to inner streaming iterator
+                        if (innerChunks && !innerIterator) {
+                            innerIterator = innerChunks[Symbol.asyncIterator]();
+                        }
+                        if (innerIterator) {
+                            return innerIterator.next();
+                        }
+                        return { value: undefined, done: true };
+                    },
+                };
+            },
+        };
+        return { chunks, result };
+    },
+};
+// ── Apparatus export ─────────────────────────────────────────────────
+/**
+ * Create the Claude Code session provider apparatus.
+ *
+ * The apparatus has no startup logic — it just provides the
+ * AnimatorSessionProvider implementation. The Animator looks it up
+ * via guild().apparatus('claude-code').
+ */
+export function createClaudeCodeProvider() {
+    return {
+        apparatus: {
+            requires: [],
+            provides: provider,
+            start() {
+                // No startup work — the provider is stateless.
+            },
+        },
+    };
+}
+export default createClaudeCodeProvider();
+// ── MCP server re-exports ───────────────────────────────────────────
+// The MCP server module is used by the session provider to attach tools
+// to sessions via --mcp-config, and can be imported directly for
+// testing or custom integrations.
+export { createMcpServer, startMcpHttpServer } from "./mcp-server.js";
+/**
+ * Parse a single NDJSON message from stream-json output.
+ *
+ * Returns parsed chunks for streaming and accumulates data into the
+ * provided accumulators (transcript, metrics).
+ *
+ * @internal Exported for testing only.
+ */
+export function parseStreamJsonMessage(msg, acc) {
+    const chunks = [];
+    if (msg.type === 'assistant') {
+        acc.transcript.push(msg);
+        const message = msg.message;
+        if (message) {
+            const content = message.content;
+            if (content) {
+                for (const block of content) {
+                    if (block.type === 'text' && typeof block.text === 'string') {
+                        process.stderr.write(block.text);
+                        chunks.push({ type: 'text', text: block.text });
+                    }
+                    else if (block.type === 'tool_use' && typeof block.name === 'string') {
+                        chunks.push({ type: 'tool_use', tool: block.name });
+                    }
+                }
+            }
+        }
+    }
+    else if (msg.type === 'user') {
+        acc.transcript.push(msg);
+        const content = msg.content;
+        if (content) {
+            for (const block of content) {
+                if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') {
+                    chunks.push({ type: 'tool_result', tool: String(block.tool_use_id) });
+                }
+            }
+        }
+    }
+    else if (msg.type === 'result') {
+        acc.costUsd = typeof msg.total_cost_usd === 'number' ? msg.total_cost_usd : undefined;
+        acc.providerSessionId = typeof msg.session_id === 'string' ? msg.session_id : undefined;
+        const usage = msg.usage;
+        if (usage) {
+            acc.tokenUsage = {
+                inputTokens: (typeof usage.input_tokens === 'number' ? usage.input_tokens : 0),
+                outputTokens: (typeof usage.output_tokens === 'number' ? usage.output_tokens : 0),
+                cacheReadTokens: typeof usage.cache_read_input_tokens === 'number'
+                    ? usage.cache_read_input_tokens : undefined,
+                cacheWriteTokens: typeof usage.cache_creation_input_tokens === 'number'
+                    ? usage.cache_creation_input_tokens : undefined,
+            };
+        }
+    }
+    return chunks;
+}
+/**
+ * Process NDJSON buffer, calling handler for each complete line.
+ * Returns the remaining incomplete buffer.
+ *
+ * @internal Exported for testing only.
+ */
+export function processNdjsonBuffer(buffer, handler) {
+    let newlineIdx;
+    while ((newlineIdx = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, newlineIdx).trim();
+        buffer = buffer.slice(newlineIdx + 1);
+        if (!line)
+            continue;
+        try {
+            const msg = JSON.parse(line);
+            handler(msg);
+        }
+        catch {
+            // Non-JSON line — ignore
+        }
+    }
+    return buffer;
+}
+/**
+ * Spawn Claude in autonomous mode with --output-format stream-json.
+ *
+ * Captures stdout (NDJSON lines), parses each line to extract:
+ * - assistant messages → transcript
+ * - result message → cost, token usage, session ID
+ *
+ * Forwards assistant text content to stderr so it's visible during execution.
+ */
+function spawnClaudeStreamJson(args, cwd) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn('claude', args, {
+            cwd,
+            stdio: ['pipe', 'pipe', 'inherit'],
+        });
+        const acc = { transcript: [] };
+        let buffer = '';
+        proc.stdout.on('data', (chunk) => {
+            buffer += chunk.toString();
+            buffer = processNdjsonBuffer(buffer, (msg) => {
+                parseStreamJsonMessage(msg, acc);
+            });
+        });
+        proc.on('error', (err) => {
+            reject(new Error(`Failed to spawn claude: ${err.message}`));
+        });
+        proc.on('close', (code) => {
+            if (acc.transcript.length > 0) {
+                process.stderr.write('\n');
+            }
+            resolve({
+                exitCode: code ?? 1,
+                transcript: acc.transcript,
+                costUsd: acc.costUsd,
+                tokenUsage: acc.tokenUsage,
+                providerSessionId: acc.providerSessionId,
+            });
+        });
+    });
+}
+/**
+ * Spawn Claude with streaming — yields SessionChunks as they arrive
+ * while also accumulating the full result.
+ *
+ * Returns an async iterable of chunks for real-time consumption and
+ * a promise for the final StreamJsonResult.
+ */
+function spawnClaudeStreamingJson(args, cwd) {
+    const chunkQueue = [];
+    let chunkResolve = null;
+    let done = false;
+    const acc = { transcript: [] };
+    const proc = spawn('claude', args, {
+        cwd,
+        stdio: ['pipe', 'pipe', 'inherit'],
+    });
+    let buffer = '';
+    proc.stdout.on('data', (chunk) => {
+        buffer += chunk.toString();
+        buffer = processNdjsonBuffer(buffer, (msg) => {
+            const newChunks = parseStreamJsonMessage(msg, acc);
+            if (newChunks.length > 0) {
+                chunkQueue.push(...newChunks);
+                if (chunkResolve) {
+                    chunkResolve();
+                    chunkResolve = null;
+                }
+            }
+        });
+    });
+    const result = new Promise((resolve, reject) => {
+        proc.on('error', (err) => {
+            done = true;
+            if (chunkResolve) {
+                chunkResolve();
+                chunkResolve = null;
+            }
+            reject(new Error(`Failed to spawn claude: ${err.message}`));
+        });
+        proc.on('close', (code) => {
+            if (acc.transcript.length > 0) {
+                process.stderr.write('\n');
+            }
+            done = true;
+            if (chunkResolve) {
+                chunkResolve();
+                chunkResolve = null;
+            }
+            resolve({
+                exitCode: code ?? 1,
+                transcript: acc.transcript,
+                costUsd: acc.costUsd,
+                tokenUsage: acc.tokenUsage,
+                providerSessionId: acc.providerSessionId,
+            });
+        });
+    });
+    const chunks = {
+        [Symbol.asyncIterator]() {
+            return {
+                async next() {
+                    while (true) {
+                        if (chunkQueue.length > 0) {
+                            return { value: chunkQueue.shift(), done: false };
+                        }
+                        if (done) {
+                            return { value: undefined, done: true };
+                        }
+                        await new Promise((resolve) => { chunkResolve = resolve; });
+                    }
+                },
+            };
+        },
+    };
+    return { chunks, result };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/mcp-server.d.ts

@@ -0,0 +1,61 @@
+/**
+ * MCP Tool Server — serves guild tools as typed MCP tools during anima sessions.
+ *
+ * Two entry points:
+ *
+ * 1. **`createMcpServer(tools)`** — library function. Takes an array of
+ *    ToolDefinitions (already resolved by the Instrumentarium) and returns
+ *    a configured McpServer.
+ *
+ * 2. **`startMcpHttpServer(tools)`** — starts an in-process HTTP server
+ *    serving the MCP tool set via Streamable HTTP on an ephemeral localhost
+ *    port. Returns a handle with the URL (for --mcp-config) and a close()
+ *    function for cleanup.
+ *
+ * The MCP server is one-per-session. The claude-code provider owns the
+ * lifecycle — starts before the Claude process, stops after it exits.
+ *
+ * See: docs/architecture/apparatus/claude-code.md
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolDefinition } from '@shardworks/tools-apparatus';
+/**
+ * Handle returned by startMcpHttpServer().
+ *
+ * Provides the URL for --mcp-config and a close() function for cleanup.
+ */
+export interface McpHttpHandle {
+    /** URL for --mcp-config (e.g. "http://127.0.0.1:PORT/mcp"). */
+    url: string;
+    /** Shut down the HTTP server and MCP transport. */
+    close(): Promise<void>;
+}
+/**
+ * Create and configure an MCP server with the given tools.
+ *
+ * Each tool's Zod param schema is registered directly with the MCP SDK
+ * (which handles JSON Schema conversion). The handler is wrapped to
+ * validate params via Zod and format the result as MCP tool output.
+ *
+ * Tools with `callableBy` set that does not include `'anima'` are
+ * filtered out. Tools without `callableBy` are included (available
+ * to all callers by default).
+ */
+export declare function createMcpServer(tools: ToolDefinition[]): Promise<McpServer>;
+/**
+ * Start an in-process HTTP server serving the MCP tool set via SSE.
+ *
+ * Uses the MCP SDK's SSE transport: the client GETs /sse to establish
+ * the event stream, then POSTs messages to /message. Claude Code's
+ * --mcp-config expects `type: "sse"` for HTTP-based MCP servers.
+ *
+ * The server binds to 127.0.0.1 only — not network-accessible.
+ *
+ * Returns a handle with the URL (for --mcp-config) and a close() function.
+ * The caller is responsible for calling close() after the session exits.
+ *
+ * Each session gets its own server instance. Concurrent sessions get
+ * independent servers on different ports.
+ */
+export declare function startMcpHttpServer(tools: ToolDefinition[]): Promise<McpHttpHandle>;
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAIlE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAwCjF;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAoDxF"}

package/dist/mcp-server.js

@@ -0,0 +1,135 @@
+/**
+ * MCP Tool Server — serves guild tools as typed MCP tools during anima sessions.
+ *
+ * Two entry points:
+ *
+ * 1. **`createMcpServer(tools)`** — library function. Takes an array of
+ *    ToolDefinitions (already resolved by the Instrumentarium) and returns
+ *    a configured McpServer.
+ *
+ * 2. **`startMcpHttpServer(tools)`** — starts an in-process HTTP server
+ *    serving the MCP tool set via Streamable HTTP on an ephemeral localhost
+ *    port. Returns a handle with the URL (for --mcp-config) and a close()
+ *    function for cleanup.
+ *
+ * The MCP server is one-per-session. The claude-code provider owns the
+ * lifecycle — starts before the Claude process, stops after it exits.
+ *
+ * See: docs/architecture/apparatus/claude-code.md
+ */
+import http from 'node:http';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { VERSION } from '@shardworks/nexus-core';
+// ── Library API ─────────────────────────────────────────────────────────
+/**
+ * Create and configure an MCP server with the given tools.
+ *
+ * Each tool's Zod param schema is registered directly with the MCP SDK
+ * (which handles JSON Schema conversion). The handler is wrapped to
+ * validate params via Zod and format the result as MCP tool output.
+ *
+ * Tools with `callableBy` set that does not include `'anima'` are
+ * filtered out. Tools without `callableBy` are included (available
+ * to all callers by default).
+ */
+export async function createMcpServer(tools) {
+    const server = new McpServer({
+        name: 'nexus-guild',
+        version: VERSION,
+    });
+    for (const def of tools) {
+        // Filter by callableBy — only serve tools callable by animas.
+        // Tools with no callableBy default to all callers (available everywhere).
+        if (def.callableBy && !def.callableBy.includes('anima')) {
+            continue;
+        }
+        server.tool(def.name, def.description, def.params.shape, async (params) => {
+            try {
+                const validated = def.params.parse(params);
+                const result = await def.handler(validated);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                        }],
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: 'text', text: `Error: ${message}` }],
+                    isError: true,
+                };
+            }
+        });
+    }
+    return server;
+}
+// ── HTTP Server ─────────────────────────────────────────────────────────
+/**
+ * Start an in-process HTTP server serving the MCP tool set via SSE.
+ *
+ * Uses the MCP SDK's SSE transport: the client GETs /sse to establish
+ * the event stream, then POSTs messages to /message. Claude Code's
+ * --mcp-config expects `type: "sse"` for HTTP-based MCP servers.
+ *
+ * The server binds to 127.0.0.1 only — not network-accessible.
+ *
+ * Returns a handle with the URL (for --mcp-config) and a close() function.
+ * The caller is responsible for calling close() after the session exits.
+ *
+ * Each session gets its own server instance. Concurrent sessions get
+ * independent servers on different ports.
+ */
+export async function startMcpHttpServer(tools) {
+    const mcpServer = await createMcpServer(tools);
+    // SSE transport: the client GETs /sse, the transport tells it to POST
+    // messages to /message. One transport per connection (single-session).
+    let transport = null;
+    const httpServer = http.createServer(async (req, res) => {
+        try {
+            if (req.method === 'GET' && req.url === '/sse') {
+                // New SSE connection — create transport bound to this response.
+                transport = new SSEServerTransport('/message', res);
+                await mcpServer.connect(transport);
+            }
+            else if (req.method === 'POST' && req.url?.startsWith('/message')) {
+                if (!transport) {
+                    res.writeHead(400).end('No active SSE connection');
+                    return;
+                }
+                await transport.handlePostMessage(req, res);
+            }
+            else {
+                res.writeHead(404).end('Not found');
+            }
+        }
+        catch {
+            if (!res.headersSent) {
+                res.writeHead(500).end('Internal Server Error');
+            }
+        }
+    });
+    // Listen on ephemeral port, localhost only.
+    await new Promise((resolve) => {
+        httpServer.listen(0, '127.0.0.1', resolve);
+    });
+    const addr = httpServer.address();
+    if (!addr || typeof addr === 'string') {
+        throw new Error('Failed to get server address');
+    }
+    const url = `http://127.0.0.1:${addr.port}/sse`;
+    return {
+        url,
+        async close() {
+            if (transport) {
+                await transport.close();
+            }
+            await new Promise((resolve, reject) => {
+                httpServer.close((err) => (err ? reject(err) : resolve()));
+            });
+        },
+    };
+}
+//# sourceMappingURL=mcp-server.js.map

package/dist/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAiBjD,2EAA2E;AAE3E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,KAAuB;IAC3D,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,8DAA8D;QAC9D,0EAA0E;QAC1E,IAAI,GAAG,CAAC,UAAU,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACxD,SAAS;QACX,CAAC;QAED,MAAM,CAAC,IAAI,CACT,GAAG,CAAC,IAAI,EACR,GAAG,CAAC,WAAW,EACf,GAAG,CAAC,MAAM,CAAC,KAAK,EAChB,KAAK,EAAE,MAAM,EAAE,EAAE;YACf,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBAC3C,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;gBAE5C,OAAO;oBACL,OAAO,EAAE,CAAC;4BACR,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;yBAC5E,CAAC;iBACH,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjE,OAAO;oBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,UAAU,OAAO,EAAE,EAAE,CAAC;oBAC/D,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,2EAA2E;AAE3E;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,KAAuB;IAC9D,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,KAAK,CAAC,CAAC;IAE/C,sEAAsE;IACtE,uEAAuE;IACvE,IAAI,SAAS,GAA8B,IAAI,CAAC;IAEhD,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QACtD,IAAI,CAAC;YACH,IAAI,GAAG,CAAC,MAAM,KAAK,KAAK,IAAI,GAAG,CAAC,GAAG,KAAK,MAAM,EAAE,CAAC;gBAC/C,gEAAgE;gBAChE,SAAS,GAAG,IAAI,kBAAkB,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;gBACpD,MAAM,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YACrC,CAAC;iBAAM,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;gBACpE,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;oBACnD,OAAO;gBACT,CAAC;gBACD,MAAM,SAAS,CAAC,iBAAiB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YAC9C,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YACtC,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;gBACrB,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;YAClD,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,4CAA4C;IAC5C,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAClC,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC;IAClC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAClD,CAAC;IAED,MAAM,GAAG,GAAG,oBAAoB,IAAI,CAAC,IAAI,MAAM,CAAC;IAEhD,OAAO;QACL,GAAG;QACH,KAAK,CAAC,KAAK;YACT,IAAI,SAAS,EAAE,CAAC;gBACd,MAAM,SAAS,CAAC,KAAK,EAAE,CAAC;YAC1B,CAAC;YACD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC1C,UAAU,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAC7D,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@shardworks/claude-code-apparatus",
+  "version": "0.1.101",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shardworks/nexus",
+    "directory": "packages/plugins/claude-code"
+  },
+  "description": "Claude Code session provider apparatus — launches claude sessions via the Animator",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.27.1",
+    "zod": "4.3.6",
+    "@shardworks/animator-apparatus": "0.1.101",
+    "@shardworks/nexus-core": "0.1.101",
+    "@shardworks/tools-apparatus": "0.1.101"
+  },
+  "devDependencies": {
+    "@types/node": "25.5.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --disable-warning=ExperimentalWarning --experimental-transform-types --test 'src/**/*.test.ts'",
+    "typecheck": "tsc --noEmit"
+  }
+}