stitchkit 0.0.1 → 0.2.0

package/dist/tools/manifest.d.ts

@@ -0,0 +1,13 @@
+import type { MountableTool } from './mount';
+export interface ToolManifestEntry {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * Build a searchable manifest from collected tools — name, description and
+ * JSON Schema for each. Use it to power a `tool_search` native tool: the app
+ * decides the search algorithm and the unlock mechanism.
+ */
+export declare function buildToolManifest(tools: MountableTool[]): ToolManifestEntry[];
+//# sourceMappingURL=manifest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/tools/manifest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,iBAAiB,EAAE,CAM7E"}

package/dist/tools/mcp-handler.d.ts

@@ -0,0 +1,21 @@
+import { type McpServerBuildConfig } from './mcp';
+export interface McpHandlerConfig<TAuth> extends McpServerBuildConfig<TAuth> {
+    /** Resolve an incoming request to an identity. Return `null` → 401. */
+    auth: (req: Request) => TAuth | null | Promise<TAuth | null>;
+}
+/**
+ * Build a Streamable-HTTP MCP request handler (`Request → Response`).
+ *
+ * Owns the entire MCP server lifecycle — SSE event store, per-session
+ * transports, the `McpServer` instances — so the consuming app never imports
+ * `@modelcontextprotocol/sdk` itself. The app only declares WHAT to expose:
+ * how to authenticate and which contract services. MCP tools come from
+ * contracts; native multimodal tools attach via `nativeTools`.
+ *
+ * The server itself is built by the transport-neutral `buildMcpServer` — the
+ * same core used by `createStdioMcpServer`.
+ *
+ * Mount the returned handler in your server's fetch router (e.g. under `/mcp`).
+ */
+export declare function createMcpHandler<TAuth>(config: McpHandlerConfig<TAuth>): (req: Request) => Promise<Response>;
+//# sourceMappingURL=mcp-handler.d.ts.map

package/dist/tools/mcp-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-handler.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-handler.ts"],"names":[],"mappings":"AASA,OAAO,EAAkB,KAAK,oBAAoB,EAAsB,MAAM,OAAO,CAAC;AAyDtF,MAAM,WAAW,gBAAgB,CAAC,KAAK,CAAE,SAAQ,oBAAoB,CAAC,KAAK,CAAC;IAC1E,uEAAuE;IACvE,IAAI,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;CAC9D;AAYD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EACpC,MAAM,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAC9B,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA+DrC"}

package/dist/tools/mcp-stdio.d.ts

@@ -0,0 +1,25 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type McpServerBuildConfig } from './mcp';
+/**
+ * Config for a stdio MCP server. Unlike the HTTP handler, a stdio server is a
+ * single process serving one client — identity is resolved ONCE at startup
+ * (from an env var / CLI arg), not per request.
+ */
+export interface StdioMcpServerConfig<TAuth> extends McpServerBuildConfig<TAuth> {
+    /** Identity for the single stdio session — a value or a promise of one. */
+    auth: TAuth | Promise<TAuth>;
+}
+/**
+ * Build an MCP server and connect it over stdio — the server runs as a
+ * subprocess of the MCP client, on the client's machine, so it can reach the
+ * client's local filesystem.
+ *
+ * Same contract pipeline as `createMcpHandler` (`buildMcpServer`); only the
+ * transport differs. For a local CLI: resolve the identity from `process.env`
+ * and pass it as `auth`.
+ *
+ * Note: stdout is reserved for the JSON-RPC stream — the caller MUST keep all
+ * logging on stderr (`console.error`), never `console.log`.
+ */
+export declare function createStdioMcpServer<TAuth>(config: StdioMcpServerConfig<TAuth>): Promise<McpServer>;
+//# sourceMappingURL=mcp-stdio.d.ts.map

package/dist/tools/mcp-stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-stdio.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-stdio.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,EAAkB,KAAK,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAElE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,KAAK,CAAE,SAAQ,oBAAoB,CAAC,KAAK,CAAC;IAC9E,2EAA2E;IAC3E,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAC9C,MAAM,EAAE,oBAAoB,CAAC,KAAK,CAAC,GAClC,OAAO,CAAC,SAAS,CAAC,CAKpB"}

package/dist/tools/mcp.d.ts

