@toolgrain/mcp 0.0.0-stage → 0.1.0

package/src/auth/errors.ts

@@ -0,0 +1,35 @@
+export type AuthErrorCode =
+  | "invalid_request"
+  | "invalid_token"
+  | "access_denied"
+  | "temporarily_unavailable";
+
+const brand = Symbol.for("@toolgrain/mcp/AuthError/v1");
+
+/** Only an explicitly public description is exposed; provider causes stay private. */
+export class AuthError extends Error {
+  readonly [brand] = true;
+  readonly description?: string | undefined;
+
+  constructor(
+    readonly code: AuthErrorCode,
+    options?: ErrorOptions & { description?: string },
+  ) {
+    super(
+      options?.description ??
+        {
+          invalid_request: "Invalid authorization request",
+          invalid_token: "Invalid access token",
+          access_denied: "Access denied",
+          temporarily_unavailable: "Authorization service unavailable",
+        }[code],
+      options,
+    );
+    this.name = "AuthError";
+    this.description = options?.description;
+  }
+}
+
+export function isAuthError(value: unknown): value is AuthError {
+  return value instanceof Error && Reflect.get(value, brand) === true;
+}

package/src/auth/types.ts

@@ -0,0 +1,34 @@
+/** Implemented by integrations; the HTTP adapter supplies the resolved resource. */
+export interface AuthProvider<Identity extends object = object> {
+  readonly type: symbol;
+  readonly resource?: string;
+  readonly authorizationServers: readonly string[];
+  verify(accessToken: string, options: AuthVerifyOptions): Promise<Identity>;
+}
+
+export interface AuthVerifyOptions {
+  readonly signal: AbortSignal;
+  readonly resource: string;
+}
+
+export interface AuthMetadata {
+  readonly resource?: string;
+  readonly authorizationServers: readonly string[];
+}
+
+/** An opaque, single-use authorization for one server invocation. Always dispose it. */
+export interface AuthScope {
+  readonly signal: AbortSignal;
+  dispose(): void;
+}
+
+export type AuthReadonly<T> = T extends readonly (infer Item)[]
+  ? readonly AuthReadonly<Item>[]
+  : T extends object
+    ? { readonly [Key in keyof T]: AuthReadonly<T[Key]> }
+    : T;
+
+export interface AuthIdentity {
+  readonly type: symbol;
+  readonly value: object;
+}

package/src/auth/url.ts

@@ -0,0 +1,22 @@
+/** Canonical external URL; HTTP is permitted only for local development. */
+export function authUrl(value: string): string {
+  const url = new URL(value);
+  if (
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: Reject control characters that URL parsing would silently remove.
+    /[\u0000-\u0020\u007f]/.test(value) ||
+    !/^https?:\/\/[^/]/i.test(value) ||
+    (url.protocol !== "https:" &&
+      !(
+        url.protocol === "http:" &&
+        ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)
+      )) ||
+    url.username ||
+    url.password ||
+    value.includes("#") ||
+    value.includes("?")
+  )
+    throw new TypeError(
+      "Auth URLs must use HTTPS without credentials, query, or fragment (HTTP loopback is allowed)",
+    );
+  return value;
+}

package/src/connection.ts

