@cairn-tool/cairn 2.0.0

package/dist/serve/server.d.ts

@@ -0,0 +1,31 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type CallToolResult, type Tool } from "@modelcontextprotocol/sdk/types.js";
+import { type ValidateFunction } from "ajv/dist/2020.js";
+import { type ServeContext } from "./tools.js";
+/** The advertised `tools/list` payload — the tool table minus its handlers. */
+export declare function toolManifest(): Tool[];
+/**
+ * One compiled validator per tool, built once at startup.
+ *
+ * Compiling per call would put schema compilation on the request path for every
+ * invocation, and a malformed schema should fail the server's own startup
+ * rather than surface as a runtime error to a client.
+ */
+export declare function compileValidators(): Map<string, ValidateFunction>;
+/**
+ * Runs one tool call.
+ *
+ * The split matters: an unknown tool or arguments that fail their schema are the
+ * client's protocol mistakes and are raised as JSON-RPC errors, while anything
+ * the workspace itself reports comes back as an `isError` result the model can
+ * read and correct.
+ */
+export declare function callTool(name: string, args: Record<string, unknown>, context: ServeContext, validators: Map<string, ValidateFunction>): Promise<CallToolResult>;
+export interface RunningServer {
+    server: Server;
+    /** Resolves once no tool call is still in flight. */
+    idle: () => Promise<void>;
+}
+export declare function createServer(context: ServeContext, validators?: Map<string, ValidateFunction>): RunningServer;
+/** Serves until the client closes the transport. */
+export declare function serveStdio(context: ServeContext): Promise<void>;

package/dist/serve/server.js

