@toolgrain/mcp 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,41 @@
+export { validateTokenAudience } from "./auth/audience.js";
+export { createAuthAccessor } from "./auth/context.js";
+export type { AuthErrorCode } from "./auth/errors.js";
+export { AuthError, isAuthError } from "./auth/errors.js";
+export type {
+  AuthMetadata,
+  AuthProvider,
+  AuthReadonly,
+  AuthScope,
+  AuthVerifyOptions,
+} from "./auth/types.js";
+export { authUrl as validateAuthUrl } from "./auth/url.js";
+export type { ContextProvider } from "./context/definition.js";
+export { createContext } from "./context/definition.js";
+export type { ToolErrorDetails } from "./diagnostics.js";
+export type { HandleOptions, Server, ServerOptions } from "./server.js";
+export { createServer } from "./server.js";
+export type {
+  ToolClient,
+  ToolContext,
+  ToolContextOptions,
+  ToolRequest,
+} from "./tools/context.js";
+export { toolContext } from "./tools/context.js";
+export type { Tool, ToolDefinition, ToolMetadata } from "./tools/definition.js";
+export { tool } from "./tools/definition.js";
+export { ToolNameError } from "./tools/name.js";
+export type { ToolMap } from "./tools/registry.js";
+export type {
+  McpErrorResult,
+  McpResult,
+  McpResultOptions,
+  McpStructuredResult,
+} from "./tools/rich-result.js";
+export { mcpResult } from "./tools/rich-result.js";
+export { ToolSchemaError } from "./tools/schema.js";
+export type {
+  RequestTransport,
+  Transport,
+  TransportCallbacks,
+} from "./transport.js";

package/src/legacy/connection.ts

@@ -0,0 +1,101 @@
+import {
+  INVALID_REQUEST,
+  type JSONRPCErrorResponse,
+  LEGACY_PROTOCOL_VERSION,
+  type ProtocolResponse,
+  type RequestId,
+  type SupportedProtocolVersion,
+} from "@toolgrain/protocol";
+import type {
+  ClientCapabilities,
+  Implementation,
+} from "@toolgrain/protocol/2025-06-18";
+import type { Notification, Request } from "../protocol/messages.js";
+import { protocolError } from "../protocol/responses.js";
+import {
+  hasProtocolVersionMetadata,
+  metadataMatchesVersion,
+} from "../protocol/version-metadata.js";
+import { type ToolClient, toolClient } from "../tools/context.js";
+import { commonParams, initializeParams } from "./messages.js";
+import { errorResponse } from "./responses.js";
+
+/** Owns the initialization lifecycle for one attached transport. */
+export function createLegacyConnection() {
+  let state: "initializing" | "awaiting-initialized" | "ready" | undefined;
+  let initializeId: RequestId | undefined;
+  let client: ToolClient | undefined;
+  return {
+    prepare(request: Request) {
+      const legacy =
+        (state !== undefined &&
+          metadataMatchesVersion(request, LEGACY_PROTOCOL_VERSION)) ||
+        (!hasProtocolVersionMetadata(request) &&
+          (state !== undefined ||
+            request.method === "initialize" ||
+            request.method === "ping"));
+      if (!legacy) return {};
+      const initialize = request.method === "initialize";
+      if (
+        initialize
+          ? state !== undefined
+          : state !== "ready" && request.method !== "ping"
+      )
+        return {
+          error: protocolError(
+            INVALID_REQUEST,
+            initialize
+              ? "Server is already initialized"
+              : "Server is not initialized",
+            request.id,
+          ),
+        };
+      return { protocolVersion: LEGACY_PROTOCOL_VERSION } as const;
+    },
+    begin(request: Request, protocolVersion?: SupportedProtocolVersion) {
+      if (
+        protocolVersion !== LEGACY_PROTOCOL_VERSION ||
+        request.method !== "initialize"
+      )
+        return;
+      state = "initializing";
+      initializeId = request.id;
+      return {
+        respond(response: ProtocolResponse | undefined) {
+          state =
+            response && "result" in response
+              ? "awaiting-initialized"
+              : undefined;
+          // The response succeeded only if these parameters already validated.
+          const params = initializeParams.safeParse(request.params);
+          if (state && params.success)
+            client = toolClient(
+              params.data.clientInfo as Implementation,
+              params.data.capabilities as ClientCapabilities,
+            );
+        },
+        finish() {
+          initializeId = undefined;
+        },
+      };
+    },
+    notification(notification: Notification) {
+      if (
+        notification.method === "notifications/initialized" &&
+        commonParams.safeParse(notification.params ?? {}).success &&
+        state === "awaiting-initialized"
+      )
+        state = "ready";
+    },
+    /** Details from a completed legacy initialization on this connection. */
+    client() {
+      return client;
+    },
+    canCancel(id: RequestId) {
+      return id !== initializeId;
+    },
+    errorResponse(response: JSONRPCErrorResponse) {
+      return state === undefined ? response : errorResponse(response);
+    },
+  };
+}

