@graphorin/mcp 0.6.1 → 0.7.0

package/src/helpers/identity.ts

@@ -0,0 +1,128 @@
+/**
+ * Helpers for deriving stable {@link ServerIdentity} records from the
+ * supplied {@link MCPTransportConfig}, plus the operator-facing
+ * formatter the audit emitter and the trace span attributes use.
+ *
+ * @packageDocumentation
+ */
+
+import { createHash } from 'node:crypto';
+
+import type {
+  MCPTransportConfig,
+  ServerIdentity,
+  SseTransportConfig,
+  StdioTransportConfig,
+  StreamableHttpTransportConfig,
+} from '../transport/types.js';
+
+/**
+ * Compute the canonical {@link ServerIdentity} for the supplied
+ * transport. The id is suitable for use as a registry key and as the
+ * operator-facing label in audit rows + trace attributes.
+ *
+ * W-016: the id derives ONLY from operator-controlled data (the
+ * transport config) plus the optional operator-supplied
+ * `serverInfoName` override. The name a server self-reports on
+ * `initialize` never participates: every security-relevant surface
+ * keys off this id (TOFU pins, `mcp:<id>:<uri>` handle scoping, taint
+ * labels, audit rows), and a server-controlled id let a rug-pull
+ * server mint a fresh TOFU record by renaming itself, or impersonate a
+ * trusted server's scope by claiming its name. HTTP-family ids include
+ * a non-default port, so localhost:3001 and localhost:3002 are
+ * distinct servers.
+ *
+ * @stable
+ */
+export function deriveServerIdentity(
+  transport: MCPTransportConfig,
+  serverInfoName?: string,
+): ServerIdentity {
+  switch (transport.kind) {
+    case 'stdio':
+      return deriveStdioIdentity(transport, serverInfoName);
+    case 'streamable-http':
+      return deriveStreamableHttpIdentity(transport, serverInfoName);
+    case 'sse':
+      return deriveSseIdentity(transport, serverInfoName);
+  }
+}
+
+function deriveStdioIdentity(
+  transport: StdioTransportConfig,
+  serverInfoName?: string,
+): ServerIdentity {
+  const argsHash = createHash('sha256')
+    .update((transport.args ?? []).join('\u0000'))
+    .digest('hex')
+    .slice(0, 16);
+  const command = basenameWithoutExt(transport.command);
+  const id = serverInfoName ?? `${command}-${argsHash}`;
+  return Object.freeze({
+    kind: 'mcp-stdio',
+    id,
+    command,
+    argsHash,
+    ...(serverInfoName === undefined ? {} : { serverInfoName }),
+  });
+}
+
+function deriveStreamableHttpIdentity(
+  transport: StreamableHttpTransportConfig,
+  serverInfoName?: string,
+): ServerIdentity {
+  const url = new URL(typeof transport.url === 'string' ? transport.url : transport.url.toString());
+  const urlHostname = url.hostname;
+  const urlPath = url.pathname.length === 0 ? '/' : url.pathname;
+  // W-016: `url.host` (hostname:port for non-default ports) - two local
+  // servers on different ports must not collide into one identity.
+  const id = serverInfoName ?? `${url.host}${urlPath}`;
+  return Object.freeze({
+    kind: 'mcp-streamable-http',
+    id,
+    urlHostname,
+    urlPath,
+    ...(serverInfoName === undefined ? {} : { serverInfoName }),
+  });
+}
+
+function deriveSseIdentity(transport: SseTransportConfig, serverInfoName?: string): ServerIdentity {
+  const url = new URL(typeof transport.url === 'string' ? transport.url : transport.url.toString());
+  const urlHostname = url.hostname;
+  const urlPath = url.pathname.length === 0 ? '/' : url.pathname;
+  // W-016: see deriveStreamableHttpIdentity - port-inclusive host.
+  const id = serverInfoName ?? `${url.host}${urlPath}`;
+  return Object.freeze({
+    kind: 'mcp-sse',
+    id,
+    urlHostname,
+    urlPath,
+    ...(serverInfoName === undefined ? {} : { serverInfoName }),
+  });
+}
+
+function basenameWithoutExt(command: string): string {
+  const slashIdx = Math.max(command.lastIndexOf('/'), command.lastIndexOf('\\'));
+  const base = slashIdx === -1 ? command : command.slice(slashIdx + 1);
+  const dotIdx = base.lastIndexOf('.');
+  return dotIdx <= 0 ? base : base.slice(0, dotIdx);
+}
+
+/**
+ * Operator-facing single-line label for a {@link MCPTransportConfig}.
+ * Suitable for trace attributes, audit rows, and CLI output.
+ *
+ * @stable
+ */
+export function formatMCPServerName(transport: MCPTransportConfig): string {
+  switch (transport.kind) {
+    case 'stdio':
+      return `stdio:${basenameWithoutExt(transport.command)}${
+        (transport.args ?? []).length === 0 ? '' : ` ${(transport.args ?? []).join(' ')}`
+      }`;
+    case 'streamable-http':
+      return `streamable-http:${typeof transport.url === 'string' ? transport.url : transport.url.toString()}`;
+    case 'sse':
+      return `sse:${typeof transport.url === 'string' ? transport.url : transport.url.toString()}`;
+  }
+}

