@toolgrain/mcp 0.0.0-stage → 0.1.0

package/src/protocol/decode.ts

@@ -0,0 +1,69 @@
+import {
+  INVALID_REQUEST,
+  type JSONRPCErrorResponse,
+  type RequestId,
+} from "@toolgrain/protocol";
+import {
+  cancellation,
+  envelope,
+  type Notification,
+  type Request,
+  requestId,
+} from "./messages.js";
+import { protocolError } from "./responses.js";
+
+type Incoming =
+  | { kind: "request"; request: Request }
+  | { kind: "cancel"; id: RequestId }
+  | { kind: "notification"; notification: Notification }
+  | { kind: "ignore" }
+  | {
+      kind: "error";
+      response: JSONRPCErrorResponse;
+    };
+
+/** Decode the envelope; method parameters are validated by the dispatcher. */
+export function decode(message: unknown): Incoming {
+  const parsed = envelope.safeParse(message);
+  if (!parsed.success) {
+    if (
+      typeof message === "object" &&
+      message !== null &&
+      !Array.isArray(message) &&
+      (("method" in message && !Object.hasOwn(message, "id")) ||
+        isResponse(message))
+    )
+      return { kind: "ignore" };
+    const id =
+      typeof message === "object" && message !== null && "id" in message
+        ? requestId.safeParse(message.id)
+        : undefined;
+    return {
+      kind: "error",
+      response: protocolError(
+        INVALID_REQUEST,
+        "Invalid request",
+        id?.success ? id.data : undefined,
+      ),
+    };
+  }
+  if (parsed.data.id !== undefined)
+    return { kind: "request", request: { ...parsed.data, id: parsed.data.id } };
+  if (parsed.data.method === "notifications/cancelled") {
+    const params = cancellation.safeParse(parsed.data.params);
+    if (params.success) return { kind: "cancel", id: params.data.requestId };
+    return { kind: "ignore" };
+  }
+  return { kind: "notification", notification: parsed.data };
+}
+
+/** Servers send no requests, so a client response has nothing to answer. */
+function isResponse(message: object): boolean {
+  return (
+    "jsonrpc" in message &&
+    message.jsonrpc === "2.0" &&
+    !Object.hasOwn(message, "method") &&
+    Object.hasOwn(message, "id") &&
+    Object.hasOwn(message, "result") !== Object.hasOwn(message, "error")
+  );
+}

package/src/protocol/icon.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+
+export const icon = z.looseObject({
+  src: z.string(),
+  mimeType: z.string().optional(),
+  sizes: z.array(z.string()).optional(),
+  theme: z.enum(["light", "dark"]).optional(),
+});

package/src/protocol/messages.ts

@@ -0,0 +1,29 @@
+import { JSONRPC_VERSION } from "@toolgrain/protocol";
+import { z } from "zod";
+
+export const object = z.record(z.string(), z.unknown());
+export const requestId = z.union([
+  z.string(),
+  z.number().finite().refine(Number.isInteger, "Request ID must be an integer"),
+]);
+export const envelope = z
+  .looseObject({
+    jsonrpc: z.literal(JSONRPC_VERSION),
+    method: z.string(),
+    id: requestId.optional(),
+    params: object.optional(),
+  })
+  .refine(
+    (value) =>
+      !Object.hasOwn(value, "result") && !Object.hasOwn(value, "error"),
+  );
+export const cancellation = z.looseObject({
+  requestId,
+  reason: z.string().optional(),
+  _meta: object.optional(),
+});
+
+export type Request = z.infer<typeof envelope> & {
+  id: z.infer<typeof requestId>;
+};
+export type Notification = z.infer<typeof envelope>;

package/src/protocol/responses.ts

