@metalabdesign/mcp-client 1.0.1

package/src/bin/metalab-mcp.ts

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+/**
+ * Metalab MCP Client - Zero-config connection to Metalab's MCP Gateway
+ *
+ * Usage:
+ *   metalab-mcp [options]
+ *
+ * The gateway URL is auto-detected from:
+ *   1. AWS SSM Parameter Store (requires AWS credentials)
+ *   2. MCP_SERVER_URL environment variable
+ *   3. Hardcoded production URL (fallback)
+ */
+
+import { spawn } from 'node:child_process';
+import { createProxy } from '../index.js';
+import { resolveGatewayUrl, getSourceDescription, DEFAULTS } from '../config/index.js';
+
+interface CliArgs {
+    profile?: string;
+    callbackUrl?: string;
+    tokenStorageDir?: string;
+    timeout?: number;
+    openBrowser?: boolean;
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    serviceTokens?: Record<string, string>;
+    inspect?: boolean;
+    help?: boolean;
+}
+
+function printBanner(config: {
+    gatewayUrl: string;
+    source: string;
+    profile?: string;
+    callbackUrl: string;
+    figmaToken?: string;
+    notionToken?: string;
+}): void {
+    const truncateUrl = (url: string, maxLen: number = 50): string => {
+        if (url.length <= maxLen) return url;
+        return url.substring(0, maxLen - 3) + '...';
+    };
+
+    const checkmark = '\u2713';
+    const cross = '\u2717';
+
+    console.error('');
+    console.error('\u2554' + '\u2550'.repeat(62) + '\u2557');
+    console.error('\u2551' + '                    Metalab MCP Client                        '.substring(0, 62) + '\u2551');
+    console.error('\u2560' + '\u2550'.repeat(62) + '\u2563');
+    console.error(`\u2551  Gateway URL: ${truncateUrl(config.gatewayUrl, 45).padEnd(46)}\u2551`);
+    console.error(`\u2551  Source:      ${config.source.padEnd(46)}\u2551`);
+    if (config.profile) {
+        console.error(`\u2551  AWS Profile: ${config.profile.padEnd(46)}\u2551`);
+    }
+    console.error(`\u2551  Callback:    ${truncateUrl(config.callbackUrl, 45).padEnd(46)}\u2551`);
+    console.error(`\u2551  Figma Token: ${(config.figmaToken ? `${checkmark} configured` : `${cross} not configured`).padEnd(46)}\u2551`);
+    console.error(`\u2551  Notion Token: ${(config.notionToken ? `${checkmark} configured` : `${cross} not configured`).padEnd(45)}\u2551`);
+    console.error('\u255A' + '\u2550'.repeat(62) + '\u255D');
+    console.error('');
+    console.error('Press Ctrl+C to stop');
+    console.error('');
+}
+
+function printHelp(): void {
+    console.error(`
+Metalab MCP Client - Zero-config connection to Metalab's MCP Gateway
+
+USAGE:
+  metalab-mcp [options]
+
+The gateway URL is automatically detected from:
+  1. AWS SSM Parameter Store (if AWS credentials available)
+  2. MCP_SERVER_URL environment variable
+  3. Hardcoded production URL (fallback)
+
+OPTIONS:
+  --profile <name>       AWS SSO profile to use for SSM lookup
+  --callback-url <url>   OAuth callback URL (default: ${DEFAULTS.CALLBACK_URL})
+  --token-dir <dir>      Directory for token storage (default: ${DEFAULTS.TOKEN_DIR})
+  --timeout <ms>         Request timeout in milliseconds (default: ${DEFAULTS.TIMEOUT_MS})
+  --no-browser           Don't auto-open browser for auth
+  --log-level <level>    Log level: debug, info, warn, error (default: info)
+  --figma-token <token>  Figma access token (or set FIGMA_ACCESS_TOKEN env var)
+  --notion-token <token> Notion access token (or set NOTION_ACCESS_TOKEN env var)
+  --inspect              Run with MCP Inspector for debugging
+  --help, -h             Show this help message
+
+EXAMPLES:
+  # Basic usage (auto-detects everything)
+  metalab-mcp
+
+  # With AWS SSO profile
+  metalab-mcp --profile metalab-dev
+
+  # With Figma token
+  metalab-mcp --figma-token figd_xxxxx
+
+  # Debug mode with inspector
+  metalab-mcp --inspect
+
+  # Via environment variables
+  FIGMA_ACCESS_TOKEN=figd_xxxxx metalab-mcp
+
+QUICK SETUP:
+  1. (Optional) Login to AWS SSO: aws sso login --profile metalab-dev
+  2. Generate config: npx @metalabdesign/mcp-client-config --client claude
+  3. Restart your MCP client (Claude Desktop, etc.)
+
+For more information, see:
+  https://github.com/metalabdesign/metalab-core-mcps
+`);
+}
+
+function parseArgs(argv: string[]): CliArgs {
+    const args: CliArgs = {
+        serviceTokens: {},
+    };
+    let i = 2; // Skip 'node' and script path
+
+    while (i < argv.length) {
+        const arg = argv[i];
+
+        switch (arg) {
+            case '--profile':
+                args.profile = argv[++i];
+                break;
+            case '--callback-url':
+                args.callbackUrl = argv[++i];
+                break;
+            case '--token-dir':
+                args.tokenStorageDir = argv[++i];
+                break;
+            case '--timeout':
+                args.timeout = Number.parseInt(argv[++i] ?? '', 10);
+                break;
+            case '--no-browser':
+                args.openBrowser = false;
+                break;
+            case '--log-level':
+                args.logLevel = argv[++i] as CliArgs['logLevel'];
+                break;
+            case '--figma-token':
+            case '--figma':
+                args.serviceTokens!.figma = argv[++i] ?? '';
+                break;
+            case '--notion-token':
+            case '--notion':
+                args.serviceTokens!.notion = argv[++i] ?? '';
+                break;
+            case '--inspect':
+                args.inspect = true;
+                break;
+            case '--help':
+            case '-h':
+                args.help = true;
+                break;
+            default:
+                if (arg?.startsWith('-')) {
+                    console.error(`Unknown option: ${arg}`);
+                    console.error('Run with --help for usage information');
+                    process.exit(1);
+                }
+        }
+        i++;
+    }
+
+    // Load service tokens from environment variables (fallback)
+    if (process.env.FIGMA_ACCESS_TOKEN) {
+        args.serviceTokens!.figma = args.serviceTokens!.figma || process.env.FIGMA_ACCESS_TOKEN;
+    }
+    if (process.env.NOTION_ACCESS_TOKEN) {
+        args.serviceTokens!.notion = args.serviceTokens!.notion || process.env.NOTION_ACCESS_TOKEN;
+    }
+
+    // Clean up empty serviceTokens object
+    if (Object.keys(args.serviceTokens!).length === 0) {
+        delete args.serviceTokens;
+    }
+
+    return args;
+}
+
+async function runWithInspector(args: CliArgs, gatewayUrl: string): Promise<void> {
+    // Build args for the inspector
+    const inspectorArgs = [
+        '@modelcontextprotocol/inspector',
+        'node',
+        new URL('../bin/cli.js', import.meta.url).pathname,
+        '--remote-url',
+        gatewayUrl + '/mcp',
+        '--callback-url',
+        args.callbackUrl || DEFAULTS.CALLBACK_URL,
+    ];
+
+    if (args.tokenStorageDir) {
+        inspectorArgs.push('--token-dir', args.tokenStorageDir);
+    }
+    if (args.timeout) {
+        inspectorArgs.push('--timeout', args.timeout.toString());
+    }
+    if (args.openBrowser === false) {
+        inspectorArgs.push('--no-browser');
+    }
+    if (args.logLevel) {
+        inspectorArgs.push('--log-level', args.logLevel);
+    }
+    if (args.serviceTokens?.figma) {
+        inspectorArgs.push('--figma-token', args.serviceTokens.figma);
+    }
+    if (args.serviceTokens?.notion) {
+        inspectorArgs.push('--notion-token', args.serviceTokens.notion);
+    }
+
+    console.error('Starting MCP Inspector...');
+    console.error('');
+
+    const child = spawn('npx', inspectorArgs, {
+        stdio: 'inherit',
+        shell: true,
+    });
+
+    child.on('exit', (code) => {
+        process.exit(code ?? 0);
+    });
+}
+
+async function main(): Promise<void> {
+    const args = parseArgs(process.argv);
+
+    if (args.help) {
+        printHelp();
+        process.exit(0);
+    }
+
+    // Resolve gateway URL
+    const config = await resolveGatewayUrl(args.profile);
+    const callbackUrl = args.callbackUrl || DEFAULTS.CALLBACK_URL;
+
+    // Print banner
+    printBanner({
+        gatewayUrl: config.gatewayUrl,
+        source: getSourceDescription(config.source),
+        profile: config.profile,
+        callbackUrl,
+        figmaToken: args.serviceTokens?.figma,
+        notionToken: args.serviceTokens?.notion,
+    });
+
+    // If --inspect flag, run with MCP Inspector
+    if (args.inspect) {
+        await runWithInspector(args, config.gatewayUrl);
+        return;
+    }
+
+    try {
+        const proxy = await createProxy({
+            remoteUrl: config.gatewayUrl + '/mcp',
+            callbackUrl,
+            tokenStorageDir: args.tokenStorageDir,
+            timeout: args.timeout,
+            openBrowser: args.openBrowser ?? true,
+            logLevel: args.logLevel ?? 'info',
+            serviceTokens: args.serviceTokens,
+        });
+
+        // Handle shutdown gracefully
+        const shutdown = async (): Promise<void> => {
+            console.error('Shutting down...');
+            await proxy.disconnect();
+            process.exit(0);
+        };
+
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+
+        // Start the proxy
+        await proxy.start();
+    } catch (error) {
+        console.error('Failed to start proxy:', error);
+        process.exit(1);
+    }
+}
+
+main();