package/src/legacy/dispatcher.ts

@@ -0,0 +1,72 @@
+import {
+  type Implementation,
+  LEGACY_PROTOCOL_VERSION,
+  METHOD_NOT_FOUND,
+  type SupportedProtocolVersion,
+} from "@toolgrain/protocol";
+import type { JSONRPCResponse, Result } from "@toolgrain/protocol/2025-06-18";
+import type { ContextRegistry } from "../context/registry.js";
+import type { RequestScope } from "../dispatcher.js";
+import type { Request } from "../protocol/messages.js";
+import { ProtocolError } from "../protocol/responses.js";
+import { hasProtocolVersionMetadata } from "../protocol/version-metadata.js";
+import type { ToolAdapter } from "../tools/adapter.js";
+import { createToolContext } from "../tools/context.js";
+import { callTool, initialize, listTools, ping } from "./handlers.js";
+import { successResponse } from "./responses.js";
+
+/** Initialization selects this adapter only without an explicit modern context. */
+export function usesLegacyProtocol(
+  request: Request,
+  protocolVersion?: SupportedProtocolVersion,
+): boolean {
+  return (
+    protocolVersion === LEGACY_PROTOCOL_VERSION ||
+    (protocolVersion === undefined &&
+      !hasProtocolVersionMetadata(request) &&
+      request.method === "initialize")
+  );
+}
+
+export function createLegacyDispatcher(
+  tools: ToolAdapter,
+  identity: Implementation,
+  instructions?: string,
+  providers?: ContextRegistry,
+) {
+  return async (
+    request: Request,
+    scope: RequestScope,
+  ): Promise<JSONRPCResponse | undefined> => {
+    let result: Result | undefined;
+    switch (request.method) {
+      case "initialize":
+        result = initialize(request.params, identity, instructions);
+        break;
+      case "ping":
+        result = ping(request.params);
+        break;
+      case "tools/list":
+        result = listTools(request.params, tools);
+        break;
+      case "tools/call":
+        result = await callTool(request.params, tools, (params) =>
+          createToolContext(
+            scope.signal,
+            {
+              id: request.id,
+              protocolVersion: LEGACY_PROTOCOL_VERSION,
+              ...(scope.client === undefined ? {} : { client: scope.client }),
+              meta: params._meta ?? {},
+            },
+            scope.auth,
+            providers,
+          ),
+        );
+        break;
+      default:
+        throw new ProtocolError(METHOD_NOT_FOUND, "Method not found");
+    }
+    return result ? successResponse(request.id, result) : undefined;
+  };
+}

package/src/legacy/handlers.ts