@@ -0,0 +1,27 @@
+import type { JSONRPCErrorResponse, RequestId } from "@toolgrain/protocol";
+import { JSONRPC_VERSION } from "@toolgrain/protocol";
+
+export function protocolError(
+  code: number,
+  message: string,
+  id?: RequestId,
+  data?: unknown,
+): JSONRPCErrorResponse {
+  return {
+    jsonrpc: JSONRPC_VERSION,
+    ...(id === undefined ? {} : { id }),
+    error: { code, message, ...(data === undefined ? {} : { data }) },
+  };
+}
+
+/** An internal dispatch failure, converted to a protocol response at the connection boundary. */
+export class ProtocolError extends Error {
+  constructor(
+    public readonly code: number,
+    message: string,
+    public readonly data?: unknown,
+  ) {
+    super(message);
+    this.name = "ProtocolError";
+  }
+}

package/src/protocol/version-metadata.ts

@@ -0,0 +1,42 @@
+import {
+  INVALID_PARAMS,
+  type SupportedProtocolVersion,
+} from "@toolgrain/protocol";
+import type { Request } from "./messages.js";
+import { ProtocolError } from "./responses.js";
+
+export function hasProtocolVersionMetadata(request: Request): boolean {
+  const meta = request.params?._meta;
+  return (
+    typeof meta === "object" &&
+    meta !== null &&
+    Object.hasOwn(meta, "io.modelcontextprotocol/protocolVersion")
+  );
+}
+
+export function metadataMatchesVersion(
+  request: Request,
+  version: SupportedProtocolVersion,
+): boolean {
+  const meta = request.params?._meta as Record<string, unknown>;
+  return (
+    hasProtocolVersionMetadata(request) &&
+    meta["io.modelcontextprotocol/protocolVersion"] === version
+  );
+}
+
+/** A transport-selected revision cannot contradict an explicit request revision. */
+export function validateVersionContext(
+  request: Request,
+  version?: SupportedProtocolVersion,
+): void {
+  if (
+    version !== undefined &&
+    hasProtocolVersionMetadata(request) &&
+    !metadataMatchesVersion(request, version)
+  )
+    throw new ProtocolError(
+      INVALID_PARAMS,
+      "Protocol version does not match request metadata",
+    );
+}

package/src/server.ts

