@civic/hub-bridge/README.md

Stdio <-> HTTP/SSE MCP bridge with Civic auth handling

# Hub Bridge

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

## Overview

Hub Bridge 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 hub bridge provides a convenient installer command that automatically configures Claude Desktop to use Civic's MCP servers:

```bash
npx @civic/hub-bridge install claude-desktop
```

Then just start Claude Desktop.

## Requirements

- Node.js >= 18.0.0

## Architecture

The Hub Bridge 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:

```bash
npx @civic/hub-bridge install claude-desktop
```

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

### Available Install Targets

The hub bridge 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://nexus.civic.com/hub/mcp')
- `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: `pnpm install`
2. Build the project: `pnpm build`
3. Run in development mode: `pnpm dev`

### 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:
```bash
LOG_LEVEL=debug LOG_TIMESTAMPS=true node dist/index.js
```