@@ -0,0 +1,123 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import addFormatsImport from "ajv-formats";
+import { packageName, packageVersion } from "../version.js";
+import { toolFailure } from "./errors.js";
+import { SERVE_TOOLS, TOOL_BY_NAME } from "./tools.js";
+/** The advertised `tools/list` payload — the tool table minus its handlers. */
+export function toolManifest() {
+    return SERVE_TOOLS.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+    }));
+}
+/**
+ * One compiled validator per tool, built once at startup.
+ *
+ * Compiling per call would put schema compilation on the request path for every
+ * invocation, and a malformed schema should fail the server's own startup
+ * rather than surface as a runtime error to a client.
+ */
+export function compileValidators() {
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    const addFormats = addFormatsImport;
+    addFormats(ajv);
+    return new Map(SERVE_TOOLS.map((tool) => [tool.name, ajv.compile(tool.inputSchema)]));
+}
+function describeErrors(validate) {
+    const errors = validate.errors ?? [];
+    return errors
+        .map((error) => `${error.instancePath || "(root)"} ${error.message ?? "is invalid"}`)
+        .join("; ");
+}
+/**
+ * Runs one tool call.
+ *
+ * The split matters: an unknown tool or arguments that fail their schema are the
+ * client's protocol mistakes and are raised as JSON-RPC errors, while anything
+ * the workspace itself reports comes back as an `isError` result the model can
+ * read and correct.
+ */
+export async function callTool(name, args, context, validators) {
+    const tool = TOOL_BY_NAME.get(name);
+    if (!tool)
+        throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
+    const validate = validators.get(name);
+    if (validate && !validate(args)) {
+        throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for ${name}: ${describeErrors(validate)}`);
+    }
+    try {
+        const payload = await tool.handler(args, context);
+        return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+    }
+    catch (error) {
+        if (error instanceof McpError)
+            throw error;
+        return toolFailure(error, context.root);
+    }
+}
+export function createServer(context, validators = compileValidators()) {
+    const server = new Server({ name: packageName, version: packageVersion }, 
+    // Declared up front: the SDK asserts the capability when a handler is
+    // registered, so omitting it fails at startup rather than at request time.
+    { capabilities: { tools: {} } });
+    // Tool calls are tracked so shutdown can drain them. The SDK dispatches
+    // requests concurrently, and a client that has sent its last frame and closed
+    // stdin would otherwise lose the responses still being computed.
+    const pending = new Set();
+    const idle = async () => {
+        while (pending.size > 0)
+            await Promise.allSettled([...pending]);
+    };
+    server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: toolManifest() }));
+    server.setRequestHandler(CallToolRequestSchema, (request) => {
+        const call = callTool(request.params.name, request.params.arguments ?? {}, context, validators);
+        pending.add(call);
+        return call.finally(() => pending.delete(call));
+    });
+    return { server, idle };
+}
+/** Serves until the client closes the transport. */
+export async function serveStdio(context) {
+    const { server, idle } = createServer(context);
+    const transport = new StdioServerTransport();
+    // stdout is the protocol channel, so every diagnostic goes to stderr, which
+    // MCP treats as the server's log. A single malformed frame or a failure while
+    // writing a response must not take down a session that is otherwise healthy,
+    // so these are reported rather than thrown.
+    const report = (label, error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`cairn serve: ${label}: ${message}\n`);
+    };
+    server.onerror = (error) => report("protocol error", error);
+    const onRejection = (reason) => report("unhandled rejection", reason);
+    process.on("unhandledRejection", onRejection);
+    try {
+        await server.connect(transport);
+        // A client disconnecting shows up as EOF on stdin, which does not
+        // necessarily reach `onclose`; waiting on `onclose` alone leaves the process
+        // hanging on an unsettled promise until Node notices and warns.
+        await new Promise((resolve) => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve();
+            };
+            transport.onclose = finish;
+            process.stdin.once("end", finish);
+            process.stdin.once("close", finish);
+        });
+        // Requests already dispatched still need their responses written.
+        await idle();
+        await server.close();
+    }
+    finally {
+        process.off("unhandledRejection", onRejection);
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/serve/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/serve/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,SAAS,EACT,sBAAsB,EACtB,QAAQ,GAGT,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAyB,MAAM,kBAAkB,CAAC;AAClE,OAAO,gBAAgB,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,YAAY,EAAqC,MAAM,YAAY,CAAC;AAE1F,+EAA+E;AAC/E,MAAM,UAAU,YAAY;IAC1B,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAChC,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;KAC9B,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5D,MAAM,UAAU,GAAG,gBAA6D,CAAC;IACjF,UAAU,CAAC,GAAG,CAAC,CAAC;IAChB,OAAO,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;AACxF,CAAC;AAED,SAAS,cAAc,CAAC,QAA0B;IAChD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC;IACrC,OAAO,MAAM;SACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,YAAY,IAAI,QAAQ,IAAI,KAAK,CAAC,OAAO,IAAI,YAAY,EAAE,CAAC;SACpF,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAY,EACZ,IAA6B,EAC7B,OAAqB,EACrB,UAAyC;IAEzC,MAAM,IAAI,GAA0B,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3D,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,QAAQ,CAAC,SAAS,CAAC,aAAa,EAAE,iBAAiB,IAAI,EAAE,CAAC,CAAC;IAEhF,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,QAAQ,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,QAAQ,CAChB,SAAS,CAAC,aAAa,EACvB,yBAAyB,IAAI,KAAK,cAAc,CAAC,QAAQ,CAAC,EAAE,CAC7D,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAClD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACjF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,QAAQ;YAAE,MAAM,KAAK,CAAC;QAC3C,OAAO,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC;AAQD,MAAM,UAAU,YAAY,CAC1B,OAAqB,EACrB,aAA4C,iBAAiB,EAAE;IAE/D,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE;IAC9C,sEAAsE;IACtE,2EAA2E;IAC3E,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAC;IAEF,wEAAwE;IACxE,8EAA8E;IAC9E,iEAAiE;IACjE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC5C,MAAM,IAAI,GAAG,KAAK,IAAmB,EAAE;QACrC,OAAO,OAAO,CAAC,IAAI,GAAG,CAAC;YAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAClE,CAAC,CAAC;IAEF,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,CAAC,CAAC,CAAC;IACpF,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,CAAC,OAAO,EAAE,EAAE;QAC1D,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;QAChG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED,oDAAoD;AACpD,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAAqB;IACpD,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAE7C,4EAA4E;IAC5E,8EAA8E;IAC9E,6EAA6E;IAC7E,4CAA4C;IAC5C,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,KAAc,EAAQ,EAAE;QACrD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,KAAK,KAAK,OAAO,IAAI,CAAC,CAAC;IAC9D,CAAC,CAAC;IACF,MAAM,CAAC,OAAO,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IAC5D,MAAM,WAAW,GAAG,CAAC,MAAe,EAAQ,EAAE,CAAC,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IACrF,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,WAAW,CAAC,CAAC;IAE9C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChC,kEAAkE;QAClE,6EAA6E;QAC7E,gEAAgE;QAChE,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAClC,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,MAAM,MAAM,GAAG,GAAS,EAAE;gBACxB,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,GAAG,IAAI,CAAC;gBACf,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;YACF,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC;YAC3B,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAClC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;QACH,kEAAkE;QAClE,MAAM,IAAI,EAAE,CAAC;QACb,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,WAAW,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}

package/dist/serve/tools.d.ts

@@ -0,0 +1,19 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { ResolvedConfig } from "../config.js";
+import type { Workspace } from "../workspace.js";
+export interface ServeContext {
+    workspace: Workspace;
+    config: ResolvedConfig;
+    /** Confinement boundary, already resolved through symlinks. */
+    root: string;
+    /** Upper bound on parallel lints, so a large audit cannot starve the transport. */
+    concurrency: number;
+}
+export interface ServeTool {
+    name: string;
+    description: string;
+    inputSchema: Tool["inputSchema"];
+    handler: (args: Record<string, unknown>, context: ServeContext) => Promise<unknown> | unknown;
+}
+export declare const SERVE_TOOLS: readonly ServeTool[];
+export declare const TOOL_BY_NAME: ReadonlyMap<string, ServeTool>;