@@ -0,0 +1,164 @@
+import type {
+  ProtocolResponse,
+  Tool as ProtocolTool,
+  SupportedProtocolVersion,
+} from "@toolgrain/protocol";
+import { createAuthorization } from "./auth/authorization.js";
+import { AuthError, isAuthError } from "./auth/errors.js";
+import type { AuthMetadata, AuthProvider, AuthScope } from "./auth/types.js";
+import { createConnection } from "./connection.js";
+import type { RegisteredContextProvider } from "./context/definition.js";
+import { createContextRegistry } from "./context/registry.js";
+import { type ErrorHandler, reportError } from "./diagnostics.js";
+import { createDispatcher, formatErrorResponse } from "./dispatcher.js";
+import { executeRequest } from "./execute-request.js";
+import { decode } from "./protocol/decode.js";
+import { createToolAdapter } from "./tools/adapter.js";
+import type { ToolMap } from "./tools/registry.js";
+import {
+  isRequestTransport,
+  type RequestTransport,
+  type Transport,
+} from "./transport.js";
+
+export interface ServerOptions<Tools extends ToolMap = ToolMap> {
+  name: string;
+  version: string;
+  tools: Tools;
+  instructions?: string;
+  /** Tool failures include frozen tool/request details; other diagnostics omit them. */
+  onError?: ErrorHandler;
+  auth?: AuthProvider;
+  context?: readonly RegisteredContextProvider[];
+}
+
+export interface HandleOptions {
+  signal?: AbortSignal;
+  protocolVersion?: SupportedProtocolVersion;
+  auth?: AuthScope;
+}
+
+export interface Server {
+  handle(
+    message: unknown,
+    options?: HandleOptions,
+  ): Promise<ProtocolResponse | undefined>;
+  getToolDefinitions(): ProtocolTool[];
+  getAuthMetadata(): AuthMetadata | undefined;
+  authorize(
+    accessToken: string,
+    options: { resource: string; signal?: AbortSignal },
+  ): Promise<AuthScope>;
+  listen(transport: Transport | RequestTransport): Promise<void>;
+  close(): Promise<void>;
+}
+
+/** Compose the tool adapter, MCP dispatcher, and transport connection. */
+export function createServer<const Tools extends ToolMap>(
+  options: ServerOptions<Tools>,
+): Server {
+  const authorization = createAuthorization(options.auth);
+  const tools = createToolAdapter(options.tools, options.onError);
+  const dispatch = createDispatcher(
+    tools,
+    { name: options.name, version: options.version },
+    options.instructions,
+    createContextRegistry(options.context),
+  );
+  let closed = false;
+  const running = new Set<AbortController>();
+  const closeIndependent = () => {
+    if (closed) return;
+    closed = true;
+    for (const controller of running)
+      controller.abort(new DOMException("Server closed", "AbortError"));
+    running.clear();
+  };
+  const connection = createConnection(
+    dispatch,
+    options.onError,
+    closeIndependent,
+  );
+  const requestController = (signal?: AbortSignal) => {
+    const controller = new AbortController();
+    const abort = () => controller.abort(signal?.reason);
+    if (signal?.aborted) abort();
+    else signal?.addEventListener("abort", abort, { once: true });
+    running.add(controller);
+    return {
+      signal: controller.signal,
+      finish() {
+        signal?.removeEventListener("abort", abort);
+        running.delete(controller);
+      },
+    };
+  };
+  const server: Server = {
+    async listen(transport) {
+      if (isRequestTransport(transport))
+        return connection.listenRequests(transport, server);
+      if (authorization.metadata())
+        throw new Error(
+          "Auth-configured servers require HTTP and cannot listen on a message transport",
+        );
+      return connection.listen(transport);
+    },
+    getToolDefinitions: () => tools.list(),
+    getAuthMetadata: authorization.metadata,
+    async authorize(accessToken, { resource, signal }) {
+      if (closed) throw new AuthError("temporarily_unavailable");
+      const pending = requestController(signal);
+      try {
+        return await authorization.authorize(
+          accessToken,
+          resource,
+          pending.signal,
+          pending.finish,
+        );
+      } catch (error) {
+        pending.finish();
+        if (
+          !pending.signal.aborted &&
+          (!isAuthError(error) || error.code === "temporarily_unavailable")
+        )
+          reportError(options.onError, error);
+        throw error;
+      }
+    },
+    async handle(
+      message,
+      { signal, protocolVersion, auth }: HandleOptions = {},
+    ) {
+      if (closed) throw new Error("Server is closed");
+      const identity = authorization.consume(auth);
+      if (auth?.signal.aborted) return;
+      const active = () => !closed && !signal?.aborted;
+      if (!active()) return;
+      const incoming = decode(message);
+      if (incoming.kind === "error")
+        return formatErrorResponse(incoming.response, protocolVersion);
+      if (incoming.kind !== "request") return;
+      const pending = requestController(signal);
+      // The authorization signal covers verification and body decoding too.
+      const combined = auth
+        ? AbortSignal.any([pending.signal, auth.signal])
+        : pending.signal;
+      try {
+        return await executeRequest(
+          dispatch,
+          incoming.request,
+          { signal: combined, ...(identity ? { auth: identity } : {}) },
+          options.onError,
+          protocolVersion,
+        );
+      } finally {
+        pending.finish();
+      }
+    },
+    close() {
+      closeIndependent();
+      return connection.close();
+    },
+  };
+  return server;
+}

package/src/tools/adapter.ts

