mcpico 0.1.1 → 0.2.0

package/src/auth.test.ts

@@ -0,0 +1,218 @@
+/**
+ * Tests for auth utilities.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  resolveEnvVars,
+  resolveUpstreamAuth,
+  resolveListenAuth,
+  upstreamAuthHeaders,
+  extractBearerToken,
+  validateBearerToken,
+  sendUnauthorized,
+} from "./auth.js";
+import type {
+  BearerAuth,
+  HeaderAuth,
+  OAuthClientCredentials,
+  ListenBearerAuth,
+} from "./auth-types.js";
+
+describe("resolveEnvVars", () => {
+  beforeEach(() => {
+    vi.stubEnv("TEST_TOKEN", "secret123");
+    vi.stubEnv("API_KEY", "key-abc");
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("replaces ${VAR} patterns with env values", () => {
+    expect(resolveEnvVars("Bearer ${TEST_TOKEN}")).toBe("Bearer secret123");
+  });
+
+  it("replaces multiple env vars in one string", () => {
+    expect(resolveEnvVars("${API_KEY}:${TEST_TOKEN}")).toBe("key-abc:secret123");
+  });
+
+  it("returns string unchanged if no env vars", () => {
+    expect(resolveEnvVars("plain-value")).toBe("plain-value");
+  });
+
+  it("throws if referenced env var is not set", () => {
+    expect(() => resolveEnvVars("${MISSING}")).toThrow(
+      'Environment variable "MISSING" is not set'
+    );
+  });
+});
+
+describe("resolveUpstreamAuth", () => {
+  beforeEach(() => {
+    vi.stubEnv("BEARER_TOKEN", "bearer-token-123");
+    vi.stubEnv("CUSTOM_KEY", "custom-key-456");
+    vi.stubEnv("OAUTH_CLIENT_ID", "client-id");
+    vi.stubEnv("OAUTH_CLIENT_SECRET", "client-secret");
+    vi.stubEnv("OAUTH_TOKEN_URL", "https://auth.example.com/token");
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("resolves bearer auth", () => {
+    const auth: BearerAuth = { type: "bearer", token: "${BEARER_TOKEN}" };
+    const resolved = resolveUpstreamAuth(auth);
+    expect(resolved).toEqual({
+      type: "bearer",
+      token: "bearer-token-123",
+    });
+  });
+
+  it("resolves header auth", () => {
+    const auth: HeaderAuth = {
+      type: "header",
+      name: "X-API-Key",
+      value: "${CUSTOM_KEY}",
+    };
+    const resolved = resolveUpstreamAuth(auth);
+    expect(resolved).toEqual({
+      type: "header",
+      name: "X-API-Key",
+      value: "custom-key-456",
+    });
+  });
+
+  it("resolves oauth auth", () => {
+    const auth: OAuthClientCredentials = {
+      type: "oauth",
+      grant_type: "client_credentials",
+      client_id: "${OAUTH_CLIENT_ID}",
+      client_secret: "${OAUTH_CLIENT_SECRET}",
+      token_url: "${OAUTH_TOKEN_URL}",
+    };
+    const resolved = resolveUpstreamAuth(auth);
+    expect(resolved).toEqual({
+      type: "oauth",
+      grant_type: "client_credentials",
+      client_id: "client-id",
+      client_secret: "client-secret",
+      token_url: "https://auth.example.com/token",
+    });
+  });
+});
+
+describe("resolveListenAuth", () => {
+  beforeEach(() => {
+    vi.stubEnv("MCPICO_KEY", "mcplico-key-789");
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("resolves listen bearer auth", () => {
+    const auth: ListenBearerAuth = { type: "bearer", token: "${MCPICO_KEY}" };
+    const resolved = resolveListenAuth(auth);
+    expect(resolved).toEqual({
+      type: "bearer",
+      token: "mcplico-key-789",
+    });
+  });
+});
+
+describe("upstreamAuthHeaders", () => {
+  it("returns Authorization header for bearer auth", () => {
+    const headers = upstreamAuthHeaders({
+      type: "bearer",
+      token: "my-token",
+    });
+    expect(headers).toEqual({ Authorization: "Bearer my-token" });
+  });
+
+  it("returns custom header for header auth", () => {
+    const headers = upstreamAuthHeaders({
+      type: "header",
+      name: "X-API-Key",
+      value: "key-123",
+    });
+    expect(headers).toEqual({ "X-API-Key": "key-123" });
+  });
+
+  it("returns empty object for oauth auth (handled by SDK)", () => {
+    const headers = upstreamAuthHeaders({
+      type: "oauth",
+      grant_type: "client_credentials",
+      client_id: "id",
+      client_secret: "secret",
+      token_url: "https://auth.example.com/token",
+    });
+    expect(headers).toEqual({});
+  });
+});
+
+describe("extractBearerToken", () => {
+  it("extracts token from Authorization header", () => {
+    const req = { headers: { authorization: "Bearer my-token" } } as any;
+    expect(extractBearerToken(req)).toBe("my-token");
+  });
+
+  it("is case-insensitive for Bearer prefix", () => {
+    const req = { headers: { authorization: "bearer my-token" } } as any;
+    expect(extractBearerToken(req)).toBe("my-token");
+  });
+
+  it("returns undefined if no Authorization header", () => {
+    const req = { headers: {} } as any;
+    expect(extractBearerToken(req)).toBeUndefined();
+  });
+
+  it("returns undefined if header is not Bearer", () => {
+    const req = { headers: { authorization: "Basic dXNlcjpwYXNz" } } as any;
+    expect(extractBearerToken(req)).toBeUndefined();
+  });
+
+  it("returns undefined if Authorization is empty string", () => {
+    const req = { headers: { authorization: "" } } as any;
+    expect(extractBearerToken(req)).toBeUndefined();
+  });
+});
+
+describe("validateBearerToken", () => {
+  it("returns true when tokens match", () => {
+    expect(validateBearerToken("secret", "secret")).toBe(true);
+  });
+
+  it("returns false when tokens differ", () => {
+    expect(validateBearerToken("wrong", "secret")).toBe(false);
+  });
+
+  it("returns false when provided token is undefined", () => {
+    expect(validateBearerToken(undefined, "secret")).toBe(false);
+  });
+
+  it("returns false when tokens have different length", () => {
+    expect(validateBearerToken("short", "longer-token")).toBe(false);
+  });
+
+  it("is case-sensitive", () => {
+    expect(validateBearerToken("Secret", "secret")).toBe(false);
+  });
+});
+
+describe("sendUnauthorized", () => {
+  it("sends 401 with WWW-Authenticate header", () => {
+    const res = {
+      writeHead: vi.fn(),
+      end: vi.fn(),
+    } as any;
+
+    sendUnauthorized(res);
+
+    expect(res.writeHead).toHaveBeenCalledWith(401, {
+      "Content-Type": "application/json",
+      "WWW-Authenticate": 'Bearer realm="mcplico"',
+    });
+    expect(res.end).toHaveBeenCalled();
+  });
+});

package/src/auth.ts

@@ -0,0 +1,159 @@
+/**
+ * Auth utilities: env var resolution, header generation, listen token validation.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type {
+  UpstreamAuth,
+  ListenAuth,
+  ResolvedUpstreamAuth,
+  ResolvedListenAuth,
+  BearerAuth,
+  HeaderAuth,
+  OAuthClientCredentials,
+} from "./auth-types.js";
+
+// ── Env var interpolation ──
+
+/**
+ * Replace ${VAR} patterns with process.env values.
+ * Throws if a referenced env var is not set.
+ */
+export function resolveEnvVars(value: string): string {
+  return value.replace(/\$\{(\w+)\}/g, (_match, varName: string) => {
+    const envValue = process.env[varName];
+    if (envValue === undefined) {
+      throw new Error(
+        `Environment variable "${varName}" is not set. ` +
+          `Referenced in auth config. Set it or remove the auth block.`
+      );
+    }
+    return envValue;
+  });
+}
+
+// ── Auth resolution ──
+
+/**
+ * Resolve an UpstreamAuth config to a ResolvedUpstreamAuth with env vars interpolated.
+ */
+export function resolveUpstreamAuth(
+  auth: UpstreamAuth
+): ResolvedUpstreamAuth {
+  switch (auth.type) {
+    case "bearer":
+      return {
+        type: "bearer",
+        token: resolveEnvVars(auth.token),
+      } as ResolvedUpstreamAuth;
+
+    case "header":
+      return {
+        type: "header",
+        name: resolveEnvVars(auth.name),
+        value: resolveEnvVars(auth.value),
+      } as ResolvedUpstreamAuth;
+
+    case "oauth":
+      // OAuth credentials are resolved at request time by the provider
+      return {
+        type: "oauth",
+        grant_type: auth.grant_type,
+        client_id: resolveEnvVars(auth.client_id),
+        client_secret: resolveEnvVars(auth.client_secret),
+        token_url: resolveEnvVars(auth.token_url),
+        scopes: auth.scopes,
+        authorization_server_url: auth.authorization_server_url
+          ? resolveEnvVars(auth.authorization_server_url)
+          : undefined,
+      } as ResolvedUpstreamAuth;
+  }
+}
+
+/**
+ * Resolve a ListenAuth config to ResolvedListenAuth.
+ */
+export function resolveListenAuth(
+  auth: ListenAuth
+): ResolvedListenAuth {
+  return {
+    type: "bearer",
+    token: resolveEnvVars(auth.token),
+  };
+}
+
+// ── Header generation for upstream requests ──
+
+/**
+ * Generate HTTP headers from a resolved upstream auth config.
+ * For bearer/header types, returns headers to attach to requests.
+ * For OAuth, returns empty — the SDK authProvider handles it.
+ */
+export function upstreamAuthHeaders(
+  auth: ResolvedUpstreamAuth
+): Record<string, string> {
+  if (auth.type === "bearer") {
+    return { Authorization: `Bearer ${auth.token}` };
+  }
+  if (auth.type === "header") {
+    return { [auth.name]: auth.value };
+  }
+  // OAuth is handled by the MCP SDK's authProvider — no static headers
+  return {};
+}
+
+// ── Listen endpoint auth middleware ──
+
+/**
+ * Extract bearer token from an Authorization header.
+ * Returns undefined if no Bearer token found.
+ */
+export function extractBearerToken(req: IncomingMessage): string | undefined {
+  const auth = req.headers.authorization;
+  if (!auth) return undefined;
+  const match = auth.match(/^Bearer\s+(.+)$/i);
+  return match ? match[1] : undefined;
+}
+
+/**
+ * Validate a bearer token against the configured token.
+ * Returns true if token is valid, false otherwise.
+ */
+export function validateBearerToken(
+  providedToken: string | undefined,
+  expectedToken: string
+): boolean {
+  if (!providedToken) return false;
+  // Constant-time comparison to prevent timing attacks
+  return timingSafeEqual(providedToken, expectedToken);
+}
+
+/**
+ * Send a 401 Unauthorized response with a WWW-Authenticate header.
+ */
+export function sendUnauthorized(res: ServerResponse): void {
+  res.writeHead(401, {
+    "Content-Type": "application/json",
+    "WWW-Authenticate": 'Bearer realm="mcplico"',
+  });
+  res.end(JSON.stringify({ error: "Unauthorized", message: "Bearer token required" }));
+}
+
+// ── Constant-time string comparison ──
+
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    // Still compare to avoid leaking length via timing
+    const maxLen = Math.max(a.length, b.length);
+    let result = 0;
+    for (let i = 0; i < maxLen; i++) {
+      result |= a.charCodeAt(i % a.length) ^ b.charCodeAt(i % b.length);
+    }
+    return false;
+  }
+
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return result === 0;
+}

