@cat-factory/mcp-server 0.2.1 → 0.3.1

package/dist/instructions.js

@@ -14,8 +14,10 @@ import { CAT_FACTORY_OMITTED_OPERATIONS, CAT_FACTORY_TOOL_GROUPS } from './tools
  * free to disagree with the first.
  */
 export function buildInstructions(selection) {
-    const { exposed, filteredGroups, writeToolsHidden } = selection;
+    const { exposed, filteredGroups, writeToolsHidden, deniedTools, toolsAllowListed } = selection;
     const groups = [...new Set(exposed.map((tool) => tool.group))];
+    // Nullable entries so a section that has nothing to say can decline to appear, rather than every
+    // caller having to keep the push order in step with the narrative order by hand.
     const sections = [
         "cat-factory runs coding agents against a team's real repositories: a board of services and " +
             'tasks, each task run through a pipeline of agent steps that opens and merges pull requests. ' +
@@ -23,12 +25,19 @@ export function buildInstructions(selection) {
         `Available tool groups:\n${groups
             .map((group) => `- ${group}: ${CAT_FACTORY_TOOL_GROUPS[group]}`)
             .join('\n')}`,
-        'Two things here cost real money and real time, so confirm with the user before calling them: ' +
-            '`tasks_start` / `tasks_retry` and `jobs_create` each begin an agent run against a real ' +
-            'repository, and `notifications_act` can merge a pull request. Everything else is cheap.',
+        costlyTools(exposed),
         'A run PARKS on a human decision and then waits indefinitely by design; it is not stuck. Read ' +
             'the park with `decisions_list` and answer it with the other `decisions_*` tools, or leave ' +
             'it for a person.',
+        // The two absent operations are the platform's live channels, so "how do I watch a run" is the
+        // question this surface most needs answered in prose. Without it a model either invents a
+        // streaming tool, calls the poll in a tight loop, or reports one non-terminal reading as the
+        // outcome, and the last of those is the one nobody catches, because it looks like an answer.
+        'To WATCH work, poll rather than stream: `tasks_get_run` for a task run, `jobs_get` for a ' +
+            'headless job. An agent step takes minutes, so poll every 15-30 seconds and say so to the ' +
+            'user instead of going quiet. Keep polling until the status is terminal (`done`, `failed`, ' +
+            '`cancelled`) or until `decisions_list` shows a park to answer; anything else is a run still ' +
+            'in flight, and reporting it as the outcome is wrong rather than early.',
         'Results are JSON. Lists are keyset-paginated: pass the `cursor` a page returns to get the ' +
             'next one, and stop when it comes back null (an empty page with a cursor is normal).',
     ];
@@ -40,10 +49,62 @@ export function buildInstructions(selection) {
         sections.push(`The operator switched off these tool groups on THIS server: ${filteredGroups.join(', ')}. ` +
             'The deployment still supports them; they are not reachable from here.');
     }
+    // The per-tool filters are stated in the same voice and for the same reason as the group one. The
+    // deny-list matters most: it is the filter an operator reaches for to keep ONE capability away
+    // from a model, and a model that reads the absence as a missing platform feature will offer to do
+    // it some other way instead of asking the person who switched it off.
+    if (deniedTools.length > 0) {
+        sections.push(`The operator withheld these individual tools on THIS server: ${deniedTools.join(', ')}. ` +
+            'The deployment still supports them; do not look for another route to the same effect.');
+    }
+    if (toolsAllowListed) {
+        sections.push("This server exposes an explicitly chosen subset of the deployment's tools, so what you " +
+            'can see is not the whole API. Everything listed works; anything you expect and cannot ' +
+            'find was left out here on purpose.');
+    }
     // The omissions are stated in the same voice as the filters above, and for the same reason: a
     // model that cannot find a way to watch a run live should learn that the platform streams and
     // that a tool call is the wrong shape for it, rather than concluding the platform does not.
     sections.push(`Not available as tools:\n${CAT_FACTORY_OMITTED_OPERATIONS.map((omitted) => `- ${omitted.route}: ${omitted.reason}`).join('\n')}`);
-    return sections.join('\n\n');
+    return sections.filter(Boolean).join('\n\n');
+}
+/**
+ * The "check with a human first" section, or null when nothing exposed here needs one.
+ *
+ * DERIVED from the generated table's own `destructive` hint rather than restating the tool names in
+ * prose: a list written here would be a second declaration of which tools spend, free to disagree
+ * with the one a host reads off the annotations, and it would go on naming a tool the operator has
+ * withheld on this server. A model told to be careful with a tool it cannot see learns that this
+ * prose is not about the server in front of it.
+ */
+function costlyTools(exposed) {
+    const costly = exposed.filter((tool) => tool.hints?.destructive);
+    if (costly.length === 0)
+        return null;
+    const exposes = (name) => costly.some((tool) => tool.name === name);
+    const lines = [
+        'Confirm with the user before calling these, because each does something a person cannot ' +
+            `simply undo: ${costly.map((tool) => `\`${tool.name}\``).join(', ')}.`,
+    ];
+    // Each consequence is stated only where the tool that has it survived the filters, for the same
+    // reason the names are derived rather than restated: prose describing a capability this server does
+    // not serve teaches a model that the prose is not about the server in front of it.
+    if (['tasks_start', 'tasks_retry', 'jobs_create'].some(exposes)) {
+        lines.push('Starting, retrying or creating work begins an agent run against a real repository: real ' +
+            'model spend, real time.');
+    }
+    if (exposes('notifications_act')) {
+        lines.push('Acting on a notification can merge a pull request.');
+    }
+    if (exposes('tasks_delete')) {
+        lines.push('A deleted task does not come back.');
+    }
+    // Only where there IS something else. A filter can narrow this server down to the spending tools
+    // alone (an allow-list naming just `tasks_start` is the realistic one), and a closing sentence
+    // about everything else would then be describing tools the model cannot see, which teaches it
+    // that this prose is not about the server in front of it.
+    if (exposed.length > costly.length)
+        lines.push('Everything else here is cheap.');
+    return lines.join(' ');
 }
 //# sourceMappingURL=instructions.js.map

package/dist/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,8BAA8B,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAA;AAE9F,8FAA8F;AAC9F,EAAE;AACF,iGAAiG;AACjG,4FAA4F;AAC5F,+FAA+F;AAC/F,gGAAgG;AAChG,2EAA2E;AAE3E;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAwB;IACxD,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,GAAG,SAAS,CAAA;IAC/D,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IAC9D,MAAM,QAAQ,GAAa;QACzB,6FAA6F;YAC3F,8FAA8F;YAC9F,yFAAyF;QAC3F,2BAA2B,MAAM;aAC9B,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,KAAK,uBAAuB,CAAC,KAAK,CAAC,EAAE,CAAC;aAC/D,IAAI,CAAC,IAAI,CAAC,EAAE;QACf,+FAA+F;YAC7F,yFAAyF;YACzF,yFAAyF;QAC3F,+FAA+F;YAC7F,4FAA4F;YAC5F,kBAAkB;QACpB,4FAA4F;YAC1F,qFAAqF;KACxF,CAAA;IACD,IAAI,gBAAgB,EAAE,CAAC;QACrB,QAAQ,CAAC,IAAI,CACX,yFAAyF;YACvF,6EAA6E,CAChF,CAAA;IACH,CAAC;IACD,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,QAAQ,CAAC,IAAI,CACX,+DAA+D,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YAC1F,uEAAuE,CAC1E,CAAA;IACH,CAAC;IACD,8FAA8F;IAC9F,8FAA8F;IAC9F,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,CACX,4BAA4B,8BAA8B,CAAC,GAAG,CAC5D,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,OAAO,CAAC,KAAK,KAAK,OAAO,CAAC,MAAM,EAAE,CACrD,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACf,CAAA;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;AAC9B,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"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"}

package/dist/result.d.ts

@@ -23,6 +23,7 @@ export type ToolResult = {
         type: 'text';
         text: string;
     }[];
+    structuredContent?: Record<string, unknown>;
     isError?: boolean;
 };
 /**
@@ -31,10 +32,16 @@ export type ToolResult = {
  * A `204` endpoint resolves to `undefined`, which is a real answer ("it worked, there is nothing
  * to return") and not an empty one, so it is SAID rather than rendered as `undefined` or as an
  * empty string a model would read as a failure.
+ *
+ * The JSON is COMPACT. Two-space indentation reads better to a human than to a model and costs
+ * roughly a third of every result in whitespace, which on this surface is a third of an
+ * agent-context snapshot; a host that wants it pretty can re-print the structured content it also
+ * gets back.
  */
 export declare function renderResult(value: unknown, options: {
     maxChars?: number;
     toolName: string;
+    structured?: boolean;
 }): ToolResult;
 /**
  * Render a failure as tool content.

package/dist/result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,SAAU,CAAA;AAE/C;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IACzC,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAQD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC/C,UAAU,CAiBZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CA+BrF"}
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,SAAU,CAAA;AAE/C;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IACzC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3C,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAQD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACrE,UAAU,CA8BZ;AA8CD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CA+BrF"}

package/dist/result.js

@@ -23,24 +23,78 @@ function text(value, isError = false) {
  * A `204` endpoint resolves to `undefined`, which is a real answer ("it worked, there is nothing
  * to return") and not an empty one, so it is SAID rather than rendered as `undefined` or as an
  * empty string a model would read as a failure.
+ *
+ * The JSON is COMPACT. Two-space indentation reads better to a human than to a model and costs
+ * roughly a third of every result in whitespace, which on this surface is a third of an
+ * agent-context snapshot; a host that wants it pretty can re-print the structured content it also
+ * gets back.
  */
 export function renderResult(value, options) {
     if (value === undefined) {
-        return text('The request succeeded. This endpoint returns no content.');
+        // A tool that declares an output schema may not answer successfully with no structured content:
+        // the caller's own client raises a PROTOCOL error for that, which is not shown to the model at
+        // all. So an empty body from an operation the spec says answers with one takes the same
+        // deployment-disagrees-with-the-schema route as a non-object below, rather than the honest
+        // "returns no content" that belongs to a `204` operation (which declares no schema).
+        return options.structured
+            ? text(schemaMismatch(options.toolName, 'answered with no body at all'), true)
+            : text('The request succeeded. This endpoint returns no content.');
     }
     const maxChars = options.maxChars ?? DEFAULT_MAX_RESULT_CHARS;
-    const json = JSON.stringify(value, null, 2);
-    if (json.length <= maxChars)
+    const json = JSON.stringify(value);
+    if (json.length > maxChars)
+        return text(overCap(options.toolName, json.length, maxChars), true);
+    if (!options.structured)
         return text(json);
-    // The note goes FIRST and names the truncation in the same breath as the remedy: what follows
-    // is no longer parseable JSON, and a model that starts reading at the top must know that before
-    // it starts, not after it has already summarised half a document as complete.
-    const dropped = json.length - maxChars;
-    const note = `[TRUNCATED] \`${options.toolName}\` returned ${json.length} characters, over this server's ` +
-        `${maxChars}-character limit; the last ${dropped} were dropped. What follows is the beginning ` +
-        'of the response and is NOT valid JSON. Narrow the request instead of reading on: list ' +
-        'endpoints take `limit` and `cursor`, and the debug text reads take `offset`.';
-    return text(`${note}\n\n${json.slice(0, maxChars)}`);
+    if (!isJsonObject(value)) {
+        // The tool DECLARES an output schema, so the protocol obliges a successful result to carry
+        // structured content, and this value cannot be any. Reported as a failure of the call rather
+        // than dropped to text, because it means the deployment answered with something the published
+        // schema does not describe, and a caller silently getting the text form would never find out.
+        return text(schemaMismatch(options.toolName, `returned a ${describeJson(value)}`) +
+            ` The response was: ${json}`, true);
+    }
+    // Both halves, which is what the protocol asks of a tool that returns structured content: the
+    // text block is what a host with no structured-content support shows the model, and the
+    // structured half is what an agent framework consumes without re-parsing prose.
+    return { content: [{ type: 'text', text: json }], structuredContent: value };
+}
+/**
+ * The message for a result that does not fit.
+ *
+ * A REFUSAL, where this used to render the first `maxChars` under a `[TRUNCATED]` note. Two reasons
+ * it changed together: a tool declaring an `outputSchema` may not answer successfully without
+ * structured content, and half an object cannot satisfy the schema it was cut out of, and the old
+ * note itself told the model that what followed was not valid JSON and to narrow instead of reading
+ * on, which is a hundred thousand characters of context spent to deliver that instruction.
+ */
+function overCap(toolName, length, maxChars) {
+    return (`${toolName} returned ${length} characters, over this server's ${maxChars}-character limit, ` +
+        'so none of it was rendered: a response cut off mid-object is not valid JSON, and a model ' +
+        'reading the surviving half summarises it as though it were whole. Narrow the request and ' +
+        'call again (list endpoints take `limit` and `cursor`, and the debug text reads take ' +
+        '`offset`), or raise CAT_FACTORY_MCP_MAX_RESULT_CHARS on this server.');
+}
+/**
+ * The message for a response the published output schema does not describe.
+ *
+ * One wording for both shapes of the same fault, because the fix is the same one either way: this
+ * package and the deployment it is pointed at disagree about what an operation answers with, and
+ * only an upgrade of one of them settles it. Reported as a failed CALL rather than left to the
+ * caller's client, whose protocol-level refusal never reaches the model.
+ */
+function schemaMismatch(toolName, what) {
+    return (`${toolName} ${what}, where its published output schema describes an object. This is a ` +
+        'mismatch between the deployment and this server, not something the arguments caused: check ' +
+        'that the two are on compatible versions.');
+}
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function describeJson(value) {
+    if (value === null)
+        return 'null';
+    return Array.isArray(value) ? 'array' : typeof value;
 }
 /**
  * Render a failure as tool content.

package/dist/result.js.map

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

package/dist/server.d.ts

@@ -2,7 +2,7 @@ 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.2.1";
+export declare const MCP_SERVER_VERSION = "0.3.1";
 /** The name this server reports to a host. */
 export declare const MCP_SERVER_NAME = "cat-factory";
 export interface CatFactoryMcpServer {

package/dist/server.d.ts.map

@@ -1 +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"}
+{"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,CA+E5F"}

package/dist/server.js

@@ -19,7 +19,7 @@ import { CAT_FACTORY_TOOLS } from './tools.generated.js';
 // 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.2.1';
+export const MCP_SERVER_VERSION = '0.3.1';
 /** The name this server reports to a host. */
 export const MCP_SERVER_NAME = 'cat-factory';
 /**
@@ -55,13 +55,19 @@ export function createCatFactoryMcpServer(options) {
             title: tool.title,
             description: tool.description,
             inputSchema: tool.inputSchema,
+            // Declared only where the operation has an object to describe (a `204` has none). A tool that
+            // declares one is then OBLIGED to return `structuredContent` on every success, which is why
+            // `renderResult` refuses an over-cap result rather than truncating it.
+            ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
             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` follows from the HTTP method. The other two come from the generated table
+                // and are present only where the consequence is real money or a merged pull request; where
+                // they are absent the protocol's own defaults apply, which are the cautious ones.
                 readOnlyHint: tool.readOnly,
+                ...(tool.hints
+                    ? { destructiveHint: tool.hints.destructive, idempotentHint: tool.hints.idempotent }
+                    : {}),
             },
         })),
     }));
@@ -80,6 +86,7 @@ export function createCatFactoryMcpServer(options) {
             const result = await tool.invoke(client, args);
             return renderResult(result, {
                 toolName: tool.name,
+                structured: tool.outputSchema !== undefined,
                 ...(options.maxResultChars !== undefined ? { maxChars: options.maxResultChars } : {}),
             });
         }

package/dist/server.js.map

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

package/dist/stdio.d.ts

@@ -0,0 +1,38 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type EnvReadDeps } from './config.ts';
+/** What the boot needs from the process around it. */
+export interface StdioBootDeps extends EnvReadDeps {
+    /** The environment the options are read from. */
+    env: Record<string, string | undefined>;
+    /** Where every human-readable byte goes. NEVER stdout. */
+    log: (line: string) => void;
+    /**
+     * Attach the built server to a transport.
+     *
+     * Defaults to the real stdio transport. A test overrides it rather than the whole server, so
+     * everything up to and including the connect ordering below is the code that actually ships.
+     */
+    connect?: (server: Server) => Promise<void>;
+}
+/** What the boot reports back, so a caller can say it in its own words. */
+export interface StdioBootResult {
+    toolCount: number;
+    baseUrl: string;
+}
+/**
+ * Build the server from the environment and connect it.
+ *
+ * The transport is connected BEFORE the ready line is written. A host reads that line as "this
+ * server is up"; writing it first would mean announcing readiness and then failing to connect, which
+ * is the one ordering that produces a log claiming success next to a server that never served.
+ */
+export declare function bootStdioServer(deps: StdioBootDeps): Promise<StdioBootResult>;
+/**
+ * What to write when the boot failed.
+ *
+ * It names the configuration rather than only the error, because every way this fails is a
+ * configuration problem and the operator reading it is looking at a host's config file: the cause
+ * says what is wrong and the second line says where to fix it.
+ */
+export declare function startupFailureMessage(error: unknown): string;
+//# sourceMappingURL=stdio.d.ts.map

package/dist/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAA;AAEvE,OAAO,EAAY,KAAK,WAAW,EAAkB,MAAM,aAAa,CAAA;AAaxE,sDAAsD;AACtD,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IACvC,0DAA0D;IAC1D,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC5C;AAED,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAUnF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAM5D"}

package/dist/stdio.js

@@ -0,0 +1,31 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ENV_VARS, optionsFromEnv } from './config.js';
+import { createCatFactoryMcpServer } from './server.js';
+/**
+ * Build the server from the environment and connect it.
+ *
+ * The transport is connected BEFORE the ready line is written. A host reads that line as "this
+ * server is up"; writing it first would mean announcing readiness and then failing to connect, which
+ * is the one ordering that produces a log claiming success next to a server that never served.
+ */
+export async function bootStdioServer(deps) {
+    const options = optionsFromEnv(deps.env, deps.readSecretFile ? { readSecretFile: deps.readSecretFile } : {});
+    const { server, tools } = createCatFactoryMcpServer(options);
+    const connect = deps.connect ?? ((built) => built.connect(new StdioServerTransport()));
+    await connect(server);
+    deps.log(`cat-factory MCP server ready: ${tools.length} tools against ${options.baseUrl}\n`);
+    return { toolCount: tools.length, baseUrl: options.baseUrl };
+}
+/**
+ * What to write when the boot failed.
+ *
+ * It names the configuration rather than only the error, because every way this fails is a
+ * configuration problem and the operator reading it is looking at a host's config file: the cause
+ * says what is wrong and the second line says where to fix it.
+ */
+export function startupFailureMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return (`cat-factory MCP server failed to start: ${message}\n` +
+        `Configure it with ${ENV_VARS.baseUrl} and either ${ENV_VARS.apiKey} or ${ENV_VARS.apiKeyFile}.\n`);
+}
+//# sourceMappingURL=stdio.js.map

