@evantahler/mcpx 0.15.0

package/src/client/oauth.ts

@@ -0,0 +1,314 @@
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import {
+  auth,
+  discoverOAuthServerInfo,
+  refreshAuthorization,
+} from "@modelcontextprotocol/sdk/client/auth.js";
+import type {
+  OAuthClientMetadata,
+  OAuthClientInformationMixed,
+  OAuthTokens,
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { AuthFile } from "../config/schemas.ts";
+import { saveAuth } from "../config/loader.ts";
+import type { FormatOptions } from "../output/formatter.ts";
+import { logger } from "../output/logger.ts";
+import { openBrowser } from "./browser.ts";
+
+export class McpOAuthProvider implements OAuthClientProvider {
+  private serverName: string;
+  private configDir: string;
+  private auth: AuthFile;
+  private _codeVerifier?: string;
+  private _callbackPort = 0;
+
+  constructor(opts: { serverName: string; configDir: string; auth: AuthFile }) {
+    this.serverName = opts.serverName;
+    this.configDir = opts.configDir;
+    this.auth = opts.auth;
+  }
+
+  get redirectUrl(): string {
+    return `http://127.0.0.1:${this._callbackPort}/callback`;
+  }
+
+  get clientMetadata(): OAuthClientMetadata {
+    return {
+      redirect_uris: [`http://127.0.0.1:${this._callbackPort}/callback`],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      client_name: "mcpx",
+      token_endpoint_auth_method: "none",
+    };
+  }
+
+  clientInformation(): OAuthClientInformationMixed | undefined {
+    const entry = this.auth[this.serverName];
+    // During an active auth flow, return client_info even if incomplete.
+    // For normal usage (transport), the manager checks isComplete() separately.
+    return entry?.client_info;
+  }
+
+  async saveClientInformation(info: OAuthClientInformationMixed): Promise<void> {
+    if (!this.auth[this.serverName]) {
+      this.auth[this.serverName] = { tokens: {} as OAuthTokens };
+    }
+    this.auth[this.serverName]!.client_info = info;
+    await saveAuth(this.configDir, this.auth);
+  }
+
+  tokens(): OAuthTokens | undefined {
+    return this.auth[this.serverName]?.tokens;
+  }
+
+  async saveTokens(tokens: OAuthTokens): Promise<void> {
+    if (!this.auth[this.serverName]) {
+      this.auth[this.serverName] = { tokens };
+    } else {
+      this.auth[this.serverName]!.tokens = tokens;
+    }
+
+    // Compute expires_at from expires_in
+    if (tokens.expires_in) {
+      const expiresAt = new Date(Date.now() + tokens.expires_in * 1000);
+      this.auth[this.serverName]!.expires_at = expiresAt.toISOString();
+    }
+
+    // Mark auth as complete — tokens have been successfully obtained
+    this.auth[this.serverName]!.complete = true;
+
+    await saveAuth(this.configDir, this.auth);
+  }
+
+  async redirectToAuthorization(url: URL): Promise<void> {
+    const urlStr = url.toString();
+    logger.info(urlStr);
+    await openBrowser(urlStr);
+  }
+
+  async saveCodeVerifier(v: string): Promise<void> {
+    this._codeVerifier = v;
+  }
+
+  codeVerifier(): string {
+    if (!this._codeVerifier) {
+      throw new Error("Code verifier not set");
+    }
+    return this._codeVerifier;
+  }
+
+  async invalidateCredentials(
+    scope: "all" | "client" | "tokens" | "verifier" | "discovery",
+  ): Promise<void> {
+    const entry = this.auth[this.serverName];
+    if (!entry) return;
+
+    switch (scope) {
+      case "all":
+        delete this.auth[this.serverName];
+        break;
+      case "client":
+        delete entry.client_info;
+        break;
+      case "tokens":
+        delete this.auth[this.serverName];
+        // Re-create entry without tokens but keep client_info
+        if (entry.client_info) {
+          this.auth[this.serverName] = {
+            tokens: {} as OAuthTokens,
+            client_info: entry.client_info,
+          };
+        }
+        break;
+      case "verifier":
+        this._codeVerifier = undefined;
+        return; // No need to persist
+      case "discovery":
+        return; // Nothing to clear locally
+    }
+
+    await saveAuth(this.configDir, this.auth);
+  }
+
+  /** Whether the auth flow completed successfully (tokens were obtained) */
+  isComplete(): boolean {
+    return !!this.auth[this.serverName]?.complete;
+  }
+
+  /** Clear any incomplete auth state from a previously cancelled flow */
+  async clearIncomplete(): Promise<void> {
+    const entry = this.auth[this.serverName];
+    if (entry && !entry.complete) {
+      delete this.auth[this.serverName];
+      await saveAuth(this.configDir, this.auth);
+    }
+  }
+
+  setCallbackPort(port: number): void {
+    this._callbackPort = port;
+  }
+
+  isExpired(): boolean {
+    const entry = this.auth[this.serverName];
+    if (!entry?.expires_at) return false;
+    return new Date(entry.expires_at) <= new Date();
+  }
+
+  hasRefreshToken(): boolean {
+    const tokens = this.auth[this.serverName]?.tokens;
+    return !!tokens?.refresh_token;
+  }
+
+  async refreshIfNeeded(serverUrl: string): Promise<void> {
+    if (!this.isExpired()) return;
+
+    if (!this.hasRefreshToken()) {
+      throw new Error(
+        `Token expired for "${this.serverName}" and no refresh token available. Run: mcpx auth ${this.serverName}`,
+      );
+    }
+
+    const clientInfo = this.clientInformation();
+    if (!clientInfo) {
+      throw new Error(
+        `No client information for "${this.serverName}". Run: mcpx auth ${this.serverName}`,
+      );
+    }
+
+    const tokens = await refreshAuthorization(serverUrl, {
+      clientInformation: clientInfo,
+      refreshToken: this.auth[this.serverName]!.tokens.refresh_token!,
+    });
+
+    await this.saveTokens(tokens);
+
+    logger.info(`Token refreshed for "${this.serverName}"`);
+  }
+}
+
+/** Start a local callback server to receive the OAuth authorization code */
+export function startCallbackServer(): {
+  server: ReturnType<typeof Bun.serve>;
+  authCodePromise: Promise<string>;
+} {
+  let resolveCode: (code: string) => void;
+  let rejectCode: (err: Error) => void;
+
+  const authCodePromise = new Promise<string>((resolve, reject) => {
+    resolveCode = resolve;
+    rejectCode = reject;
+  });
+
+  const server = Bun.serve({
+    port: 0,
+    fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname !== "/callback") {
+        return new Response("Not found", { status: 404 });
+      }
+
+      const error = url.searchParams.get("error");
+      if (error) {
+        const desc = url.searchParams.get("error_description") || error;
+        rejectCode!(new Error(`OAuth error: ${desc}`));
+        return new Response(
+          "<html><body><h1>Authentication Failed</h1><p>You can close this window.</p></body></html>",
+          { headers: { "Content-Type": "text/html" } },
+        );
+      }
+
+      const code = url.searchParams.get("code");
+      if (!code) {
+        rejectCode!(new Error("No authorization code received"));
+        return new Response(
+          "<html><body><h1>Error</h1><p>No authorization code received.</p></body></html>",
+          { headers: { "Content-Type": "text/html" } },
+        );
+      }
+
+      resolveCode!(code);
+      return new Response(
+        "<html><body><h1>Authenticated!</h1><p>You can close this window.</p></body></html>",
+        { headers: { "Content-Type": "text/html" } },
+      );
+    },
+  });
+
+  return { server, authCodePromise };
+}
+
+/** Resolve the canonical resource URL for an HTTP MCP server.
+ * Some servers advertise a canonical URL in their OAuth protected resource metadata
+ * that may differ from the URL provided by the user (e.g. hf.co → huggingface.co).
+ * Returns the canonical URL if found, or the original URL otherwise. */
+export async function resolveResourceUrl(serverUrl: string): Promise<string> {
+  try {
+    const info = await discoverOAuthServerInfo(serverUrl);
+    const canonical = info.resourceMetadata?.resource;
+    if (canonical && canonical !== serverUrl) {
+      // Preserve the path/query/hash from the original URL — the canonical URL
+      // from OAuth resource metadata identifies the origin (scheme + host + port),
+      // not the endpoint path (e.g. /mcp).
+      const orig = new URL(serverUrl);
+      const canon = new URL(canonical);
+      canon.pathname = orig.pathname;
+      canon.search = orig.search;
+      canon.hash = orig.hash;
+      const merged = canon.toString();
+      return merged === serverUrl ? serverUrl : merged;
+    }
+  } catch {
+    // OAuth discovery not available — use original URL
+  }
+  return serverUrl;
+}
+
+/** Probe for OAuth support and run the auth flow if the server supports it.
+ * Returns true if auth ran, false if server doesn't support OAuth (silent skip). */
+export async function tryOAuthIfSupported(
+  serverName: string,
+  serverUrl: string,
+  configDir: string,
+  auth: AuthFile,
+  formatOptions: FormatOptions,
+): Promise<boolean> {
+  let oauthSupported: boolean;
+  try {
+    const info = await discoverOAuthServerInfo(serverUrl);
+    oauthSupported = info.authorizationServerMetadata !== undefined;
+  } catch {
+    return false;
+  }
+
+  if (!oauthSupported) return false;
+
+  const provider = new McpOAuthProvider({ serverName, configDir, auth });
+  const spinner = logger.startSpinner(`Authenticating with "${serverName}"…`, formatOptions);
+  try {
+    await runOAuthFlow(serverUrl, provider);
+    spinner.success(`Authenticated with "${serverName}"`);
+    return true;
+  } catch (err) {
+    spinner.error(`Authentication failed: ${err instanceof Error ? err.message : err}`);
+    throw err;
+  }
+}
+
+/** Run a full OAuth authorization flow for an HTTP MCP server */
+export async function runOAuthFlow(serverUrl: string, provider: McpOAuthProvider): Promise<void> {
+  // Clear any leftover state from a previously cancelled auth flow
+  await provider.clearIncomplete();
+
+  const { server, authCodePromise } = startCallbackServer();
+  try {
+    provider.setCallbackPort(server.port);
+
+    const result = await auth(provider, { serverUrl });
+    if (result === "REDIRECT") {
+      const code = await authCodePromise;
+      await auth(provider, { serverUrl, authorizationCode: code });
+    }
+  } finally {
+    server.stop();
+  }
+}

