@cat-factory/mcp-server 0.1.0

package/dist/server.d.ts

@@ -0,0 +1,24 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type CatFactoryMcpOptions } from './config.ts';
+import { type CatFactoryTool } from './tools.generated.ts';
+/** The npm version, stamped into the SDK's `User-Agent` so a deployment can attribute calls. */
+export declare const MCP_SERVER_VERSION = "0.1.0";
+/** The name this server reports to a host. */
+export declare const MCP_SERVER_NAME = "cat-factory";
+export interface CatFactoryMcpServer {
+    /** The MCP server, ready to `connect()` to a transport. */
+    server: Server;
+    /** The tools it exposes, after the group / read-only filters. */
+    tools: readonly CatFactoryTool[];
+}
+/**
+ * Build the MCP server for a deployment.
+ *
+ * The client is constructed HERE rather than taken as a parameter, and a test injects
+ * `options.fetch` instead of a whole client. A client parameter would let a caller hand this one
+ * pointed at a different deployment than the options describe, and would let a test pass one
+ * without the `User-Agent` below — which is exactly the property most worth pinning, since it
+ * only exists on the path a test would then not be exercising.
+ */
+export declare function createCatFactoryMcpServer(options: CatFactoryMcpOptions): CatFactoryMcpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAA;AAElE,OAAO,EAAE,KAAK,oBAAoB,EAAe,MAAM,aAAa,CAAA;AAGpE,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAgB7E,gGAAgG;AAChG,eAAO,MAAM,kBAAkB,UAAU,CAAA;AAEzC,8CAA8C;AAC9C,eAAO,MAAM,eAAe,gBAAgB,CAAA;AAE5C,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAA;IACd,iEAAiE;IACjE,KAAK,EAAE,SAAS,cAAc,EAAE,CAAA;CACjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,oBAAoB,GAAG,mBAAmB,CAwE5F"}

package/dist/server.js

