@studio-foundation/runner 0.3.0-beta.1

package/src/plugins/mcp-client.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect, vi } from 'vitest';
+import { MCPClient } from './mcp-client.js';
+
+describe('MCPClient', () => {
+  it('generates correct tool prefix', () => {
+    const client = new MCPClient('code-review', 'github', {
+      command: 'npx',
+      args: ['-y', '@mcp/server-github'],
+    });
+    expect(client.toolPrefix()).toBe('code-review-github');
+  });
+
+  it('resolves ${ENV_VAR} in env config', () => {
+    process.env.TEST_TOKEN = 'secret-123';
+    const client = new MCPClient('myplugin', 'myserver', {
+      command: 'npx',
+      env: { MY_TOKEN: '${TEST_TOKEN}' },
+    });
+    const resolved = client.resolveEnv({ MY_TOKEN: '${TEST_TOKEN}' });
+    expect(resolved.MY_TOKEN).toBe('secret-123');
+    delete process.env.TEST_TOKEN;
+  });
+
+  it('leaves env vars without substitution syntax as-is', () => {
+    const client = new MCPClient('p', 's', { command: 'cmd' });
+    const resolved = client.resolveEnv({ KEY: 'literal-value' });
+    expect(resolved.KEY).toBe('literal-value');
+  });
+
+  it('uses HTTP transport for type:http — invalid url throws TypeError', () => {
+    // StreamableHTTPClientTransport validates the URL in its constructor via `new URL(url)`.
+    // If the old StdioClientTransport code path runs instead, no error is thrown (command
+    // is only validated at start() time). So a throw here proves the right transport is used.
+    expect(() => {
+      new MCPClient('linear', 'linear', { type: 'http', url: 'not-a-valid-url' });
+    }).toThrow(TypeError);
+  });
+
+  it('constructs successfully with a valid HTTP url', () => {
+    expect(() => {
+      new MCPClient('linear', 'linear', { type: 'http', url: 'https://mcp.linear.app/sse' });
+    }).not.toThrow();
+  });
+});
+
+describe('MCPClient — OAuth constructor', () => {
+  it('creates an oauthProvider when auth.type is oauth', () => {
+    const client = new MCPClient('linear', 'linear', {
+      type: 'http',
+      url: 'https://mcp.linear.app/mcp',
+      auth: { type: 'oauth' },
+    });
+    expect(client.oauthProvider).toBeDefined();
+  });
+
+  it('does not create oauthProvider for plain HTTP server', () => {
+    const client = new MCPClient('github', 'github', {
+      type: 'http',
+      url: 'https://mcp.github.com/mcp',
+      headers: { Authorization: 'Bearer tok' },
+    });
+    expect(client.oauthProvider).toBeUndefined();
+  });
+
+  it('does not create oauthProvider for stdio server', () => {
+    const client = new MCPClient('myplugin', 'myserver', { command: 'cmd' });
+    expect(client.oauthProvider).toBeUndefined();
+  });
+});
+
+describe('MCPClient.start() — OAuth dance', () => {
+  it('calls startCallbackServer and finishAuth when UnauthorizedError is thrown', async () => {
+    const client = new MCPClient('linear', 'linear', {
+      type: 'http',
+      url: 'https://mcp.linear.app/mcp',
+      auth: { type: 'oauth' },
+    });
+
+    const mockClose = vi.fn();
+    vi.spyOn(client.oauthProvider!, 'startCallbackServer').mockResolvedValue({
+      codePromise: Promise.resolve('auth-code-xyz'),
+      close: mockClose,
+    });
+
+    const { UnauthorizedError } = await import('@modelcontextprotocol/sdk/client/auth.js');
+    const originalTransport = client['transport'];
+    const transportsPassedToConnect: unknown[] = [];
+    vi.spyOn(client['client'], 'connect').mockImplementation(async (t) => {
+      transportsPassedToConnect.push(t);
+      if (transportsPassedToConnect.length === 1) throw new UnauthorizedError('needs auth');
+    });
+    const mockFinishAuth = vi.fn().mockResolvedValue(undefined);
+    (client['transport'] as any).finishAuth = mockFinishAuth;
+
+    await client.start();
+
+    expect(mockFinishAuth).toHaveBeenCalledWith('auth-code-xyz');
+    expect(transportsPassedToConnect).toHaveLength(2);
+    // Second connect must use a fresh transport (not the already-started one)
+    expect(transportsPassedToConnect[1]).not.toBe(originalTransport);
+    expect(mockClose).toHaveBeenCalled();
+
+    vi.restoreAllMocks();
+  });
+
+  it('closes the callback server and rethrows on non-OAuth error', async () => {
+    const client = new MCPClient('linear', 'linear', {
+      type: 'http',
+      url: 'https://mcp.linear.app/mcp',
+      auth: { type: 'oauth' },
+    });
+
+    const mockClose = vi.fn();
+    vi.spyOn(client.oauthProvider!, 'startCallbackServer').mockResolvedValue({
+      codePromise: Promise.resolve('unused'),
+      close: mockClose,
+    });
+
+    vi.spyOn(client['client'], 'connect').mockRejectedValue(new Error('network failure'));
+
+    await expect(client.start()).rejects.toThrow('network failure');
+    expect(mockClose).toHaveBeenCalled();
+
+    vi.restoreAllMocks();
+  });
+
+  it('closes the callback server immediately when connect() succeeds (tokens exist)', async () => {
+    const client = new MCPClient('linear', 'linear', {
+      type: 'http',
+      url: 'https://mcp.linear.app/mcp',
+      auth: { type: 'oauth' },
+    });
+
+    const mockClose = vi.fn();
+    vi.spyOn(client.oauthProvider!, 'startCallbackServer').mockResolvedValue({
+      codePromise: new Promise(() => { /* never resolves */ }),
+      close: mockClose,
+    });
+
+    vi.spyOn(client['client'], 'connect').mockResolvedValue(undefined);
+
+    await client.start();
+
+    expect(mockClose).toHaveBeenCalled();
+
+    vi.restoreAllMocks();
+  });
+});