package/dist/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAChF,OAAO,EAAE,QAAQ,EAAoB,cAAc,EAAE,MAAM,aAAa,CAAA;AACxE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AAiCvD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAmB;IACvD,MAAM,OAAO,GAAG,cAAc,CAC5B,IAAI,CAAC,GAAG,EACR,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CACnE,CAAA;IACD,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,yBAAyB,CAAC,OAAO,CAAC,CAAA;IAC5D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,KAAa,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC,CAAA;IAC9F,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;IACrB,IAAI,CAAC,GAAG,CAAC,iCAAiC,KAAK,CAAC,MAAM,kBAAkB,OAAO,CAAC,OAAO,IAAI,CAAC,CAAA;IAC5F,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAA;AAC9D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACtE,OAAO,CACL,2CAA2C,OAAO,IAAI;QACtD,qBAAqB,QAAQ,CAAC,OAAO,eAAe,QAAQ,CAAC,MAAM,OAAO,QAAQ,CAAC,UAAU,KAAK,CACnG,CAAA;AACH,CAAC"}

package/dist/tools.generated.d.ts

@@ -11,6 +11,15 @@ export interface CatFactoryTool {
     operationId: string;
     /** Whether the call changes nothing (a GET). Hosts use it to decide what needs confirming. */
     readOnly: boolean;
+    /**
+     * The annotations the HTTP method cannot supply, present only where the consequence is real
+     * money or a merged pull request. Absent means the protocol's own cautious defaults apply
+     * (`destructiveHint` true, `idempotentHint` false), which is never worse than the truth.
+     */
+    hints?: {
+        destructive: boolean;
+        idempotent: boolean;
+    };
     description: string;
     inputSchema: {
         type: 'object';
@@ -18,6 +27,19 @@ export interface CatFactoryTool {
         required?: readonly string[];
         additionalProperties: false;
     };
+    /**
+     * The shape of a successful result, absent when the operation answers with no body.
+     *
+     * Rendered permissively ON PURPOSE: no `required`, no `enum`, no closed `anyOf`, no length or
+     * range bounds, and for a union not even `type`. A caller's MCP client VALIDATES a result against
+     * this, and `/api/v1` is additive forever, so every one of those would be a way for an older copy
+     * of this package to reject a newer deployment's honest answer. What is left is the field names and
+     * their types, plus the known members of a vocabulary named in prose.
+     */
+    outputSchema?: {
+        type: 'object';
+        properties: Record<string, unknown>;
+    };
     /** Forward the validated arguments to the SDK. */
     invoke: (client: CatFactoryClient, args: Record<string, unknown>) => Promise<unknown>;
 }

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

@@ -1 +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,EAmXtD,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"}
+{"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;;;;OAIG;IACH,KAAK,CAAC,EAAE;QAAE,WAAW,EAAE,OAAO,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAA;IACrD,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;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE;QACb,IAAI,EAAE,QAAQ,CAAA;QACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACpC,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,EA4ZtD,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"}