package/src/config/aws-sso.ts

@@ -0,0 +1,78 @@
+import { execSync } from 'node:child_process';
+import { DEFAULTS } from './defaults.js';
+
+export interface AwsConfig {
+    gatewayUrl: string;
+    source: 'ssm' | 'env' | 'hardcoded';
+    profile?: string;
+}
+
+/**
+ * Resolution order:
+ * 1. AWS SSO/credentials → SSM Parameter Store → gateway URL
+ * 2. MCP_SERVER_URL environment variable
+ * 3. Hardcoded production URL (fallback)
+ */
+export async function resolveGatewayUrl(profile?: string): Promise<AwsConfig> {
+    // Try SSM Parameter Store first (requires AWS credentials)
+    const ssmUrl = await getUrlFromSsm(profile);
+    if (ssmUrl) {
+        return { gatewayUrl: ssmUrl, source: 'ssm', profile };
+    }
+
+    // Fallback to environment variable
+    const envUrl = process.env.MCP_SERVER_URL;
+    if (envUrl) {
+        return { gatewayUrl: envUrl, source: 'env' };
+    }
+
+    // Final fallback to hardcoded URL
+    return { gatewayUrl: DEFAULTS.GATEWAY_URL, source: 'hardcoded' };
+}
+
+async function getUrlFromSsm(profile?: string): Promise<string | null> {
+    try {
+        // Check if AWS CLI is available
+        execSync('which aws', { encoding: 'utf-8', stdio: 'pipe' });
+
+        // Build the AWS CLI command
+        const profileArg = profile ? `--profile ${profile}` : '';
+        const cmd = `aws ssm get-parameter ${profileArg} --name ${DEFAULTS.SSM_GATEWAY_URL_PARAM} --region ${DEFAULTS.AWS_REGION} --query 'Parameter.Value' --output text`;
+
+        const result = execSync(cmd, { encoding: 'utf-8', stdio: 'pipe' }).trim();
+        return result || null;
+    } catch {
+        // AWS CLI not available, not authenticated, or parameter doesn't exist
+        return null;
+    }
+}
+
+/**
+ * Check if AWS SSO session is active for the given profile
+ */
+export function isSsoAuthenticated(profile?: string): boolean {
+    try {
+        const profileArg = profile ? `--profile ${profile}` : '';
+        execSync(`aws sts get-caller-identity ${profileArg}`, {
+            encoding: 'utf-8',
+            stdio: 'pipe',
+        });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Get a human-readable description of the gateway URL source
+ */
+export function getSourceDescription(source: AwsConfig['source']): string {
+    switch (source) {
+        case 'ssm':
+            return 'SSM Parameter Store';
+        case 'env':
+            return 'MCP_SERVER_URL environment variable';
+        case 'hardcoded':
+            return 'Default (hardcoded)';
+    }
+}

package/src/config/defaults.ts

@@ -0,0 +1,26 @@
+/**
+ * Default configuration values for @metalabdesign/mcp-client
+ */
+export const DEFAULTS = {
+    // Production MCP Gateway URL (hardcoded fallback)
+    // This is the current API Gateway URL - will be updated if infrastructure changes
+    GATEWAY_URL: 'https://qe40bdp1jh.execute-api.us-east-2.amazonaws.com',
+
+    // SSM Parameter path for dynamic gateway URL
+    SSM_GATEWAY_URL_PARAM: '/mcp/gateway-url',
+
+    // AWS Region for SSM lookups
+    AWS_REGION: 'us-east-2',
+
+    // OAuth callback URL (matches Okta redirect URI configuration)
+    CALLBACK_URL: 'http://localhost:9861/oauth/callback',
+
+    // Token storage directory
+    TOKEN_DIR: '~/.metalab/mcp-client/tokens',
+
+    // Timeouts
+    TIMEOUT_MS: 30000,
+    AUTH_TIMEOUT_MS: 300000,
+} as const;
+
+export type Defaults = typeof DEFAULTS;

package/src/config/index.ts

@@ -0,0 +1,8 @@
+export { DEFAULTS } from './defaults.js';
+export type { Defaults } from './defaults.js';
+export {
+    resolveGatewayUrl,
+    isSsoAuthenticated,
+    getSourceDescription,
+} from './aws-sso.js';
+export type { AwsConfig } from './aws-sso.js';

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * MCP Local Proxy - Factory and exports
+ */
+
+import type { McpProxy } from './proxy.js';
+
+export interface CreateProxyOptions {
+  /** Remote MCP server URL */
+  remoteUrl: string;
+  /** OAuth callback URL (port is extracted from this URL) */
+  callbackUrl: string;
+  /** Directory for token storage */
+  tokenStorageDir?: string;
+  /** Custom headers for remote requests */
+  headers?: Record<string, string>;
+  /** Request timeout in ms (default: 30000) */
+  timeout?: number;
+  /** Auto-open browser for auth (default: true) */
+  openBrowser?: boolean;
+  /** Log level (default: 'info') */
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+  /** Service-specific access tokens (e.g., { figma: "token", notion: "token" }) */
+  serviceTokens?: Record<string, string>;
+}
+
+/**
+ * Create and configure an MCP OAuth proxy
+ */
+export async function createProxy(options: CreateProxyOptions): Promise<McpProxy> {
+  const { ProxyConfigSchema } = await import('./types.js');
+  const { TokenStorage } = await import('./storage.js');
+  const { OAuthManager } = await import('./oauth.js');
+  const { McpProxy } = await import('./proxy.js');
+  const { StderrLogger } = await import('./utils.js');
+
+  // Validate and parse configuration
+  const config = ProxyConfigSchema.parse({
+    remoteUrl: options.remoteUrl,
+    callbackUrl: options.callbackUrl,
+    tokenStorageDir: options.tokenStorageDir,
+    headers: options.headers,
+    timeout: options.timeout ?? 30000,
+    openBrowser: options.openBrowser ?? true,
+    serviceTokens: options.serviceTokens,
+  });
+
+  // Create components
+  const logger = new StderrLogger(options.logLevel ?? 'info');
+  const storage = new TokenStorage(config.tokenStorageDir);
+  const oauthManager = new OAuthManager(config, storage, logger);
+  const proxy = new McpProxy(config, oauthManager, logger);
+
+  return proxy;
+}