Bridge Commander (deprecated - moving to @civic/nexus-bridge)

⚠️ DEPRECATION NOTICE: This package is being renamed to @civic/nexus-bridge. Please use the new package name for future installations:

npx @civic/nexus-bridge install claude-desktop

A CLI tool that bridges stdio-based Model Context Protocol (MCP) clients with HTTP/SSE-based MCP servers, while handling authentication.

Overview

Bridge Commander connects local MCP clients (such as Claude Desktop) using stdio transport with remote MCP servers using HTTP/SSE transport. It handles authentication flows for both the Civic identity service and third-party services that require OAuth.

Easy Installation for Claude Desktop

The bridge commander provides a convenient installer command that automatically configures Claude Desktop to use Civic's MCP servers:

npx @civic/mcp-bridge-commander install claude-desktop

Then just start Claude Desktop.

Requirements

• Node.js >= 18.0.0

Architecture

The Bridge Commander follows a modular architecture with clear separation of concerns:

Core Components

1. Bridge (bridge.ts)

   • Core functionality that connects stdio and SSE transports
   • Manages message forwarding between client and server
   • Handles service-specific authentication flows

2. Auth Provider (authProvider.ts)

   • Implements the OAuth client interface for Civic authentication
   • Manages PKCE flow and token storage
   • Provides client information to the server

3. Callback Server (callbackServer.ts)

   • Creates a local HTTP server to receive OAuth redirects
   • Implements dynamic port selection to avoid conflicts
   • Handles token exchange after authorization

4. Token Store (tokenStore.ts)

   • Manages secure storage of authentication tokens
   • Provides methods for storing and retrieving different token types
   • Handles file system operations for persistence

5. OIDC Configuration (oidc.ts)

   • Fetches OpenID Connect configuration from discovery endpoints
   • Provides fallback values if discovery fails
   • Caches configuration for improved performance

6. Configuration (config.ts)

   • Centralizes all configuration values
   • Loads environment variables with sensible defaults
   • Defines client and server information

7. Type Definitions (types.ts)

   • Contains shared type definitions and interfaces
   • Includes helpers for type checking

Authentication Flow

1. Civic Authentication

   • Automatically initiated when the bridge starts
   • Uses PKCE (Proof Key for Code Exchange) for enhanced security
   • Discovers the authorization endpoint using OpenID Connect discovery
   • Opens a browser window to the correct Civic auth URL during first startup
   • Stores tokens locally for subsequent uses
   • The MCP SDK proactively attempts authentication at startup rather than waiting for the first request
   • The bridge overrides the default SDK behavior to use the correct auth server URL

2. Service-Specific Authentication

   • Intercepts auth URL errors from the server
   • Opens browser for user authorization
   • Manages callback and token exchange
   • Continues the original request after authentication

Usage

Installation for Claude Desktop

For the easiest setup with Claude Desktop:

npx @civic/mcp-bridge-commander install claude-desktop

Then launch Claude Desktop and select "Civic" from the list of MCP providers in settings.

Available Install Targets

The bridge commander supports automatic installation for:

• claude-desktop - Configures Claude Desktop (macOS only)
• claude-code - Configures Claude Code (CLI tool)

Environment Variables

• MCP_REMOTE_URL: URL of the remote MCP server (default: 'https://ai.civic.com/api/hub/mcp/sse')
• CIVIC_AUTH_URL: URL of the Civic auth service (default: 'https://auth.civic.com/oauth')
• CIVIC_AUTH_CLIENT_ID: OAuth client ID for authentication
• NO_LOGIN: When set to 'true', bypasses the authentication process and uses a public configuration. With this option enabled, you will not be asked to login when using the Civic MCP hub, but will instead access a limited set of servers available to the public.
• NO_AUTH_CAPTURE: When set to 'true', disables third-party service authorization prompts. The bridge will not attempt to open authorization URLs in the browser when services require authentication.
• CALLBACK_PORT: Port for the OAuth callback server (default: 8976)

Development

1. Install dependencies: yarn install
2. Build the project: yarn build
3. Run in development mode: yarn dev

Logger Utility

The Bridge Commander includes a powerful centralized logging utility that provides consistent formatting, configurable log levels, and sensitive data masking. The logger helps maintain clean, structured logs while ensuring that sensitive information like tokens and secrets are never exposed in logs.

Features

• Log Levels: ERROR, WARN, INFO, DEBUG, TRACE
• Sensitive Data Masking: Automatically detects and masks tokens, API keys, and other sensitive information
• Configurable Output: Enable/disable timestamps, JSON formatting, and other output options
• Environment Configuration: Configure logging behavior through environment variables
• Module/Component Tagging: Tag logs with component names for better context
• Circular Reference Handling: Safely logs objects with circular references without crashing
• Deep Object Inspection: Recursively masks sensitive data in deeply nested objects

Usage

import { logger } from './utils/logger.js';

// Basic usage
logger.info('Server started on port 3000');
logger.debug('Processing request:', requestData);
logger.error('Failed to connect to remote server:', error);

// With objects (sensitive data is automatically masked)
logger.info('User authenticated:', { 
  user: 'username',
  accessToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  permissions: ['read', 'write']
});

// Creating a component-specific logger
import { Logger, LogLevel } from './utils/logger.js';

const authLogger = new Logger({
  name: 'auth-service',
  level: LogLevel.DEBUG,
  includeTimestamps: true
});

authLogger.info('Processing authentication request');

// Safe handling of circular references
const circularObj = { name: 'Circular Object' };
circularObj.self = circularObj; // Creates circular reference
logger.info('Object with circular reference:', circularObj); // Won't crash

Environment Configuration

The logger can be configured through environment variables:

• LOG_LEVEL: Set the log level (error, warn, info, debug, trace)
• DEBUG=true: Shorthand to set log level to DEBUG
• LOG_TIMESTAMPS=true: Include ISO timestamps in log output
• MASK_SENSITIVE_DATA=false: Disable sensitive data masking (not recommended for production)

Example:

LOG_LEVEL=debug LOG_TIMESTAMPS=true node dist/index.js