@teampitch/mcpx 0.2.1 → 0.3.1

package/src/oauth-client.ts

@@ -0,0 +1,337 @@
+/**
+ * OAuth client for MCP HTTP backends.
+ * Handles: metadata discovery, client registration, auth code + PKCE, token storage, refresh.
+ * Tokens stored in .mcpx/tokens/{backend-name}.json
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { createServer, type Server } from "node:http";
+import { join } from "node:path";
+
+interface OAuthMetadata {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  registration_endpoint?: string;
+  response_types_supported?: string[];
+  grant_types_supported?: string[];
+  code_challenge_methods_supported?: string[];
+}
+
+interface StoredToken {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt: number;
+  clientId: string;
+  clientSecret?: string;
+  tokenEndpoint: string;
+}
+
+interface PkceChallenge {
+  verifier: string;
+  challenge: string;
+}
+
+async function generatePkce(): Promise<PkceChallenge> {
+  const array = new Uint8Array(32);
+  crypto.getRandomValues(array);
+  const verifier = Array.from(array, (b) => b.toString(16).padStart(2, "0")).join("");
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  const challenge = btoa(String.fromCharCode(...new Uint8Array(digest)))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+  return { verifier, challenge };
+}
+
+/** Discover OAuth metadata from an MCP server */
+async function discoverMetadata(serverUrl: string): Promise<OAuthMetadata> {
+  const base = new URL(serverUrl);
+  const metadataUrl = `${base.origin}/.well-known/oauth-authorization-server`;
+
+  const res = await fetch(metadataUrl);
+  if (!res.ok) {
+    // Fall back to default endpoints
+    return {
+      issuer: base.origin,
+      authorization_endpoint: `${base.origin}/authorize`,
+      token_endpoint: `${base.origin}/token`,
+      registration_endpoint: `${base.origin}/register`,
+    };
+  }
+  return res.json();
+}
+
+/** Register as an OAuth client with the server */
+async function registerClient(
+  metadata: OAuthMetadata,
+  redirectUri: string,
+): Promise<{ clientId: string; clientSecret?: string }> {
+  if (!metadata.registration_endpoint) {
+    throw new Error("Server doesn't support dynamic client registration");
+  }
+
+  const res = await fetch(metadata.registration_endpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_name: "mcpx",
+      redirect_uris: [redirectUri],
+    }),
+  });
+
+  if (!res.ok) {
+    throw new Error(`Client registration failed: ${res.status} ${await res.text()}`);
+  }
+
+  const body = await res.json();
+  return { clientId: body.client_id, clientSecret: body.client_secret };
+}
+
+/** Exchange authorization code for tokens */
+async function exchangeCode(
+  tokenEndpoint: string,
+  code: string,
+  redirectUri: string,
+  clientId: string,
+  clientSecret: string | undefined,
+  codeVerifier: string,
+): Promise<{ accessToken: string; refreshToken?: string; expiresIn: number }> {
+  const body: Record<string, string> = {
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+    client_id: clientId,
+    code_verifier: codeVerifier,
+  };
+  if (clientSecret) body.client_secret = clientSecret;
+
+  const res = await fetch(tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    throw new Error(`Token exchange failed: ${res.status} ${await res.text()}`);
+  }
+
+  const data = await res.json();
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token,
+    expiresIn: data.expires_in ?? 3600,
+  };
+}
+
+/** Refresh an expired access token */
+async function refreshAccessToken(
+  tokenEndpoint: string,
+  refreshToken: string,
+  clientId: string,
+  clientSecret?: string,
+): Promise<{ accessToken: string; refreshToken?: string; expiresIn: number }> {
+  const body: Record<string, string> = {
+    grant_type: "refresh_token",
+    refresh_token: refreshToken,
+    client_id: clientId,
+  };
+  if (clientSecret) body.client_secret = clientSecret;
+
+  const res = await fetch(tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    throw new Error(`Token refresh failed: ${res.status}`);
+  }
+
+  const data = await res.json();
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token ?? refreshToken,
+    expiresIn: data.expires_in ?? 3600,
+  };
+}
+
+function getTokenPath(tokensDir: string, backendName: string): string {
+  return join(tokensDir, `${backendName}.json`);
+}
+
+function loadToken(tokensDir: string, backendName: string): StoredToken | null {
+  const path = getTokenPath(tokensDir, backendName);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function saveToken(tokensDir: string, backendName: string, token: StoredToken): void {
+  mkdirSync(tokensDir, { recursive: true });
+  writeFileSync(getTokenPath(tokensDir, backendName), JSON.stringify(token, null, 2) + "\n");
+}
+
+/** Start a temporary local server to receive the OAuth callback */
+function startCallbackServer(port: number): Promise<{ code: string; server: Server }> {
+  return new Promise((resolve, reject) => {
+    const server = createServer((req, res) => {
+      const url = new URL(req.url!, `http://localhost:${port}`);
+      const code = url.searchParams.get("code");
+      const error = url.searchParams.get("error");
+
+      if (error) {
+        res.writeHead(400, { "Content-Type": "text/html" });
+        res.end(
+          `<html><body><h2>Authorization failed: ${error}</h2><p>You can close this tab.</p></body></html>`,
+        );
+        reject(new Error(`OAuth error: ${error}`));
+        server.close();
+        return;
+      }
+
+      if (code) {
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(
+          "<html><body><h2>Authorization successful!</h2><p>You can close this tab and return to the terminal.</p></body></html>",
+        );
+        resolve({ code, server });
+        return;
+      }
+
+      res.writeHead(400);
+      res.end("Missing code parameter");
+    });
+
+    server.listen(port, () => {
+      // Server ready
+    });
+
+    server.on("error", reject);
+
+    // Timeout after 5 minutes
+    setTimeout(
+      () => {
+        server.close();
+        reject(new Error("OAuth callback timeout (5 minutes)"));
+      },
+      5 * 60 * 1000,
+    );
+  });
+}
+
+export interface OAuthClientConfig {
+  redirectUri?: string;
+  callbackPort?: number;
+}
+
+/**
+ * Get a valid access token for an HTTP backend.
+ * Handles the full OAuth flow: discovery → registration → auth code → token exchange.
+ * Caches tokens in .mcpx/tokens/ and refreshes when expired.
+ */
+export async function getAccessToken(
+  backendName: string,
+  serverUrl: string,
+  tokensDir: string,
+  oauthConfig: OAuthClientConfig = {},
+): Promise<string> {
+  const callbackPort = oauthConfig.callbackPort ?? 9876;
+  const redirectUri = oauthConfig.redirectUri ?? `http://localhost:${callbackPort}/oauth/callback`;
+
+  // Check for cached token
+  const cached = loadToken(tokensDir, backendName);
+  if (cached) {
+    // Token still valid (with 60s buffer)
+    if (cached.expiresAt > Date.now() + 60_000) {
+      return cached.accessToken;
+    }
+
+    // Try refresh
+    if (cached.refreshToken) {
+      try {
+        console.log(`  ${backendName}: refreshing OAuth token...`);
+        const refreshed = await refreshAccessToken(
+          cached.tokenEndpoint,
+          cached.refreshToken,
+          cached.clientId,
+          cached.clientSecret,
+        );
+        const token: StoredToken = {
+          accessToken: refreshed.accessToken,
+          refreshToken: refreshed.refreshToken,
+          expiresAt: Date.now() + refreshed.expiresIn * 1000,
+          clientId: cached.clientId,
+          clientSecret: cached.clientSecret,
+          tokenEndpoint: cached.tokenEndpoint,
+        };
+        saveToken(tokensDir, backendName, token);
+        return token.accessToken;
+      } catch {
+        console.log(`  ${backendName}: refresh failed, re-authenticating...`);
+      }
+    }
+  }
+
+  // Full OAuth flow
+  console.log(`  ${backendName}: discovering OAuth metadata...`);
+  const metadata = await discoverMetadata(serverUrl);
+
+  console.log(`  ${backendName}: registering OAuth client...`);
+  const { clientId, clientSecret } = await registerClient(metadata, redirectUri);
+
+  const pkce = await generatePkce();
+  const state = crypto.randomUUID();
+
+  const authUrl = new URL(metadata.authorization_endpoint);
+  authUrl.searchParams.set("client_id", clientId);
+  authUrl.searchParams.set("redirect_uri", redirectUri);
+  authUrl.searchParams.set("response_type", "code");
+  authUrl.searchParams.set("code_challenge", pkce.challenge);
+  authUrl.searchParams.set("code_challenge_method", "S256");
+  authUrl.searchParams.set("state", state);
+
+  // Start callback server and prompt user
+  console.log(`\n  ${backendName}: authorize mcpx at:\n`);
+  console.log(`  ${authUrl.toString()}\n`);
+  console.log(`  Waiting for callback on ${redirectUri}...\n`);
+
+  // Try to open browser automatically
+  try {
+    const open =
+      process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    Bun.spawn([open, authUrl.toString()], {
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+  } catch {
+    // Manual open is fine
+  }
+
+  const { code, server } = await startCallbackServer(callbackPort);
+  server.close();
+
+  console.log(`  ${backendName}: exchanging code for token...`);
+  const tokens = await exchangeCode(
+    metadata.token_endpoint,
+    code,
+    redirectUri,
+    clientId,
+    clientSecret,
+    pkce.verifier,
+  );
+
+  const stored: StoredToken = {
+    accessToken: tokens.accessToken,
+    refreshToken: tokens.refreshToken,
+    expiresAt: Date.now() + tokens.expiresIn * 1000,
+    clientId,
+    clientSecret,
+    tokenEndpoint: metadata.token_endpoint,
+  };
+  saveToken(tokensDir, backendName, stored);
+  console.log(`  ${backendName}: OAuth token saved`);
+
+  return stored.accessToken;
+}

package/src/skills.test.ts

@@ -0,0 +1,166 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  loadSkills,
+  saveSkill,
+  registerSkill,
+  recordExecution,
+  searchSkills,
+  generateSkillTypeDefs,
+  type Skill,
+} from "./skills.js";
+
+let skillsDir: string;
+let skills: Map<string, Skill>;
+
+beforeEach(() => {
+  skillsDir = join(tmpdir(), `mcpx-skills-test-${Date.now()}`);
+  mkdirSync(skillsDir, { recursive: true });
+  skills = new Map();
+});
+
+afterEach(() => {
+  try {
+    rmSync(skillsDir, { recursive: true });
+  } catch {}
+});
+
+describe("registerSkill", () => {
+  test("creates a new skill", () => {
+    const skill = registerSkill(skillsDir, skills, {
+      name: "find-errors",
+      description: "Find error logs in Loki",
+      code: 'const r = await grafana.queryLokiLogs({ logql: "{level=\\"error\\"}" }); return r;',
+    });
+    expect(skill.name).toBe("find-errors");
+    expect(skill.trust).toBe("untrusted");
+    expect(skill.stats.runs).toBe(0);
+    expect(skills.has("find-errors")).toBe(true);
+  });
+
+  test("updates an existing skill preserving stats", () => {
+    registerSkill(skillsDir, skills, {
+      name: "my-skill",
+      description: "v1",
+      code: "return 1;",
+    });
+    recordExecution(skillsDir, skills, "my-skill", true);
+    registerSkill(skillsDir, skills, {
+      name: "my-skill",
+      description: "v2",
+      code: "return 2;",
+    });
+    const updated = skills.get("my-skill")!;
+    expect(updated.description).toBe("v2");
+    expect(updated.code).toBe("return 2;");
+    expect(updated.stats.runs).toBe(1);
+  });
+});
+
+describe("recordExecution", () => {
+  test("increments success count", () => {
+    registerSkill(skillsDir, skills, {
+      name: "s1",
+      description: "test",
+      code: "return 1;",
+    });
+    recordExecution(skillsDir, skills, "s1", true);
+    recordExecution(skillsDir, skills, "s1", true);
+    expect(skills.get("s1")!.stats.successes).toBe(2);
+    expect(skills.get("s1")!.stats.runs).toBe(2);
+  });
+
+  test("increments failure count", () => {
+    registerSkill(skillsDir, skills, {
+      name: "s1",
+      description: "test",
+      code: "return 1;",
+    });
+    recordExecution(skillsDir, skills, "s1", false);
+    expect(skills.get("s1")!.stats.failures).toBe(1);
+  });
+
+  test("promotes to provisional at 10 runs with 90% success", () => {
+    registerSkill(skillsDir, skills, {
+      name: "s1",
+      description: "test",
+      code: "return 1;",
+    });
+    for (let i = 0; i < 9; i++) recordExecution(skillsDir, skills, "s1", true);
+    expect(skills.get("s1")!.trust).toBe("untrusted");
+    recordExecution(skillsDir, skills, "s1", true);
+    expect(skills.get("s1")!.trust).toBe("provisional");
+  });
+});
+
+describe("loadSkills", () => {
+  test("loads skills from directory", () => {
+    registerSkill(skillsDir, skills, {
+      name: "a",
+      description: "A",
+      code: "return 'a';",
+    });
+    registerSkill(skillsDir, skills, {
+      name: "b",
+      description: "B",
+      code: "return 'b';",
+    });
+    const loaded = loadSkills(skillsDir);
+    expect(loaded.size).toBe(2);
+    expect(loaded.get("a")!.description).toBe("A");
+  });
+
+  test("returns empty map for missing directory", () => {
+    const loaded = loadSkills("/tmp/nonexistent-mcpx-skills-dir");
+    expect(loaded.size).toBe(0);
+  });
+});
+
+describe("searchSkills", () => {
+  test("finds by name", () => {
+    registerSkill(skillsDir, skills, {
+      name: "find-errors",
+      description: "Find errors",
+      code: "",
+    });
+    registerSkill(skillsDir, skills, {
+      name: "check-latency",
+      description: "Check API latency",
+      code: "",
+    });
+    const results = searchSkills(skills, "error");
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe("find-errors");
+  });
+
+  test("finds by description", () => {
+    registerSkill(skillsDir, skills, {
+      name: "s1",
+      description: "Query Grafana dashboards",
+      code: "",
+    });
+    const results = searchSkills(skills, "grafana");
+    expect(results).toHaveLength(1);
+  });
+});
+
+describe("generateSkillTypeDefs", () => {
+  test("returns empty string for no skills", () => {
+    expect(generateSkillTypeDefs(new Map())).toBe("");
+  });
+
+  test("generates type stubs with trust level", () => {
+    registerSkill(skillsDir, skills, {
+      name: "find-errors",
+      description: "Find errors in Loki",
+      code: "",
+    });
+    const defs = generateSkillTypeDefs(skills);
+    expect(defs).toContain("skill_find_errors");
+    expect(defs).toContain("[untrusted]");
+    expect(defs).toContain("Find errors in Loki");
+  });
+});

package/src/skills.ts

@@ -0,0 +1,153 @@
+import { readFileSync, writeFileSync, readdirSync, mkdirSync, existsSync, watch } from "node:fs";
+import { join } from "node:path";
+
+export interface Skill {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  code: string;
+  trust: TrustLevel;
+  stats: { runs: number; successes: number; failures: number };
+  createdAt: string;
+  updatedAt: string;
+}
+
+export type TrustLevel = "untrusted" | "provisional" | "trusted";
+
+function computeTrust(stats: Skill["stats"]): TrustLevel {
+  if (stats.runs >= 100 && stats.successes / stats.runs >= 0.95) return "trusted";
+  if (stats.runs >= 10 && stats.successes / stats.runs >= 0.9) return "provisional";
+  return "untrusted";
+}
+
+/** Load all skills from .mcpx/skills/ directory */
+export function loadSkills(skillsDir: string): Map<string, Skill> {
+  const skills = new Map<string, Skill>();
+  if (!existsSync(skillsDir)) return skills;
+
+  for (const file of readdirSync(skillsDir)) {
+    if (!file.endsWith(".json")) continue;
+    try {
+      const raw = readFileSync(join(skillsDir, file), "utf-8");
+      const skill: Skill = JSON.parse(raw);
+      skills.set(skill.name, skill);
+    } catch {
+      // skip invalid files
+    }
+  }
+
+  return skills;
+}
+
+/** Save a skill to disk */
+export function saveSkill(skillsDir: string, skill: Skill): void {
+  mkdirSync(skillsDir, { recursive: true });
+  const filename = `${skill.name.replace(/[^a-zA-Z0-9_-]/g, "-")}.json`;
+  writeFileSync(join(skillsDir, filename), JSON.stringify(skill, null, 2) + "\n");
+}
+
+/** Register a new skill from working code */
+export function registerSkill(
+  skillsDir: string,
+  skills: Map<string, Skill>,
+  params: {
+    name: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+    code: string;
+  },
+): Skill {
+  const now = new Date().toISOString();
+  const existing = skills.get(params.name);
+
+  const skill: Skill = {
+    name: params.name,
+    description: params.description,
+    inputSchema: params.inputSchema ?? { type: "object", properties: {} },
+    code: params.code,
+    trust: existing?.trust ?? "untrusted",
+    stats: existing?.stats ?? { runs: 0, successes: 0, failures: 0 },
+    createdAt: existing?.createdAt ?? now,
+    updatedAt: now,
+  };
+
+  skills.set(skill.name, skill);
+  saveSkill(skillsDir, skill);
+  return skill;
+}
+
+/** Record execution result for trust progression */
+export function recordExecution(
+  skillsDir: string,
+  skills: Map<string, Skill>,
+  name: string,
+  success: boolean,
+): void {
+  const skill = skills.get(name);
+  if (!skill) return;
+
+  if (success) skill.stats.successes++;
+  else skill.stats.failures++;
+  skill.stats.runs++;
+  skill.trust = computeTrust(skill.stats);
+  skill.updatedAt = new Date().toISOString();
+
+  saveSkill(skillsDir, skill);
+}
+
+/** Search skills by query (simple text matching) */
+export function searchSkills(skills: Map<string, Skill>, query: string): Skill[] {
+  const q = query.toLowerCase();
+  return Array.from(skills.values()).filter(
+    (s) => s.name.toLowerCase().includes(q) || s.description.toLowerCase().includes(q),
+  );
+}
+
+/** Watch skills directory for changes */
+export function watchSkills(
+  skillsDir: string,
+  skills: Map<string, Skill>,
+  onChange?: () => void,
+): () => void {
+  if (!existsSync(skillsDir)) {
+    mkdirSync(skillsDir, { recursive: true });
+  }
+
+  let debounce: ReturnType<typeof setTimeout> | null = null;
+  const watcher = watch(skillsDir, () => {
+    if (debounce) clearTimeout(debounce);
+    debounce = setTimeout(() => {
+      const fresh = loadSkills(skillsDir);
+      skills.clear();
+      for (const [name, skill] of fresh) {
+        skills.set(name, skill);
+      }
+      onChange?.();
+    }, 500);
+  });
+
+  return () => {
+    if (debounce) clearTimeout(debounce);
+    watcher.close();
+  };
+}
+
+/** Generate type stubs for skills (for LLM context) */
+export function generateSkillTypeDefs(skills: Map<string, Skill>): string {
+  if (skills.size === 0) return "";
+
+  const lines: string[] = ["// === Saved Skills ==="];
+  for (const skill of skills.values()) {
+    const params = skill.inputSchema?.properties
+      ? Object.entries(skill.inputSchema.properties as Record<string, { type?: string }>)
+          .map(([k, v]) => `${k}: ${v.type ?? "any"}`)
+          .join(", ")
+      : "";
+    lines.push(
+      `// [${skill.trust}] ${skill.description}`,
+      `declare function skill_${skill.name.replace(/[^a-zA-Z0-9_]/g, "_")}(args: { ${params} }): Promise<any>;`,
+      "",
+    );
+  }
+  return lines.join("\n");
+}

package/src/stdio.ts

@@ -1,3 +1,5 @@
+import { join } from "node:path";
+
 // Entrypoint for stdio mode — Claude Code runs this directly as a subprocess
 // Usage: mcpx stdio mcpx.json
 // Or: bunx mcpx stdio mcpx.json
@@ -23,7 +25,8 @@ export async function startStdioServer(configPath: string): Promise<void> {
   process.stderr.write(`  config: ${configPath}\n`);
   process.stderr.write(`  backends: ${Object.keys(config.backends).join(", ")}\n`);
 
-  const backends = await connectBackends(config.backends);
+  const tokensDir = join(configPath.replace(/[^/]+$/, ""), ".mcpx", "tokens");
+  const backends = await connectBackends(config.backends, { tokensDir });
 
   if (backends.size === 0 && !config.failOpen) {
     process.stderr.write("No backends connected. Use failOpen: true to start anyway.\n");
@@ -131,12 +134,8 @@ ${toolListing}`,
 Write an async function body. Available tool functions (call with await):
 ${typeDefs}
 
-Example (namespace style):
+Example:
   const result = await grafana.searchDashboards({ query: "pods" });
-  return result;
-
-Example (classic style):
-  const result = await grafana_search_dashboards({ query: "pods" });
   return result;`,
     { code: z.string().describe("JavaScript async function body to execute") },
     async ({ code }) => {