@@ -0,0 +1,92 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServiceDef, StitchLogger } from '../server/types';
+import { type ToolCallHooks, type ToolLifecycle } from './execute';
+import { type ToolExtend } from './mount';
+/**
+ * What to do when a tool's schema cannot be advertised on the MCP surface — a
+ * union / discriminated-union input (MCP needs an object), or a construct
+ * JSON Schema cannot represent (`z.date()`, `z.map()`, …):
+ * - `throw` (default) — fail the build loudly, listing every bad tool. Better
+ *   a failed deploy than a tool that silently vanishes from the MCP surface.
+ * - `warn` — log and drop the tool.
+ * - `skip` — drop the tool silently.
+ */
+export type IncompatibleSchemaPolicy = 'throw' | 'skip' | 'warn';
+export interface McpMountConfig {
+    context?: Record<string, unknown>;
+    /** Tool-call observability hooks. */
+    hooks?: ToolCallHooks;
+    /**
+     * Auth / scope gate and result transform for every tool call — the tool-side
+     * twin of `createServer`'s `beforeHandle` / `afterHandle`. Pass the same
+     * `createAuthHook` result here as on the HTTP server to guard tools too;
+     * without it a tool call bypasses the HTTP `beforeHandle` auth gate.
+     */
+    lifecycle?: ToolLifecycle;
+    extend?: ToolExtend;
+    /** What to do when a tool's schema is not MCP-compatible. Default `'throw'`. */
+    onIncompatibleSchema?: IncompatibleSchemaPolicy;
+    /** Logger for the `'warn'` policy — defaults to `console`. */
+    logger?: StitchLogger;
+    /** Coerce JSON-stringified arrays/objects in tool arguments. Default: true. */
+    coerceJsonArgs?: boolean;
+    /** Flatten discriminated union inputs into a single object. Default: false. */
+    flattenUnionInput?: boolean;
+    /** Global error hint injected into every failed tool result. */
+    errorHint?: (toolName: string, errorCode: string) => string | null;
+}
+/**
+ * Validate that every contract tool in `services` can be advertised on the MCP
+ * surface — object-shaped, JSON Schema-compatible input / output, no tool-name
+ * collision across services. The build-time check behind `mountMcp` — also
+ * callable on its own (a startup assertion, a test) to fail a deploy before
+ * the first request.
+ */
+export declare function validateMcpSchemas(services: ServiceDef[], onIncompatibleSchema?: IncompatibleSchemaPolicy, logger?: StitchLogger): void;
+export declare function mountMcp(mcpServer: McpServer, services: ServiceDef | ServiceDef[], config?: McpMountConfig): void;
+/**
+ * Transport-neutral build config for an MCP server — everything needed to turn
+ * contract services into a live `McpServer`, minus how the identity is
+ * resolved. `createMcpHandler` (HTTP) and `createStdioMcpServer` (stdio) each
+ * add their own `auth` on top.
+ */
+export interface McpServerBuildConfig<TAuth> {
+    /** MCP server identity (name + version). */
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    /** Contract services exposed as MCP tools — may depend on the identity. */
+    services: ServiceDef[] | ((auth: TAuth) => ServiceDef[]);
+    /** Context merged into every contract handler (`mountMcp` context). */
+    context?: (auth: TAuth) => Record<string, unknown>;
+    /** Tool-call observability hooks — `afterToolCall` fires for every result
+     *  (success and error), so the consuming app can log MCP tool outcomes. */
+    hooks?: ToolCallHooks;
+    /** Auth / scope gate and result transform for every tool call — pass the
+     *  same `createAuthHook` result used for the HTTP `beforeHandle` to guard
+     *  tools with the identical rules. */
+    lifecycle?: ToolLifecycle;
+    /** What to do when a tool's schema is not MCP-compatible. Default `'throw'`. */
+    onIncompatibleSchema?: IncompatibleSchemaPolicy;
+    /** Logger for schema-incompatibility warnings — defaults to `console`. */
+    logger?: StitchLogger;
+    /** Register native (non-contract) MCP tools — receives the `McpServer`
+     *  directly. For tools returning multimodal content, e.g. `mountViewFile`. */
+    nativeTools?: (server: McpServer) => void;
+    /** Server instructions — a short (≤2KB) hint to the host on when and how to
+     *  use these tools. Surfaced to MCP tool-search. */
+    instructions?: string;
+    /** Coerce JSON-stringified arrays/objects in tool arguments. Default: true. */
+    coerceJsonArgs?: boolean;
+    /** Flatten discriminated union inputs into a single object. Default: false. */
+    flattenUnionInput?: boolean;
+    /** Global error hint injected into every failed tool result. */
+    errorHint?: (toolName: string, errorCode: string) => string | null;
+}
+/**
+ * Build an `McpServer` from contract services for a resolved identity.
+ * Transport-agnostic — the shared core behind every MCP transport.
+ */
+export declare function buildMcpServer<TAuth>(config: McpServerBuildConfig<TAuth>, auth: TAuth): McpServer;
+//# sourceMappingURL=mcp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/tools/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,aAAa,EAGnB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;GAQG;AACH,MAAM,MAAM,wBAAwB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AA8JjE,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,gFAAgF;IAChF,oBAAoB,CAAC,EAAE,wBAAwB,CAAC;IAChD,8DAA8D;IAC9D,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACpE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,UAAU,EAAE,EACtB,oBAAoB,GAAE,wBAAkC,EACxD,MAAM,CAAC,EAAE,YAAY,GACpB,IAAI,CAWN;AAED,wBAAgB,QAAQ,CACtB,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,cAAmB,GAC1B,IAAI,CAsDN;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB,CAAC,KAAK;IACzC,4CAA4C;IAC5C,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,2EAA2E;IAC3E,QAAQ,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK,UAAU,EAAE,CAAC,CAAC;IACzD,uEAAuE;IACvE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD;+EAC2E;IAC3E,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;0CAEsC;IACtC,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,gFAAgF;IAChF,oBAAoB,CAAC,EAAE,wBAAwB,CAAC;IAChD,0EAA0E;IAC1E,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;kFAC8E;IAC9E,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC;IAC1C;wDACoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACpE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAClC,MAAM,EAAE,oBAAoB,CAAC,KAAK,CAAC,EACnC,IAAI,EAAE,KAAK,GACV,SAAS,CAoBX"}