@@ -0,0 +1,76 @@
+import {
+  type Implementation,
+  INVALID_PARAMS,
+  LEGACY_PROTOCOL_VERSION,
+} from "@toolgrain/protocol";
+import type {
+  InitializeResult,
+  ListToolsResult,
+} from "@toolgrain/protocol/2025-06-18";
+import { ProtocolError } from "../protocol/responses.js";
+import type { ToolAdapter } from "../tools/adapter.js";
+import { callTool as executeToolCall } from "../tools/call.js";
+import type { ToolContext } from "../tools/context.js";
+import {
+  callParams,
+  commonParams,
+  initializeParams,
+  listParams,
+} from "./messages.js";
+import { toolResult } from "./results.js";
+
+/** Initialization can only negotiate the initialization-based revision. */
+export function initialize(
+  params: unknown,
+  identity: Implementation,
+  instructions?: string,
+): InitializeResult {
+  if (!initializeParams.safeParse(params).success)
+    throw new ProtocolError(
+      INVALID_PARAMS,
+      "Invalid initialization parameters",
+    );
+  return {
+    protocolVersion: LEGACY_PROTOCOL_VERSION,
+    capabilities: { tools: {} },
+    serverInfo: { ...identity },
+    ...(instructions === undefined ? {} : { instructions }),
+  };
+}
+
+export function ping(params: unknown): Record<string, never> {
+  if (!commonParams.safeParse(params ?? {}).success)
+    throw new ProtocolError(INVALID_PARAMS, "Invalid ping parameters");
+  return {};
+}
+
+export function listTools(
+  params: unknown,
+  tools: ToolAdapter,
+): ListToolsResult {
+  const parsed = listParams.safeParse(params ?? {});
+  if (!parsed.success || parsed.data.cursor)
+    throw new ProtocolError(INVALID_PARAMS, "Invalid tool list parameters");
+  return {
+    tools: tools
+      .list()
+      .map(({ icons: _icons, outputSchema, ...definition }) => ({
+        ...definition,
+        ...(outputSchema?.type === "object"
+          ? { outputSchema: { ...outputSchema, type: "object" as const } }
+          : {}),
+      })),
+  };
+}
+
+export async function callTool(
+  params: unknown,
+  tools: ToolAdapter,
+  ctx: (params: { _meta?: Record<string, unknown> | undefined }) => ToolContext,
+) {
+  const parsed = callParams.safeParse(params);
+  if (!parsed.success)
+    throw new ProtocolError(INVALID_PARAMS, "Invalid tool call parameters");
+  const result = await executeToolCall(parsed.data, tools, ctx(parsed.data));
+  return result ? toolResult(result) : undefined;
+}

package/src/legacy/messages.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { object } from "../protocol/messages.js";
+
+export const commonParams = z.looseObject({
+  _meta: object.optional(),
+});
+export const initializeParams = commonParams.extend({
+  protocolVersion: z.string(),
+  capabilities: z.looseObject({
+    experimental: z.record(z.string(), object).optional(),
+    roots: z.looseObject({ listChanged: z.boolean().optional() }).optional(),
+    sampling: object.optional(),
+    elicitation: object.optional(),
+  }),
+  clientInfo: z.looseObject({
+    name: z.string(),
+    version: z.string(),
+    title: z.string().optional(),
+  }),
+});
+export const listParams = commonParams.extend({
+  cursor: z.string().optional(),
+});
+export const callParams = commonParams.extend({
+  name: z.string(),
+  arguments: object.optional(),
+});

package/src/legacy/responses.ts

@@ -0,0 +1,20 @@
+import {
+  JSONRPC_VERSION,
+  type JSONRPCErrorResponse,
+  type LegacyJSONRPCErrorResponse,
+  type RequestId,
+} from "@toolgrain/protocol";
+import type { JSONRPCResponse, Result } from "@toolgrain/protocol/2025-06-18";
+
+export function successResponse(
+  id: RequestId,
+  result: Result,
+): JSONRPCResponse {
+  return { jsonrpc: JSONRPC_VERSION, id, result };
+}
+
+export function errorResponse(
+  response: JSONRPCErrorResponse,
+): LegacyJSONRPCErrorResponse {
+  return { ...response, id: response.id ?? null };
+}

package/src/legacy/results.ts

@@ -0,0 +1,20 @@
+import type { CallToolResult } from "@toolgrain/protocol/2025-06-18";
+import type { ToolExecutionResult } from "../tools/results.js";
+
+/** The initialization-based format permits structured content only at an object root. */
+export function toolResult(result: ToolExecutionResult): CallToolResult {
+  const { structuredContent, ...content } = result;
+  return {
+    ...content,
+    content: content.content.map((block) => {
+      if (block.type !== "resource_link") return block;
+      const { icons: _icons, ...resource } = block;
+      return resource;
+    }),
+    ...(structuredContent !== null &&
+    typeof structuredContent === "object" &&
+    !Array.isArray(structuredContent)
+      ? { structuredContent: structuredContent as Record<string, unknown> }
+      : {}),
+  };
+}

package/src/modern/dispatcher.ts

