npm - @metalabdesign/mcp-client - Versions diffs - 1.0.1 - Mend

@metalabdesign/mcp-client 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (64) hide show

package/CHANGELOG.md +43 -0
package/README.md +243 -0
package/dist/bin/cli.d.ts +14 -0
package/dist/bin/cli.d.ts.map +1 -0
package/dist/bin/cli.js +216 -0
package/dist/bin/cli.js.map +1 -0
package/dist/bin/metalab-mcp-config.d.ts +9 -0
package/dist/bin/metalab-mcp-config.d.ts.map +1 -0
package/dist/bin/metalab-mcp-config.js +224 -0
package/dist/bin/metalab-mcp-config.js.map +1 -0
package/dist/bin/metalab-mcp.d.ts +14 -0
package/dist/bin/metalab-mcp.d.ts.map +1 -0
package/dist/bin/metalab-mcp.js +242 -0
package/dist/bin/metalab-mcp.js.map +1 -0
package/dist/config/aws-sso.d.ts +21 -0
package/dist/config/aws-sso.d.ts.map +1 -0
package/dist/config/aws-sso.js +67 -0
package/dist/config/aws-sso.js.map +1 -0
package/dist/config/defaults.d.ts +14 -0
package/dist/config/defaults.d.ts.map +1 -0
package/dist/config/defaults.js +20 -0
package/dist/config/defaults.js.map +1 -0
package/dist/config/index.d.ts +5 -0
package/dist/config/index.d.ts.map +1 -0
package/dist/config/index.js +3 -0
package/dist/config/index.js.map +1 -0
package/dist/index.d.ts +27 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +30 -0
package/dist/index.js.map +1 -0
package/dist/oauth.d.ts +34 -0
package/dist/oauth.d.ts.map +1 -0
package/dist/oauth.js +401 -0
package/dist/oauth.js.map +1 -0
package/dist/proxy.d.ts +39 -0
package/dist/proxy.d.ts.map +1 -0
package/dist/proxy.js +203 -0
package/dist/proxy.js.map +1 -0
package/dist/storage.d.ts +15 -0
package/dist/storage.d.ts.map +1 -0
package/dist/storage.js +64 -0
package/dist/storage.js.map +1 -0
package/dist/types.d.ts +78 -0
package/dist/types.d.ts.map +1 -0
package/dist/types.js +40 -0
package/dist/types.js.map +1 -0
package/dist/utils.d.ts +42 -0
package/dist/utils.d.ts.map +1 -0
package/dist/utils.js +89 -0
package/dist/utils.js.map +1 -0
package/package.json +51 -0
package/src/bin/cli.ts +242 -0
package/src/bin/metalab-mcp-config.ts +262 -0
package/src/bin/metalab-mcp.ts +284 -0
package/src/config/aws-sso.ts +78 -0
package/src/config/defaults.ts +26 -0
package/src/config/index.ts +8 -0
package/src/index.ts +54 -0
package/src/oauth.ts +540 -0
package/src/proxy.ts +274 -0
package/src/storage.ts +81 -0
package/src/types.ts +79 -0
package/src/utils.ts +115 -0
package/tsconfig.json +25 -0

package/src/oauth.ts ADDED Viewed