package/dist/tools/mount.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared mounting machinery for MCP and agent tools. `mountMcp` and `mountAgent`
+ * differ only in their transport SDK — the method walk, the schema merge, the
+ * extend handling and the call execution are identical and live here.
+ */
+import { z } from 'zod';
+import type { Transport, TransportSource } from '../contract';
+import type { MethodDef, ServiceDef } from '../server/types';
+import { type ToolCallHooks, type ToolLifecycle, type ToolResult } from './execute';
+/**
+ * Extra arguments folded into a mounted tool's schema — the host supplies them,
+ * `resolve` turns them into handler context. Shared by `mountMcp` / `mountAgent`.
+ */
+export interface ToolExtend {
+    /** Extra Zod fields added to every (matching) tool's input schema. */
+    schema: Record<string, z.ZodType>;
+    /** Turn the extra arguments into context merged into the handler. */
+    resolve: (args: Record<string, unknown>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /** Limit the extension to specific methods — default: every method. */
+    filter?: (service: ServiceDef, method: MethodDef) => boolean;
+}
+/** One contract method resolved for mounting as a tool. */
+export interface MountableTool {
+    /** The contract method behind the tool. */
+    method: MethodDef<unknown, unknown, unknown>;
+    /** Tool name — the `toolName` override, else derived from service + method. */
+    name: string;
+    /** Merged params + input schema, with the extend fields folded in when they apply. */
+    schema: z.ZodType;
+    /** Whether `ToolExtend` applies to this method. */
+    shouldExtend: boolean;
+}
+export interface CollectToolsConfig {
+    extend?: ToolExtend;
+    /** Coerce JSON-stringified arrays/objects in tool arguments. Default: true. */
+    coerceJsonArgs?: boolean;
+    /** Flatten discriminated union inputs into a single object for MCP. Default: false. */
+    flattenUnionInput?: boolean;
+}
+/**
+ * Walk a service's methods and resolve each one exposed on `transport` to a
+ * tool name and schema — the shared front half of `mountMcp` / `mountAgent`.
+ */
+export declare function collectTools(service: ServiceDef, transport: Transport, config?: CollectToolsConfig): MountableTool[];
+/** Per-mount config a tool runner closes over. */
+export interface ToolRunnerConfig {
+    /** Transport tag put on every call's context. */
+    source: TransportSource;
+    /** Extend applied at mount — its arguments are resolved then stripped. */
+    extend?: ToolExtend;
+    /** Static context merged into every handler. */
+    context?: Record<string, unknown>;
+    /** Tool-call observability hooks. */
+    hooks?: ToolCallHooks;
+    /** Auth / scope gate and result transform — runs for every tool call. */
+    lifecycle?: ToolLifecycle;
+    /** Global error hint injected into every failed tool result. */
+    errorHint?: (toolName: string, errorCode: string) => string | null;
+}
+/**
+ * Build the call executor for a mount — resolve the extend context, strip the
+ * extend arguments, execute. The shared back half of `mountMcp` / `mountAgent`.
+ */
+export declare function createToolRunner(config: ToolRunnerConfig): (tool: MountableTool, rawArgs: Record<string, unknown>) => Promise<ToolResult>;
+/**
+ * Shape a failed `ToolResult` into the `{ error, details?, _hint? }` object
+ * both transports return on error. When a global `errorHint` is provided, it
+ * is appended after the per-error `AppError.hint` (if any).
+ */
+export declare function formatToolError(result: Extract<ToolResult, {
+    ok: false;
+}>, toolName?: string, errorHint?: (toolName: string, errorCode: string) => string | null): Record<string, unknown>;
+//# sourceMappingURL=mount.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../src/tools/mount.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,WAAW,CAAC;AAKnB;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IAClC,qEAAqE;IACrE,OAAO,EAAE,CACP,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAChE,uEAAuE;IACvE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC;CAC9D;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,MAAM,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7C,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC;IAClB,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC;CACvB;AAkBD,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,uFAAuF;IACvF,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,SAAS,EACpB,MAAM,GAAE,kBAAuB,GAC9B,aAAa,EAAE,CAuBjB;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,MAAM,EAAE,eAAe,CAAC;IACxB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,yEAAyE;IACzE,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,gEAAgE;IAChE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACpE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,gBAAgB,GACvB,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAqBhF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,EAC1C,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GACjE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB"}

package/dist/tools/names.d.ts

@@ -0,0 +1,2 @@
+export declare function toToolName(serviceName: string, methodName: string): string;
+//# sourceMappingURL=names.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../src/tools/names.ts"],"names":[],"mappings":"AAiBA,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAY1E"}

package/dist/tools/remote.d.ts

@@ -0,0 +1,22 @@
+import type { HttpClient } from '../browser/http';
+import type { ContractDef, EndpointDef } from '../contract';
+import type { ServiceDef } from '../server/types';
+export interface ImplementRemoteOptions {
+    /**
+     * Rewrite a call's arguments before they are forwarded to the remote API.
+     * Receives the endpoint key and the merged args, returns the args to send —
+     * e.g. to upload a local file referenced in the args and swap in its URL.
+     */
+    transformArgs?: (endpointKey: string, args: Record<string, unknown>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+}
+/**
+ * Bind a contract to a remote HTTP client, producing a `ServiceDef` whose every
+ * handler forwards the call to the remote API. The transport twin of
+ * `implement`: instead of local business logic, each endpoint proxies to a
+ * deployed server.
+ *
+ * Used to build a thin local MCP / agent server that re-exposes a remote API —
+ * `buildMcpServer({ services: contracts.map((c) => implementRemote(c, http)) })`.
+ */
+export declare function implementRemote<T extends Record<string, EndpointDef>>(contract: ContractDef<T, string>, http: HttpClient, options?: ImplementRemoteOptions): ServiceDef;
+//# sourceMappingURL=remote.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../../src/tools/remote.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAkB,MAAM,aAAa,CAAC;AAE5E,OAAO,KAAK,EAAa,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAc7D,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,aAAa,CAAC,EAAE,CACd,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACnE,QAAQ,EAAE,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,EAChC,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,UAAU,CAsCZ"}

package/dist/tools/schema.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+/** Keys of a Zod object schema's shape — `[]` for a non-object or absent schema. */
+export declare function objectShapeKeys(schema?: z.ZodType): string[];
+/**
+ * Merge an endpoint's `params` and `input` schemas into the single schema a
+ * tool advertises.
+ *
+ * - Both object → one merged `z.object`. A key declared in both is a contract
+ *   bug and throws.
+ * - A non-object `input` (a union, a discriminated union, a refined / piped
+ *   schema) is kept intact and intersected with `params` when present — the
+ *   transport SDK converts it natively (a discriminated union becomes a clean
+ *   `oneOf`).
+ *
+ * The merged schema is exactly the two source schemas side by side: nothing is
+ * coerced, flattened or transformed, so the schema a tool advertises is the
+ * schema its arguments are validated against (`executeToolMethod` parses each
+ * source schema over its own slice of the args).
+ */
+export declare function mergeSchemas(paramsSchema?: z.ZodType<unknown>, inputSchema?: z.ZodType<unknown>): z.ZodType;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/tools/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,GAAG,MAAM,EAAE,CAE5D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAC1B,YAAY,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EACjC,WAAW,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAC/B,CAAC,CAAC,OAAO,CA2BX"}

package/dist/tools/view-file.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Native MCP `view_file` tool — materialises a media URL/path into MCP content
+ * blocks so the model can SEE images and HEAR audio.
+ *
+ * Native (not contract-based): contract tools return JSON text via
+ * `formatMcpResult`; this returns multimodal content (`image` / `audio` blocks).
+ *
+ * `resolveMedia` is the extractable core — when other tools need inline media
+ * it becomes the shared resolver.
+ *
+ * Inputs are model-controlled, so this tool is guarded: URLs that resolve to a
+ * private/internal address are refused (SSRF), local file access is opt-in and
+ * sandboxed to a `baseDir`, and downloads are capped before they reach memory.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** An MCP content block — text / image / audio (video cannot be inlined). */
+export type McpMediaContent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    data: string;
+    mimeType: string;
+} | {
+    type: 'audio';
+    data: string;
+    mimeType: string;
+};
+export interface ViewFileOptions {
+    /**
+     * Directory that local file paths must resolve within. Omitted → local file
+     * access is disabled and only `http(s)` URLs are accepted.
+     */
+    baseDir?: string;
+    /**
+     * Allow fetching URLs that resolve to private / loopback / link-local
+     * addresses. Default `false` — the SSRF guard. Enable only in a trusted
+     * network where the model is allowed to reach internal hosts.
+     */
+    allowPrivateHosts?: boolean;
+}
+/**
+ * Resolve a single media path/URL into MCP content. The extractable core —
+ * reusable wherever inline media is needed.
+ *
+ *  - `image/*` / `audio/*` → an inline base64 block — the model sees / hears it;
+ *  - `video/*` → a text link (MCP has no video block);
+ *  - anything else, or too large → a text link.
+ */
+export declare function resolveMedia(pathOrUrl: string, options?: ViewFileOptions): Promise<McpMediaContent[]>;
+/**
+ * Register the native MCP `view_file` tool on a server. Pass to
+ * `createMcpHandler` via `nativeTools`. `options` controls the security
+ * boundary — see `ViewFileOptions`.
+ */
+export declare function mountViewFile(server: McpServer, options?: ViewFileOptions): void;
+//# sourceMappingURL=view-file.d.ts.map

package/dist/tools/view-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-file.d.ts","sourceRoot":"","sources":["../../src/tools/view-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAsBzE,6EAA6E;AAC7E,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AA6HD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,eAAe,EAAE,CAAC,CA+B5B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,IAAI,CA4BpF"}

package/dist/tools.d.ts

@@ -0,0 +1,12 @@
+export { type AgentContext, type AgentMountConfig, mountAgent } from './tools/agent';
+export { withJsonCoercion } from './tools/coerce';
+export type { ToolCallHooks, ToolLifecycle, ToolResult } from './tools/execute';
+export { flattenDiscriminatedUnion } from './tools/flatten';
+export { buildToolManifest, type ToolManifestEntry } from './tools/manifest';
+export { buildMcpServer, type IncompatibleSchemaPolicy, type McpMountConfig, type McpServerBuildConfig, mountMcp, validateMcpSchemas, } from './tools/mcp';
+export { createMcpHandler, type McpHandlerConfig } from './tools/mcp-handler';
+export { createStdioMcpServer, type StdioMcpServerConfig } from './tools/mcp-stdio';
+export { collectTools, type MountableTool, type ToolExtend } from './tools/mount';
+export { type ImplementRemoteOptions, implementRemote } from './tools/remote';
+export { type McpMediaContent, mountViewFile, resolveMedia } from './tools/view-file';
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,EACL,cAAc,EACd,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,QAAQ,EACR,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,KAAK,sBAAsB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EAAE,KAAK,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}