@cosyte/cli 0.0.6 → 0.1.1

package/dist/mcp.d.cts

@@ -1,5 +1,5 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { R as RunDeps } from './io-B2EobRzC.cjs';
+import { C as CliCode, R as RunDeps } from './io-C9bSG2zF.cjs';
 import 'node:stream';
 
 /**
@@ -29,6 +29,10 @@ declare const SERVER_INFO: {
  * the caller connects it to stdio (in production) or to an in-memory transport (in tests), so the
  * handler wiring is drivable without a subprocess.
  *
+ * Both handlers are **explicit about what reaches the wire**: `tools/list` copies each tool's title,
+ * description, input schema and **output schema**, and `tools/call` passes the whole structured result
+ * through, so what a client validates is exactly what the tool declared and produced.
+ *
  * @returns A configured, unconnected {@link Server}.
  * @example
  * ```ts
@@ -73,6 +77,14 @@ declare function startStdioServer(): Promise<void>;
  * carries only the value-free diagnostic the command already produced (a stable code + positional
  * context), never an input value.
  *
+ * **The published contract.** Every tool declares an {@link McpToolOutputSchema}, and every dispatch
+ * path returns {@link McpStructuredResult} conforming to the schema its own tool declared, so a client
+ * validates an object instead of pattern-matching prose. The text content block carries the serialized
+ * JSON of that same structured value. On a **failed** call every field of the structured result is
+ * drawn from a fixed enumeration (the outcome vocabulary, the exit-code contract, the
+ * {@link CLI_CODES} registry), so no part of the caller's input can appear in it; the tool's own
+ * payload is present only on a call that produced data, which is the explicit request.
+ *
  * @packageDocumentation
  */
 
@@ -81,21 +93,46 @@ interface McpTextContent {
     readonly type: "text";
     readonly text: string;
 }