@@ -0,0 +1,207 @@
+import {
+  INVALID_REQUEST,
+  PARSE_ERROR,
+  type ProtocolResponse,
+} from "@toolgrain/protocol";
+import { type ErrorHandler, reportError } from "./diagnostics.js";
+import type { Dispatcher } from "./dispatcher.js";
+import { executeRequest } from "./execute-request.js";
+import { createLegacyConnection } from "./legacy/connection.js";
+import { createPendingRequests } from "./pending-requests.js";
+import { decode } from "./protocol/decode.js";
+import type { Request } from "./protocol/messages.js";
+import { protocolError } from "./protocol/responses.js";
+import type { Server } from "./server.js";
+import type {
+  RequestTransport,
+  Transport,
+  TransportCallbacks,
+} from "./transport.js";
+import { claimTransport } from "./transport-ownership.js";
+
+export function createConnection(
+  dispatch: Dispatcher,
+  onError?: ErrorHandler,
+  onClose?: () => void,
+): ConnectionLifecycle {
+  return new Connection(dispatch, onError, onClose);
+}
+
+interface ConnectionLifecycle {
+  listen(transport: Transport): Promise<void>;
+  listenRequests(transport: RequestTransport, server: Server): Promise<void>;
+  close(): Promise<void>;
+}
+
+/** Owns transport attachment, serialized writes, and connection shutdown. */
+class Connection implements ConnectionLifecycle {
+  private state: "idle" | "starting" | "listening" | "closed" = "idle";
+  private transport: Transport | RequestTransport | undefined;
+  private closePromise: Promise<void> | undefined;
+  private writes = Promise.resolve();
+  private readonly requests = createPendingRequests(() => this.isOpen());
+  private readonly legacy = createLegacyConnection();
+
+  constructor(
+    private readonly dispatch: Dispatcher,
+    private readonly onError?: ErrorHandler,
+    private readonly onClose?: () => void,
+  ) {}
+
+  // Public methods remain safe to call detached from the returned server.
+  readonly listen = (transport: Transport): Promise<void> =>
+    this.attach(transport, () => transport.start(this.transportCallbacks));
+
+  readonly listenRequests = (
+    transport: RequestTransport,
+    server: Server,
+  ): Promise<void> =>
+    this.attach(transport, () =>
+      transport.start(server, {
+        onError: this.transportCallbacks.onError,
+        onClose: this.transportCallbacks.onClose,
+      }),
+    );
+
+  private readonly attach = async (
+    transport: Transport | RequestTransport,
+    start: () => Promise<void>,
+  ): Promise<void> => {
+    if (this.state !== "idle")
+      throw new Error(
+        "Server can only attach one transport and cannot restart after closing",
+      );
+    claimTransport(transport);
+    this.state = "starting";
+    this.transport = transport;
+    try {
+      await start();
+      if (!this.isOpen()) throw new Error("Transport closed during startup");
+      this.state = "listening";
+    } catch (error) {
+      await this.terminate(error);
+      throw error;
+    }
+  };
+
+  readonly close = (): Promise<void> => {
+    if (this.closePromise) return this.closePromise;
+    this.state = "closed";
+    this.closePromise = Promise.resolve().then(async () => {
+      const transport = this.transport;
+      this.transport = undefined;
+      await transport?.close();
+    });
+    // Aborting runs handler listeners synchronously; a nested close reuses this promise.
+    this.onClose?.();
+    this.requests.clear();
+    return this.closePromise;
+  };
+
+  private readonly transportCallbacks: TransportCallbacks = {
+    onMessage: (message) => {
+      void this.receive(message).catch((error) => this.terminate(error));
+    },
+    onParseError: () => {
+      if (this.isOpen())
+        void this.send(
+          this.legacy.errorResponse(protocolError(PARSE_ERROR, "Parse error")),
+        );
+    },
+    onError: (error) => {
+      void this.terminate(error);
+    },
+    onClose: () => {
+      void this.close().catch((error) => this.report(error));
+    },
+  };
+
+  private isOpen(): boolean {
+    return this.state === "starting" || this.state === "listening";
+  }
+
+  private report(error: unknown): void {
+    reportError(this.onError, error);
+  }
+
+  private async terminate(error: unknown): Promise<void> {
+    this.report(error);
+    try {
+      await this.close();
+    } catch (failure) {
+      this.report(failure);
+    }
+  }
+
+  private send(
+    message: ProtocolResponse,
+    isActive: () => boolean = () => this.isOpen(),
+  ): Promise<void> {
+    const write = this.writes.then(async () => {
+      if (
+        this.isOpen() &&
+        isActive() &&
+        this.transport &&
+        "send" in this.transport
+      )
+        await this.transport.send(message);
+    });
+    this.writes = write.catch((error) => this.terminate(error));
+    return this.writes;
+  }
+
+  private async receive(message: unknown): Promise<void> {
+    if (!this.isOpen()) return;
+    const incoming = decode(message);
+    switch (incoming.kind) {
+      case "ignore":
+        return;
+      case "cancel":
+        if (this.legacy.canCancel(incoming.id))
+          this.requests.cancel(incoming.id);
+        return;
+      case "notification":
+        this.legacy.notification(incoming.notification);
+        return;
+      case "error":
+        await this.send(this.legacy.errorResponse(incoming.response));
+        return;
+      case "request":
+        await this.handleRequest(incoming.request);
+    }
+  }
+
+  private async handleRequest(request: Request): Promise<void> {
+    const prepared = this.legacy.prepare(request);
+    if (prepared.error) {
+      await this.send(prepared.error);
+      return;
+    }
+    const pending = this.requests.begin(request.id);
+    if (!pending) {
+      await this.send(
+        protocolError(
+          INVALID_REQUEST,
+          "Request ID is already in use",
+          request.id,
+        ),
+      );
+      return;
+    }
+    const initialization = this.legacy.begin(request, prepared.protocolVersion);
+    try {
+      const response = await executeRequest(
+        this.dispatch,
+        request,
+        { signal: pending.signal, client: this.legacy.client() },
+        (error) => this.report(error),
+        prepared.protocolVersion,
+      );
+      initialization?.respond(response);
+      if (response) await this.send(response, pending.isActive);
+    } finally {
+      initialization?.finish();
+      pending.finish();
+    }
+  }
+}