package/src/plugins/mcp-client.ts

@@ -0,0 +1,128 @@
+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 { UnauthorizedError } from '@modelcontextprotocol/sdk/client/auth.js';
+import type { Tool } from '../tools/tool-registry.js';
+import type { MCPServerDef } from './plugin-loader.js';
+import { StudioOAuthProvider } from './oauth-provider.js';
+
+export class MCPClient {
+  private client: Client;
+  private transport: StdioClientTransport | StreamableHTTPClientTransport;
+  oauthProvider: StudioOAuthProvider | undefined;
+
+  constructor(
+    private pluginName: string,
+    private serverName: string,
+    private def: MCPServerDef
+  ) {
+    if (def.type === 'http') {
+      if (def.auth?.type === 'oauth') {
+        this.oauthProvider = new StudioOAuthProvider(def.url);
+        this.transport = new StreamableHTTPClientTransport(new URL(def.url), {
+          authProvider: this.oauthProvider,
+        });
+      } else {
+        const headers = this.resolveEnv(def.headers ?? {});
+        this.transport = new StreamableHTTPClientTransport(new URL(def.url), {
+          requestInit: Object.keys(headers).length > 0 ? { headers } : undefined,
+        });
+      }
+    } else {
+      const env = this.resolveEnv(def.env ?? {});
+      this.transport = new StdioClientTransport({
+        command: def.command,
+        args: def.args ?? [],
+        env: { ...process.env, ...env } as Record<string, string>,
+      });
+    }
+    this.client = new Client(
+      { name: 'studio', version: '1.0.0' },
+      { capabilities: {} }
+    );
+  }
+
+  toolPrefix(): string {
+    return `${this.pluginName}-${this.serverName}`;
+  }
+
+  /** Resolves ${VAR_NAME} placeholders from process.env. */
+  resolveEnv(env: Record<string, string>): Record<string, string> {
+    const result: Record<string, string> = {};
+    for (const [key, val] of Object.entries(env)) {
+      result[key] = val.replace(/\$\{([^}]+)\}/g, (_, v: string) => {
+        if (process.env[v] === undefined) {
+          console.warn(`Warning: env var '${v}' not set (referenced in MCP server config for plugin '${this.pluginName}')`);
+        }
+        return process.env[v] ?? '';
+      });
+    }
+    return result;
+  }
+
+  async start(): Promise<void> {
+    if (this.oauthProvider) {
+      const { codePromise, close } = await this.oauthProvider.startCallbackServer();
+      try {
+        await this.client.connect(this.transport);
+        close();
+      } catch (err) {
+        if (err instanceof UnauthorizedError) {
+          const code = await codePromise;
+          await (this.transport as StreamableHTTPClientTransport).finishAuth(code);
+          close();
+          // The SDK closes the client after UnauthorizedError but transport.close() aborts
+          // _abortController without clearing it, so start() would throw "already started!".
+          // Recreate the transport; the client itself is already reset (_transport = undefined).
+          this.transport = new StreamableHTTPClientTransport(
+            new URL((this.def as { url: string }).url),
+            { authProvider: this.oauthProvider }
+          );
+          await this.client.connect(this.transport);
+        } else {
+          close();
+          throw err;
+        }
+      }
+    } else {
+      await this.client.connect(this.transport);
+    }
+  }
+
+  async getTools(): Promise<Tool[]> {
+    const { tools } = await this.client.listTools();
+    const prefix = this.toolPrefix();
+
+    return tools.map((t) => ({
+      name: `${prefix}-${t.name}`,
+      description: t.description ?? '',
+      parameters: (t.inputSchema as Record<string, unknown>) ?? { type: 'object', properties: {} },
+      execute: async (args: Record<string, unknown>) => {
+        try {
+          const result = await this.client.callTool({ name: t.name, arguments: args });
+          // Extract text content from MCP result (filter out images/resources for now)
+          const rawContent = result.content as Array<{ type: string; text?: string }>;
+          const text = (rawContent ?? [])
+            .filter((c): c is { type: 'text'; text: string } => c.type === 'text')
+            .map((c) => c.text)
+            .join('\n');
+          return { success: true, output: text || JSON.stringify(result.content) };
+        } catch (err) {
+          return {
+            success: false,
+            output: null,
+            error: (err as Error).message,
+          };
+        }
+      },
+    }));
+  }
+
+  async close(): Promise<void> {
+    try {
+      await this.client.close();
+    } catch {
+      // Ignore close errors — process may have already exited
+    }
+  }
+}