@@ -0,0 +1,96 @@
+import { CatFactoryClient } from '@cat-factory/sdk';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { selectTools } from './config.js';
+import { buildInstructions } from './instructions.js';
+import { renderError, renderResult } from './result.js';
+import { CAT_FACTORY_TOOLS } from './tools.generated.js';
+// The facade itself: an MCP server whose every tool is one call on `@cat-factory/sdk`.
+//
+// "Thin" is a design constraint rather than a description. This module decides which tools to
+// list, how to turn one result or one failure into MCP content, and nothing else. Retries, auth,
+// error classes, pagination, encoding and timeouts are the SDK's, which is what makes the tools
+// behave identically to the same calls made from code — and what stops this becoming a second,
+// quietly divergent implementation of the API's rules.
+//
+// The LOW-LEVEL `Server` rather than `McpServer`: the tool schemas are GENERATED as JSON Schema
+// from the same spec the deployment validates against, and the high-level helper wants Zod
+// schemas it would then convert back. Going through Zod would mean the model reads a schema that
+// has been round-tripped through a second type system, and every gap in that conversion becomes a
+// tool that misdescribes its own input.
+/** The npm version, stamped into the SDK's `User-Agent` so a deployment can attribute calls. */
+export const MCP_SERVER_VERSION = '0.1.0';
+/** The name this server reports to a host. */
+export const MCP_SERVER_NAME = 'cat-factory';
+/**
+ * Build the MCP server for a deployment.
+ *
+ * The client is constructed HERE rather than taken as a parameter, and a test injects
+ * `options.fetch` instead of a whole client. A client parameter would let a caller hand this one
+ * pointed at a different deployment than the options describe, and would let a test pass one
+ * without the `User-Agent` below — which is exactly the property most worth pinning, since it
+ * only exists on the path a test would then not be exercising.
+ */
+export function createCatFactoryMcpServer(options) {
+    const selection = selectTools(CAT_FACTORY_TOOLS, options);
+    const { exposed } = selection;
+    const client = new CatFactoryClient({
+        baseUrl: options.baseUrl,
+        apiKey: options.apiKey,
+        // Named so a deployment's request log attributes a call to the MCP facade rather than to
+        // "some SDK user": the two have very different debugging stories, and an operator reading
+        // an audit trail is entitled to know a model made the call.
+        userAgent: `cat-factory-mcp/${MCP_SERVER_VERSION}`,
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+    const server = new Server({ name: MCP_SERVER_NAME, version: MCP_SERVER_VERSION }, {
+        capabilities: { tools: {} },
+        instructions: buildInstructions(selection),
+    });
+    server.setRequestHandler(ListToolsRequestSchema, () => ({
+        tools: exposed.map((tool) => ({
+            name: tool.name,
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: {
+                title: tool.title,
+                // The only annotation this facade can state truthfully. `readOnlyHint` follows from the
+                // HTTP method; `destructiveHint` and `idempotentHint` are deliberately left unset rather
+                // than guessed, because a DELETE here is idempotent AND destructive and the defaults a
+                // host assumes for an unset hint are safer than a wrong one.
+                readOnlyHint: tool.readOnly,
+            },
+        })),
+    }));
+    const byName = new Map(exposed.map((tool) => [tool.name, tool]));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const name = request.params.name;
+        const tool = byName.get(name);
+        if (!tool) {
+            // A name this server does not serve. Answered as a tool ERROR rather than a protocol one,
+            // and phrased so the model can recover: on a filtered server the tool may genuinely exist
+            // in the deployment, just not here.
+            return renderError(new Error(`no such tool on this server. Available: ${[...byName.keys()].sort().join(', ')}`), { toolName: name });
+        }
+        const args = (request.params.arguments ?? {});
+        try {
+            const result = await tool.invoke(client, args);
+            return renderResult(result, {
+                toolName: tool.name,
+                ...(options.maxResultChars !== undefined ? { maxChars: options.maxResultChars } : {}),
+            });
+        }
+        catch (error) {
+            // Every failure lands here, including one thrown while building the request. Nothing is
+            // rethrown: a throw out of this handler becomes a JSON-RPC protocol error, which the host
+            // treats as the server misbehaving and does not show the model — and the most useful thing
+            // this facade ever returns is a 422 naming the field the model got wrong.
+            return renderError(error, { toolName: tool.name });
+        }
+    });
+    return { server, tools: exposed };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/tools.generated.d.ts

@@ -0,0 +1,45 @@
+import type { CatFactoryClient } from '@cat-factory/sdk';
+/** One exposed operation, as an MCP tool. */
+export interface CatFactoryTool {
+    /** The name a host lists and a model calls, `<group>_<method>`. */
+    name: string;
+    /** One-line label from the spec's `summary`. */
+    title: string;
+    /** The SDK resource group it belongs to, so a deployment can expose a subset. */
+    group: string;
+    /** The spec's `operationId`, for correlating a tool call with a deployment's logs. */
+    operationId: string;
+    /** Whether the call changes nothing (a GET). Hosts use it to decide what needs confirming. */
+    readOnly: boolean;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: readonly string[];
+        additionalProperties: false;
+    };
+    /** Forward the validated arguments to the SDK. */
+    invoke: (client: CatFactoryClient, args: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * An operation the facade deliberately does NOT expose, and why.
+ *
+ * Reported rather than merely absent: a caller comparing the tool list against the published API
+ * would otherwise have to guess whether a missing operation is an omission, an oversight, or a
+ * version skew. The server exposes this list through its instructions for the same reason.
+ */
+export interface CatFactoryOmittedOperation {
+    operationId: string;
+    /** The route it would have called. */
+    route: string;
+    /** The equivalent call on the TypeScript SDK, which CAN serve it. */
+    sdkCall: string;
+    reason: string;
+}
+/** Every `/api/v1` operation this facade exposes as a tool, in resource-group order. */
+export declare const CAT_FACTORY_TOOLS: readonly CatFactoryTool[];
+/** The operations this facade does not expose, each with its reason. */
+export declare const CAT_FACTORY_OMITTED_OPERATIONS: readonly CatFactoryOmittedOperation[];
+/** One line per resource group, for the server's instructions. */
+export declare const CAT_FACTORY_TOOL_GROUPS: Readonly<Record<string, string>>;
+//# sourceMappingURL=tools.generated.d.ts.map

package/dist/tools.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.generated.d.ts","sourceRoot":"","sources":["../src/tools.generated.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExD,6CAA6C;AAC7C,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAA;IACZ,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAA;IACb,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAA;IACb,sFAAsF;IACtF,WAAW,EAAE,MAAM,CAAA;IACnB,8FAA8F;IAC9F,QAAQ,EAAE,OAAO,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAA;QACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACnC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;QAC5B,oBAAoB,EAAE,KAAK,CAAA;KAC5B,CAAA;IACD,kDAAkD;IAClD,MAAM,EAAE,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACtF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,MAAM,CAAA;IACnB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;CACf;AAwCD,wFAAwF;AACxF,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAyWtD,CAAA;AAED,wEAAwE;AACxE,eAAO,MAAM,8BAA8B,EAAE,SAAS,0BAA0B,EAa/E,CAAA;AAED,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASpE,CAAA"}