@@ -0,0 +1,540 @@
+/**
+ * OAuth 2.1 implementation with PKCE
+ * Handles metadata discovery, client registration, authorization flow, token management
+ */
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import type { Logger } from './utils.js';
+import { generateCodeChallenge, generateCodeVerifier, generateState, openBrowser } from './utils.js';
+import type { TokenStorage } from './storage.js';
+import type {
+  OAuthClientInfo,
+  OAuthServerMetadata,
+  OAuthTokens,
+  ProxyConfig,
+} from './types.js';
+import { OAuthError } from './types.js';
+// Constants
+const AUTH_TIMEOUT_MS = 300000; // 5 minutes
+const TOKEN_REFRESH_BUFFER_MS = 60000; // Refresh 1 minute before expiry
+// ==================== HTTP Utilities ====================
+interface TokenResponse {
+  access_token: string;
+  token_type: string;
+  expires_in?: number;
+  refresh_token?: string;
+  scope?: string;
+}
+interface RegistrationResponse {
+  client_id: string;
+  client_secret?: string;
+  redirect_uris: string[];
+}
+// ==================== Callback Server ====================
+interface PendingCallback {
+  resolve: (result: { code: string } | { error: string }) => void;
+  timeout: NodeJS.Timeout;
+}
+function createSuccessPage(): string {
+  return `<!DOCTYPE html>
+<html>
+<head>
+  <title>Authorization Complete</title>
+  <style>
+    body { font-family: system-ui, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #f5f5f5; }
+    .card { background: white; padding: 2rem; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); text-align: center; max-width: 400px; }
+    h1 { color: #22c55e; margin-bottom: 0.5rem; }
+    p { color: #666; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>✓ Authorization Complete</h1>
+    <p>You can close this window and return to your terminal.</p>
+  </div>
+</body>
+</html>`;
+}
+function createErrorPage(error: string): string {
+  const escaped = error
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+  return `<!DOCTYPE html>
+<html>
+<head>
+  <title>Authorization Failed</title>
+  <style>
+    body { font-family: system-ui, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #f5f5f5; }
+    .card { background: white; padding: 2rem; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); text-align: center; max-width: 400px; }
+    h1 { color: #ef4444; margin-bottom: 0.5rem; }
+    p { color: #666; }
+    .error { background: #fef2f2; padding: 1rem; border-radius: 4px; color: #991b1b; margin-top: 1rem; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>✗ Authorization Failed</h1>
+    <p>Something went wrong during authorization.</p>
+    <div class="error">${escaped}</div>
+  </div>
+</body>
+</html>`;
+}
+class CallbackServer {
+  private server: Server | null = null;
+  private pendingCallbacks = new Map<string, PendingCallback>();
+  private callbackPath: string;
+  constructor(callbackPath: string) {
+    this.callbackPath = callbackPath;
+  }
+  async start(port: number): Promise<void> {
+    if (this.server) return;
+    return new Promise((resolve, reject) => {
+      this.server = createServer((req, res) => this.handleRequest(req, res));
+      this.server.on('error', reject);
+      this.server.listen(port, '127.0.0.1', () => resolve());
+    });
+  }
+  private handleRequest(req: IncomingMessage, res: ServerResponse): void {
+    const url = new URL(req.url ?? '/', `http://${req.headers.host}`);
+    if (url.pathname !== this.callbackPath) {
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      res.end('Not Found');
+      return;
+    }
+    const code = url.searchParams.get('code');
+    const state = url.searchParams.get('state');
+    const error = url.searchParams.get('error');
+    const errorDescription = url.searchParams.get('error_description');
+    if (!state) {
+      res.writeHead(400, { 'Content-Type': 'text/html' });
+      res.end(createErrorPage('Missing state parameter'));
+      return;
+    }
+    const pending = this.pendingCallbacks.get(state);
+    if (!pending) {
+      res.writeHead(400, { 'Content-Type': 'text/html' });
+      res.end(createErrorPage('Invalid or expired state'));
+      return;
+    }
+    clearTimeout(pending.timeout);
+    this.pendingCallbacks.delete(state);
+    if (error) {
+      const errorMessage = errorDescription ?? error;
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(createErrorPage(errorMessage));
+      pending.resolve({ error: errorMessage });
+      return;
+    }
+    if (!code) {
+      res.writeHead(400, { 'Content-Type': 'text/html' });
+      res.end(createErrorPage('Missing authorization code'));
+      pending.resolve({ error: 'Missing authorization code' });
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end(createSuccessPage());
+    pending.resolve({ code });
+  }
+  waitForCallback(state: string, timeoutMs: number): Promise<{ code: string } | { error: string }> {
+    return new Promise((resolve) => {
+      const timeout = setTimeout(() => {
+        this.pendingCallbacks.delete(state);
+        resolve({ error: 'Authorization timed out' });
+      }, timeoutMs);
+      this.pendingCallbacks.set(state, { resolve, timeout });
+    });
+  }
+  async stop(): Promise<void> {
+    if (!this.server) return;
+    for (const [state, pending] of this.pendingCallbacks) {
+      clearTimeout(pending.timeout);
+      pending.resolve({ error: 'Server stopped' });
+      this.pendingCallbacks.delete(state);
+    }
+    return new Promise((resolve) => {
+      this.server?.close(() => {
+        this.server = null;
+        resolve();
+      });
+    });
+  }
+}
+// ==================== OAuth Manager ====================
+interface ClientRegistration {
+  metadata: OAuthServerMetadata;
+  client: OAuthClientInfo;
+}
+export class OAuthManager {
+  private clientRegistration: ClientRegistration | null = null;
+  private callbackServer: CallbackServer;
+  private readonly callbackPort: number;
+  constructor(
+    private readonly config: ProxyConfig,
+    private readonly storage: TokenStorage,
+    private readonly logger: Logger
+  ) {
+    const callbackUrl = new URL(config.callbackUrl);
+    this.callbackServer = new CallbackServer(callbackUrl.pathname);
+    // Extract port from callback URL, default to 9876 if not specified
+    this.callbackPort = callbackUrl.port ? Number.parseInt(callbackUrl.port, 10) : 9876;
+  }
+  /**
+   * Get a valid access token, refreshing or re-authenticating as needed
+   */
+  async getAccessToken(): Promise<string> {
+    let tokens = await this.storage.load(this.config.remoteUrl);
+    if (tokens) {
+      if (this.isTokenValid(tokens)) {
+        this.logger.debug('Using existing valid token');
+        return tokens.accessToken;
+      }
+      if (tokens.refreshToken) {
+        try {
+          tokens = await this.refreshToken(tokens.refreshToken);
+          this.logger.info('Token refreshed successfully');
+          return tokens.accessToken;
+        } catch (error) {
+          this.logger.warn('Token refresh failed, re-authenticating', error);
+        }
+      }
+    }
+    tokens = await this.performAuthorization();
+    return tokens.accessToken;
+  }
+  /**
+   * Clear stored tokens
+   */
+  async clearTokens(): Promise<void> {
+    await this.storage.delete(this.config.remoteUrl);
+    this.logger.info('Tokens cleared');
+  }
+  private isTokenValid(tokens: OAuthTokens): boolean {
+    if (!tokens.expiresAt) return true;
+    return tokens.expiresAt > Date.now() + TOKEN_REFRESH_BUFFER_MS;
+  }
+  private async ensureClientRegistration(): Promise<ClientRegistration> {
+    if (this.clientRegistration) {
+      return this.clientRegistration;
+    }
+    this.logger.info('Discovering OAuth metadata...');
+    const metadata = await this.discoverMetadata(this.config.remoteUrl);
+    if (!metadata) {
+      throw new OAuthError(
+        'Server does not support OAuth 2.1 (no metadata found)',
+        'NO_OAUTH_METADATA'
+      );
+    }
+    this.logger.debug('OAuth metadata discovered', {
+      issuer: metadata.issuer,
+      hasRegistration: !!metadata.registrationEndpoint
+    });
+    this.logger.info('Registering OAuth client...');
+    const client = await this.registerClient(metadata, this.config.callbackUrl);
+    this.logger.debug('Client registered', { clientId: client.clientId });
+    this.clientRegistration = { metadata, client };
+    return this.clientRegistration;
+  }
+  // ==================== OAuth Protocol Methods ====================
+  private async discoverMetadata(serverUrl: string): Promise<OAuthServerMetadata | null> {
+    const baseUrl = new URL(serverUrl);
+    const wellKnownPaths = [
+      '/.well-known/oauth-authorization-server',
+      '/.well-known/openid-configuration',
+    ];
+    for (const path of wellKnownPaths) {
+      try {
+        const metadataUrl = new URL(path, baseUrl);
+        const response = await fetch(metadataUrl.toString(), {
+          method: 'GET',
+          headers: { 'Accept': 'application/json' },
+          signal: AbortSignal.timeout(this.config.timeout),
+        });
+        if (response.ok) {
+          const data = await response.json() as Record<string, unknown>;
+          return this.parseMetadata(data, baseUrl);
+        }
+      } catch {
+        // Continue to next path
+      }
+    }
+    return null;
+  }
+  private parseMetadata(data: Record<string, unknown>, baseUrl: URL): OAuthServerMetadata {
+    const getString = (key: string): string | undefined => {
+      const value = data[key];
+      return typeof value === 'string' ? value : undefined;
+    };
+    const getStringArray = (key: string): string[] | undefined => {
+      const value = data[key];
+      return Array.isArray(value) && value.every(v => typeof v === 'string') ? value : undefined;
+    };
+    const authorizationEndpoint = getString('authorization_endpoint');
+    const tokenEndpoint = getString('token_endpoint');
+    if (!authorizationEndpoint || !tokenEndpoint) {
+      throw new OAuthError(
+        'Invalid metadata: missing required endpoints',
+        'INVALID_METADATA'
+      );
+    }
+    return {
+      issuer: getString('issuer') ?? baseUrl.origin,
+      authorizationEndpoint,
+      tokenEndpoint,
+      registrationEndpoint: getString('registration_endpoint'),
+      jwksUri: getString('jwks_uri'),
+      scopesSupported: getStringArray('scopes_supported'),
+      responseTypesSupported: getStringArray('response_types_supported') ?? ['code'],
+      codeChallengeMethodsSupported: getStringArray('code_challenge_methods_supported'),
+    };
+  }
+  private async registerClient(
+    metadata: OAuthServerMetadata,
+    redirectUri: string
+  ): Promise<OAuthClientInfo> {
+    if (!metadata.registrationEndpoint) {
+      throw new OAuthError(
+        'Server does not support dynamic client registration',
+        'REGISTRATION_NOT_SUPPORTED'
+      );
+    }
+    const registrationRequest = {
+      client_name: 'MCP OAuth Proxy',
+      redirect_uris: [redirectUri],
+      grant_types: ['authorization_code', 'refresh_token'],
+      response_types: ['code'],
+      token_endpoint_auth_method: 'none',
+    };
+    const response = await fetch(metadata.registrationEndpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+      },
+      body: JSON.stringify(registrationRequest),
+      signal: AbortSignal.timeout(this.config.timeout),
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new OAuthError(
+        `Client registration failed: ${errorText}`,
+        'REGISTRATION_FAILED',
+        { status: response.status }
+      );
+    }
+    const data = await response.json() as RegistrationResponse;
+    return {
+      clientId: data.client_id,
+      clientSecret: data.client_secret,
+      redirectUri,
+    };
+  }
+  private async performAuthorization(): Promise<OAuthTokens> {
+    const { metadata, client } = await this.ensureClientRegistration();
+    await this.callbackServer.start(this.callbackPort);
+    this.logger.debug('Callback server started on port', this.callbackPort);
+    try {
+      // Generate PKCE parameters
+      const state = generateState();
+      const codeVerifier = generateCodeVerifier();
+      const codeChallenge = generateCodeChallenge(codeVerifier);
+      // Build authorization URL
+      const authUrl = new URL(metadata.authorizationEndpoint);
+      authUrl.searchParams.set('response_type', 'code');
+      authUrl.searchParams.set('client_id', client.clientId);
+      authUrl.searchParams.set('redirect_uri', client.redirectUri);
+      authUrl.searchParams.set('state', state);
+      authUrl.searchParams.set('code_challenge', codeChallenge);
+      authUrl.searchParams.set('code_challenge_method', 'S256');
+      if (metadata.scopesSupported && metadata.scopesSupported.length > 0) {
+        authUrl.searchParams.set('scope', metadata.scopesSupported.join(' '));
+      }
+      this.logger.info('Authorization required. Opening browser...');
+      this.logger.info(`Authorization URL: ${authUrl.toString()}`);
+      if (this.config.openBrowser) {
+        await openBrowser(authUrl.toString());
+      }
+      // Wait for callback
+      this.logger.info('Waiting for authorization...');
+      const result = await this.callbackServer.waitForCallback(state, AUTH_TIMEOUT_MS);
+      if ('error' in result) {
+        throw new OAuthError(
+          `Authorization failed: ${result.error}`,
+          'AUTHORIZATION_FAILED'
+        );
+      }
+      // Exchange code for tokens
+      this.logger.debug('Exchanging code for tokens...');
+      const tokens = await this.exchangeCode(metadata, client, result.code, codeVerifier);
+      await this.storage.save(this.config.remoteUrl, tokens);
+      this.logger.info('Authorization complete, tokens saved');
+      return tokens;
+    } finally {
+      await this.callbackServer.stop();
+      this.logger.debug('Callback server stopped');
+    }
+  }
+  private async exchangeCode(
+    metadata: OAuthServerMetadata,
+    client: OAuthClientInfo,
+    code: string,
+    codeVerifier: string
+  ): Promise<OAuthTokens> {
+    const body = new URLSearchParams({
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: client.redirectUri,
+      client_id: client.clientId,
+      code_verifier: codeVerifier,
+    });
+    if (client.clientSecret) {
+      body.set('client_secret', client.clientSecret);
+    }
+    const response = await fetch(metadata.tokenEndpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'Accept': 'application/json',
+      },
+      body: body.toString(),
+      signal: AbortSignal.timeout(this.config.timeout),
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new OAuthError(
+        `Token exchange failed: ${errorText}`,
+        'TOKEN_EXCHANGE_FAILED',
+        { status: response.status }
+      );
+    }
+    const data = await response.json() as TokenResponse;
+    return this.parseTokenResponse(data);
+  }
+  private async refreshToken(refreshToken: string): Promise<OAuthTokens> {
+    const { metadata, client } = await this.ensureClientRegistration();
+    const body = new URLSearchParams({
+      grant_type: 'refresh_token',
+      refresh_token: refreshToken,
+      client_id: client.clientId,
+    });
+    if (client.clientSecret) {
+      body.set('client_secret', client.clientSecret);
+    }
+    const response = await fetch(metadata.tokenEndpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'Accept': 'application/json',
+      },
+      body: body.toString(),
+      signal: AbortSignal.timeout(this.config.timeout),
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new OAuthError(
+        `Token refresh failed: ${errorText}`,
+        'TOKEN_REFRESH_FAILED',
+        { status: response.status }
+      );
+    }
+    const data = await response.json() as TokenResponse;
+    const tokens = this.parseTokenResponse(data);
+    await this.storage.save(this.config.remoteUrl, tokens);
+    return tokens;
+  }
+  private parseTokenResponse(data: TokenResponse): OAuthTokens {
+    return {
+      accessToken: data.access_token,
+      tokenType: data.token_type,
+      refreshToken: data.refresh_token,
+      expiresAt: data.expires_in ? Date.now() + data.expires_in * 1000 : undefined,
+      scope: data.scope,
+    };
+  }
+}