stitchkit 0.0.1 → 0.1.0

package/dist/tools/mcp.d.ts

@@ -0,0 +1,42 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServiceDef } from '../server/types';
+import type { ToolCallHooks } from './execute';
+import { type ToolExtend } from './mount';
+export interface McpMountConfig {
+    context?: Record<string, unknown>;
+    hooks?: ToolCallHooks;
+    extend?: ToolExtend;
+}
+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 lifecycle hooks — `afterToolCall` fires for every result
+     *  (success and error), so the consuming app can log MCP tool outcomes. */
+    hooks?: ToolCallHooks;
+    /** 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;
+}
+/**
+ * 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;AAIpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAmD,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AA0B3F,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,wBAAgB,QAAQ,CACtB,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,cAAmB,GAC1B,IAAI,CA0DN;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;kFAC8E;IAC9E,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC;IAC1C;wDACoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAClC,MAAM,EAAE,oBAAoB,CAAC,KAAK,CAAC,EACnC,IAAI,EAAE,KAAK,GACV,SAAS,CAWX"}

package/dist/tools/mount.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 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.ZodObject<z.ZodRawShape>;
+    /** Whether `ToolExtend` applies to this method. */
+    shouldExtend: 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, extend: ToolExtend | undefined): 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 lifecycle hooks. */
+    hooks?: ToolCallHooks;
+}
+/**
+ * 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.
+ */
+export declare function formatToolError(result: Extract<ToolResult, {
+    ok: false;
+}>): 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;AAC7D,OAAO,EAAqB,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAInF;;;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,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACnC,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,UAAU,GAAG,SAAS,GAC7B,aAAa,EAAE,CAejB;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,iCAAiC;IACjC,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;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,CAkBhF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,GACzC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKzB"}

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,4 @@
+import { z } from 'zod';
+export declare function withJsonCoercion(schema: z.ZodObject<z.ZodRawShape>): z.ZodObject<z.ZodRawShape>;
+export declare function mergeSchemas(paramsSchema?: z.ZodType<unknown>, inputSchema?: z.ZodType<unknown>): z.ZodObject<z.ZodRawShape>;
+//# 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;AAyBxB,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GACjC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CA4B5B;AA0DD,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,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAsB5B"}

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,8 @@
+export { type AgentContext, type AgentMountConfig, mountAgent } from './tools/agent';
+export { buildMcpServer, type McpMountConfig, type McpServerBuildConfig, mountMcp, } from './tools/mcp';
+export { createMcpHandler, type McpHandlerConfig } from './tools/mcp-handler';
+export { createStdioMcpServer, type StdioMcpServerConfig } from './tools/mcp-stdio';
+export 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,EACL,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,QAAQ,GACT,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,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,KAAK,sBAAsB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EAAE,KAAK,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}