package/src/plugins/oauth-provider.test.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { StudioOAuthProvider } from './oauth-provider.js';
+
+vi.mock('node:child_process', () => ({ exec: vi.fn() }));
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), 'studio-oauth-test-'));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+describe('StudioOAuthProvider — storage', () => {
+  it('tokens() returns undefined when no file exists', async () => {
+    const p = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    expect(await p.tokens()).toBeUndefined();
+  });
+
+  it('saveTokens() + tokens() round-trips correctly', async () => {
+    const p = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    const tokens = { access_token: 'tok123', token_type: 'bearer', expires_in: 3600, refresh_token: 'ref456' };
+    await p.saveTokens(tokens);
+    expect(await p.tokens()).toEqual(tokens);
+  });
+
+  it('clientInformation() returns undefined when no file exists', async () => {
+    const p = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    expect(await p.clientInformation()).toBeUndefined();
+  });
+
+  it('saveClientInformation() + clientInformation() round-trips correctly', async () => {
+    const p = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    const info = { client_id: 'cid', client_secret: 'csec' };
+    await p.saveClientInformation(info);
+    expect(await p.clientInformation()).toEqual(info);
+  });
+
+  it('two providers with same URL share the same storage file', async () => {
+    const p1 = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    const p2 = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    await p1.saveTokens({ access_token: 'shared', token_type: 'bearer' });
+    expect(await p2.tokens()).toEqual({ access_token: 'shared', token_type: 'bearer' });
+  });
+
+  it('two providers with different URLs use different storage files', async () => {
+    const p1 = new StudioOAuthProvider('https://mcp.linear.app/mcp', tmpDir);
+    const p2 = new StudioOAuthProvider('https://mcp.github.com/mcp', tmpDir);
+    await p1.saveTokens({ access_token: 'linear-tok', token_type: 'bearer' });
+    expect(await p2.tokens()).toBeUndefined();
+  });
+});
+
+describe('StudioOAuthProvider — PKCE', () => {
+  it('codeVerifier() throws before saveCodeVerifier() is called', () => {
+    const p = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    expect(() => p.codeVerifier()).toThrow();
+  });
+
+  it('saveCodeVerifier() + codeVerifier() round-trips in memory', () => {
+    const p = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    p.saveCodeVerifier('verifier-abc');
+    expect(p.codeVerifier()).toBe('verifier-abc');
+  });
+
+  it('codeVerifier is NOT persisted across instances', async () => {
+    const p1 = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    const p2 = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    p1.saveCodeVerifier('only-in-p1');
+    expect(() => p2.codeVerifier()).toThrow();
+  });
+});
+
+describe('StudioOAuthProvider — metadata', () => {
+  it('redirectUrl is undefined before startCallbackServer()', () => {
+    const p = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    expect(p.redirectUrl).toBeUndefined();
+  });
+
+  it('clientMetadata includes redirect_uri after server starts', async () => {
+    const p = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    const { close } = await p.startCallbackServer();
+    try {
+      const redirectUrl = p.redirectUrl;
+      expect(redirectUrl).toMatch(/^http:\/\/localhost:\d+\/callback$/);
+      const meta = p.clientMetadata;
+      expect(meta.client_name).toBe('Studio');
+      expect(meta.redirect_uris).toHaveLength(1);
+      expect(meta.redirect_uris[0].toString()).toMatch(/^http:\/\/localhost:\d+\/callback$/);
+    } finally {
+      close();
+    }
+  });
+});
+
+describe('StudioOAuthProvider — callback server', () => {
+  it('startCallbackServer() resolves codePromise when /callback?code=X is hit', async () => {
+    const p = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    const { codePromise, close } = await p.startCallbackServer();
+
+    const port = (p.redirectUrl as string).match(/:(\d+)/)![1];
+    const res = await fetch(`http://localhost:${port}/callback?code=auth-code-123`);
+    expect(res.ok).toBe(true);
+    expect(await codePromise).toBe('auth-code-123');
+    close();
+  });
+
+  it('callback response contains success HTML', async () => {
+    const p = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    const { close } = await p.startCallbackServer();
+
+    const port = (p.redirectUrl as string).match(/:(\d+)/)![1];
+    const res = await fetch(`http://localhost:${port}/callback?code=x`);
+    const html = await res.text();
+    expect(html).toContain('Authorization successful');
+    close();
+  });
+
+  it('codePromise rejects after timeout', async () => {
+    const p = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir, 50);
+    const { codePromise, close } = await p.startCallbackServer();
+    await expect(codePromise).rejects.toThrow('timed out');
+    close();
+  });
+
+  it('sets callbackPort so redirectUrl reflects the server port', async () => {
+    const p = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    expect(p.redirectUrl).toBeUndefined();
+    const { close } = await p.startCallbackServer();
+    expect(p.redirectUrl).toMatch(/^http:\/\/localhost:\d+\/callback$/);
+    close();
+  });
+
+  it('clears stale clientInformation but preserves tokens on startCallbackServer()', async () => {
+    const p = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    // Seed stale state: clientInformation with old redirect_uri + existing tokens
+    await p.saveClientInformation({ client_id: 'old-client', redirect_uris: ['http://localhost:9999/callback'] } as any);
+    await p.saveTokens({ access_token: 'tok', token_type: 'Bearer' });
+
+    const { close } = await p.startCallbackServer();
+    close();
+
+    expect(await p.clientInformation()).toBeUndefined();
+    expect(await p.tokens()).toEqual({ access_token: 'tok', token_type: 'Bearer' });
+  });
+});
+
+describe('StudioOAuthProvider — redirectToAuthorization', () => {
+  it('prints the authorization URL to stderr', async () => {
+    const p = new StudioOAuthProvider('https://mcp.example.com/mcp', tmpDir);
+    const written: string[] = [];
+    const spy = vi.spyOn(process.stderr, 'write').mockImplementation((s) => {
+      written.push(String(s));
+      return true;
+    });
+
+    await p.redirectToAuthorization(new URL('https://auth.example.com/authorize?foo=bar'));
+
+    spy.mockRestore();
+    expect(written.join('')).toContain('https://auth.example.com/authorize');
+  });
+});