@@ -0,0 +1,77 @@
+import {
+  type ClientCapabilities,
+  type Implementation,
+  INVALID_PARAMS,
+  type JSONRPCResultResponse,
+  METHOD_NOT_FOUND,
+  PROTOCOL_VERSION,
+  type Result,
+  SUPPORTED_PROTOCOL_VERSIONS,
+  UNSUPPORTED_PROTOCOL_VERSION,
+} from "@toolgrain/protocol";
+import type { ContextRegistry } from "../context/registry.js";
+import type { RequestScope } from "../dispatcher.js";
+import type { Request } from "../protocol/messages.js";
+import { ProtocolError } from "../protocol/responses.js";
+import type { ToolAdapter } from "../tools/adapter.js";
+import { createToolContext, toolClient } from "../tools/context.js";
+import { callTool, discover, listTools } from "./handlers.js";
+import { metadata } from "./metadata.js";
+import { successResponse } from "./responses.js";
+
+export function createModernDispatcher(
+  tools: ToolAdapter,
+  identity: Implementation,
+  instructions?: string,
+  providers?: ContextRegistry,
+) {
+  return async (
+    request: Request,
+    scope: RequestScope,
+  ): Promise<JSONRPCResultResponse | undefined> => {
+    const parsed = metadata.safeParse(request.params?._meta);
+    if (!parsed.success)
+      throw new ProtocolError(INVALID_PARAMS, "Invalid request metadata");
+    const revision = parsed.data["io.modelcontextprotocol/protocolVersion"];
+    if (revision !== PROTOCOL_VERSION)
+      throw new ProtocolError(
+        UNSUPPORTED_PROTOCOL_VERSION,
+        "Unsupported protocol version",
+        { supported: [...SUPPORTED_PROTOCOL_VERSIONS], requested: revision },
+      );
+    let result: Result | undefined;
+    switch (request.method) {
+      case "server/discover":
+        result = discover(request.params, instructions);
+        break;
+      case "tools/list":
+        result = listTools(request.params, tools);
+        break;
+      case "tools/call":
+        result = await callTool(request.params, tools, (params) =>
+          createToolContext(
+            scope.signal,
+            {
+              id: request.id,
+              protocolVersion: PROTOCOL_VERSION,
+              client: toolClient(
+                parsed.data["io.modelcontextprotocol/clientInfo"] as
+                  | Implementation
+                  | undefined,
+                parsed.data[
+                  "io.modelcontextprotocol/clientCapabilities"
+                ] as ClientCapabilities,
+              ),
+              meta: params._meta ?? {},
+            },
+            scope.auth,
+            providers,
+          ),
+        );
+        break;
+      default:
+        throw new ProtocolError(METHOD_NOT_FOUND, "Method not found");
+    }
+    return result ? successResponse(request.id, result, identity) : undefined;
+  };
+}

package/src/modern/handlers.ts

@@ -0,0 +1,55 @@
+import {
+  type DiscoverResult,
+  INVALID_PARAMS,
+  type ListToolsResult,
+  SUPPORTED_PROTOCOL_VERSIONS,
+} from "@toolgrain/protocol";
+import { ProtocolError } from "../protocol/responses.js";
+import type { ToolAdapter } from "../tools/adapter.js";
+import { callTool as executeToolCall } from "../tools/call.js";
+import type { ToolContext } from "../tools/context.js";
+import { callParams, commonParams, listParams } from "./messages.js";
+import { toolResult } from "./results.js";
+
+export function discover(
+  params: unknown,
+  instructions?: string,
+): DiscoverResult {
+  if (!commonParams.safeParse(params).success)
+    throw new ProtocolError(INVALID_PARAMS, "Invalid discovery parameters");
+  return {
+    resultType: "complete",
+    ttlMs: 0,
+    cacheScope: "private",
+    supportedVersions: [...SUPPORTED_PROTOCOL_VERSIONS],
+    capabilities: { tools: {} },
+    ...(instructions === undefined ? {} : { instructions }),
+  };
+}
+
+export function listTools(
+  params: unknown,
+  tools: ToolAdapter,
+): ListToolsResult {
+  const parsed = listParams.safeParse(params);
+  if (!parsed.success || parsed.data.cursor)
+    throw new ProtocolError(INVALID_PARAMS, "Invalid tool list parameters");
+  return {
+    resultType: "complete",
+    ttlMs: 0,
+    cacheScope: "private",
+    tools: tools.list(),
+  };
+}
+
+export async function callTool(
+  params: unknown,
+  tools: ToolAdapter,
+  ctx: (params: { _meta?: Record<string, unknown> | undefined }) => ToolContext,
+) {
+  const parsed = callParams.safeParse(params);
+  if (!parsed.success)
+    throw new ProtocolError(INVALID_PARAMS, "Invalid tool call parameters");
+  const result = await executeToolCall(parsed.data, tools, ctx(parsed.data));
+  return result ? toolResult(result) : undefined;
+}

