@toolgrain/mcp 0.0.0-stage → 0.1.0-rc.0

package/dist/tools/registry.js

@@ -0,0 +1,31 @@
+import * as core from "zod/v4/core";
+import { isRegisteredTool, } from "./definition.js";
+import { ToolInputError, UnknownToolError } from "./errors.js";
+export function createRegistry(tools) {
+    const entries = new Map(Object.entries(tools).map(([name, definition]) => {
+        if (!isRegisteredTool(definition))
+            throw new TypeError(`Tool ${JSON.stringify(name)} must be created with tool()`);
+        return [name, Object.freeze({ ...definition })];
+    }));
+    return {
+        list() {
+            return Array.from(entries, ([name, definition]) => {
+                const { execute: _execute, ...metadata } = definition;
+                return { name, ...metadata };
+            });
+        },
+        async execute(name, input, ctx) {
+            const definition = entries.get(name);
+            if (!definition)
+                throw new UnknownToolError(name);
+            const parsed = await core.safeParseAsync(definition.input, input);
+            if (!parsed.success)
+                throw new ToolInputError(name, parsed.error);
+            // A request cancelled during validation never starts its handler.
+            ctx.signal.throwIfAborted();
+            // Parsing with this definition's schema establishes its handler input type.
+            return definition.execute(parsed.data, ctx);
+        },
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AAEpC,OAAO,EACL,gBAAgB,GAGjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAe/D,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,MAAM,OAAO,GAAG,IAAI,GAAG,CACrB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,EAAE;QAC/C,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC;YAC/B,MAAM,IAAI,SAAS,CACjB,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,8BAA8B,CAC3D,CAAC;QACJ,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,UAAU,EAAE,CAAC,CAAU,CAAC;IAC3D,CAAC,CAAC,CACH,CAAC;IAEF,OAAO;QACL,IAAI;YACF,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,EAAE;gBAChD,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,GAAG,UAAU,CAAC;gBACtD,OAAO,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC/B,CAAC,CAAC,CAAC;QACL,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG;YAC5B,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,CAAC,UAAU;gBAAE,MAAM,IAAI,gBAAgB,CAAC,IAAI,CAAC,CAAC;YAClD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAClE,IAAI,CAAC,MAAM,CAAC,OAAO;gBAAE,MAAM,IAAI,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YAClE,kEAAkE;YAClE,GAAG,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;YAC5B,4EAA4E;YAC5E,OAAO,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,IAAa,EAAE,GAAG,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/results.d.ts

@@ -0,0 +1,14 @@
+import type { ContentBlock, MetaObject } from "@toolgrain/protocol";
+import * as core from "zod/v4/core";
+/** Validated output shared by both protocol adapters. */
+export interface ToolExecutionResult {
+    content: ContentBlock[];
+    structuredContent?: unknown;
+    isError?: boolean;
+    _meta?: MetaObject;
+}
+export declare function toolResult(value: unknown): ToolExecutionResult;
+/** Validate supplied structured data, including data in explicit error results. */
+export declare function resolveToolResult(name: string, value: unknown, output?: core.$ZodType): Promise<ToolExecutionResult>;
+export declare function toolError(message: string): ToolExecutionResult;
+//# sourceMappingURL=results.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../src/tools/results.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AAKpC,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAK9D;AAsCD,mFAAmF;AACnF,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,IAAI,CAAC,QAAQ,GACrB,OAAO,CAAC,mBAAmB,CAAC,CA8B9B;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAK9D"}

package/dist/tools/results.js

@@ -0,0 +1,71 @@
+import * as core from "zod/v4/core";
+import { explicitResult } from "./content.js";
+import { assertJSON } from "./json-value.js";
+import { isMcpResult } from "./rich-result.js";
+export function toolResult(value) {
+    if (isMcpResult(value))
+        return withStructuredText(readExplicit(value));
+    if (typeof value === "string")
+        return { content: [{ type: "text", text: value }] };
+    return structuredResult(value);
+}
+function structuredResult(value, options) {
+    assertJSON(value, options);
+    const text = JSON.stringify(value);
+    return {
+        content: [{ type: "text", text }],
+        structuredContent: JSON.parse(text),
+    };
+}
+function readExplicit(value) {
+    // Structured content is application data, so undefined values inside it fail.
+    const { structuredContent } = value.value;
+    if (structuredContent !== undefined)
+        assertJSON(structuredContent);
+    // Undefined optional envelope fields, such as `isError: undefined`, are absent.
+    assertJSON(value.value, { omitUndefined: true });
+    return explicitResult.parse(JSON.parse(JSON.stringify(value.value)));
+}
+function withStructuredText(result) {
+    if (Object.hasOwn(result, "structuredContent")) {
+        const text = JSON.stringify(result.structuredContent);
+        if (!result.content.some((block) => block.type === "text" && block.text === text))
+            result.content.push({ type: "text", text });
+    }
+    return result;
+}
+/** Validate supplied structured data, including data in explicit error results. */
+export async function resolveToolResult(name, value, output) {
+    if (!output)
+        return toolResult(value);
+    const explicit = isMcpResult(value) ? readExplicit(value) : undefined;
+    if (explicit && !Object.hasOwn(explicit, "structuredContent")) {
+        if (explicit.isError)
+            return explicit;
+        throw new Error(`Output schema requires structuredContent for tool: ${name}`);
+    }
+    const parsed = await core.safeParseAsync(output, explicit ? explicit.structuredContent : value);
+    if (!parsed.success)
+        throw new Error(`Invalid output for tool: ${name}`, {
+            cause: parsed.error,
+        });
+    // The schema accepted these values; undefined optional properties are absent.
+    const result = structuredResult(parsed.data, { omitUndefined: true });
+    if (!explicit)
+        return result;
+    // Text serializing the raw data describes the parsed data after output parsing.
+    const raw = JSON.stringify(explicit.structuredContent);
+    const text = JSON.stringify(result.structuredContent);
+    return withStructuredText({
+        ...explicit,
+        content: explicit.content.map((block) => block.type === "text" && block.text === raw ? { ...block, text } : block),
+        structuredContent: result.structuredContent,
+    });
+}
+export function toolError(message) {
+    return {
+        isError: true,
+        content: [{ type: "text", text: message }],
+    };
+}
+//# sourceMappingURL=results.js.map

package/dist/tools/results.js.map

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

package/dist/tools/rich-result.d.ts

@@ -0,0 +1,44 @@
+import type { ContentBlock, MetaObject } from "@toolgrain/protocol";
+import type { DeepReadonly, JsonCompatible } from "./json-value.js";
+export interface McpResultOptions<Structured = unknown> {
+    content: readonly DeepReadonly<ContentBlock>[];
+    structuredContent?: Structured & JsonCompatible<NoInfer<Structured>>;
+    isError?: boolean;
+    _meta?: MetaObject;
+}
+export declare class McpResult<Structured> {
+    readonly value: McpResultOptions<Structured>;
+    constructor(value: McpResultOptions<Structured>);
+    /** Structural brand shared by package copies; object spreads do not keep it. */
+    "~toolgrain"(): "result@1";
+}
+/** Recognize results created by any compatible copy of this package. */
+export declare function isMcpResult(value: unknown): value is McpResult<unknown>;
+export type McpErrorResult<Structured = never> = McpResult<Structured> & {
+    readonly value: McpResultOptions<Structured> & {
+        isError: true;
+    };
+};
+/** A result whose structured data is present, as required by an output schema. */
+export type McpStructuredResult<Structured> = McpResult<Structured> & {
+    readonly value: McpResultOptions<Structured> & {
+        structuredContent: Structured;
+    };
+};
+/** Explicitly return MCP content. Ordinary objects always remain application data. */
+export declare function mcpResult<Structured = never>(value: McpResultOptions<Structured> & {
+    isError: true;
+    structuredContent: Structured;
+}): McpErrorResult<Structured> & McpStructuredResult<Structured>;
+export declare function mcpResult(value: McpResultOptions<never> & {
+    isError: true;
+}): McpErrorResult<never>;
+export declare function mcpResult<Structured>(value: McpResultOptions<Structured> & {
+    isError: true;
+}): McpErrorResult<Structured>;
+export declare function mcpResult<Structured>(value: McpResultOptions<Structured> & {
+    structuredContent: Structured;
+}): McpStructuredResult<Structured>;
+export declare function mcpResult(value: McpResultOptions<never>): McpResult<never>;
+export declare function mcpResult<Structured = never>(value: McpResultOptions<Structured>): McpResult<Structured>;
+//# sourceMappingURL=rich-result.d.ts.map

package/dist/tools/rich-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rich-result.d.ts","sourceRoot":"","sources":["../../src/tools/rich-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEpE,MAAM,WAAW,gBAAgB,CAAC,UAAU,GAAG,OAAO;IACpD,OAAO,EAAE,SAAS,YAAY,CAAC,YAAY,CAAC,EAAE,CAAC;IAC/C,iBAAiB,CAAC,EAAE,UAAU,GAAG,cAAc,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IACrE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAKD,qBAAa,SAAS,CAAC,UAAU;IACnB,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC;IAAxD,YAAqB,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,EAEvD;IAED,gFAAgF;IAChF,YAAY,IAAI,UAAU,CAEzB;CACF;AAGD,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAAC,OAAO,CAAC,CAMvE;AAED,MAAM,MAAM,cAAc,CAAC,UAAU,GAAG,KAAK,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG;IACvE,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG;QAAE,OAAO,EAAE,IAAI,CAAA;KAAE,CAAC;CAClE,CAAC;AAEF,kFAAkF;AAClF,MAAM,MAAM,mBAAmB,CAAC,UAAU,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG;IACpE,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG;QAC7C,iBAAiB,EAAE,UAAU,CAAC;KAC/B,CAAC;CACH,CAAC;AAEF,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,UAAU,GAAG,KAAK,EAC1C,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG;IACpC,OAAO,EAAE,IAAI,CAAC;IACd,iBAAiB,EAAE,UAAU,CAAC;CAC/B,GACA,cAAc,CAAC,UAAU,CAAC,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC;AAChE,wBAAgB,SAAS,CACvB,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GACjD,cAAc,CAAC,KAAK,CAAC,CAAC;AACzB,wBAAgB,SAAS,CAAC,UAAU,EAClC,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GACtD,cAAc,CAAC,UAAU,CAAC,CAAC;AAC9B,wBAAgB,SAAS,CAAC,UAAU,EAClC,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG;IAAE,iBAAiB,EAAE,UAAU,CAAA;CAAE,GACtE,mBAAmB,CAAC,UAAU,CAAC,CAAC;AACnC,wBAAgB,SAAS,CAAC,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;AAC5E,wBAAgB,SAAS,CAAC,UAAU,GAAG,KAAK,EAC1C,KAAK,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAClC,SAAS,CAAC,UAAU,CAAC,CAAC"}

package/dist/tools/rich-result.js

@@ -0,0 +1,24 @@
+// Registered symbols let duplicate package copies recognize each other's results.
+const RESULT_BRAND = Symbol.for("@toolgrain/mcp/result@1");
+export class McpResult {
+    value;
+    constructor(value) {
+        this.value = value;
+        Object.freeze(this);
+    }
+    /** Structural brand shared by package copies; object spreads do not keep it. */
+    "~toolgrain"() {
+        return "result@1";
+    }
+}
+Object.defineProperty(McpResult.prototype, RESULT_BRAND, { value: true });
+/** Recognize results created by any compatible copy of this package. */
+export function isMcpResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[RESULT_BRAND] === true);
+}
+export function mcpResult(value) {
+    return new McpResult(value);
+}
+//# sourceMappingURL=rich-result.js.map