@@ -0,0 +1,76 @@
+import type { Tool as ProtocolTool } from "@toolgrain/protocol";
+import { type ErrorHandler, reportError } from "../diagnostics.js";
+import type { ToolContext } from "./context.js";
+import { ToolInputError } from "./errors.js";
+import { createRegistry, type ToolMap } from "./registry.js";
+import {
+  resolveToolResult,
+  type ToolExecutionResult,
+  toolError,
+} from "./results.js";
+import { describeTool } from "./schema.js";
+
+export interface ToolAdapter {
+  has(name: string): boolean;
+  list(): ProtocolTool[];
+  execute(
+    name: string,
+    input: unknown,
+    ctx: ToolContext,
+  ): Promise<ToolExecutionResult | undefined>;
+}
+
+export function createToolAdapter(
+  tools: ToolMap,
+  onError?: ErrorHandler,
+): ToolAdapter {
+  const registry = createRegistry(tools);
+  const entries = registry.list();
+  const names = new Set(entries.map(({ name }) => name));
+  const outputs = new Map(entries.map(({ name, output }) => [name, output]));
+  const listed = entries.map((entry) => describeTool(entry.name, entry));
+  return {
+    has: (name: string) => names.has(name),
+    list: () => structuredClone(listed),
+    async execute(
+      name: string,
+      input: unknown,
+      ctx: ToolContext,
+    ): Promise<ToolExecutionResult | undefined> {
+      const isActive = () => !ctx.signal.aborted;
+      if (!names.has(name) || !isActive()) return;
+      try {
+        const result = await registry.execute(name, input, ctx);
+        if (!isActive()) return;
+        const converted = await resolveToolResult(
+          name,
+          result,
+          outputs.get(name),
+        );
+        return isActive() ? converted : undefined;
+      } catch (error) {
+        if (!isActive()) return;
+        try {
+          if (error instanceof ToolInputError) {
+            return toolError(
+              error.issues
+                .map(
+                  (issue) =>
+                    `${issue.path.map(String).join(".") || "input"}: ${issue.message}`,
+                )
+                .join("; "),
+            );
+          }
+        } catch {
+          // Inspecting a thrown value can fail, including revoked or trapped proxies.
+        }
+        reportError(
+          onError,
+          error,
+          Object.freeze({ toolName: name, request: ctx.request }),
+        );
+        return isActive() ? toolError("Tool execution failed") : undefined;
+      }
+    },
+  };
+}

package/src/tools/call.ts

@@ -0,0 +1,18 @@
+import { INVALID_PARAMS } from "@toolgrain/protocol";
+import { ProtocolError } from "../protocol/responses.js";
+import type { ToolAdapter } from "./adapter.js";
+import type { ToolContext } from "./context.js";
+
+/** Execute an already-validated call through the shared registry. */
+export function callTool(
+  {
+    name,
+    arguments: input = {},
+  }: { name: string; arguments?: Record<string, unknown> | undefined },
+  tools: ToolAdapter,
+  ctx: ToolContext,
+) {
+  if (!tools.has(name))
+    throw new ProtocolError(INVALID_PARAMS, `Unknown tool: ${name}`);
+  return tools.execute(name, input, ctx);
+}

package/src/tools/content.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { icon } from "../protocol/icon.js";
+import { object } from "../protocol/messages.js";
+
+const annotations = z.looseObject({
+  audience: z.array(z.enum(["user", "assistant"])).optional(),
+  priority: z.number().min(0).max(1).optional(),
+  lastModified: z.string().optional(),
+});
+
+const common = z.looseObject({
+  annotations: annotations.optional(),
+  _meta: object.optional(),
+});
+const resourceContents = z.looseObject({
+  uri: z.string(),
+  mimeType: z.string().optional(),
+  _meta: object.optional(),
+});
+
+export const contentBlock = z.discriminatedUnion("type", [
+  common.extend({ type: z.literal("text"), text: z.string() }),
+  common.extend({
+    type: z.literal("image"),
+    data: z.string(),
+    mimeType: z.string(),
+  }),
+  common.extend({
+    type: z.literal("audio"),
+    data: z.string(),
+    mimeType: z.string(),
+  }),
+  common.extend({
+    type: z.literal("resource_link"),
+    uri: z.string(),
+    name: z.string(),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    mimeType: z.string().optional(),
+    size: z.number().optional(),
+    icons: z.array(icon).optional(),
+  }),
+  common.extend({
+    type: z.literal("resource"),
+    resource: z.union([
+      resourceContents.extend({ text: z.string() }),
+      resourceContents.extend({ blob: z.string() }),
+    ]),
+  }),
+]);
+
+export const explicitResult = z.strictObject({
+  content: z.array(contentBlock),
+  structuredContent: z.unknown().optional(),
+  isError: z.boolean().optional(),
+  _meta: object.optional(),
+});

