@toolgrain/mcp 0.0.0-stage → 0.1.0

package/src/tools/definition.ts

@@ -0,0 +1,144 @@
+import type { Tool as ProtocolTool } from "@toolgrain/protocol";
+import type * as core from "zod/v4/core";
+import type { ToolContext } from "./context.js";
+import type {
+  DeepReadonly,
+  IsJsonCompatible,
+  JsonCompatible,
+} from "./json-value.js";
+import type {
+  McpErrorResult,
+  McpResult,
+  McpStructuredResult,
+} from "./rich-result.js";
+
+export const TOOL_METADATA_KEYS = [
+  "title",
+  "description",
+  "annotations",
+  "icons",
+  "_meta",
+] as const;
+
+export type ToolMetadata = DeepReadonly<
+  Pick<ProtocolTool, (typeof TOOL_METADATA_KEYS)[number]>
+>;
+
+export interface ToolDefinition<
+  Schema extends core.$ZodType,
+  Result,
+  Output extends core.$ZodType = never,
+> extends ToolMetadata {
+  readonly input: Schema;
+  readonly output?: Output;
+  /** Raw handler; server invocation performs validation and result conversion. */
+  readonly execute: (input: core.output<Schema>, ctx: ToolContext) => Result;
+}
+
+// Registered symbols let duplicate package copies recognize each other's tools.
+const TOOL_BRAND = Symbol.for("@toolgrain/mcp/tool@1");
+
+/** Internal erased type for heterogeneous, schema-checked registrations. */
+export abstract class RegisteredTool {
+  abstract readonly input: core.$ZodType;
+  abstract readonly output?: core.$ZodType;
+  abstract readonly execute: (input: never, ctx: ToolContext) => unknown;
+  abstract readonly title?: string;
+  abstract readonly description?: string;
+  abstract readonly annotations?: NonNullable<ToolMetadata["annotations"]>;
+  abstract readonly icons?: NonNullable<ToolMetadata["icons"]>;
+  abstract readonly _meta?: NonNullable<ToolMetadata["_meta"]>;
+
+  /**
+   * Structural brand shared by package copies. Object spreads drop prototype
+   * methods, so modified spreads must pass through tool() again.
+   */
+  "~toolgrain"(): "tool@1" {
+    return "tool@1";
+  }
+}
+Object.defineProperty(RegisteredTool.prototype, TOOL_BRAND, { value: true });
+
+/** Recognize definitions created by any compatible copy of this package. */
+export function isRegisteredTool(value: unknown): value is RegisteredTool {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { [TOOL_BRAND]?: unknown })[TOOL_BRAND] === true
+  );
+}
+
+export class Tool<
+  Schema extends core.$ZodType,
+  Result,
+  Output extends core.$ZodType = core.$ZodType,
+> extends RegisteredTool {
+  declare readonly input: Schema;
+  declare readonly output?: Output;
+  declare readonly execute: (
+    input: core.output<Schema>,
+    ctx: ToolContext,
+  ) => Result;
+  declare readonly title?: string;
+  declare readonly description?: string;
+  declare readonly annotations?: NonNullable<ToolMetadata["annotations"]>;
+  declare readonly icons?: NonNullable<ToolMetadata["icons"]>;
+  declare readonly _meta?: NonNullable<ToolMetadata["_meta"]>;
+
+  constructor(definition: ToolDefinition<Schema, Result, core.$ZodType>) {
+    super();
+    this.input = definition.input;
+    this.execute = definition.execute;
+    for (const key of ["output", ...TOOL_METADATA_KEYS] as const) {
+      const value = definition[key];
+      if (value !== undefined)
+        Object.defineProperty(this, key, { value, enumerable: true });
+    }
+    Object.freeze(this);
+  }
+}
+
+type OutputResult<Output extends core.$ZodType> =
+  | core.input<Output>
+  | McpStructuredResult<core.input<Output>>
+  | McpErrorResult<core.input<Output>>;
+
+type JsonSafeOutput<Result> =
+  Result extends PromiseLike<infer Resolved>
+    ? PromiseLike<JsonSafeOutput<Resolved>>
+    : Result extends McpResult<infer Structured>
+      ? IsJsonCompatible<Structured> extends true
+        ? Result
+        : never
+      : JsonCompatible<Result>;
+
+type ToolDefinitionWithoutOutput<Schema extends core.$ZodType, Result> = Omit<
+  ToolDefinition<Schema, Result>,
+  "execute"
+> & {
+  readonly execute: (
+    input: core.output<Schema>,
+    ctx: ToolContext,
+  ) => Result & JsonSafeOutput<Result>;
+};
+
+export function tool<
+  Schema extends core.$ZodType,
+  Output extends core.$ZodType,
+  Result extends
+    | OutputResult<NoInfer<Output>>
+    | PromiseLike<OutputResult<NoInfer<Output>>>,
+>(
+  definition: ToolDefinition<Schema, Result, Output> & {
+    readonly output: Output;
+  },
+): Tool<Schema, Result, Output> & { readonly output: Output };
+export function tool<Schema extends core.$ZodType, Result>(
+  definition: ToolDefinitionWithoutOutput<Schema, Result>,
+): Tool<Schema, Result, never>;
+/** Define a reusable MCP tool. Its execute property remains the raw handler. */
+export function tool<Schema extends core.$ZodType, Result>(
+  definition: ToolDefinition<Schema, Result, core.$ZodType>,
+): Tool<Schema, Result> {
+  return new Tool(definition);
+}