package/dist/tools/rich-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rich-result.js","sourceRoot":"","sources":["../../src/tools/rich-result.ts"],"names":[],"mappings":"AAUA,kFAAkF;AAClF,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAE3D,MAAM,OAAO,SAAS;IACC,KAAK;IAA1B,YAAqB,KAAmC;qBAAnC,KAAK;QACxB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAED,gFAAgF;IAChF,YAAY;QACV,OAAO,UAAU,CAAC;IACpB,CAAC;CACF;AACD,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAE1E,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAsC,CAAC,YAAY,CAAC,KAAK,IAAI,CAC/D,CAAC;AACJ,CAAC;AAiCD,MAAM,UAAU,SAAS,CACvB,KAAmC;IAEnC,OAAO,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC"}

package/dist/tools/schema.d.ts

@@ -0,0 +1,18 @@
+import type { Tool as ProtocolTool } from "@toolgrain/protocol";
+import { z } from "zod";
+import * as core from "zod/v4/core";
+import type { ToolMap } from "./registry.js";
+export declare const toolAnnotations: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+    destructiveHint: z.ZodOptional<z.ZodBoolean>;
+    idempotentHint: z.ZodOptional<z.ZodBoolean>;
+    openWorldHint: z.ZodOptional<z.ZodBoolean>;
+}, core.$loose>;
+export declare class ToolSchemaError extends Error {
+    readonly toolName: string;
+    readonly schemaKind: "input" | "output" | "metadata";
+    constructor(toolName: string, cause: unknown, schemaKind?: "input" | "output" | "metadata");
+}
+export declare function describeTool(name: string, definition: Pick<ToolMap[string], "input" | "output" | "title" | "description" | "icons" | "annotations" | "_meta">): ProtocolTool;
+//# 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,KAAK,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,IAAI,MAAM,aAAa,CAAC;AAMpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,eAAO,MAAM,eAAe;;;;;;eAM1B,CAAC;AAUH,qBAAa,eAAgB,SAAQ,KAAK;aAEtB,QAAQ,EAAE,MAAM;aAEhB,UAAU,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU;IAH7D,YACkB,QAAQ,EAAE,MAAM,EAChC,KAAK,EAAE,OAAO,EACE,UAAU,GAAE,OAAO,GAAG,QAAQ,GAAG,UAAoB,EAMtE;CACF;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,IAAI,CACd,OAAO,CAAC,MAAM,CAAC,EACb,OAAO,GACP,QAAQ,GACR,OAAO,GACP,aAAa,GACb,OAAO,GACP,aAAa,GACb,OAAO,CACV,GACA,YAAY,CAkCd"}