package/src/tools/context.ts

@@ -0,0 +1,119 @@
+import {
+  type ClientCapabilities,
+  type Implementation,
+  PROTOCOL_VERSION,
+  type RequestId,
+  type SupportedProtocolVersion,
+} from "@toolgrain/protocol";
+import type {
+  ClientCapabilities as LegacyClientCapabilities,
+  Implementation as LegacyImplementation,
+} from "@toolgrain/protocol/2025-06-18";
+import { attachAuth } from "../auth/context.js";
+import type { AuthIdentity } from "../auth/types.js";
+import type { RegisteredContextProvider } from "../context/definition.js";
+import {
+  type ContextRegistry,
+  createContextRegistry,
+} from "../context/registry.js";
+import { createContextScope } from "../context/scope.js";
+import type { DeepReadonly } from "./json-value.js";
+
+/** What the client reported about itself; unverified, so not a basis for security decisions. */
+export interface ToolClient {
+  readonly info?: DeepReadonly<Implementation | LegacyImplementation>;
+  readonly capabilities?: DeepReadonly<
+    ClientCapabilities | LegacyClientCapabilities
+  >;
+}
+
+export interface ToolRequest {
+  readonly id: RequestId;
+  readonly protocolVersion: SupportedProtocolVersion;
+  /** Absent when the era and transport carry no client information, such as legacy HTTP. */
+  readonly client?: ToolClient;
+  /** A deeply frozen copy of the request's `_meta`; empty when the request carried none. */
+  readonly meta: Readonly<Record<string, unknown>>;
+}
+
+export interface ToolContext {
+  /** Aborts when the client cancels or disconnects, or the transport or server closes. */
+  readonly signal: AbortSignal;
+  readonly request: ToolRequest;
+}
+
+export interface ToolContextOptions {
+  signal?: AbortSignal;
+  request?: Partial<ToolRequest>;
+  context?: readonly RegisteredContextProvider[];
+}
+
+/** Build a context for calling a definition's `execute` directly, for example in tests. */
+export function toolContext(options: ToolContextOptions = {}): ToolContext {
+  // Default each field separately so an explicit undefined cannot replace a default.
+  const {
+    id = 0,
+    protocolVersion = PROTOCOL_VERSION,
+    client,
+    meta = {},
+  } = options.request ?? {};
+  return createToolContext(
+    options.signal ?? new AbortController().signal,
+    {
+      id,
+      protocolVersion,
+      ...(client === undefined ? {} : { client }),
+      meta,
+    },
+    undefined,
+    createContextRegistry(options.context),
+  );
+}
+
+/** Each request gets its own deeply frozen copies, so handlers cannot affect one another. */
+export function createToolContext(
+  signal: AbortSignal,
+  { client, ...request }: ToolRequest,
+  auth?: AuthIdentity,
+  providers: ContextRegistry = createContextRegistry(),
+): ToolContext {
+  const ctx = attachAuth(
+    {
+      signal,
+      request: Object.freeze({
+        ...request,
+        ...(client === undefined
+          ? {}
+          : {
+              client: frozenCopy(toolClient(client.info, client.capabilities)),
+            }),
+        meta: frozenCopy(request.meta),
+      }),
+    },
+    auth,
+  );
+  return createContextScope(ctx, providers);
+}
+
+/** Omit absent fields so the client matches its optional-property types. */
+export function toolClient(
+  info: ToolClient["info"],
+  capabilities: ToolClient["capabilities"],
+): ToolClient {
+  return {
+    ...(info === undefined ? {} : { info }),
+    ...(capabilities === undefined ? {} : { capabilities }),
+  };
+}
+
+function frozenCopy<T>(value: T): T {
+  return deepFreeze(structuredClone(value));
+}
+
+function deepFreeze<T>(value: T): T {
+  if (typeof value === "object" && value !== null) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+}