package/src/tools/errors.ts

@@ -0,0 +1,21 @@
+import type * as core from "zod/v4/core";
+
+export class UnknownToolError extends Error {
+  constructor(public readonly toolName: string) {
+    super(`Unknown tool: ${toolName}`);
+    this.name = "UnknownToolError";
+  }
+}
+
+export class ToolInputError extends Error {
+  readonly issues: core.$ZodError["issues"];
+
+  constructor(
+    public readonly toolName: string,
+    cause: core.$ZodError,
+  ) {
+    super(`Invalid input for tool: ${toolName}`, { cause });
+    this.name = "ToolInputError";
+    this.issues = cause.issues;
+  }
+}

package/src/tools/json-value.ts

@@ -0,0 +1,81 @@
+import type { JSONValue } from "@toolgrain/protocol";
+
+/** Readonly authoring views of protocol data; wire types remain unchanged. */
+export type DeepReadonly<T> = T extends readonly (infer Item)[]
+  ? readonly DeepReadonly<Item>[]
+  : T extends object
+    ? { readonly [Key in keyof T]: DeepReadonly<T[Key]> }
+    : T;
+
+export type JsonCompatible<Value> = Value extends
+  | string
+  | number
+  | boolean
+  | null
+  ? Value
+  : Value extends (...args: never[]) => unknown
+    ? never
+    : Value extends readonly (infer Item)[]
+      ? readonly JsonCompatible<Item>[]
+      : Value extends object
+        ? { [Key in keyof Value]: JsonCompatible<Value[Key]> }
+        : never;
+
+export type IsJsonCompatible<Value> = [Value] extends [JsonCompatible<Value>]
+  ? true
+  : false;
+
+export interface AssertJSONOptions {
+  /** Treat undefined object properties as absent, matching JSON serialization. */
+  readonly omitUndefined?: boolean;
+}
+
+export function assertJSON(
+  value: unknown,
+  options: AssertJSONOptions = {},
+  ancestors = new Set<object>(),
+): asserts value is JSONValue {
+  if (value === null || typeof value === "string" || typeof value === "boolean")
+    return;
+  if (typeof value === "number" && Number.isFinite(value)) return;
+  if (typeof value !== "object" || value === null)
+    throw new Error("Tool output must be a JSON value");
+  if (ancestors.has(value)) throw new Error("Tool output contains a cycle");
+  const prototype = Object.getPrototypeOf(value);
+  if (
+    !Array.isArray(value) &&
+    prototype !== Object.prototype &&
+    prototype !== null
+  )
+    throw new Error("Tool output contains a non-JSON object instance");
+  ancestors.add(value);
+  try {
+    const keys = Reflect.ownKeys(value);
+    for (const key of keys) {
+      if (Array.isArray(value) && key === "length") continue;
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (
+        typeof key !== "string" ||
+        !descriptor?.enumerable ||
+        !("value" in descriptor)
+      )
+        throw new Error("Tool output contains a non-JSON property");
+      if (
+        Array.isArray(value) &&
+        (!/^(0|[1-9]\d*)$/.test(key) || Number(key) >= value.length)
+      )
+        throw new Error("Tool output contains a non-JSON array property");
+      if (
+        options.omitUndefined &&
+        !Array.isArray(value) &&
+        descriptor.value === undefined
+      )
+        continue;
+      assertJSON(descriptor.value, options, ancestors);
+    }
+    if (Array.isArray(value) && keys.length !== value.length + 1)
+      throw new Error("Tool output contains a sparse array");
+  } finally {
+    ancestors.delete(value);
+  }
+}

package/src/tools/name.ts

@@ -0,0 +1,13 @@
+export class ToolNameError extends Error {
+  constructor(public readonly toolName: string) {
+    super(
+      `Invalid MCP tool name: ${JSON.stringify(toolName)}. Use 1–128 ASCII letters, digits, underscores, hyphens, or dots.`,
+    );
+    this.name = "ToolNameError";
+  }
+}
+
+export function validateToolName(name: string): void {
+  if (name.length < 1 || name.length > 128 || /[^A-Za-z0-9_.-]/.test(name))
+    throw new ToolNameError(name);
+}

package/src/tools/registry.ts

@@ -0,0 +1,52 @@
+import * as core from "zod/v4/core";
+import type { ToolContext } from "./context.js";
+import {
+  isRegisteredTool,
+  type RegisteredTool,
+  type ToolMetadata,
+} from "./definition.js";
+import { ToolInputError, UnknownToolError } from "./errors.js";
+
+export type ToolMap = Record<string, RegisteredTool>;
+
+export interface ToolEntry extends ToolMetadata {
+  name: string;
+  input: RegisteredTool["input"];
+  output?: NonNullable<RegisteredTool["output"]>;
+}
+
+export interface Registry {
+  list(): ToolEntry[];
+  execute(name: string, input: unknown, ctx: ToolContext): Promise<unknown>;
+}
+
+export function createRegistry(tools: ToolMap): Registry {
+  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 })] as const;
+    }),
+  );
+
+  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 as never, ctx);
+    },
+  };
+}