-/** Value-free metadata every tool result carries so an agent can branch on the outcome. */
-interface McpToolMeta {
-    /** The CLI exit code the underlying command resolved to (the documented exit-code contract). */
-    readonly exit: number;
+/**
+ * The outcome of a tool call, as the single property a client branches on with **no text parsing**:
+ * `success` the operation completed cleanly, `verdict` the tool ran and reports a negative finding
+ * *about the message* (an invalid resource, an error-severity conversion issue), `failed` the call
+ * itself produced no data (a usage mistake, unparseable input, an unavailable parser, an internal
+ * error). `verdict` and `failed` are the two a text blob could never reliably separate.
+ */
+type McpToolStatus = "success" | "verdict" | "failed";
+/**
+ * The **structured result** of one tool call: the value-free outcome fields every tool carries, plus
+ * that tool's own payload on a call that produced data. This is the object an MCP `tools/call` reply
+ * carries as `structuredContent`, and the value whose serialization is the reply's text block.
+ */
+interface McpStructuredResult {
     /** `true` iff the tool *call* succeeded (data was produced): distinct from a negative verdict. */
     readonly ok: boolean;
+    /** The three-way outcome a client branches on: see {@link McpToolStatus}. */
+    readonly status: McpToolStatus;
+    /** The CLI exit code the underlying command resolved to (the documented exit-code contract). */
+    readonly exit: number;
+    /** The stable, value-free diagnostic code on a failed call; absent when data was produced. */
+    readonly code?: CliCode;
+    /** The tool's own payload (the parsed model, the verdict, the summary, the Bundle); absent on a
+     * failed call, which produced none. */
+    readonly data?: unknown;
 }
+/**
+ * The historical name for a tool result's structured content, kept as the published alias of
+ * {@link McpStructuredResult}.
+ */
+type McpToolMeta = McpStructuredResult;
 /**
  * The value-free result of dispatching one MCP tool call. Structurally an MCP `CallToolResult`: a text
- * content channel, an `isError` flag, and value-free `structuredContent` metadata.
+ * content channel carrying the serialized structured result, an `isError` flag, and the
+ * {@link McpStructuredResult} itself.
  */
 interface McpToolResult {
     readonly content: readonly McpTextContent[];
     readonly isError: boolean;
-    readonly structuredContent: McpToolMeta;
+    readonly structuredContent: McpStructuredResult;
 }
 /** A JSON-Schema description of a tool's input (the wire schema advertised to `tools/list`). */
 interface McpToolInputSchema {
@@ -104,11 +141,29 @@ interface McpToolInputSchema {
     readonly required?: readonly string[];
     readonly additionalProperties?: boolean;
 }
-/** A tool advertised by the server: an agent-callable name, a description, and its input schema. */
+/**
+ * A JSON-Schema description of a tool's **structured result**: the schema advertised alongside the
+ * tool on `tools/list` and the one every reply from that tool conforms to. The protocol fixes the
+ * root type as `object`; `required` and `additionalProperties` are declared (never omitted) so the
+ * published contract states exactly which properties a client may rely on and forbids the rest.
+ */
+interface McpToolOutputSchema {
+    readonly type: "object";
+    readonly properties: Readonly<Record<string, unknown>>;
+    readonly required: readonly string[];
+    readonly additionalProperties: boolean;
+}
+/**
+ * A tool advertised by the server: an agent-callable name, a human-readable title, a description, and
+ * the schemas of its input and of its structured result.
+ */
 interface McpToolDef {
     readonly name: string;
+    /** A human-readable title, so these four generic names stay distinguishable in an aggregating client. */
+    readonly title: string;
     readonly description: string;
     readonly inputSchema: McpToolInputSchema;
+    readonly outputSchema: McpToolOutputSchema;
 }
 /**
  * The tools this server exposes: the read/convert operations that share the `core` cleanly and whose
@@ -124,6 +179,11 @@ declare const TOOL_DEFS: readonly McpToolDef[];
  * posture), and maps the {@link RunResult} onto an MCP result. An unknown tool name or a missing
  * `content` argument is a value-free usage error, never a thrown stack trace carrying input.
  *
+ * Every path returns an {@link McpStructuredResult} conforming to the called tool's declared
+ * {@link McpToolDef.outputSchema}, with the same value serialized into the text content block. An
+ * unknown tool name has no schema of its own, so it answers with the shared outcome fields alone,
+ * which every tool's schema declares.
+ *
  * @param name - The tool name (one of {@link TOOL_DEFS}).
  * @param args - The tool-call arguments object.
  * @param deps - Optional {@link RunDeps} override (tests inject fakes); defaults to feeding `content` as
@@ -136,8 +196,9 @@ declare const TOOL_DEFS: readonly McpToolDef[];
  *
  * const r = await dispatchTool("parse", { content: '{"resourceType":"Patient"}' });
  * r.isError; // => false
+ * r.structuredContent.status; // => "success"
  * ```
  */
 declare function dispatchTool(name: string, args: Readonly<Record<string, unknown>>, deps?: RunDeps): Promise<McpToolResult>;
 
-export { type McpTextContent, type McpToolDef, type McpToolInputSchema, type McpToolMeta, type McpToolResult, SERVER_INFO, TOOL_DEFS, createMcpServer, dispatchTool, startStdioServer };
+export { type McpStructuredResult, type McpTextContent, type McpToolDef, type McpToolInputSchema, type McpToolMeta, type McpToolOutputSchema, type McpToolResult, type McpToolStatus, SERVER_INFO, TOOL_DEFS, createMcpServer, dispatchTool, startStdioServer };

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { R as RunDeps } from './io-B2EobRzC.js';
+import { C as CliCode, R as RunDeps } from './io-C9bSG2zF.js';
 import 'node:stream';
 
 /**
@@ -29,6 +29,10 @@ declare const SERVER_INFO: {
  * the caller connects it to stdio (in production) or to an in-memory transport (in tests), so the
  * handler wiring is drivable without a subprocess.
  *
+ * Both handlers are **explicit about what reaches the wire**: `tools/list` copies each tool's title,
+ * description, input schema and **output schema**, and `tools/call` passes the whole structured result
+ * through, so what a client validates is exactly what the tool declared and produced.
+ *
  * @returns A configured, unconnected {@link Server}.
  * @example
  * ```ts
@@ -73,6 +77,14 @@ declare function startStdioServer(): Promise<void>;
  * carries only the value-free diagnostic the command already produced (a stable code + positional
  * context), never an input value.
  *
+ * **The published contract.** Every tool declares an {@link McpToolOutputSchema}, and every dispatch
+ * path returns {@link McpStructuredResult} conforming to the schema its own tool declared, so a client
+ * validates an object instead of pattern-matching prose. The text content block carries the serialized
+ * JSON of that same structured value. On a **failed** call every field of the structured result is
+ * drawn from a fixed enumeration (the outcome vocabulary, the exit-code contract, the
+ * {@link CLI_CODES} registry), so no part of the caller's input can appear in it; the tool's own
+ * payload is present only on a call that produced data, which is the explicit request.
+ *
  * @packageDocumentation
  */
 
@@ -81,21 +93,46 @@ interface McpTextContent {
     readonly type: "text";
     readonly text: string;
 }
-/** Value-free metadata every tool result carries so an agent can branch on the outcome. */
-interface McpToolMeta {
-    /** The CLI exit code the underlying command resolved to (the documented exit-code contract). */
-    readonly exit: number;
+/**
+ * The outcome of a tool call, as the single property a client branches on with **no text parsing**:
+ * `success` the operation completed cleanly, `verdict` the tool ran and reports a negative finding
+ * *about the message* (an invalid resource, an error-severity conversion issue), `failed` the call
+ * itself produced no data (a usage mistake, unparseable input, an unavailable parser, an internal
+ * error). `verdict` and `failed` are the two a text blob could never reliably separate.
+ */
+type McpToolStatus = "success" | "verdict" | "failed";
+/**
+ * The **structured result** of one tool call: the value-free outcome fields every tool carries, plus
+ * that tool's own payload on a call that produced data. This is the object an MCP `tools/call` reply
+ * carries as `structuredContent`, and the value whose serialization is the reply's text block.
+ */
+interface McpStructuredResult {
     /** `true` iff the tool *call* succeeded (data was produced): distinct from a negative verdict. */
     readonly ok: boolean;
+    /** The three-way outcome a client branches on: see {@link McpToolStatus}. */
+    readonly status: McpToolStatus;
+    /** The CLI exit code the underlying command resolved to (the documented exit-code contract). */
+    readonly exit: number;
+    /** The stable, value-free diagnostic code on a failed call; absent when data was produced. */
+    readonly code?: CliCode;
+    /** The tool's own payload (the parsed model, the verdict, the summary, the Bundle); absent on a
+     * failed call, which produced none. */
+    readonly data?: unknown;
 }
+/**
+ * The historical name for a tool result's structured content, kept as the published alias of
+ * {@link McpStructuredResult}.
+ */
+type McpToolMeta = McpStructuredResult;
 /**
  * The value-free result of dispatching one MCP tool call. Structurally an MCP `CallToolResult`: a text
- * content channel, an `isError` flag, and value-free `structuredContent` metadata.
+ * content channel carrying the serialized structured result, an `isError` flag, and the
+ * {@link McpStructuredResult} itself.
  */
 interface McpToolResult {
     readonly content: readonly McpTextContent[];
     readonly isError: boolean;
-    readonly structuredContent: McpToolMeta;
+    readonly structuredContent: McpStructuredResult;
 }
 /** A JSON-Schema description of a tool's input (the wire schema advertised to `tools/list`). */
 interface McpToolInputSchema {
@@ -104,11 +141,29 @@ interface McpToolInputSchema {
     readonly required?: readonly string[];
     readonly additionalProperties?: boolean;
 }
-/** A tool advertised by the server: an agent-callable name, a description, and its input schema. */
+/**
+ * A JSON-Schema description of a tool's **structured result**: the schema advertised alongside the
+ * tool on `tools/list` and the one every reply from that tool conforms to. The protocol fixes the
+ * root type as `object`; `required` and `additionalProperties` are declared (never omitted) so the
+ * published contract states exactly which properties a client may rely on and forbids the rest.
+ */
+interface McpToolOutputSchema {
+    readonly type: "object";
+    readonly properties: Readonly<Record<string, unknown>>;
+    readonly required: readonly string[];
+    readonly additionalProperties: boolean;
+}
+/**
+ * A tool advertised by the server: an agent-callable name, a human-readable title, a description, and
+ * the schemas of its input and of its structured result.
+ */
 interface McpToolDef {
     readonly name: string;
+    /** A human-readable title, so these four generic names stay distinguishable in an aggregating client. */
+    readonly title: string;
     readonly description: string;
     readonly inputSchema: McpToolInputSchema;
+    readonly outputSchema: McpToolOutputSchema;
 }
 /**
  * The tools this server exposes: the read/convert operations that share the `core` cleanly and whose
@@ -124,6 +179,11 @@ declare const TOOL_DEFS: readonly McpToolDef[];
  * posture), and maps the {@link RunResult} onto an MCP result. An unknown tool name or a missing
  * `content` argument is a value-free usage error, never a thrown stack trace carrying input.
  *
+ * Every path returns an {@link McpStructuredResult} conforming to the called tool's declared
+ * {@link McpToolDef.outputSchema}, with the same value serialized into the text content block. An
+ * unknown tool name has no schema of its own, so it answers with the shared outcome fields alone,
+ * which every tool's schema declares.
+ *
  * @param name - The tool name (one of {@link TOOL_DEFS}).
  * @param args - The tool-call arguments object.
  * @param deps - Optional {@link RunDeps} override (tests inject fakes); defaults to feeding `content` as
@@ -136,8 +196,9 @@ declare const TOOL_DEFS: readonly McpToolDef[];
  *
  * const r = await dispatchTool("parse", { content: '{"resourceType":"Patient"}' });
  * r.isError; // => false
+ * r.structuredContent.status; // => "success"
  * ```
  */
 declare function dispatchTool(name: string, args: Readonly<Record<string, unknown>>, deps?: RunDeps): Promise<McpToolResult>;
 
-export { type McpTextContent, type McpToolDef, type McpToolInputSchema, type McpToolMeta, type McpToolResult, SERVER_INFO, TOOL_DEFS, createMcpServer, dispatchTool, startStdioServer };
+export { type McpStructuredResult, type McpTextContent, type McpToolDef, type McpToolInputSchema, type McpToolMeta, type McpToolOutputSchema, type McpToolResult, type McpToolStatus, SERVER_INFO, TOOL_DEFS, createMcpServer, dispatchTool, startStdioServer };