package/src/context/access.ts

@@ -0,0 +1,36 @@
+import type { ToolContext } from "../tools/context.js";
+
+const key = Symbol.for("@toolgrain/mcp/context-access/v1");
+type Access = (identity: symbol, name: string) => Promise<unknown>;
+
+/** Keep own auth properties and shared request data on dependency-aware views. */
+export function withContextAccess(
+  ctx: ToolContext,
+  access: Access,
+): ToolContext {
+  return Object.freeze(
+    Object.create(Object.getPrototypeOf(ctx), {
+      ...Object.getOwnPropertyDescriptors(ctx),
+      [key]: { value: access },
+    }) as ToolContext,
+  );
+}
+
+export function readContext<Value>(
+  ctx: ToolContext,
+  identity: symbol,
+  name: string,
+): Promise<Value> {
+  try {
+    const access = Object.getOwnPropertyDescriptor(ctx, key)?.value as
+      | Access
+      | undefined;
+    if (!access)
+      throw new Error("Context access requires a Toolgrain-created context");
+    ctx.signal.throwIfAborted();
+    return access(identity, name) as Promise<Value>;
+  } catch (error) {
+    // Accessors always return promises, including invalid contexts and aborts.
+    return Promise.reject(error);
+  }
+}

package/src/context/definition.ts

@@ -0,0 +1,100 @@
+import type { ToolContext } from "../tools/context.js";
+import { readContext } from "./access.js";
+
+const brand = Symbol.for("@toolgrain/mcp/context-provider/v1");
+const bindingKey = Symbol.for("@toolgrain/mcp/context-binding/v1");
+
+export interface ContextBinding {
+  readonly identity: symbol;
+  readonly name: string;
+  readonly resolve: (ctx: ToolContext) => unknown;
+}
+
+/** Erase values for heterogeneous registrations without exposing unsafe overrides. */
+export abstract class RegisteredContextProvider {
+  abstract readonly name: string;
+  abstract readonly use: (ctx: ToolContext) => Promise<unknown>;
+
+  // Structural branding keeps compatible package copies interoperable.
+  "~toolgrain"(): "context@1" {
+    return "context@1";
+  }
+}
+Object.defineProperty(RegisteredContextProvider.prototype, brand, {
+  value: true,
+});
+
+/** An opaque, invariant value contract; use createContext() and provide() for bindings. */
+export abstract class ContextProvider<Value> extends RegisteredContextProvider {
+  abstract readonly use: (ctx: ToolContext) => Promise<Value>;
+  // A function property prevents widening Value and then overriding it incompatibly.
+  abstract readonly provide: (
+    resolve: (ctx: ToolContext) => Value | PromiseLike<Value>,
+  ) => ContextProvider<Value>;
+}
+
+class Provider<Value> extends ContextProvider<Value> {
+  readonly name: string;
+  readonly use: (ctx: ToolContext) => Promise<Value>;
+
+  constructor(
+    binding: ContextBinding,
+    use = (ctx: ToolContext) =>
+      readContext<Value>(ctx, binding.identity, binding.name),
+  ) {
+    super();
+    this.name = binding.name;
+    this.use = use;
+    Object.defineProperty(this, bindingKey, { value: Object.freeze(binding) });
+    Object.freeze(this);
+  }
+
+  readonly provide = (
+    resolve: (ctx: ToolContext) => Value | PromiseLike<Value>,
+  ): ContextProvider<Value> => {
+    if (typeof resolve !== "function")
+      throw new TypeError(
+        "Context provider overrides require a resolver function",
+      );
+    return new Provider<Value>({ ...contextBinding(this), resolve }, this.use);
+  };
+}
+
+/** Infer the resolved value type, including asynchronous factories. */
+export function createContext<Value>(options: {
+  name: string;
+  resolve: (ctx: ToolContext) => Value;
+}): ContextProvider<Awaited<Value>> {
+  if (
+    !options ||
+    typeof options.name !== "string" ||
+    !options.name.trim() ||
+    typeof options.resolve !== "function"
+  )
+    throw new TypeError(
+      "Context providers require a nonempty name and a resolver function",
+    );
+  return new Provider<Awaited<Value>>({
+    identity: Symbol(options.name),
+    name: options.name,
+    resolve: options.resolve,
+  });
+}
+
+export function contextBinding(provider: unknown): ContextBinding {
+  if (
+    typeof provider !== "object" ||
+    provider === null ||
+    (provider as { [brand]?: unknown })[brand] !== true
+  )
+    throw new TypeError(
+      "Context providers must be created with createContext()",
+    );
+  const binding = Object.getOwnPropertyDescriptor(provider, bindingKey)
+    ?.value as ContextBinding | undefined;
+  if (!binding)
+    throw new TypeError(
+      "Context providers must be created with createContext()",
+    );
+  return binding;
+}