package/src/tools/results.ts

@@ -0,0 +1,100 @@
+import type { ContentBlock, MetaObject } from "@toolgrain/protocol";
+import * as core from "zod/v4/core";
+import { explicitResult } from "./content.js";
+import { type AssertJSONOptions, assertJSON } from "./json-value.js";
+import { isMcpResult, type McpResult } from "./rich-result.js";
+
+/** Validated output shared by both protocol adapters. */
+export interface ToolExecutionResult {
+  content: ContentBlock[];
+  structuredContent?: unknown;
+  isError?: boolean;
+  _meta?: MetaObject;
+}
+
+export function toolResult(value: unknown): ToolExecutionResult {
+  if (isMcpResult(value)) return withStructuredText(readExplicit(value));
+  if (typeof value === "string")
+    return { content: [{ type: "text", text: value }] };
+  return structuredResult(value);
+}
+
+function structuredResult(
+  value: unknown,
+  options?: AssertJSONOptions,
+): ToolExecutionResult {
+  assertJSON(value, options);
+  const text = JSON.stringify(value);
+  return {
+    content: [{ type: "text", text }],
+    structuredContent: JSON.parse(text),
+  };
+}
+
+function readExplicit(value: McpResult<unknown>): ToolExecutionResult {
+  // 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)),
+  ) as ToolExecutionResult;
+}
+
+function withStructuredText(result: ToolExecutionResult): ToolExecutionResult {
+  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: string,
+  value: unknown,
+  output?: core.$ZodType,
+): Promise<ToolExecutionResult> {
+  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: string): ToolExecutionResult {
+  return {
+    isError: true,
+    content: [{ type: "text", text: message }],
+  };
+}

package/src/tools/rich-result.ts

@@ -0,0 +1,70 @@
+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;
+}
+
+// Registered symbols let duplicate package copies recognize each other's results.
+const RESULT_BRAND = Symbol.for("@toolgrain/mcp/result@1");
+
+export class McpResult<Structured> {
+  constructor(readonly value: McpResultOptions<Structured>) {
+    Object.freeze(this);
+  }
+
+  /** Structural brand shared by package copies; object spreads do not keep it. */
+  "~toolgrain"(): "result@1" {
+    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: unknown): value is McpResult<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { [RESULT_BRAND]?: unknown })[RESULT_BRAND] === true
+  );
+}
+
+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 function mcpResult<Structured = never>(
+  value: McpResultOptions<Structured> & {
+    isError: true;
+    structuredContent: Structured;
+  },
+): McpErrorResult<Structured> & McpStructuredResult<Structured>;
+export function mcpResult(
+  value: McpResultOptions<never> & { isError: true },
+): McpErrorResult<never>;
+export function mcpResult<Structured>(
+  value: McpResultOptions<Structured> & { isError: true },
+): McpErrorResult<Structured>;
+export function mcpResult<Structured>(
+  value: McpResultOptions<Structured> & { structuredContent: Structured },
+): McpStructuredResult<Structured>;
+export function mcpResult(value: McpResultOptions<never>): McpResult<never>;
+export function mcpResult<Structured = never>(
+  value: McpResultOptions<Structured>,
+): McpResult<Structured>;
+export function mcpResult<Structured = never>(
+  value: McpResultOptions<Structured>,
+): McpResult<Structured> {
+  return new McpResult(value);
+}

package/src/tools/schema.ts

@@ -0,0 +1,86 @@
+import type { Tool as ProtocolTool } from "@toolgrain/protocol";
+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";
+import type { ToolMap } from "./registry.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 {
+  constructor(
+    public readonly toolName: string,
+    cause: unknown,
+    public readonly schemaKind: "input" | "output" | "metadata" = "input",
+  ) {
+    super(`Cannot expose ${schemaKind} schema for tool: ${toolName}`, {
+      cause,
+    });
+    this.name = "ToolSchemaError";
+  }
+}
+
+export function describeTool(
+  name: string,
+  definition: Pick<
+    ToolMap[string],
+    | "input"
+    | "output"
+    | "title"
+    | "description"
+    | "icons"
+    | "annotations"
+    | "_meta"
+  >,
+): ProtocolTool {
+  validateToolName(name);
+  let schemaKind: "input" | "output" | "metadata" = "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: Record<string, unknown> = {};
+    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) as ProtocolTool;
+  } catch (cause) {
+    throw new ToolSchemaError(name, cause, schemaKind);
+  }
+}

package/src/transport-ownership.ts

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

package/src/transport.ts

@@ -0,0 +1,34 @@
+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 function isRequestTransport(
+  transport: Transport | RequestTransport,
+): transport is RequestTransport {
+  return "mode" in transport && transport.mode === "request";
+}