@automatey-org/mcp 0.1.1

package/README.md

@@ -0,0 +1,30 @@
+# @automatey-org/mcp
+
+Provider-agnostic [Model Context Protocol](https://modelcontextprotocol.io) helpers for the
+[Vercel AI SDK](https://sdk.vercel.ai).
+
+- **`McpHttpClient`** (aka `NativeMcpHttpClient`) — a lazily-connecting MCP client over
+  Streamable HTTP. Normalizes network failures into friendly "unavailable" errors while
+  re-throwing abort errors so callers can tell cancellation apart from an outage.
+- **`buildMcpToolSet()`** — turns MCP tools into an AI SDK `ToolSet`: each tool's JSON Schema
+  is wrapped with `jsonSchema()`, destructive tools are gated unless `unattended`, results are
+  flattened for the model, and call/result/error callbacks fire around every invocation.
+- **tooling** — `safeToolName`, `compactToolResult`, `isDestructiveToolName`,
+  `destructiveActionPattern` (all overridable via `buildMcpToolSet` options).
+
+```ts
+import { McpHttpClient, buildMcpToolSet } from "@automatey-org/mcp";
+import { streamText } from "ai";
+
+const mcp = new McpHttpClient("http://127.0.0.1:8123/mcp", abortSignal);
+const tools = buildMcpToolSet({
+  tools: await mcp.listTools(),
+  mcp,
+  unattended: false,
+  onToolCall: (name, input) => console.log("call", name, input),
+});
+
+const result = streamText({ model, tools, prompt });
+```
+
+Peer deps: `ai` (>=7 <8), `@modelcontextprotocol/sdk` (>=1.29 <2).

package/dist/client.d.ts

@@ -0,0 +1,48 @@
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { McpCallResult, McpToolInfo } from "./types";
+export interface McpHttpClientOptions {
+    /** Signals the AI SDK abort down into the transport + closes the session. */
+    abortSignal?: AbortSignal;
+    /** Client identity advertised during `initialize`. */
+    clientName?: string;
+    clientVersion?: string;
+    /**
+     * Supply a custom transport instead of the default Streamable HTTP one.
+     * Useful for in-memory testing (e.g. `InMemoryTransport` from the MCP SDK)
+     * or non-HTTP transports. When provided, `endpoint` is ignored.
+     */
+    transportFactory?: () => Transport;
+}
+export interface McpInitializeResult {
+    protocolVersion?: string;
+    capabilities?: unknown;
+    serverInfo?: {
+        name?: string;
+        version?: string;
+    };
+}
+/**
+ * A thin, lazily-connecting MCP client over Streamable HTTP. Network failures
+ * are normalized into friendly "unavailable" errors while abort errors are
+ * re-thrown untouched so the caller can distinguish user cancellation.
+ */
+export declare class McpHttpClient {
+    private readonly endpoint;
+    private client;
+    private transport;
+    private readonly abortSignal?;
+    private readonly clientName;
+    private readonly clientVersion;
+    private readonly transportFactory?;
+    constructor(endpoint: string, optionsOrSignal?: AbortSignal | McpHttpClientOptions);
+    getSessionId(): string | undefined;
+    private unavailableMessage;
+    private ensureConnected;
+    initialize(): Promise<McpInitializeResult>;
+    listTools(): Promise<McpToolInfo[]>;
+    callTool(name: string, args: unknown): Promise<McpCallResult>;
+    close(): Promise<void>;
+}
+/** Back-compat alias for the original MadeHuman UX name. */
+export { McpHttpClient as NativeMcpHttpClient };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE1D,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD;AAyBD;;;;GAIG;AACH,qBAAa,aAAa;IActB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAb3B,OAAO,CAAC,MAAM,CAAqB;IAEnC,OAAO,CAAC,SAAS,CAAwB;IAEzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAc;IAE3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAkB;gBAGjC,QAAQ,EAAE,MAAM,EACjC,eAAe,CAAC,EAAE,WAAW,GAAG,oBAAoB;IAYtD,YAAY,IAAI,MAAM,GAAG,SAAS;IAIlC,OAAO,CAAC,kBAAkB;YAIZ,eAAe;IA+BvB,UAAU,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAkB1C,SAAS,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAcnC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC;IAgB7D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAwB7B;AAED,4DAA4D;AAC5D,OAAO,EAAE,aAAa,IAAI,mBAAmB,EAAE,CAAC"}

package/dist/client.js

@@ -0,0 +1,142 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+function isAbortError(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+function isNetworkError(error) {
+    return (error instanceof TypeError ||
+        (error instanceof Error && /fetch|network|Failed to fetch/i.test(error.message)));
+}
+function normalizeToolInfo(tool) {
+    return {
+        name: tool.name,
+        description: tool.description ?? "",
+        inputSchema: tool.inputSchema,
+    };
+}
+/**
+ * A thin, lazily-connecting MCP client over Streamable HTTP. Network failures
+ * are normalized into friendly "unavailable" errors while abort errors are
+ * re-thrown untouched so the caller can distinguish user cancellation.
+ */
+export class McpHttpClient {
+    endpoint;
+    client;
+    transport;
+    abortSignal;
+    clientName;
+    clientVersion;
+    transportFactory;
+    constructor(endpoint, optionsOrSignal) {
+        this.endpoint = endpoint;
+        const options = optionsOrSignal instanceof AbortSignal
+            ? { abortSignal: optionsOrSignal }
+            : optionsOrSignal ?? {};
+        this.abortSignal = options.abortSignal;
+        this.clientName = options.clientName ?? "automatey-mcp";
+        this.clientVersion = options.clientVersion ?? "0.1.0";
+        this.transportFactory = options.transportFactory;
+    }
+    getSessionId() {
+        return this.transport?.sessionId;
+    }
+    unavailableMessage(target) {
+        return `${target} is unavailable because the MCP server at ${this.endpoint} could not be reached.`;
+    }
+    async ensureConnected() {
+        if (this.client && this.transport) {
+            return this.client;
+        }
+        const transport = this.transportFactory?.() ??
+            new StreamableHTTPClientTransport(new URL(this.endpoint), {
+                requestInit: this.abortSignal ? { signal: this.abortSignal } : undefined,
+            });
+        const client = new Client({ name: this.clientName, version: this.clientVersion }, { capabilities: {} });
+        if (this.abortSignal) {
+            this.abortSignal.addEventListener("abort", () => {
+                void this.close();
+            }, { once: true });
+        }
+        await client.connect(transport);
+        this.transport = transport;
+        this.client = client;
+        return client;
+    }
+    async initialize() {
+        try {
+            const client = await this.ensureConnected();
+            return {
+                protocolVersion: this.transport
+                    ?.protocolVersion,
+                capabilities: client.getServerCapabilities(),
+                serverInfo: client.getServerVersion(),
+            };
+        }
+        catch (error) {
+            if (isAbortError(error))
+                throw error;
+            if (isNetworkError(error)) {
+                throw new Error(this.unavailableMessage("MCP server"));
+            }
+            throw error;
+        }
+    }
+    async listTools() {
+        try {
+            const client = await this.ensureConnected();
+            const result = await client.listTools();
+            return (result.tools ?? []).map(normalizeToolInfo);
+        }
+        catch (error) {
+            if (isAbortError(error))
+                throw error;
+            if (isNetworkError(error)) {
+                throw new Error(this.unavailableMessage("MCP tool catalog"));
+            }
+            throw error;
+        }
+    }
+    async callTool(name, args) {
+        try {
+            const client = await this.ensureConnected();
+            return (await client.callTool({
+                name,
+                arguments: (args ?? {}),
+            }));
+        }
+        catch (error) {
+            if (isAbortError(error))
+                throw error;
+            if (isNetworkError(error)) {
+                throw new Error(this.unavailableMessage(`MCP ${name}`));
+            }
+            throw error;
+        }
+    }
+    async close() {
+        const transport = this.transport;
+        const client = this.client;
+        this.transport = undefined;
+        this.client = undefined;
+        if (!transport || !client) {
+            return;
+        }
+        if ("terminateSession" in transport) {
+            try {
+                await transport.terminateSession();
+            }
+            catch {
+                // Some servers may not support DELETE /mcp; fall through to close.
+            }
+        }
+        try {
+            await client.close();
+        }
+        catch {
+            // best-effort shutdown only
+        }
+    }
+}
+/** Back-compat alias for the original MadeHuman UX name. */
+export { McpHttpClient as NativeMcpHttpClient };
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { McpToolInfo, McpCallResult } from "./types";
+export { McpHttpClient, NativeMcpHttpClient, type McpHttpClientOptions, type McpInitializeResult, } from "./client";
+export { buildMcpToolSet, type BuildMcpToolSetOptions, type McpToolCaller, } from "./toolset";
+export { compactToolResult, isDestructiveToolName, safeToolName, destructiveActionPattern, } from "./tooling";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,GACzB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,aAAa,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,YAAY,EACZ,wBAAwB,GACzB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { McpHttpClient, NativeMcpHttpClient, } from "./client";
+export { buildMcpToolSet, } from "./toolset";
+export { compactToolResult, isDestructiveToolName, safeToolName, destructiveActionPattern, } from "./tooling";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,aAAa,EACb,mBAAmB,GAGpB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,eAAe,GAGhB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,YAAY,EACZ,wBAAwB,GACzB,MAAM,WAAW,CAAC"}

package/dist/tooling.d.ts

@@ -0,0 +1,17 @@
+import type { McpCallResult } from "./types";
+/**
+ * Heuristic pattern for tools whose side effects should require explicit
+ * approval (or unattended mode) before they run. Callers can override the
+ * gate entirely via {@link BuildMcpToolSetOptions.isDestructive}.
+ */
+export declare const destructiveActionPattern: RegExp;
+export declare function isDestructiveToolName(name: string): boolean;
+/** Sanitize an MCP tool name into an identifier the AI SDK / model will accept. */
+export declare function safeToolName(name: string): string;
+/**
+ * Flatten an MCP call result to a string for the model. Concatenates text
+ * parts when present, otherwise pretty-prints the whole result. Truncates to
+ * `maxChars` to keep tool output from blowing up the context window.
+ */
+export declare function compactToolResult(result: McpCallResult, maxChars?: number): string;
+//# sourceMappingURL=tooling.d.ts.map

package/dist/tooling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooling.d.ts","sourceRoot":"","sources":["../src/tooling.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QACiF,CAAC;AAEvH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,SAAO,GAAG,MAAM,CAUhF"}

package/dist/tooling.js

@@ -0,0 +1,30 @@
+/**
+ * Heuristic pattern for tools whose side effects should require explicit
+ * approval (or unattended mode) before they run. Callers can override the
+ * gate entirely via {@link BuildMcpToolSetOptions.isDestructive}.
+ */
+export const destructiveActionPattern = /(delete|remove|save|write|commit|push|spawn|create|import|export|build|run|execute|python|system|manage_pipeline)/i;
+export function isDestructiveToolName(name) {
+    return destructiveActionPattern.test(name);
+}
+/** Sanitize an MCP tool name into an identifier the AI SDK / model will accept. */
+export function safeToolName(name) {
+    return name.replace(/[^A-Za-z0-9_]/g, "_");
+}
+/**
+ * Flatten an MCP call result to a string for the model. Concatenates text
+ * parts when present, otherwise pretty-prints the whole result. Truncates to
+ * `maxChars` to keep tool output from blowing up the context window.
+ */
+export function compactToolResult(result, maxChars = 8000) {
+    if (Array.isArray(result.content)) {
+        const text = result.content
+            .filter((part) => part.type === "text" && typeof part.text === "string")
+            .map((part) => part.text)
+            .join("\n");
+        return text.length > maxChars ? `${text.slice(0, maxChars)}\n…[truncated]` : text;
+    }
+    const text = JSON.stringify(result, null, 2);
+    return text.length > maxChars ? `${text.slice(0, maxChars)}\n…[truncated]` : text;
+}
+//# sourceMappingURL=tooling.js.map

package/dist/tooling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooling.js","sourceRoot":"","sources":["../src/tooling.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GACnC,oHAAoH,CAAC;AAEvH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO,wBAAwB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAqB,EAAE,QAAQ,GAAG,IAAI;IACtE,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO;aACxB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;aACvE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;aACxB,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,OAAO,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC;IACpF,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC7C,OAAO,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC;AACpF,CAAC"}

package/dist/toolset.d.ts

@@ -0,0 +1,29 @@
+import { type ToolSet } from "ai";
+import type { McpCallResult, McpToolInfo } from "./types";
+/** The subset of an MCP client that {@link buildMcpToolSet} needs. */
+export interface McpToolCaller {
+    callTool(name: string, args: unknown): Promise<McpCallResult>;
+}
+export interface BuildMcpToolSetOptions {
+    tools: McpToolInfo[];
+    mcp: McpToolCaller;
+    /** When false, tools flagged destructive are blocked before execution. */
+    unattended: boolean;
+    onToolCall?: (toolName: string, input: unknown) => void;
+    onToolResult?: (toolName: string, output: string) => void;
+    onToolError?: (toolName: string, error: string) => void;
+    /** Override the destructive-tool gate. Defaults to {@link isDestructiveToolName}. */
+    isDestructive?: (toolName: string) => boolean;
+    /** Override how a raw MCP result is flattened to a string. Defaults to {@link compactToolResult}. */
+    formatResult?: (result: McpCallResult) => string;
+    /** Description used when an MCP tool advertises none. */
+    fallbackDescription?: (toolName: string) => string;
+}
+/**
+ * Turn a list of MCP tools into an AI SDK {@link ToolSet}. Each tool's JSON
+ * Schema is wrapped with `jsonSchema()`, destructive tools are gated unless
+ * `unattended`, and results are flattened for the model. Call/result/error
+ * callbacks fire around every invocation.
+ */
+export declare function buildMcpToolSet(options: BuildMcpToolSetOptions): ToolSet;
+//# sourceMappingURL=toolset.d.ts.map

package/dist/toolset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolset.d.ts","sourceRoot":"","sources":["../src/toolset.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,OAAO,EAAE,MAAM,IAAI,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG1D,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,GAAG,EAAE,aAAa,CAAC;IACnB,0EAA0E;IAC1E,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACxD,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1D,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxD,qFAAqF;IACrF,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;IAC9C,qGAAqG;IACrG,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,MAAM,CAAC;IACjD,yDAAyD;IACzD,mBAAmB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CACpD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAgCxE"}

package/dist/toolset.js

@@ -0,0 +1,39 @@
+import { jsonSchema, tool } from "ai";
+import { compactToolResult, isDestructiveToolName, safeToolName } from "./tooling";
+/**
+ * Turn a list of MCP tools into an AI SDK {@link ToolSet}. Each tool's JSON
+ * Schema is wrapped with `jsonSchema()`, destructive tools are gated unless
+ * `unattended`, and results are flattened for the model. Call/result/error
+ * callbacks fire around every invocation.
+ */
+export function buildMcpToolSet(options) {
+    const isDestructive = options.isDestructive ?? isDestructiveToolName;
+    const formatResult = options.formatResult ?? compactToolResult;
+    const fallbackDescription = options.fallbackDescription ?? ((name) => `Call MCP tool ${name}`);
+    const result = {};
+    for (const mcpTool of options.tools) {
+        const exposedName = safeToolName(mcpTool.name);
+        result[exposedName] = tool({
+            description: mcpTool.description || fallbackDescription(mcpTool.name),
+            inputSchema: jsonSchema(mcpTool.inputSchema),
+            execute: async (input) => {
+                options.onToolCall?.(mcpTool.name, input);
+                try {
+                    if (!options.unattended && isDestructive(mcpTool.name)) {
+                        throw new Error(`Tool ${mcpTool.name} requires unattended mode or explicit host approval.`);
+                    }
+                    const output = formatResult(await options.mcp.callTool(mcpTool.name, input));
+                    options.onToolResult?.(mcpTool.name, output);
+                    return output;
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    options.onToolError?.(mcpTool.name, message);
+                    throw error;
+                }
+            },
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=toolset.js.map

package/dist/toolset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolset.js","sourceRoot":"","sources":["../src/toolset.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,IAAI,EAAgB,MAAM,IAAI,CAAC;AAEpD,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAuBnF;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAA+B;IAC7D,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,qBAAqB,CAAC;IACrE,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,iBAAiB,CAAC;IAC/D,MAAM,mBAAmB,GACvB,OAAO,CAAC,mBAAmB,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC;IAE7E,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QACpC,MAAM,WAAW,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/C,MAAM,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;YACzB,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC;YACrE,WAAW,EAAE,UAAU,CAAC,OAAO,CAAC,WAAW,CAAC;YAC5C,OAAO,EAAE,KAAK,EAAE,KAAc,EAAE,EAAE;gBAChC,OAAO,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;gBAC1C,IAAI,CAAC;oBACH,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;wBACvD,MAAM,IAAI,KAAK,CACb,QAAQ,OAAO,CAAC,IAAI,sDAAsD,CAC3E,CAAC;oBACJ,CAAC;oBACD,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;oBAC7E,OAAO,CAAC,YAAY,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;oBAC7C,OAAO,MAAM,CAAC;gBAChB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBACvE,OAAO,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;oBAC7C,MAAM,KAAK,CAAC;gBACd,CAAC;YACH,CAAC;SACF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal shape of an MCP tool as advertised by `tools/list`.
+ * `inputSchema` is a raw JSON Schema object (passed to the AI SDK via `jsonSchema()`).
+ */
+export interface McpToolInfo {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+}
+/**
+ * Result of an MCP `tools/call`. The AI SDK never sees this directly — it is
+ * flattened to a string by {@link compactToolResult} (or a caller-supplied
+ * `formatResult`) before being handed back to the model.
+ */
+export interface McpCallResult {
+    content?: Array<{
+        type?: string;
+        text?: string;
+    }>;
+    isError?: boolean;
+    [key: string]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@automatey-org/mcp",
+  "version": "0.1.1",
+  "description": "Provider-agnostic MCP helpers for the Vercel AI SDK: a Streamable-HTTP MCP client and a buildMcpToolSet() that exposes MCP tools as AI SDK tools with destructive-tool gating and call/result callbacks.",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.29 <2",
+    "ai": ">=7 <8"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ai": "^7.0.11",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.2"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}