package/src/context/registry.ts

@@ -0,0 +1,25 @@
+import {
+  type ContextBinding,
+  contextBinding,
+  type RegisteredContextProvider,
+} from "./definition.js";
+
+export type ContextRegistry = ReadonlyMap<symbol, ContextBinding>;
+
+/** Snapshot definitions once; provider names are labels, not registration keys. */
+export function createContextRegistry(
+  providers: readonly RegisteredContextProvider[] = [],
+): ContextRegistry {
+  if (!Array.isArray(providers))
+    throw new TypeError("Context registration must be an array of providers");
+  const registry = new Map<symbol, ContextBinding>();
+  for (const provider of providers) {
+    const binding = contextBinding(provider);
+    if (registry.has(binding.identity))
+      throw new TypeError(
+        `Context provider ${JSON.stringify(binding.name)} is registered more than once`,
+      );
+    registry.set(binding.identity, binding);
+  }
+  return registry;
+}

package/src/context/scope.ts

@@ -0,0 +1,82 @@
+import type { ToolContext } from "../tools/context.js";
+import { withContextAccess } from "./access.js";
+import type { ContextRegistry } from "./registry.js";
+
+interface Resolution {
+  readonly name: string;
+  readonly promise: Promise<unknown>;
+  readonly dependencies: Set<Resolution>;
+  pending: boolean;
+}
+
+/** One cache and pending dependency graph per tool context, independent of request IDs. */
+export function createContextScope(
+  ctx: ToolContext,
+  registry: ContextRegistry,
+): ToolContext {
+  const resolutions = new Map<symbol, Resolution>();
+  const resolve = (
+    identity: symbol,
+    name: string,
+    caller?: Resolution,
+  ): Promise<unknown> => {
+    const binding = registry.get(identity);
+    if (!binding)
+      throw new Error(
+        `Context provider ${JSON.stringify(name)} is not registered`,
+      );
+    let resolution = resolutions.get(identity);
+    if (!resolution) {
+      const current: Resolution = {
+        name: binding.name,
+        pending: true,
+        dependencies: new Set(),
+        // Publish the promise before running user code, including synchronous factories.
+        promise: Promise.resolve()
+          .then(() => {
+            ctx.signal.throwIfAborted();
+            return binding.resolve(
+              withContextAccess(ctx, (key, label) =>
+                resolve(key, label, current),
+              ),
+            );
+          })
+          .then((value) => {
+            ctx.signal.throwIfAborted();
+            return value;
+          })
+          .finally(() => {
+            current.pending = false;
+            current.dependencies.clear();
+          }),
+      };
+      resolutions.set(identity, current);
+      resolution = current;
+    }
+    if (caller?.pending && resolution.pending) {
+      const path = dependencyPath(resolution, caller, new Set());
+      if (path)
+        throw new Error(
+          `Context dependency cycle: ${[caller, ...path].map((item) => item.name).join(" -> ")}`,
+        );
+      caller.dependencies.add(resolution);
+    }
+    return resolution.promise;
+  };
+  return withContextAccess(ctx, (identity, name) => resolve(identity, name));
+}
+
+/** Follow only unfinished resolutions; shared pending dependencies are not cycles. */
+function dependencyPath(
+  from: Resolution,
+  target: Resolution,
+  visited: Set<Resolution>,
+): Resolution[] | undefined {
+  if (from === target) return [from];
+  if (!from.pending || visited.has(from)) return;
+  visited.add(from);
+  for (const dependency of from.dependencies) {
+    const path = dependencyPath(dependency, target, visited);
+    if (path) return [from, ...path];
+  }
+}

package/src/diagnostics.ts