package/src/helpers/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Helper utilities exposed by `@graphorin/mcp`.
+ *
+ * @packageDocumentation
+ */
+
+export { deriveServerIdentity, formatMCPServerName } from './identity.js';
+export { validateMCPServerConfig } from './validate-config.js';

package/src/helpers/validate-config.ts

@@ -0,0 +1,95 @@
+/**
+ * `validateMCPServerConfig(...)` - sanity-check a transport configuration
+ * before {@link createMCPClient} runs the network-level handshake.
+ *
+ * The validator catches the most common configuration mistakes
+ * (missing url for HTTP transports, empty command for stdio,
+ * unsupported `resumable: true` for stdio / sse, …) and surfaces them
+ * as {@link MCPInvalidConfigError} so the operator does not have to
+ * read a transport-specific stack trace.
+ *
+ * @packageDocumentation
+ */
+
+import { MCPInvalidConfigError, MCPTransportNotSupportedError } from '../errors/index.js';
+import type { MCPTransportConfig } from '../transport/types.js';
+
+/**
+ * Throws {@link MCPInvalidConfigError} on invalid configuration.
+ *
+ * @stable
+ */
+export function validateMCPServerConfig(opts: {
+  readonly transport: MCPTransportConfig;
+  readonly resumable?: boolean;
+}): void {
+  validateTransport(opts.transport);
+  if (opts.resumable === true) {
+    if (opts.transport.kind === 'stdio') {
+      throw new MCPTransportNotSupportedError(
+        'Resumable streaming sessions are not supported on the stdio transport.',
+        {
+          variant: 'transport-resumable-not-supported',
+          metadata: { transport: 'stdio' },
+          hint: 'Use the streamable-http transport when you need Mcp-Session-Id + Last-Event-ID resume semantics.',
+        },
+      );
+    }
+    if (opts.transport.kind === 'sse') {
+      throw new MCPTransportNotSupportedError(
+        'Resumable streaming sessions are not supported on the deprecated sse transport.',
+        {
+          variant: 'transport-resumable-not-supported',
+          metadata: { transport: 'sse' },
+          hint: 'Migrate to the streamable-http transport for resumable session support.',
+        },
+      );
+    }
+  }
+}
+
+function validateTransport(transport: MCPTransportConfig): void {
+  switch (transport.kind) {
+    case 'stdio': {
+      if (typeof transport.command !== 'string' || transport.command.length === 0) {
+        throw new MCPInvalidConfigError('stdio transport requires a non-empty `command`.', {
+          metadata: { transport: 'stdio' },
+        });
+      }
+      if (transport.args !== undefined && !Array.isArray(transport.args)) {
+        throw new MCPInvalidConfigError('stdio transport `args` must be an array of strings.', {
+          metadata: { transport: 'stdio' },
+        });
+      }
+      return;
+    }
+    case 'streamable-http':
+    case 'sse': {
+      if (transport.url === undefined || transport.url === null || transport.url === '') {
+        throw new MCPInvalidConfigError(
+          `${transport.kind} transport requires a non-empty \`url\`.`,
+          {
+            metadata: { transport: transport.kind },
+          },
+        );
+      }
+      try {
+        const candidate =
+          typeof transport.url === 'string' ? new URL(transport.url) : transport.url;
+        if (candidate.protocol !== 'http:' && candidate.protocol !== 'https:') {
+          throw new MCPInvalidConfigError(
+            `${transport.kind} transport \`url\` must use http: or https: (got ${candidate.protocol}).`,
+            { metadata: { transport: transport.kind } },
+          );
+        }
+      } catch (cause) {
+        if (cause instanceof MCPInvalidConfigError) throw cause;
+        throw new MCPInvalidConfigError(`${transport.kind} transport \`url\` is not a valid URL.`, {
+          metadata: { transport: transport.kind },
+          cause,
+        });
+      }
+      return;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * `@graphorin/mcp` - Model Context Protocol client for the Graphorin
+ * framework.
+ *
+ * The package owns:
+ *
+ * - The {@link createMCPClient} factory that opens a typed MCP
+ *   connection over stdio, Streamable HTTP, or the deprecated SSE
+ *   transport.
+ * - The {@link MCPClient} surface (`listTools` / `listResources` /
+ *   `listPrompts` / `callTool` / `readResource` / `getPrompt` /
+ *   `close`) plus the strategy-aware {@link MCPClient.toTools}
+ *   adapter that bridges MCP tool descriptors into Graphorin
+ *   `Tool` records.
+ * - The OAuth bridge that resolves bearer headers from the
+ *   {@link OAuthAuthorizationProvider} backed by
+ *   `@graphorin/security/oauth`.
+ * - Library helpers (`mcpAuthLogin`, `mcpAuthListSessions`,
+ *   `mcpAuthRefresh`, `mcpAuthRevoke`, `mcpAuthStatus`) consumed by
+ *   the upcoming `graphorin auth` CLI surface.
+ * - Typed errors ({@link MCPConnectionError},
+ *   {@link MCPProtocolError}, {@link MCPAuthError},
+ *   {@link MCPToolNotFoundError}, {@link MCPCallTimeoutError},
+ *   {@link MCPCancelledError}, {@link MCPInvalidConfigError},
+ *   {@link MCPTransportNotSupportedError}, {@link GraphorinMCPError}).
+ *
+ * Stable sub-paths:
+ *
+ * ```ts
+ * import { createMCPClient } from '@graphorin/mcp/client';
+ * import { createOAuthAuthorizationProvider } from '@graphorin/mcp/oauth';
+ * import { formatMCPServerName, validateMCPServerConfig } from '@graphorin/mcp/helpers';
+ * import { MCPConnectionError } from '@graphorin/mcp/errors';
+ * import type { MCPTransportConfig, ServerIdentity } from '@graphorin/mcp/transport';
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** Canonical version constant, derived from `package.json` at build time. */
+import pkg from '../package.json' with { type: 'json' };
+
+export const VERSION: string = pkg.version;
+
+export * from './client/index.js';
+export * from './errors/index.js';
+export * from './helpers/index.js';
+export * from './oauth/index.js';
+export * from './transport/index.js';

package/src/oauth/bridge.ts

@@ -0,0 +1,143 @@
+/**
+ * Bridge between the MCP transport's bearer-token requirement and the
+ * outbound OAuth subsystem in `@graphorin/security/oauth`.
+ *
+ * The bridge resolves an authorization header from a stored
+ * {@link OAuthSession}, refreshes the token automatically when it is
+ * within the configured pre-expiry window, and surfaces every
+ * lifecycle transition (`oauth.granted` / `oauth.refreshed` /
+ * `oauth.revoked` / `mcp.auth.expired`) to subscribers.
+ *
+ * @packageDocumentation
+ */
+
+import type { OAuthServerStore } from '@graphorin/core/contracts';
+import type { OAuthSession } from '@graphorin/security/oauth';
+import {
+  emitOAuthLifecycle,
+  GraphorinOAuthError,
+  refreshOAuthSession,
+} from '@graphorin/security/oauth';
+
+import { MCPAuthError } from '../errors/index.js';
+
+/** Options accepted by {@link createOAuthAuthorizationProvider}. */
+export interface OAuthAuthorizationProviderOptions {
+  /**
+   * Secrets store the persisted tokens resolve from (SPL-1) - with it,
+   * the bridge issues Authorization headers across process restarts.
+   */
+  readonly secretsStore?: import('@graphorin/core/contracts').SecretsStore;
+  /** Stable identifier of the persisted OAuth server (`serverId`). */
+  readonly serverId: string;
+  /** Persistent storage. */
+  readonly storage: OAuthServerStore;
+  /**
+   * Time-to-refresh window in milliseconds. When the session is
+   * within `refreshAheadMs` of expiry the provider triggers a
+   * refresh on the next request. Defaults to 5 minutes.
+   */
+  readonly refreshAheadMs?: number;
+  /** Optional per-request `AbortSignal` (forwarded to refresh). */
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Live authorization-header provider returned by
+ * {@link createOAuthAuthorizationProvider}.
+ *
+ * @stable
+ */
+export interface OAuthAuthorizationProvider {
+  /** Resolve an `Authorization: Bearer ...` header. */
+  resolveHeader(): Promise<string>;
+  /** Force a refresh, regardless of expiry. */
+  refresh(): Promise<OAuthSession>;
+  /** Persist the most recently observed expiry timestamp. */
+  readonly serverId: string;
+}
+
+/**
+ * Build a provider that resolves the `Authorization` header value the
+ * Streamable HTTP / SSE MCP transports send on every request.
+ *
+ * The provider:
+ *
+ * 1. Loads the persisted session metadata from the supplied store.
+ * 2. Refreshes the session when it is within `refreshAheadMs` of
+ *    expiry.
+ * 3. Wraps every refresh failure in {@link MCPAuthError} carrying a
+ *    `hint` that points the operator to the upcoming
+ *    `graphorin auth refresh` CLI.
+ *
+ * @stable
+ */
+export function createOAuthAuthorizationProvider(
+  options: OAuthAuthorizationProviderOptions,
+): OAuthAuthorizationProvider {
+  const refreshAheadMs = options.refreshAheadMs ?? 5 * 60_000;
+  let activeSession: OAuthSession | undefined;
+
+  async function loadOrRefresh(force: boolean): Promise<OAuthSession> {
+    const record = await options.storage.get(options.serverId);
+    if (record === null) {
+      throw new MCPAuthError(`OAuth server '${options.serverId}' is not registered.`, {
+        hint: `run 'graphorin auth login --mcp ${options.serverId} --url <server-url>' to register the OAuth server.`,
+        metadata: { server: options.serverId },
+      });
+    }
+    const expiresAt = record.expiresAt;
+    const now = Date.now();
+    const stale =
+      force ||
+      activeSession === undefined ||
+      (expiresAt !== undefined && expiresAt - now < refreshAheadMs);
+    if (!stale && activeSession !== undefined) return activeSession;
+    try {
+      const session = await refreshOAuthSession(options.storage, options.serverId, {
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ...(options.secretsStore === undefined ? {} : { secretsStore: options.secretsStore }),
+      });
+      activeSession = session;
+      return session;
+    } catch (cause) {
+      if (cause instanceof GraphorinOAuthError) {
+        emitOAuthLifecycle({
+          type: 'mcp.auth.expired',
+          serverId: options.serverId,
+          ts: Date.now(),
+          reason: cause.kind,
+          metadata: { serverUrl: record.serverUrl },
+        });
+        throw new MCPAuthError(
+          `MCP OAuth session for '${options.serverId}' could not be refreshed: ${cause.message}`,
+          {
+            hint: `run 'graphorin auth refresh --mcp ${options.serverId}' to recover.`,
+            metadata: { server: options.serverId },
+            cause,
+          },
+        );
+      }
+      throw new MCPAuthError(
+        `MCP OAuth session for '${options.serverId}' could not be refreshed.`,
+        {
+          hint: `run 'graphorin auth refresh --mcp ${options.serverId}' to recover.`,
+          metadata: { server: options.serverId },
+          cause,
+        },
+      );
+    }
+  }
+
+  return Object.freeze({
+    serverId: options.serverId,
+    async resolveHeader(): Promise<string> {
+      const session = await loadOrRefresh(false);
+      const tokenType = session.tokenType.length === 0 ? 'Bearer' : session.tokenType;
+      return session.accessToken.use((raw) => `${tokenType} ${raw}`);
+    },
+    async refresh(): Promise<OAuthSession> {
+      return loadOrRefresh(true);
+    },
+  });
+}

package/src/oauth/index.ts

@@ -0,0 +1,18 @@
+/**
+ * OAuth integration surface for `@graphorin/mcp`.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  createOAuthAuthorizationProvider,
+  type OAuthAuthorizationProvider,
+  type OAuthAuthorizationProviderOptions,
+} from './bridge.js';
+export {
+  mcpAuthListSessions,
+  mcpAuthLogin,
+  mcpAuthRefresh,
+  mcpAuthRevoke,
+  mcpAuthStatus,
+} from './library.js';

package/src/oauth/library.ts

@@ -0,0 +1,61 @@
+/**
+ * Thin re-export wrappers for the OAuth library functions consumed by
+ * the upcoming `graphorin auth login | list | refresh | revoke |
+ * status` CLI surface (Phase 15). The wrappers attach an
+ * `mcpServerId` audit tag so downstream observers can attribute
+ * events to the MCP subsystem rather than to a generic OAuth call
+ * site.
+ *
+ * @packageDocumentation
+ */
+
+import type { OAuthServerStore } from '@graphorin/core/contracts';
+import {
+  getOAuthStatus,
+  type LoginInteractiveOptions,
+  type LoginInteractiveResult,
+  listOAuthSessions,
+  loginInteractive,
+  type OAuthSession,
+  type OAuthSessionMetadata,
+  type OAuthStatusSnapshot,
+  refreshOAuthSession,
+  revokeOAuthSession,
+} from '@graphorin/security/oauth';
+
+/** Drive `graphorin auth login --mcp <id>`. */
+export async function mcpAuthLogin(
+  options: LoginInteractiveOptions,
+): Promise<LoginInteractiveResult> {
+  return loginInteractive(options);
+}
+
+/** Drive `graphorin auth list --mcp`. */
+export async function mcpAuthListSessions(
+  storage: OAuthServerStore,
+): Promise<ReadonlyArray<OAuthSessionMetadata>> {
+  return listOAuthSessions(storage);
+}
+
+/** Drive `graphorin auth refresh --mcp <id>`. */
+export async function mcpAuthRefresh(
+  storage: OAuthServerStore,
+  serverId: string,
+  options: { readonly signal?: AbortSignal } = {},
+): Promise<OAuthSession> {
+  return refreshOAuthSession(storage, serverId, options);
+}
+
+/** Drive `graphorin auth revoke --mcp <id>`. */
+export async function mcpAuthRevoke(
+  storage: OAuthServerStore,
+  serverId: string,
+  options: { readonly reason?: string; readonly signal?: AbortSignal } = {},
+): Promise<void> {
+  await revokeOAuthSession(storage, serverId, options);
+}
+
+/** Drive `graphorin auth status --mcp`. */
+export async function mcpAuthStatus(storage: OAuthServerStore): Promise<OAuthStatusSnapshot> {
+  return getOAuthStatus(storage);
+}