package/src/modern/messages.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { object } from "../protocol/messages.js";
+import { metadata } from "./metadata.js";
+
+export const commonParams = z.looseObject({ _meta: metadata });
+export const listParams = commonParams.extend({
+  cursor: z.string().optional(),
+});
+export const callParams = commonParams.extend({
+  name: z.string(),
+  arguments: object.optional(),
+  requestState: z.string().optional(),
+  inputResponses: object.optional(),
+});

package/src/modern/metadata.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { icon } from "../protocol/icon.js";
+import { object } from "../protocol/messages.js";
+
+const capabilityObject = z.record(z.string(), z.json());
+const requestId = z.union([z.string(), z.number().finite()]);
+const capabilities = z.looseObject({
+  experimental: z.record(z.string(), capabilityObject).optional(),
+  roots: object.optional(),
+  sampling: z
+    .looseObject({
+      context: capabilityObject.optional(),
+      tools: capabilityObject.optional(),
+    })
+    .optional(),
+  elicitation: z
+    .looseObject({
+      form: capabilityObject.optional(),
+      url: capabilityObject.optional(),
+    })
+    .optional(),
+  extensions: z.record(z.string(), capabilityObject).optional(),
+});
+const implementation = z.looseObject({
+  name: z.string(),
+  version: z.string(),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  websiteUrl: z.string().optional(),
+  icons: z.array(icon).optional(),
+});
+export const metadata = z.looseObject({
+  "io.modelcontextprotocol/protocolVersion": z.string(),
+  "io.modelcontextprotocol/clientCapabilities": capabilities,
+  "io.modelcontextprotocol/clientInfo": implementation.optional(),
+  "io.modelcontextprotocol/logLevel": z
+    .enum([
+      "debug",
+      "info",
+      "notice",
+      "warning",
+      "error",
+      "critical",
+      "alert",
+      "emergency",
+    ])
+    .optional(),
+  progressToken: requestId.optional(),
+});

package/src/modern/responses.ts

@@ -0,0 +1,25 @@
+import type {
+  Implementation,
+  JSONRPCResultResponse,
+  RequestId,
+  Result,
+} from "@toolgrain/protocol";
+import { JSONRPC_VERSION } from "@toolgrain/protocol";
+
+export function successResponse(
+  id: RequestId,
+  result: Result,
+  identity: Implementation,
+): JSONRPCResultResponse {
+  return {
+    jsonrpc: JSONRPC_VERSION,
+    id,
+    result: {
+      ...result,
+      _meta: {
+        ...result._meta,
+        "io.modelcontextprotocol/serverInfo": { ...identity },
+      },
+    },
+  };
+}

package/src/modern/results.ts

@@ -0,0 +1,6 @@
+import type { CallToolResult } from "@toolgrain/protocol";
+import type { ToolExecutionResult } from "../tools/results.js";
+
+export function toolResult(result: ToolExecutionResult): CallToolResult {
+  return { resultType: "complete", ...result };
+}

package/src/pending-requests.ts

@@ -0,0 +1,30 @@
+import type { RequestId } from "@toolgrain/protocol";
+
+/** Owns duplicate detection and cancellation signals for in-flight requests. */
+export function createPendingRequests(isOpen: () => boolean) {
+  const pending = new Map<RequestId, AbortController>();
+  return {
+    begin(id: RequestId) {
+      if (pending.has(id)) return;
+      const controller = new AbortController();
+      pending.set(id, controller);
+      return {
+        signal: controller.signal,
+        isActive: () => isOpen() && !controller.signal.aborted,
+        finish: () => {
+          pending.delete(id);
+        },
+      };
+    },
+    cancel(id: RequestId) {
+      pending
+        .get(id)
+        ?.abort(new DOMException("Request cancelled by client", "AbortError"));
+    },
+    clear() {
+      for (const controller of pending.values())
+        controller.abort(new DOMException("Connection closed", "AbortError"));
+      pending.clear();
+    },
+  };
+}