package/src/plugins/oauth-provider.ts

@@ -0,0 +1,175 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { exec } from 'node:child_process';
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import type {
+  OAuthClientInformationMixed,
+  OAuthClientMetadata,
+  OAuthTokens,
+} from '@modelcontextprotocol/sdk/shared/auth.js';
+
+interface StorageData {
+  clientInformation?: OAuthClientInformationMixed;
+  tokens?: OAuthTokens;
+}
+
+function urlHash(url: string): string {
+  return createHash('sha256').update(url).digest('hex').slice(0, 16);
+}
+
+export class StudioOAuthProvider implements OAuthClientProvider {
+  private readonly filePath: string;
+  private _codeVerifier: string | undefined;
+  private _callbackPort: number | undefined;
+
+  constructor(
+    private readonly serverUrl: string,
+    private readonly storageDir: string = join(
+      process.env.HOME ?? process.env.USERPROFILE ?? '/tmp',
+      '.config', 'studio', 'oauth'
+    ),
+    private readonly timeoutMs: number = 5 * 60 * 1000
+  ) {
+    this.filePath = join(storageDir, `${urlHash(serverUrl)}.json`);
+  }
+
+  // --- Storage helpers ---
+
+  private async load(): Promise<StorageData> {
+    try {
+      const raw = await readFile(this.filePath, 'utf-8');
+      return JSON.parse(raw) as StorageData;
+    } catch {
+      return {};
+    }
+  }
+
+  private async save(data: StorageData): Promise<void> {
+    await mkdir(dirname(this.filePath), { recursive: true });
+    await writeFile(this.filePath, JSON.stringify(data, null, 2), 'utf-8');
+  }
+
+  // --- OAuthClientProvider: tokens ---
+
+  async tokens(): Promise<OAuthTokens | undefined> {
+    return (await this.load()).tokens;
+  }
+
+  async saveTokens(tokens: OAuthTokens): Promise<void> {
+    const data = await this.load();
+    await this.save({ ...data, tokens });
+  }
+
+  // --- OAuthClientProvider: client information ---
+
+  async clientInformation(): Promise<OAuthClientInformationMixed | undefined> {
+    return (await this.load()).clientInformation;
+  }
+
+  async saveClientInformation(info: OAuthClientInformationMixed): Promise<void> {
+    const data = await this.load();
+    await this.save({ ...data, clientInformation: info });
+  }
+
+  // --- OAuthClientProvider: PKCE ---
+
+  saveCodeVerifier(codeVerifier: string): void {
+    this._codeVerifier = codeVerifier;
+  }
+
+  codeVerifier(): string {
+    if (this._codeVerifier === undefined) {
+      throw new Error('No code verifier saved for this session');
+    }
+    return this._codeVerifier;
+  }
+
+  // --- OAuthClientProvider: metadata ---
+
+  get redirectUrl(): string | undefined {
+    if (this._callbackPort === undefined) return undefined;
+    return `http://localhost:${this._callbackPort}/callback`;
+  }
+
+  get clientMetadata(): OAuthClientMetadata {
+    const redirectUri = this.redirectUrl ?? 'http://localhost/callback';
+    return {
+      client_name: 'Studio',
+      redirect_uris: [redirectUri],
+    };
+  }
+
+  redirectToAuthorization(authorizationUrl: URL): void {
+    const url = authorizationUrl.toString();
+    process.stderr.write(`\n  Open this URL to authorize Studio:\n  ${url}\n\n`);
+
+    const cmd =
+      process.platform === 'darwin' ? `open "${url}"` :
+      process.platform === 'win32' ? `start "" "${url}"` :
+      `xdg-open "${url}"`;
+
+    exec(cmd, () => { /* ignore errors — URL already printed */ });
+  }
+
+  // --- Callback server ---
+
+  async startCallbackServer(): Promise<{ codePromise: Promise<string>; close: () => void }> {
+    let resolveCode!: (code: string) => void;
+    let rejectCode!: (err: Error) => void;
+    const codePromise = new Promise<string>((res, rej) => {
+      resolveCode = res;
+      rejectCode = rej;
+    });
+
+    const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+      const url = new URL(req.url ?? '/', 'http://localhost');
+      if (url.pathname === '/callback') {
+        const code = url.searchParams.get('code');
+        if (code) {
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end('<html><body><h1>Authorization successful</h1><p>You can close this tab.</p></body></html>');
+          resolveCode(code);
+        } else {
+          res.writeHead(400);
+          res.end('Missing code parameter');
+          rejectCode(new Error('OAuth callback missing code parameter'));
+        }
+      } else {
+        res.writeHead(404);
+        res.end();
+      }
+    });
+
+    await new Promise<void>((res, rej) => {
+      server.listen(0, 'localhost', res);
+      server.on('error', rej);
+    });
+
+    const { port } = server.address() as AddressInfo;
+    this._callbackPort = port;
+
+    // Clear stale client registration — redirect_uri changes with each new port.
+    // SDK will re-register with the current port's redirect_uri. Tokens are preserved.
+    const existing = await this.load();
+    if (existing.clientInformation) {
+      await this.save({ tokens: existing.tokens });
+    }
+
+    const timeout = setTimeout(() => {
+      rejectCode(new Error('OAuth authorization timed out. Run again to retry.'));
+      server.close();
+      this._callbackPort = undefined;
+    }, this.timeoutMs);
+
+    const close = () => {
+      clearTimeout(timeout);
+      server.close();
+      this._callbackPort = undefined;
+    };
+
+    return { codePromise, close };
+  }
+}