package/dist/tools/schema.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import * as core from "zod/v4/core";
+import { icon } from "../protocol/icon.js";
+import { object } from "../protocol/messages.js";
+import { TOOL_METADATA_KEYS } from "./definition.js";
+import { assertJSON } from "./json-value.js";
+import { validateToolName } from "./name.js";
+export const toolAnnotations = z.looseObject({
+    title: z.string().optional(),
+    readOnlyHint: z.boolean().optional(),
+    destructiveHint: z.boolean().optional(),
+    idempotentHint: z.boolean().optional(),
+    openWorldHint: z.boolean().optional(),
+});
+const metadata = z.strictObject({
+    title: z.string().optional(),
+    description: z.string().optional(),
+    icons: z.array(icon).optional(),
+    annotations: toolAnnotations.optional(),
+    _meta: object.optional(),
+});
+export class ToolSchemaError extends Error {
+    toolName;
+    schemaKind;
+    constructor(toolName, cause, schemaKind = "input") {
+        super(`Cannot expose ${schemaKind} schema for tool: ${toolName}`, {
+            cause,
+        });
+        this.toolName = toolName;
+        this.schemaKind = schemaKind;
+        this.name = "ToolSchemaError";
+    }
+}
+export function describeTool(name, definition) {
+    validateToolName(name);
+    let schemaKind = "input";
+    try {
+        const inputSchema = core.toJSONSchema(definition.input, {
+            io: "input",
+            target: "draft-2020-12",
+        });
+        if (inputSchema.type !== "object")
+            throw new Error("Tool input schema must have an object root");
+        schemaKind = "output";
+        const outputSchema = definition.output === undefined
+            ? undefined
+            : core.toJSONSchema(definition.output, {
+                io: "output",
+                target: "draft-2020-12",
+            });
+        schemaKind = "metadata";
+        const fields = {};
+        for (const key of TOOL_METADATA_KEYS)
+            if (definition[key] !== undefined)
+                fields[key] = definition[key];
+        assertJSON(fields);
+        metadata.parse(fields);
+        const result = {
+            name,
+            inputSchema: { ...inputSchema, type: "object" },
+            ...(outputSchema === undefined ? {} : { outputSchema }),
+            ...fields,
+        };
+        return structuredClone(result);
+    }
+    catch (cause) {
+        throw new ToolSchemaError(name, cause, schemaKind);
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/tools/schema.js.map

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

package/dist/transport-ownership.d.ts

@@ -0,0 +1,4 @@
+import type { RequestTransport, Transport } from "./transport.js";
+/** Claim once before startup. Share weak ownership across compatible package copies. */
+export declare function claimTransport(transport: Transport | RequestTransport): void;
+//# sourceMappingURL=transport-ownership.d.ts.map

package/dist/transport-ownership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-ownership.d.ts","sourceRoot":"","sources":["../src/transport-ownership.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAIlE,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,gBAAgB,GAAG,IAAI,CAW5E"}

package/dist/transport-ownership.js

@@ -0,0 +1,13 @@
+const key = Symbol.for("@toolgrain/mcp/claimed-transports/v1");
+/** Claim once before startup. Share weak ownership across compatible package copies. */
+export function claimTransport(transport) {
+    let claimed = Object.getOwnPropertyDescriptor(globalThis, key)?.value;
+    if (!claimed) {
+        claimed = new WeakSet();
+        Object.defineProperty(globalThis, key, { value: claimed });
+    }
+    if (claimed.has(transport))
+        throw new Error("Transport is already attached to a server");
+    claimed.add(transport);
+}
+//# sourceMappingURL=transport-ownership.js.map

package/dist/transport-ownership.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-ownership.js","sourceRoot":"","sources":["../src/transport-ownership.ts"],"names":[],"mappings":"AAEA,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAC;AAE/D,wFAAwF;AACxF,MAAM,UAAU,cAAc,CAAC,SAAuC;IACpE,IAAI,OAAO,GAAG,MAAM,CAAC,wBAAwB,CAAC,UAAU,EAAE,GAAG,CAAC,EAAE,KAEnD,CAAC;IACd,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,GAAG,IAAI,OAAO,EAAU,CAAC;QAChC,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AACzB,CAAC"}

package/dist/transport.d.ts

@@ -0,0 +1,24 @@
+import type { ProtocolResponse } from "@toolgrain/protocol";
+import type { Server } from "./server.js";
+/** Callbacks are synchronous; message processing runs independently. */
+export interface TransportCallbacks {
+    onMessage(message: unknown): void;
+    onParseError(error: unknown): void;
+    onError(error: unknown): void;
+    onClose(): void;
+}
+/** Single-use adapters own UTF-8 framing, JSON decoding, and stream cleanup. */
+export interface Transport {
+    readonly mode?: "message";
+    start(callbacks: TransportCallbacks): Promise<void>;
+    send(message: ProtocolResponse): Promise<void>;
+    close(): Promise<void>;
+}
+/** Single-use request transports own listeners and use per-request authorization. */
+export interface RequestTransport {
+    readonly mode: "request";
+    start(server: Server, callbacks: Pick<TransportCallbacks, "onError" | "onClose">): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function isRequestTransport(transport: Transport | RequestTransport): transport is RequestTransport;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,wEAAwE;AACxE,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,KAAK,CAAC,SAAS,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,KAAK,CACH,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,SAAS,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,GAAG,gBAAgB,GACtC,SAAS,IAAI,gBAAgB,CAE/B"}

package/dist/transport.js

@@ -0,0 +1,4 @@
+export function isRequestTransport(transport) {
+    return "mode" in transport && transport.mode === "request";
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AA6BA,MAAM,UAAU,kBAAkB,CAChC,SAAuC;IAEvC,OAAO,MAAM,IAAI,SAAS,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC;AAC7D,CAAC"}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@toolgrain/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-rc.0",
+  "description": "Define reusable, typed MCP tools and servers with Zod validation.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keshavkatwe/toolgrain.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/keshavkatwe/toolgrain/tree/main/packages/mcp#readme",
+  "bugs": {
+    "url": "https://github.com/keshavkatwe/toolgrain/issues"
+  },
+  "keywords": [
+    "toolgrain",
+    "mcp",
+    "model-context-protocol",
+    "typescript",
+    "zod",
+    "tools"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "next"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.ts"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:package": "toolgrain-repo mcp-compat && toolgrain-repo exports",
+    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "test:coverage": "vitest run --coverage",
+    "test:size": "toolgrain-repo size"
+  },
+  "peerDependencies": {
+    "zod": "^4.6.6"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.0",
+    "ajv": "8.20.0",
+    "fast-check": "4.10.2",
+    "typescript": "7.0.2",
+    "vitest": "5.0.4",
+    "zod": "4.6.7",
+    "@toolgrain/repo-tools": "0.0.0"
+  },
+  "dependencies": {
+    "@toolgrain/protocol": "0.1.0-rc.0"
+  },
+  "engines": {
+    "node": "^24.20.0",
+    "bun": ">=1.4.4 <2"
+  }
+}

package/src/auth/abort.ts

@@ -0,0 +1,14 @@
+/** Stop waiting promptly even when an integration cannot cancel its underlying work. */
+export function abortable<T>(
+  work: Promise<T>,
+  signal: AbortSignal,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    if (signal.aborted) abort();
+    else signal.addEventListener("abort", abort, { once: true });
+    work
+      .then(resolve, reject)
+      .finally(() => signal.removeEventListener("abort", abort));
+  });
+}

package/src/auth/audience.ts

@@ -0,0 +1,22 @@
+import { AuthError } from "./errors.js";
+
+/** Validate the audience of an already verified token without disclosing its claims. */
+export function validateTokenAudience(
+  audience: unknown,
+  resource: string,
+): void {
+  if (audience === undefined)
+    throw new AuthError("invalid_token", {
+      description: `Access token is missing the aud claim. Configure the authorization server to include an audience and request a new token with resource=${resource}.`,
+    });
+  const audiences = typeof audience === "string" ? [audience] : audience;
+  if (
+    !Array.isArray(audiences) ||
+    audiences.some((value) => typeof value !== "string")
+  )
+    throw new AuthError("invalid_token");
+  if (!audiences.includes(resource))
+    throw new AuthError("invalid_token", {
+      description: `Access token aud claim does not match the expected resource ${resource}. Request a new token with this resource.`,
+    });
+}

package/src/auth/authorization.ts

@@ -0,0 +1,81 @@
+import { abortable } from "./abort.js";
+import { identitySnapshot } from "./context.js";
+import { AuthError } from "./errors.js";
+import type {
+  AuthIdentity,
+  AuthMetadata,
+  AuthProvider,
+  AuthScope,
+} from "./types.js";
+import { authUrl } from "./url.js";
+
+interface Entry {
+  identity: AuthIdentity;
+  consumed: boolean;
+  disposed: boolean;
+}
+
+export function createAuthorization(provider?: AuthProvider) {
+  const scopes = new WeakMap<AuthScope, Entry>();
+  const metadata: AuthMetadata | undefined = provider && {
+    ...(provider.resource === undefined
+      ? {}
+      : { resource: authUrl(provider.resource) }),
+    authorizationServers: provider.authorizationServers.map((issuer) => {
+      authUrl(issuer);
+      return issuer;
+    }),
+  };
+  if (
+    provider &&
+    (typeof provider.type !== "symbol" ||
+      !metadata?.authorizationServers.length)
+  )
+    throw new TypeError(
+      "Auth providers require a type symbol and at least one authorization server",
+    );
+  const verify = provider?.verify.bind(provider);
+  const type = provider?.type;
+  return {
+    metadata: () => metadata && structuredClone(metadata),
+    async authorize(
+      token: string,
+      resource: string,
+      signal: AbortSignal,
+      finish: () => void,
+    ): Promise<AuthScope> {
+      if (!verify || !type) throw new Error("Server has no auth provider");
+      signal.throwIfAborted();
+      const resolved = metadata?.resource ?? authUrl(resource);
+      const identity = {
+        type,
+        value: identitySnapshot(
+          await abortable(
+            verify(token, { resource: resolved, signal }),
+            signal,
+          ),
+        ),
+      };
+      signal.throwIfAborted();
+      const entry: Entry = { identity, consumed: false, disposed: false };
+      const scope = Object.freeze({
+        signal,
+        dispose() {
+          if (entry.disposed) return;
+          entry.disposed = true;
+          finish();
+        },
+      });
+      scopes.set(scope, entry);
+      return scope;
+    },
+    consume(scope?: AuthScope): AuthIdentity | undefined {
+      if (!metadata && !scope) return;
+      const entry = scope && scopes.get(scope);
+      if (!entry || entry.consumed || entry.disposed)
+        throw new AuthError("invalid_token");
+      entry.consumed = true;
+      return entry.identity;
+    },
+  };
+}

package/src/auth/context.ts

@@ -0,0 +1,43 @@
+import type { ToolContext } from "../tools/context.js";
+import type { AuthIdentity, AuthReadonly } from "./types.js";
+
+const key = Symbol.for("@toolgrain/mcp/auth-context/v1");
+
+/** Typed integrations bind their accessor to a stable, registered provider symbol. */
+export function createAuthAccessor<Identity extends object>(type: symbol) {
+  return (ctx: ToolContext): AuthReadonly<Identity> => {
+    const auth = Object.getOwnPropertyDescriptor(ctx, key)?.value as
+      | AuthIdentity
+      | undefined;
+    if (!auth || auth.type !== type)
+      throw new Error("The context has no identity for this auth provider");
+    return auth.value as AuthReadonly<Identity>;
+  };
+}
+
+export function attachAuth(ctx: ToolContext, auth?: AuthIdentity): ToolContext {
+  if (auth) Object.defineProperty(ctx, key, { value: auth });
+  return Object.freeze(ctx);
+}
+
+/** Auth identities are plain data: copy them before exposing them to handlers. */
+export function identitySnapshot(value: object): object {
+  if (value === null || typeof value !== "object")
+    throw new TypeError("Auth identities must be objects");
+  const copy = structuredClone(value);
+  const freeze = (item: unknown, visited: Set<object>) => {
+    if (typeof item !== "object" || item === null || visited.has(item)) return;
+    const prototype = Object.getPrototypeOf(item);
+    if (
+      prototype !== Object.prototype &&
+      prototype !== Array.prototype &&
+      prototype !== null
+    )
+      throw new TypeError("Auth identities must contain plain data");
+    visited.add(item);
+    for (const child of Object.values(item)) freeze(child, visited);
+    Object.freeze(item);
+  };
+  freeze(copy, new Set());
+  return copy;
+}