@cosyte/cli 0.0.1

package/dist/mcp.d.ts

@@ -0,0 +1,143 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { R as RunDeps } from './io-B2EobRzC.js';
+import 'node:stream';
+
+/**
+ * The **stdio MCP server**: the JSON-RPC/stdio adapter over the same shared `core`/`commands` the
+ * `cosyte` terminal command drives. This is the **only** module that touches
+ * `@modelcontextprotocol/sdk`, so the SDK (the CLI's single third-party runtime dependency) stays
+ * **isolated behind the `./mcp` subpath and lazy-loaded**: a `cosyte parse` invocation never imports
+ * this file and therefore never loads the SDK (proven by `mcp-isolation.test.ts`).
+ *
+ * The server is a **local stdio subprocess**, implicitly trusted by the user/agent that launched it,
+ * not a hosted network endpoint. It is **stateless per call**: each tool request is one operation
+ * over the wrapped libraries, with the same value-free PHI posture the CLI proves once and both
+ * adapters inherit.
+ *
+ * @packageDocumentation
+ */
+
+/** The MCP server identity advertised to a client on connect. */
+declare const SERVER_INFO: {
+    readonly name: "cosyte";
+    readonly version: "0.0.0";
+};
+/**
+ * Build the cosyte MCP {@link Server} with its two request handlers wired to the shared tool surface:
+ * `tools/list` advertises {@link TOOL_DEFS}, and `tools/call` routes to {@link dispatchTool} (the same
+ * command handlers the terminal uses). The returned server is **not yet connected** to a transport:
+ * 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.
+ *
+ * @returns A configured, unconnected {@link Server}.
+ * @example
+ * ```ts
+ * import { createMcpServer } from "@cosyte/cli/mcp";
+ *
+ * const server = createMcpServer();
+ * typeof server.connect; // => "function"
+ * ```
+ */
+declare function createMcpServer(): Server;
+/**
+ * Start the cosyte MCP server on **stdio** and resolve once the transport is connected. The process
+ * then stays alive serving requests until its stdin closes. This is the entry both the `cosyte-mcp`
+ * bin and the `cosyte mcp` subcommand call.
+ *
+ * @returns A promise that resolves when the stdio transport is connected.
+ * @example
+ * ```ts
+ * import { startStdioServer } from "@cosyte/cli/mcp";
+ *
+ * typeof startStdioServer; // => "function"
+ * ```
+ */
+declare function startStdioServer(): Promise<void>;
+
+/**
+ * The **agent-facing tool surface** of the cosyte MCP server: the *second adapter* over the same
+ * `core`/`commands` the `cosyte` terminal command drives. This module
+ * is deliberately **SDK-free**: it declares the tools (name, description, JSON-Schema input) and maps a
+ * tool call onto the existing command handlers, returning a plain, value-free MCP-shaped result. The
+ * `@modelcontextprotocol/sdk` wiring lives one layer up in `./server.ts`, so the tool *logic* is unit-
+ * testable without the SDK and the SDK stays isolated behind the `./mcp` subpath.
+ *
+ * **The shared-core guarantee.** A tool does not re-implement anything: `parse` calls
+ * {@link parseCommand}, `validate` calls {@link validateCommand}, etc., each with `--json` so the
+ * library's result lands as machine JSON, so `cosyte parse` and the MCP `parse` tool agree by
+ * construction. The tool feeds the caller's `content` string in as if it were piped on stdin (`-`).
+ *
+ * **The PHI posture (load-bearing).** Every tool runs under the {@link VALUE_FREE} posture. There is
+ * **no** `--unsafe-show-values` door on the agent surface. A tool's *result* carries the requested data
+ * (the parsed model / converted bundle: the explicit request, the data channel), but a tool *error*
+ * carries only the value-free diagnostic the command already produced (a stable code + positional
+ * context), never an input value.
+ *
+ * @packageDocumentation
+ */
+
+/** A single text content block in an MCP tool result. */
+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;
+    /** `true` iff the tool *call* succeeded (data was produced): distinct from a negative verdict. */
+    readonly ok: boolean;
+}
+/**
+ * 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.
+ */
+interface McpToolResult {
+    readonly content: readonly McpTextContent[];
+    readonly isError: boolean;
+    readonly structuredContent: McpToolMeta;
+}
+/** A JSON-Schema description of a tool's input (the wire schema advertised to `tools/list`). */
+interface McpToolInputSchema {
+    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 description, and its input schema. */
+interface McpToolDef {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: McpToolInputSchema;
+}
+/**
+ * The tools this server exposes: the read/convert operations that share the `core` cleanly and whose
+ * results are safe to hand an agent. `redact`/`deid` (gated on `@cosyte/deid`)
+ * and `map-codes` are deliberately **not** exposed yet; they land when the terminal command's ground
+ * layer and the tool's PHI/So shape are settled.
+ */
+declare const TOOL_DEFS: readonly McpToolDef[];
+/**
+ * Dispatch one MCP tool call to the shared command layer and return a value-free {@link McpToolResult}.
+ * This is the agent-surface analogue of {@link run}: it validates the arguments, feeds the inline
+ * `content` through the same command handlers the terminal uses (under the always-on {@link VALUE_FREE}
+ * 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.
+ *
+ * @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
+ *   stdin. An unexpected throw from a command is mapped to a value-free `CLI_INTERNAL` result, never
+ *   propagated to the SDK (which would surface the raw message).
+ * @returns A value-free {@link McpToolResult}; this function never throws.
+ * @example
+ * ```ts
+ * import { dispatchTool } from "@cosyte/cli/mcp";
+ *
+ * const r = await dispatchTool("parse", { content: '{"resourceType":"Patient"}' });
+ * r.isError; // => false
+ * ```
+ */
+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 };