package/src/client/sse.ts

@@ -0,0 +1,17 @@
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { HttpServerConfig } from "../config/schemas.ts";
+import { createDebugFetch } from "./debug-fetch.ts";
+
+export function createSseTransport(
+  config: HttpServerConfig,
+  authProvider?: OAuthClientProvider,
+  verbose = false,
+  showSecrets = false,
+): SSEClientTransport {
+  return new SSEClientTransport(new URL(config.url), {
+    authProvider,
+    requestInit: config.headers ? { headers: config.headers } : undefined,
+    fetch: verbose ? createDebugFetch(showSecrets) : undefined,
+  });
+}

package/src/client/stdio.ts

@@ -0,0 +1,12 @@
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { StdioServerConfig } from "../config/schemas.ts";
+
+export function createStdioTransport(config: StdioServerConfig): StdioClientTransport {
+  return new StdioClientTransport({
+    command: config.command,
+    args: config.args,
+    env: config.env ? { ...process.env, ...config.env } : undefined,
+    cwd: config.cwd,
+    stderr: "pipe",
+  });
+}

package/src/client/trace.ts

@@ -0,0 +1,184 @@
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+import { cyan, dim, green, red, yellow } from "ansis";
+import { logger } from "../output/logger.ts";
+
+export interface TraceOptions {
+  json: boolean;
+  serverName: string;
+}
+
+interface PendingRequest {
+  method: string;
+  sentAt: number;
+}
+
+/**
+ * Wrap a transport with JSON-RPC message tracing.
+ * Logs all outgoing/incoming messages to stderr.
+ * Uses a Proxy so all other transport properties pass through transparently.
+ */
+export function wrapTransportWithTrace(transport: Transport, options: TraceOptions): Transport {
+  const pending = new Map<string | number, PendingRequest>();
+  const isTTY = process.stderr.isTTY ?? false;
+
+  let clientOnMessage: ((message: JSONRPCMessage, extra?: unknown) => void) | undefined;
+
+  return new Proxy(transport, {
+    get(target, prop, receiver) {
+      if (prop === "send") {
+        return async (message: JSONRPCMessage) => {
+          logOutgoing(message, pending, options, isTTY);
+          return target.send(message);
+        };
+      }
+      if (prop === "onmessage") {
+        return clientOnMessage;
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+    set(target, prop, value) {
+      if (prop === "onmessage") {
+        clientOnMessage = value;
+        target.onmessage = (message: JSONRPCMessage, extra?: unknown) => {
+          logIncoming(message, pending, options, isTTY);
+          clientOnMessage?.(message, extra);
+        };
+        return true;
+      }
+      return Reflect.set(target, prop, value);
+    },
+  });
+}
+
+function logOutgoing(
+  message: JSONRPCMessage,
+  pending: Map<string | number, PendingRequest>,
+  options: TraceOptions,
+  isTTY: boolean,
+): void {
+  // Track pending requests for timing (needed in both modes)
+  if ("id" in message && "method" in message) {
+    const m = message as { id: string | number; method: string };
+    pending.set(m.id, { method: m.method, sentAt: performance.now() });
+  }
+
+  if (options.json) {
+    logger.writeRaw(
+      JSON.stringify({ trace: "outgoing", server: options.serverName, message }) + "\n",
+    );
+    return;
+  }
+
+  if ("id" in message && "method" in message) {
+    const m = message as { id: string | number; method: string; params?: unknown };
+    const arrow = isTTY ? cyan("→") : "→";
+    const detail = summarizeParams(m.method, m.params);
+    const detailStr = detail ? ` ${detail}` : "";
+    logger.writeRaw(`${arrow} ${dim(`${m.method} (id: ${m.id})${detailStr}`)}\n`);
+  } else if ("method" in message) {
+    const m = message as { method: string };
+    const arrow = isTTY ? cyan("→") : "→";
+    logger.writeRaw(`${arrow} ${dim(m.method)}\n`);
+  }
+}
+
+function logIncoming(
+  message: JSONRPCMessage,
+  pending: Map<string | number, PendingRequest>,
+  options: TraceOptions,
+  isTTY: boolean,
+): void {
+  if ("id" in message && !("method" in message)) {
+    // Response to a request
+    const m = message as { id: string | number; result?: unknown; error?: unknown };
+    const req = pending.get(m.id);
+    pending.delete(m.id);
+    const elapsed = req ? Math.round(performance.now() - req.sentAt) : undefined;
+    const method = req?.method ?? "unknown";
+
+    if (options.json) {
+      logger.writeRaw(
+        JSON.stringify({
+          trace: "incoming",
+          server: options.serverName,
+          message,
+          ...(elapsed !== undefined && { elapsed_ms: elapsed }),
+          request_method: method,
+        }) + "\n",
+      );
+      return;
+    }
+
+    const isError = m.error !== undefined;
+    const arrow = isTTY ? (isError ? red("←") : green("←")) : "←";
+    const timing = elapsed !== undefined ? ` [${elapsed}ms]` : "";
+    const summary = summarizeResult(method, m.result);
+    const summaryStr = summary ? ` — ${summary}` : "";
+    logger.writeRaw(`${arrow} ${dim(`${method} (id: ${m.id})${timing}${summaryStr}`)}\n`);
+  } else if ("method" in message) {
+    // Notification (incoming)
+    const m = message as { method: string; params?: unknown };
+
+    if (options.json) {
+      logger.writeRaw(
+        JSON.stringify({ trace: "incoming", server: options.serverName, message }) + "\n",
+      );
+      return;
+    }
+
+    const arrow = isTTY ? yellow("←") : "←";
+    const params = m.params ? ` ${JSON.stringify(m.params)}` : "";
+    logger.writeRaw(`${arrow} ${dim(`${m.method}${params}`)}\n`);
+  }
+}
+
+function summarizeParams(method: string, params: unknown): string | undefined {
+  if (!params || typeof params !== "object") return undefined;
+  const p = params as Record<string, unknown>;
+
+  switch (method) {
+    case "tools/call": {
+      const name = p.name as string | undefined;
+      const args = p.arguments;
+      if (!name) return undefined;
+      const argsStr = args ? ` ${JSON.stringify(args)}` : "";
+      return `${name}${argsStr}`;
+    }
+    case "resources/read":
+      return p.uri ? String(p.uri) : undefined;
+    case "prompts/get":
+      return p.name ? String(p.name) : undefined;
+    default:
+      return undefined;
+  }
+}
+
+function summarizeResult(method: string, result: unknown): string | undefined {
+  if (!result || typeof result !== "object") return undefined;
+  const r = result as Record<string, unknown>;
+
+  switch (method) {
+    case "tools/list":
+      return Array.isArray(r.tools) ? `${r.tools.length} tools` : undefined;
+    case "resources/list":
+      return Array.isArray(r.resources) ? `${r.resources.length} resources` : undefined;
+    case "resources/templates/list":
+      return Array.isArray(r.resourceTemplates)
+        ? `${r.resourceTemplates.length} templates`
+        : undefined;
+    case "prompts/list":
+      return Array.isArray(r.prompts) ? `${r.prompts.length} prompts` : undefined;
+    case "initialize": {
+      const info = r.serverInfo as { name?: string; version?: string } | undefined;
+      if (info?.name) return info.version ? `${info.name} v${info.version}` : info.name;
+      return undefined;
+    }
+    case "tools/call":
+      return r.isError ? "error" : "ok";
+    case "ping":
+      return "pong";
+    default:
+      return "ok";
+  }
+}