package/src/config.ts

@@ -1,6 +1,9 @@
 /**
  * Transport configuration for connecting to an upstream MCP server.
  */
+import type { UpstreamAuth, ListenAuth } from "./auth-types.js";
+
+
 export type TransportConfig =
   | {
       type: "stdio";
@@ -25,6 +28,8 @@ export interface ServerConfig {
   transport: TransportConfig;
   /** Connection timeout in milliseconds (default: 30000) */
   connectTimeoutMs?: number;
+  /** Authentication config for this upstream server */
+  auth?: UpstreamAuth;
 }
 
 /**
@@ -34,6 +39,13 @@ export interface GroupOverrides {
   [groupName: string]: string[];
 }
 
+/**
+ * Transport to expose MCPico itself to clients.
+ */
+export type ListenConfig =
+  | { type: "stdio" }
+  | { type: "sse"; port: number; host?: string; auth?: ListenAuth };
+
 /**
  * Full MCPico configuration.
  */
@@ -44,6 +56,8 @@ export interface MCPicoConfig {
   separator?: string;
   /** Explicit group overrides — tools not listed here are auto-grouped */
   groups?: GroupOverrides;
+  /** How MCPico exposes itself to clients (default: stdio) */
+  listen?: ListenConfig;
 }
 
 /**

package/src/discoverer.ts

@@ -2,6 +2,9 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { TransportConfig } from "./config.js";
+import type { ResolvedUpstreamAuth } from "./auth-types.js";
+import { upstreamAuthHeaders } from "./auth.js";
+import { createClientCredentialsProvider } from "./oauth-provider.js";
 
 /**
  * Tool metadata from an upstream MCP server.
@@ -51,7 +54,8 @@ export interface DiscoveredServer {
 export async function discoverServer(
   name: string,
   transportConfig: TransportConfig,
-  connectTimeoutMs: number = 30_000
+  connectTimeoutMs: number = 30_000,
+  auth?: ResolvedUpstreamAuth
 ): Promise<DiscoveredServer> {
   let transport;
 
@@ -63,15 +67,31 @@ export async function discoverServer(
       cwd: transportConfig.cwd,
     });
   } else if (transportConfig.type === "sse") {
-    transport = new StreamableHTTPClientTransport(
-      new URL(transportConfig.url)
-    );
+    const url = new URL(transportConfig.url);
+    const opts: {
+      requestInit?: { headers: Record<string, string> };
+      authProvider?: ReturnType<typeof createClientCredentialsProvider>;
+    } = {};
+
+    if (auth) {
+      if (auth.type === "oauth") {
+        opts.authProvider = createClientCredentialsProvider(
+          auth.client_id,
+          auth.client_secret,
+          transportConfig.url
+        );
+      } else {
+        opts.requestInit = { headers: upstreamAuthHeaders(auth) };
+      }
+    }
+
+    transport = new StreamableHTTPClientTransport(url, opts);
   } else {
     throw new Error(`Unsupported transport type: ${(transportConfig as TransportConfig).type}`);
   }
 
   const client = new Client(
-    { name: `MCPico-${name}`, version: "0.1.0" },
+    { name: `MCPico-${name}`, version: "0.2.0" },
     { capabilities: {} }
   );
 

package/src/help.test.ts

@@ -194,4 +194,44 @@ describe("generateHelpText", () => {
     expect(text).toContain(tool.name);
     // Should not crash
   });
+
+  it("handles non-standard property types gracefully", () => {
+    const tool = makeTool({
+      inputSchema: {
+        type: "object",
+        properties: {
+          weird: { type: null, description: "Unknown type" },
+        },
+        required: ["weird"],
+      },
+    });
+    const text = generateHelpText(makeGroup({ tools: [tool] }));
+    // Should not crash — fallback to "any"
+    expect(text).toContain("(any");
+  });
+
+  it("falls back to bare subcommand for very long examples", () => {
+    // Three required params with long names → JSON.stringify > 80 chars
+    const tool = makeTool({
+      name: "do_something",
+      inputSchema: {
+        type: "object",
+        properties: {
+          configuration_file_path: { type: "string", description: "Long param" },
+          output_destination_directory: { type: "string", description: "Another long one" },
+          encryption_algorithm_identifier: { type: "string", description: "Third long one" },
+        },
+        required: [
+          "configuration_file_path",
+          "output_destination_directory",
+          "encryption_algorithm_identifier",
+        ],
+      },
+    });
+    const text = generateHelpText(makeGroup({ tools: [tool] }));
+    // Example should just be the bare subcommand name (long args overflow)
+    // (param names appear in Parameters section too, so just check the Example line)
+    const exampleLine = text.split("\n").find((l) => l.trim().startsWith("Example:"));
+    expect(exampleLine).toBe("    Example: do_something");
+  });
 });

package/src/index.ts

@@ -24,7 +24,7 @@ async function main(): Promise<void> {
       configPath = args[i + 1] || configPath;
       i++;
     } else if (args[i] === "--version" || args[i] === "-v") {
-      console.log("MCPico v0.1.0");
+      console.log("MCPico v0.2.0");
       process.exit(0);
     } else if (args[i] === "--help" || args[i] === "-h") {
       console.log(`

package/src/oauth-provider.ts

@@ -0,0 +1,110 @@
+/**
+ * OAuth client_credentials provider for MCPico.
+ *
+ * Implements the MCP SDK's OAuthClientProvider interface so that
+ * StreamableHTTPClientTransport handles auth discovery, token exchange,
+ * and refresh automatically.
+ */
+import type {
+  OAuthClientProvider,
+} from "@modelcontextprotocol/sdk/client/auth.js";
+import type {
+  OAuthClientMetadata,
+  OAuthClientInformationMixed,
+  OAuthTokens,
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+import { loadTokens, saveTokens, clearTokens } from "./token-store.js";
+
+/**
+ * Create an OAuthClientProvider for client_credentials grant.
+ *
+ * Uses a fixed server URL for token storage key and provides
+ * client metadata from config. The MCP SDK handles:
+ *  - RFC 9728 resource metadata discovery
+ *  - RFC 8414 authorization server metadata discovery
+ *  - Token exchange
+ *  - Token refresh via refreshAuthorization()
+ */
+export function createClientCredentialsProvider(
+  clientId: string,
+  clientSecret: string,
+  serverUrl: string,
+): OAuthClientProvider {
+  return new ClientCredentialsProvider(clientId, clientSecret, serverUrl);
+}
+
+class ClientCredentialsProvider implements OAuthClientProvider {
+  private _tokens: OAuthTokens | undefined;
+
+  constructor(
+    private clientId: string,
+    private clientSecret: string,
+    private serverUrl: string,
+  ) {
+    // Load any cached tokens on creation
+    this._tokens = loadTokens(serverUrl);
+  }
+
+  get redirectUrl(): string | URL | undefined {
+    // client_credentials is non-interactive — no redirect URL
+    return undefined;
+  }
+
+  get clientMetadata(): OAuthClientMetadata {
+    return {
+      redirect_uris: ["http://localhost:0/mcplico-callback"],
+      grant_types: ["client_credentials"],
+      client_name: "MCPico",
+    };
+  }
+
+  // Client information for token exchange
+  clientInformation(): OAuthClientInformationMixed | undefined {
+    return {
+      client_id: this.clientId,
+      client_secret: this.clientSecret,
+      client_secret_expires_at: 0, // Never expires
+    };
+  }
+
+  // Return cached tokens (or undefined for initial auth)
+  tokens(): OAuthTokens | undefined {
+    return this._tokens;
+  }
+
+  // Persist tokens after successful auth/refresh
+  saveTokens(tokens: OAuthTokens): void {
+    this._tokens = tokens;
+    saveTokens(this.serverUrl, tokens);
+  }
+
+  // No redirect needed for client_credentials
+  redirectToAuthorization(_authorizationUrl: URL): void {
+    // Non-interactive — no redirect
+  }
+
+  // PKCE not needed for client_credentials
+  saveCodeVerifier(_codeVerifier: string): void {
+    // No-op for client_credentials
+  }
+
+  codeVerifier(): string {
+    return "";
+  }
+
+  // Use client_credentials grant
+  prepareTokenRequest(
+    _scope?: string,
+  ): URLSearchParams | undefined {
+    const params = new URLSearchParams({
+      grant_type: "client_credentials",
+    });
+    return params;
+  }
+
+  // Clear tokens on invalidation
+  invalidateCredentials(_scope: "all" | "client" | "tokens" | "verifier" | "discovery"): void {
+    this._tokens = undefined;
+    clearTokens(this.serverUrl);
+  }
+}