@@ -0,0 +1,25 @@
+import type { ToolRequest } from "./tools/context.js";
+
+/** Private diagnostics for an unexpected tool failure; no arguments or auth data are added. */
+export interface ToolErrorDetails {
+  readonly toolName: string;
+  readonly request: ToolRequest;
+}
+
+export type ErrorHandler = (error: unknown, details?: ToolErrorDetails) => void;
+
+/** Diagnostics cannot interrupt a response or cleanup, including rejected async callbacks. */
+export function reportError(
+  onError: ErrorHandler | undefined,
+  error: unknown,
+  details?: ToolErrorDetails,
+): void {
+  if (!onError) return;
+  try {
+    const result =
+      details === undefined ? onError(error) : onError(error, details);
+    void Promise.resolve(result).catch(() => {});
+  } catch {
+    /* Diagnostics must not replace the original failure. */
+  }
+}

package/src/dispatcher.ts

@@ -0,0 +1,70 @@
+import {
+  type Implementation,
+  type JSONRPCErrorResponse,
+  LEGACY_PROTOCOL_VERSION,
+  type ProtocolResponse,
+  type SupportedProtocolVersion,
+} from "@toolgrain/protocol";
+import type { AuthIdentity } from "./auth/types.js";
+import type { ContextRegistry } from "./context/registry.js";
+import {
+  createLegacyDispatcher,
+  usesLegacyProtocol,
+} from "./legacy/dispatcher.js";
+import { errorResponse as legacyErrorResponse } from "./legacy/responses.js";
+import { createModernDispatcher } from "./modern/dispatcher.js";
+import type { Request } from "./protocol/messages.js";
+import { validateVersionContext } from "./protocol/version-metadata.js";
+import type { ToolAdapter } from "./tools/adapter.js";
+import type { ToolClient } from "./tools/context.js";
+
+/** Per-request execution state supplied by the connection or independent caller. */
+export interface RequestScope {
+  signal: AbortSignal;
+  /** Client details negotiated by legacy initialization, when the connection has them. */
+  client?: ToolClient | undefined;
+  auth?: AuthIdentity;
+}
+
+export type Dispatcher = (
+  request: Request,
+  scope: RequestScope,
+  protocolVersion?: SupportedProtocolVersion,
+) => Promise<ProtocolResponse | undefined>;
+
+/** Compose the two protocol adapters around one execution registry. */
+export function createDispatcher(
+  tools: ToolAdapter,
+  identity: Implementation,
+  instructions?: string,
+  providers?: ContextRegistry,
+): Dispatcher {
+  const legacy = createLegacyDispatcher(
+    tools,
+    identity,
+    instructions,
+    providers,
+  );
+  const modern = createModernDispatcher(
+    tools,
+    identity,
+    instructions,
+    providers,
+  );
+  return (request, scope, protocolVersion) => {
+    validateVersionContext(request, protocolVersion);
+    return usesLegacyProtocol(request, protocolVersion)
+      ? legacy(request, scope)
+      : modern(request, scope);
+  };
+}
+
+/** Envelope errors have no negotiated connection when processing independent calls. */
+export function formatErrorResponse(
+  response: JSONRPCErrorResponse,
+  protocolVersion?: SupportedProtocolVersion,
+): ProtocolResponse {
+  return protocolVersion === LEGACY_PROTOCOL_VERSION
+    ? legacyErrorResponse(response)
+    : response;
+}

package/src/execute-request.ts

@@ -0,0 +1,35 @@
+import {
+  INTERNAL_ERROR,
+  type ProtocolResponse,
+  type SupportedProtocolVersion,
+} from "@toolgrain/protocol";
+import { type ErrorHandler, reportError } from "./diagnostics.js";
+import type { Dispatcher, RequestScope } from "./dispatcher.js";
+import type { Request } from "./protocol/messages.js";
+import { ProtocolError, protocolError } from "./protocol/responses.js";
+
+/** Shared dispatch boundary for connection-scoped and independent requests. */
+export async function executeRequest(
+  dispatch: Dispatcher,
+  request: Request,
+  scope: RequestScope,
+  onError?: ErrorHandler,
+  protocolVersion?: SupportedProtocolVersion,
+): Promise<ProtocolResponse | undefined> {
+  const isActive = () => !scope.signal.aborted;
+  try {
+    const response = await dispatch(request, scope, protocolVersion);
+    return isActive() ? response : undefined;
+  } catch (error) {
+    if (!isActive()) return;
+    if (error instanceof ProtocolError)
+      return protocolError(error.code, error.message, request.id, error.data);
+    reportError(onError, error);
+    return protocolError(
+      INTERNAL_ERROR,
+      "Internal error",
+      request.id,
+      undefined,
+    );
+  }
+}