@pi-archimedes/mcp 2.3.0

package/src/oauth-provider.ts

@@ -0,0 +1,197 @@
+/**
+ * MCP SDK OAuth client provider for the archimedes mcp package.
+ *
+ * Bridges the SDK's `auth()` driver (see
+ * `@modelcontextprotocol/sdk/client/auth.js` — `OAuthClientProvider`) to
+ * archimedes' keyring-based credential storage and local callback server:
+ *
+ * - tokens and client info persist in the OS credential store via
+ *   {@link getAuthEntry}/{@link saveAuthEntry} (one `AuthEntry` per server);
+ * - interactive browser flows arrive via `onAuthorizationUrl` so the host
+ *   decides how the user is taken to the authorization page;
+ * - `client_credentials` is a non-interactive grant: no redirect URL, no
+ *   PKCE state (an empty `state()` is intentional — the flow never uses it).
+ *
+ * Storage shapes (`StoredTokens`/`StoredClientInfo`) are mapped to/from the
+ * SDK's wire shapes (`OAuthTokens`/`OAuthClientInformationMixed`) at this
+ * boundary only — the keyring never holds SDK wire shapes.
+ */
+
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type {
+  OAuthClientInformationMixed,
+  OAuthClientMetadata,
+  OAuthTokens,
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+
+import { getAuthEntry, saveAuthEntry } from "./auth-storage.js";
+import { getCallbackPath, getCallbackPort } from "./callback-server.js";
+import type { McpOAuthConfig } from "./types.js";
+
+/** Optional hooks so the host can observe or drive the interactive parts of the flow. */
+export interface OAuthCallbacks {
+  /** Called once when the SDK builds the authorization URL. */
+  onAuthorizationUrl?: (url: URL) => void | Promise<void>;
+}
+
+/**
+ * `OAuthClientProvider` backed by the per-server `AuthEntry` in the OS
+ * credential store. Constructor arguments identify the server (`serverName`
+ * is the storage key, `serverUrl` keeps `entry.serverUrl` in sync) and the
+ * optional `csrfState` is the state the callback validation will expect.
+ * `callbackPort` (interactive authorization_code flows only) is the actual
+ * port the callback server bound to — it pins the advertised redirect URL to
+ * the listening server when `config.redirectUri` is absent (dynamic clients
+ * bind an OS-assigned port, not the `MCP_OAUTH_CALLBACK_PORT` default).
+ */
+export class McpOAuthProvider implements OAuthClientProvider {
+  constructor(
+    private serverName: string,
+    private serverUrl: string,
+    private config: McpOAuthConfig,
+    private callbacks: OAuthCallbacks,
+    private csrfState?: string,
+    private callbackPort?: number,
+  ) {}
+
+  /** Current time in unix seconds (floored) — used for expires_in ↔ expiresAt math. */
+  private get nowSeconds(): number {
+    return Math.floor(Date.now() / 1000);
+  }
+
+  private get usesClientCredentials(): boolean {
+    return this.config.grantType === "client_credentials";
+  }
+
+  private get clientName(): string {
+    return this.config.clientName ?? this.serverName;
+  }
+
+  /** Loopback callback URL for interactive flows; undefined for client_credentials. */
+  get redirectUrl(): string | URL | undefined {
+    if (this.usesClientCredentials) return undefined;
+    return (
+      this.config.redirectUri ??
+      `http://localhost:${this.callbackPort ?? getCallbackPort()}${getCallbackPath()}`
+    );
+  }
+
+  /** DCR / well-known metadata, per grant type. */
+  get clientMetadata(): OAuthClientMetadata {
+    const authMethod = this.config.clientSecret ? "client_secret_post" : "none";
+
+    if (this.usesClientCredentials) {
+      return {
+        redirect_uris: [],
+        client_name: this.clientName,
+        grant_types: ["client_credentials"],
+        token_endpoint_auth_method: authMethod,
+      };
+    }
+
+    const redirectUrl = this.redirectUrl;
+    if (redirectUrl === undefined) {
+      throw new Error("redirectUrl is required for the authorization_code flow");
+    }
+    return {
+      redirect_uris: [String(redirectUrl)],
+      client_name: this.clientName,
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: authMethod,
+      ...(this.config.scope ? { scope: this.config.scope } : {}),
+    };
+  }
+
+  /**
+   * CSRF state for the authorization request. Empty when no state was
+   * pre-generated: only the never-redirected client_credentials flow can
+   * reach this, so the empty value is intentional (not an error).
+   */
+  state(): string {
+    return this.csrfState ?? "";
+  }
+
+  /** Pre-registered client from config wins; otherwise the stored (DCR) client. */
+  async clientInformation(): Promise<OAuthClientInformationMixed | undefined> {
+    if (this.config.clientId) {
+      return {
+        client_id: this.config.clientId,
+        ...(this.config.clientSecret ? { client_secret: this.config.clientSecret } : {}),
+      };
+    }
+
+    const stored = getAuthEntry(this.serverName)?.clientInfo;
+    if (stored === undefined) return undefined;
+    return {
+      client_id: stored.clientId,
+      ...(stored.clientSecret ? { client_secret: stored.clientSecret } : {}),
+      ...(stored.redirectUris ? { redirect_uris: stored.redirectUris } : {}),
+    };
+  }
+
+  /** Persist DCR-registered client info into the entry, preserving tokens/verifier. */
+  async saveClientInformation(info: OAuthClientInformationMixed): Promise<void> {
+    const existing = getAuthEntry(this.serverName) ?? {};
+    const clientInfo: { clientId: string; clientSecret?: string; redirectUris?: string[] } = {
+      clientId: info.client_id,
+    };
+    if (info.client_secret) clientInfo.clientSecret = info.client_secret;
+    // `redirect_uris` only exists on the full-registration member of the union.
+    if ("redirect_uris" in info) clientInfo.redirectUris = info.redirect_uris;
+
+    saveAuthEntry(this.serverName, { ...existing, clientInfo }, this.serverUrl);
+  }
+
+  /** Map stored tokens to the SDK wire shape; undefined when none are stored. */
+  async tokens(): Promise<OAuthTokens | undefined> {
+    const stored = getAuthEntry(this.serverName)?.tokens;
+    if (stored === undefined) return undefined;
+    return {
+      access_token: stored.accessToken,
+      token_type: "Bearer",
+      ...(stored.refreshToken ? { refresh_token: stored.refreshToken } : {}),
+      // Expired tokens are still returned (expires_in 0) so the SDK's auth()
+      // driver takes its refresh path — do not filter here.
+      ...(stored.expiresAt !== undefined
+        ? { expires_in: Math.max(0, stored.expiresAt - this.nowSeconds) }
+        : {}),
+      ...(stored.scope ? { scope: stored.scope } : {}),
+    };
+  }
+
+  /** Map SDK wire tokens to the stored shape and persist into the entry. */
+  async saveTokens(tokens: OAuthTokens): Promise<void> {
+    const existing = getAuthEntry(this.serverName) ?? {};
+    const stored = {
+      accessToken: tokens.access_token,
+      ...(tokens.refresh_token ? { refreshToken: tokens.refresh_token } : {}),
+      ...(tokens.expires_in != null
+        ? { expiresAt: this.nowSeconds + tokens.expires_in }
+        : {}),
+      ...(tokens.scope ? { scope: tokens.scope } : {}),
+    };
+
+    saveAuthEntry(this.serverName, { ...existing, tokens: stored }, this.serverUrl);
+  }
+
+  /** Hand the authorization URL to the host (browser open / prompt). */
+  async redirectToAuthorization(url: URL): Promise<void> {
+    await this.callbacks.onAuthorizationUrl?.(url);
+  }
+
+  /** Persist the PKCE verifier before the authorization redirect. */
+  async saveCodeVerifier(verifier: string): Promise<void> {
+    const existing = getAuthEntry(this.serverName) ?? {};
+    saveAuthEntry(this.serverName, { ...existing, codeVerifier: verifier }, this.serverUrl);
+  }
+
+  /** Read the PKCE verifier back for the token exchange. */
+  async codeVerifier(): Promise<string> {
+    const verifier = getAuthEntry(this.serverName)?.codeVerifier;
+    if (verifier === undefined) {
+      throw new Error("Missing OAuth code verifier");
+    }
+    return verifier;
+  }
+}

package/src/oauth-types.ts

@@ -0,0 +1,54 @@
+/**
+ * OAuth token & client storage types (persisted in the OS credential store).
+ *
+ * These are the on-disk shapes under the keyring — independent of the
+ * MCP SDK's wire shapes (@modelcontextprotocol/sdk's OAuthTokens, etc.),
+ * which are mapped to/from these at the provider boundary.
+ */
+
+/** Stored OAuth tokens for one server (keyring value, chunked if large) */
+export interface StoredTokens {
+  accessToken: string;
+  refreshToken?: string;
+  /** Unix seconds; absent when the token does not expire */
+  expiresAt?: number;
+  scope?: string;
+  /** Authorization server issuer for multi-tenant providers */
+  issuer?: string;
+}
+
+/**
+ * Stored OAuth client information — either the provider-registered
+ * (dynamic registration) client or a pre-registered client from config.
+ * `configPreRegistered` marks the latter so refresh honors ADR 0001
+ * (client-stub guard: no auto-refresh for a public client with no secret).
+ */
+export interface StoredClientInfo {
+  clientId: string;
+  clientSecret?: string;
+  redirectUris?: string[];
+  issuer?: string;
+  /** True when the client id/secret came from mcp.json `auth` config;
+   * reserved: the ADR 0001 guard keys off config.clientId/clientSecret
+   * (see auth-flow.ts); kept for port-compat with the reference adapter */
+  configPreRegistered?: boolean;
+}
+
+/**
+ * Full per-server auth entry in the keyring. All fields optional so an
+ * entry may accumulate state incrementally (code verifier during the
+ * flow, client info after registration, tokens after the exchange).
+ */
+export interface AuthEntry {
+  tokens?: StoredTokens;
+  clientInfo?: StoredClientInfo;
+  /** PKCE code verifier persisted before the authorization request */
+  codeVerifier?: string;
+  /** Reserved: not set or read — the live CSRF state lives in
+   * callback-server memory for the flow duration; kept for port-compat
+   * with the reference adapter */
+  oauthState?: string;
+  /** Server URL the credentials were obtained for; persisted for debugging +
+   * future url-binding validation — not read by current code */
+  serverUrl?: string;
+}

package/src/panel-rows.ts

@@ -0,0 +1,210 @@
+/**
+ * Pure, stateless row helpers for the `/mcp panel` management panel.
+ *
+ * Everything in this module is a pure function or type definition — no
+ * side effects, no closure over mutable state. Extracted from panel.ts so
+ * that unit tests can import them directly and so that panel.ts can focus
+ * on the stateful component logic.
+ */
+import { isHttpDef, resolveServerSettings } from "./config.js";
+import type { ServerManager } from "./server-manager.js";
+import type { ServerStatus } from "./server-client.js";
+import type { CachedTool, McpConfig, ServerDef, ServerOutcomeRecord } from "./types.js";
+
+// ── State shapes ─────────────────────────────────────────────────────────────
+
+export interface ToolRow {
+  name: string;
+  description: string;
+  /** Current direct-tools selection state (what ctrl+s would write). */
+  isDirect: boolean;
+  /** Direct state as resolved from config when the panel opened (dirty baseline). */
+  wasDirect: boolean;
+}
+
+export type ServerRowStatus = "connected" | "cached" | "needs-auth" | "disabled" | "error";
+
+export interface ServerRow {
+  name: string;
+  expanded: boolean;
+  status: ServerRowStatus;
+  /** First-line error text for needs-auth/error rows. */
+  failureMessage?: string;
+  /** Timestamp of the persisted outcome that drove this row ("X ago" suffix). */
+  statusAt?: number;
+  tools: ToolRow[];
+  /** True when valid cached tool metadata exists for this server. */
+  hasCachedData: boolean;
+}
+
+/** One navigable line in the flat visible list. */
+export type VisibleRow =
+  | { kind: "server"; server: ServerRow }
+  | { kind: "tool"; server: ServerRow; tool: ToolRow };
+
+/** Dependencies injected by commands.ts — the seams the panel touches. */
+export interface McpPanelDeps {
+  /** loadAllServerDefs() — INCLUDES disabled servers (they have status). */
+  getServerDefs: () => Record<string, ServerDef>;
+  getCachedTools: (serverName: string, def: ServerDef) => CachedTool[] | undefined;
+  /** Module-level singleton via getter (session-resilient across /reload). */
+  getManager: () => ServerManager;
+}
+
+// ── Row-seeding support ───────────────────────────────────────────────────────
+
+export interface RowSources {
+  globalConfig: McpConfig;
+  outcomes: Record<string, ServerOutcomeRecord>;
+  manager: ServerManager;
+  getCachedTools: (name: string, def: ServerDef) => CachedTool[] | undefined;
+}
+
+// ── Pure helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Flat list of visible rows: every server in order; an EXPANDED server's
+ * tool rows interleave immediately after its own row (in tool order).
+ * Collapsed servers contribute only their server row.
+ */
+export function buildVisibleRows(servers: ServerRow[]): VisibleRow[] {
+  const rows: VisibleRow[] = [];
+  for (const s of servers) {
+    rows.push({ kind: "server", server: s });
+    if (s.expanded) {
+      for (const t of s.tools) {
+        rows.push({ kind: "tool", server: s, tool: t });
+      }
+    }
+  }
+  return rows;
+}
+
+/**
+ * Filter servers for the `[/] search` box: case-insensitive substring over
+ * the server name AND every tool's name/description (a server is kept when
+ * any of those matches). Empty query passes the original array through
+ * unchanged (same reference).
+ */
+export function filterRows(servers: ServerRow[], query: string): ServerRow[] {
+  if (query.length === 0) return servers;
+  const q = query.toLowerCase();
+  return servers.filter(
+    (s) =>
+      s.name.toLowerCase().includes(q) ||
+      s.tools.some(
+        (t) => t.name.toLowerCase().includes(q) || t.description.toLowerCase().includes(q),
+      ),
+  );
+}
+
+/** Flip one tool's direct selection without touching wasDirect. */
+export function toggleTool(tool: ToolRow): void {
+  tool.isDirect = !tool.isDirect;
+}
+
+/**
+ * The per-server save value derived from tool isDirect states (same rule as
+ * the agent-manager tool picker): all direct → `true`, none direct →
+ * `false`, otherwise the exact subset of direct tool names in row order.
+ * An empty tool list counts as "all direct" → `true`.
+ */
+export function computeSelection(toolRows: ToolRow[]): true | false | string[] {
+  if (toolRows.every((t) => t.isDirect)) return true;
+  if (toolRows.every((t) => !t.isDirect)) return false;
+  return toolRows.filter((t) => t.isDirect).map((t) => t.name);
+}
+
+// ── Display helpers ───────────────────────────────────────────────────────────
+
+export function firstLine(text: string | null | undefined): string | undefined {
+  const line = text?.split("\n")[0]?.trim();
+  return line === undefined || line.length === 0 ? undefined : line;
+}
+
+/**
+ * Staleness formatting for persisted outcomes (ADR 0004). Deliberately
+ * duplicated from commands.ts instead of imported: commands.ts lazily loads
+ * panel.ts for /mcp panel, so a static import back would create a cycle.
+ */
+export function formatAge(ms: number): string {
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${Math.max(1, s)}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  if (d < 7) return `${d}d ago`;
+  if (d < 45) return `${Math.max(1, Math.round(d / 7))}w ago`;
+  return `${Math.max(1, Math.round(d / 30))}mo ago`;
+}
+
+/** "(X ago)" — omitted for fresh (<1m) entries or unknown timestamps. */
+export function ageSuffix(at: number | undefined): string {
+  if (at === undefined) return "";
+  const age = Date.now() - at;
+  if (age < 60_000) return "";
+  return ` (${formatAge(age)})`;
+}
+
+// ── Row seeding ───────────────────────────────────────────────────────────────
+
+/** Verified connection states — the only ones a row may claim live. */
+export function isVerifiedStatus(s: ServerStatus): s is "connected" | "needs-auth" | "error" {
+  return s === "connected" || s === "needs-auth" || s === "error";
+}
+
+/**
+ * Build/refresh one ServerRow from (defs, live manager, persisted outcomes,
+ * cache). Status: `disabled` wins; a live client whose captured status is
+ * VERIFIED (connected/needs-auth/error) wins next — "disconnected"/
+ * "connecting" are not verified, so ADR 0004 falls back to the persisted
+ * outcome; then the outcome (a persisted `connected` reads as "cached", i.e.
+ * was connected across sessions); else "cached". Tools: live (only while
+ * connected) wins over valid cache; wasDirect/isDirect seed from the
+ * resolved directTools setting.
+ */
+export function buildRow(name: string, def: ServerDef, sources: RowSources): ServerRow {
+  const client = sources.manager.getClient(name);
+  const clientStatus = client ? client.status : undefined;
+  const live = client && clientStatus !== undefined && isVerifiedStatus(clientStatus);
+  const outcome = live ? undefined : sources.outcomes[name];
+
+  let status: ServerRowStatus;
+  let statusAt: number | undefined;
+  let failureMessage: string | undefined;
+  if (def.disabled === true) {
+    status = "disabled";
+  } else if (live && clientStatus) {
+    status = clientStatus;
+    if (clientStatus !== "connected" && client) failureMessage = firstLine(client.error);
+  } else if (outcome) {
+    status = outcome.status === "connected" ? "cached" : outcome.status;
+    statusAt = outcome.at;
+    if (outcome.status !== "connected") failureMessage = firstLine(outcome.error);
+  } else {
+    status = "cached";
+  }
+
+  const cached = sources.getCachedTools(name, def);
+  const liveTools = live && clientStatus === "connected" && client ? client.tools : undefined;
+  const direct = resolveServerSettings(def, sources.globalConfig).directTools;
+  // Config arrives from JSON without runtime validation — a non-boolean,
+  // non-array directTools must not throw (mirror of filterDirectTools).
+  const isDirectFor = (toolName: string): boolean =>
+    Array.isArray(direct) ? direct.includes(toolName) : direct !== false;
+  const tools: ToolRow[] = (liveTools ?? cached ?? []).map((t) => ({
+    name: t.name,
+    description: t.description ?? "",
+    isDirect: isDirectFor(t.name),
+    wasDirect: isDirectFor(t.name),
+  }));
+
+  const row: ServerRow = { name, expanded: false, status, tools, hasCachedData: cached !== undefined };
+  if (statusAt !== undefined) row.statusAt = statusAt;
+  if (failureMessage !== undefined) row.failureMessage = failureMessage;
+  return row;
+}
+
+