npm package: @majkapp/mcp-http-bridge
Description: A generic stdio MCP to HTTP API bridge that exposes OpenAPI endpoints as MCP tools
Author: Majk
Latest version: 1.6.0

# MCP HTTP Bridge

A generic stdio MCP (Model Context Protocol) to HTTP API bridge that exposes OpenAPI endpoints as MCP tools for use with Claude and other AI assistants.

## 🚀 Features

- **OpenAPI/Swagger Support**: Automatically generate MCP tools from OpenAPI 3.0 specifications
- **Multiple Spec Sources**: Load from local files, remote URLs, or inline content
- **Flexible Authentication**: Bearer tokens, Basic auth, API keys, custom headers, or token files
- **Fast & Lightweight**: Optimized for quick responses with configurable timeouts and retries
- **CLI Integration**: Easy command-line interface with comprehensive options
- **Standalone Executable**: Self-contained 628K executable with zero dependencies - perfect for Electron apps and containers
- **MCP Config Generation**: Generate ready-to-use MCP server configurations (uses npx by default)
- **Filtering & Validation**: Filter tools by tags or operation IDs, validate API responses
- **Real-time Testing**: Built-in integration tests with fast execution
- **Secure Token Management**: Load sensitive tokens from files instead of command line
- **Dynamic Token Reading**: Auth files are read fresh on each API call, enabling token rotation
- **Advanced Tool Filtering**: Whitelist/blacklist tools with `--allowed-tools` and `--disallowed-tools`
- **Cascade Parameter System**: Set fixed/context parameters that cannot be overridden by agents for enhanced security
- **Comprehensive Logging**: Enhanced debugging with `--log` to capture invocation parameters and file contents
- **Tool Discovery**: Built-in discovery mode to explore available tools before deployment
- **Command-line Tool Invocation**: Test individual API endpoints directly from the command line
- **Custom Mappings**: Configure tool behavior with mappings files for parameter transformation and response formatting
- **Custom Tool Mappings**: Create semantic, workflow-oriented tool names with fixed parameters - multiple tools per endpoint supported

## 📦 Installation

### Global Installation (Recommended)
```bash
npm install -g @majkapp/mcp-http-bridge
```

### Local Installation
```bash
npm install @majkapp/mcp-http-bridge
```

### Standalone Executable (New in v1.6.0)
For environments where you need a self-contained executable without Node.js dependencies (perfect for Electron apps and containerized deployments):

```bash
# Install the package first
npm install -g @majkapp/mcp-http-bridge

# Use the standalone executable
mcp-http-bridge-standalone --spec ./api.yaml --auth-bearer "token"
```

**Key Benefits:**
- **🎯 Zero Dependencies**: Single 628K file with all dependencies bundled
- **⚡ Direct Execution**: No `node_modules/` required
- **📦 Electron-Friendly**: Perfect for Electron app packaging  
- **🚀 Container-Ready**: Ideal for Docker images and serverless deployments
- **🔒 Same Functionality**: All CLI options and features preserved

**File Location:**
```bash
# After npm install, the standalone executable is available at:
node_modules/@majkapp/mcp-http-bridge/dist/mcp-http-bridge-standalone.cjs

# Or use directly via npx:
npx @majkapp/mcp-http-bridge-standalone --spec ./api.yaml
```

## 🎯 Quick Start

### 1. Basic Usage
```bash
# Using an OpenAPI spec file
mcp-http-bridge --spec ./api.yaml

# Fetch OpenAPI spec from URL
mcp-http-bridge --spec-url https://api.example.com/openapi.json

# Using inline spec content
mcp-http-bridge --spec-content '{"openapi":"3.0.0",...}'
```

### 2. With Authentication
```bash
# Bearer token from command line
mcp-http-bridge --spec ./api.yaml --auth-bearer "your-token-here"

# Bearer token from file (secure approach - read dynamically on each request)
mcp-http-bridge --spec ./api.yaml --auth-file ./token.txt

# API key in header
mcp-http-bridge --spec ./api.yaml --auth-api-key "X-API-Key:your-key"

# Basic authentication
mcp-http-bridge --spec ./api.yaml --auth-basic "username:password"

# Custom headers
mcp-http-bridge --spec ./api.yaml --auth-custom-headers '{"Authorization":"Bearer token"}'
```

### 3. With Cascade Parameters (Security & Control)
```bash
# Set fixed parameters that agents cannot override
mcp-http-bridge --spec ./api.yaml --cascade 'user_id=12345!' --cascade 'tenant=acme-corp!'

# Route-specific restrictions
mcp-http-bridge --spec ./api.yaml --cascade '@createUser:read_only=true!' --cascade '@deleteUser:require_approval=true!'

# Load configuration from file with environment variables
mcp-http-bridge --spec ./api.yaml --cascade-file ./cascade-config.yaml --cascade 'session_id=${ENV.SESSION_ID}!'
```

**Auth File Format Examples:**
```bash
# token.txt can contain any of these formats:
echo "Bearer sk-your-token-123" > token.txt              # Bearer token
echo "Basic dXNlcjpwYXNzd29yZA==" > token.txt            # Basic auth  
echo "sk-your-token-123" > token.txt                     # Raw token (auto-prefixed with Bearer)

# Tilde paths are supported (expanded to home directory):
echo "Bearer sk-token" > ~/.majk/.majk.token             # ~/path/to/file
echo "Bearer sk-token" > ~/.config/mcp/token.txt         # Nested directories
```

### 4. Generate MCP Configuration
```bash
# Generate MCP server config (uses npx by default)
mcp-http-bridge --spec ./api.yaml --mcp-config my-api-server

# Generate config with URL and auth file
mcp-http-bridge --spec-url https://api.example.com/openapi.json --auth-file ./token.txt --mcp-config my-api

# Generate config with custom command path
mcp-http-bridge --spec ./api.yaml --command-path /usr/local/bin/mcp-http-bridge --mcp-config my-api
```

## 🔧 CLI Options

| Option | Description | Example |
|--------|-------------|---------|
| `--spec <path>` | Path to OpenAPI specification file | `--spec ./api.yaml` |
| `--spec-url <url>` | URL to OpenAPI specification | `--spec-url https://api.example.com/openapi.json` |
| `--spec-content <content>` | OpenAPI spec as string | `--spec-content '{...}'` |
| `--auth-file <path>` | Path to file containing auth token (supports ~) | `--auth-file ~/.majk/.majk.token` |
| `--base-url <url>` | Override base URL | `--base-url https://api.example.com` |
| `--auth-bearer <token>` | Bearer token auth | `--auth-bearer "jwt-token"` |
| `--auth-basic <user:pass>` | Basic authentication | `--auth-basic "user:pass"` |
| `--auth-api-key <header:key>` | API key in header | `--auth-api-key "X-API-Key:key"` |
| `--auth-api-key-query <param:key>` | API key in query | `--auth-api-key-query "apikey:key"` |
| `--auth-custom-headers <json>` | Custom headers | `--auth-custom-headers '{"X-Custom":"value"}'` |
| `--timeout <ms>` | Request timeout | `--timeout 5000` |
| `--retries <count>` | Number of retries | `--retries 3` |
| `--rate-limit <rps>` | Max requests per second | `--rate-limit 10` |
| `--tag-filter <tags>` | Filter by tags | `--tag-filter "users,posts"` |
| `--operation-filter <ids>` | Filter by operation IDs | `--operation-filter "getUser,createPost"` |
| `--allowed-tools <tools>` | Whitelist specific tools | `--allowed-tools "getUser,createPost"` |
| `--disallowed-tools <tools>` | Blacklist specific tools | `--disallowed-tools "deleteUser,deletePost"` |
| `--mappings-file <path>` | Use custom tool mappings | `--mappings-file ./mappings.json` |
| `--generate-mappings <path>` | Generate initial mappings file | `--generate-mappings ./mappings.json` |
| `--discover` | Discover available tools and exit | `--discover` |
| `--discover-format <format>` | Discovery output format | `--discover-format json` |
| `--invoke <tool-name>` | Invoke a specific tool | `--invoke getUser` |
| `--invoke-params <json>` | JSON parameters for invocation | `--invoke-params '{"id":123}'` |
| `--param <key=value>` | Key-value parameters (multiple) | `--param id=123 --param name=John` |
| `--validate-responses` | Validate API responses | `--validate-responses` |
| `--include-deprecated` | Include deprecated operations | `--include-deprecated` |
| `--mcp-config [name]` | Generate MCP config | `--mcp-config my-server` |
| `--cascade <param>` | Set fixed/context parameters (multiple) | `--cascade 'user_id=123!'` |
| `--cascade-file <path>` | Load cascade configuration file | `--cascade-file ./cascade.yaml` |
| `--command-path <path>` | Command for MCP config | `--command-path mcp-http-bridge` |
| `--verbose` | Enable verbose logging | `--verbose` |
| `--debug` | Enable debug logging | `--debug` |
| `--log <file>` | Log detailed debug information | `--log debug.log` |

## 🔗 Cascade Parameter System

The cascade parameter system enables you to set **fixed parameters** that cannot be overridden by MCP agents, providing enhanced security, consistency, and control over API interactions.

### 🎯 Key Benefits

- **Security**: Fix critical parameters like user IDs, tenant IDs, and permissions
- **Consistency**: Ensure certain values remain constant across all operations
- **Multi-tenancy**: Enforce tenant isolation automatically
- **Compliance**: Meet audit requirements with immutable parameters
- **Flexibility**: Apply parameters globally or to specific operations

### ⚡ Quick Examples

```bash
# Fix user identity across all operations
mcp-http-bridge --spec ./api.yaml --cascade 'user_id=12345!' --cascade 'tenant=acme-corp!'

# Apply different restrictions to specific operations
mcp-http-bridge --spec ./api.yaml --cascade '@createUser:permissions=read!' --cascade '@deleteUser:require_approval=true!'

# Load configuration from file
mcp-http-bridge --spec ./api.yaml --cascade-file ./cascade-config.yaml

# Use environment variables for sensitive values
mcp-http-bridge --spec ./api.yaml --cascade 'api_key=${ENV.API_SECRET}!' --cascade 'user_id=${ENV.USER_ID}!'
```

### 📝 Parameter Formats

| Format | Description | Example | Effect |
|--------|-------------|---------|--------|
| `param=value` | Context parameter | `--cascade 'debug=true'` | Agent can override |
| `param=value!` | **Fixed parameter** | `--cascade 'user_id=123!'` | **Agent CANNOT override** |
| `@route:param=value` | Route-specific context | `--cascade '@getUser:include_profile=true'` | Applied only to `getUser` operations |
| `@route:param=value!` | **Route-specific fixed** | `--cascade '@delete*:read_only=true!'` | **Fixed for matching routes** |
| `%PROFILE:name` | Load profile | `--cascade '%PROFILE:production'` | Activate named profile from config |
| `${ENV.VAR}` | Environment variable | `--cascade 'token=${ENV.API_TOKEN}!'` | Substitute from environment |

### 🏗️ Configuration Files

#### YAML Format (Recommended)
```yaml
# Global parameters applied to all routes
global:
  user_id:
    value: "${USER_ID}"     # Environment variable substitution
    fixed: true             # Cannot be overridden
  tenant_id:
    value: "acme-corp"
    fixed: true
  api_version:
    value: "v2"
    fixed: false            # Agent can override

# Route-specific parameters
routes:
  createUser:
    permissions:
      value: "read"
      fixed: true           # Force read-only for user creation
    notify_admin:
      value: true
      fixed: true
  
  deleteUser:
    require_approval:
      value: true
      fixed: true           # Always require approval for deletion
    audit_level:
      value: "HIGH"
      fixed: true

# Named profiles for different environments
profiles:
  production:
    environment: "prod"
    rate_limit: 100
    debug: false
    strict_validation: true
  
  development:
    environment: "dev"
    rate_limit: 1000
    debug: true
    strict_validation: false
```

#### JSON Format
```json
{
  "global": {
    "user_id": { "value": "12345", "fixed": true },
    "tenant_id": { "value": "acme-corp", "fixed": true }
  },
  "routes": {
    "createUser": {
      "permissions": { "value": "read", "fixed": true }
    }
  },
  "profiles": {
    "production": {
      "environment": "prod",
      "debug": false
    }
  }
}
```

### 🔄 Parameter Priority & Merging

Parameters are applied in this priority order (highest first):

1. **Agent-provided parameters** (for non-fixed params only)
2. **Route-specific cascade** from command line (`--cascade '@route:param=value'`)
3. **Route-specific cascade** from config file (`routes.routeName.param`)
4. **Global cascade** from command line (`--cascade 'param=value'`)
5. **Global cascade** from config file (`global.param`)
6. **Profile parameters** (if profile is active)

**Important**: Fixed parameters (marked with `!` or `fixed: true`) **cannot be overridden** regardless of priority.

### 🛡️ Security Use Cases

#### Multi-Tenant SaaS Protection
```bash
# Ensure tenant isolation - agent cannot access other tenants
mcp-http-bridge --spec ./api.yaml \
  --cascade 'tenant_id=tenant-123!' \
  --cascade 'user_id=user-456!' \
  --cascade 'subscription_tier=premium!'
```

#### Read-Only Mode Enforcement  
```bash
# Force all write operations to read-only mode
mcp-http-bridge --spec ./api.yaml \
  --cascade '@create*:read_only=true!' \
  --cascade '@update*:read_only=true!' \
  --cascade '@delete*:read_only=true!'
```

#### Audit Trail Requirements
```bash
# Ensure audit compliance for sensitive operations
mcp-http-bridge --spec ./api.yaml \
  --cascade 'audit_user=${ENV.AUDIT_USER}!' \
  --cascade 'compliance_mode=strict!' \
  --cascade '@deleteUser:require_mfa=true!' \
  --cascade '@updatePermissions:log_level=HIGH!'
```

### 🌍 Environment Integration

```bash
# Set environment variables
export API_USER_ID=12345
export API_TENANT=acme
export API_SECRET=sk-secret-key

# Use in cascade parameters
mcp-http-bridge --spec ./api.yaml \
  --cascade 'user_id=${ENV.API_USER_ID}!' \
  --cascade 'tenant=${ENV.API_TENANT}!' \
  --cascade 'api_key=${ENV.API_SECRET}!'
```

### 🏷️ Profile Management

Use profiles to manage environment-specific settings:

```bash
# Production deployment
mcp-http-bridge --spec ./api.yaml \
  --cascade-file ./cascade.yaml \
  --cascade '%PROFILE:production'

# Development with additional debugging
mcp-http-bridge --spec ./api.yaml \
  --cascade-file ./cascade.yaml \
  --cascade '%PROFILE:development' \
  --cascade 'debug_level=verbose'
```

### 🧪 Testing Your Configuration

Test cascade parameters before deployment:

```bash
# Test with invoke command to see parameter behavior
mcp-http-bridge --spec ./api.yaml \
  --cascade 'user_id=123!' \
  --cascade '@createUser:permissions=read!' \
  --invoke createUser \
  --param name=John \
  --param email=john@example.com

# The cascade parameters will be automatically applied and protected
```

### 💡 Best Practices

1. **Always fix security-critical parameters**: User IDs, tenant IDs, permissions
2. **Use environment variables** for sensitive values - never hardcode secrets
3. **Apply route-specific restrictions** for dangerous operations
4. **Use profiles** to manage different environments (prod/staging/dev)
5. **Test thoroughly** with `--invoke` before deploying
6. **Document your cascade configuration** for your team
7. **Use wildcard patterns** (`@delete*`, `@admin*`) for operation groups

### 🔧 Advanced Examples

#### Complete Multi-Environment Setup
```bash
# Create environment-specific cascade files
echo 'global:
  user_id: { value: "${USER_ID}", fixed: true }
  tenant_id: { value: "${TENANT_ID}", fixed: true }
profiles:
  production:
    rate_limit: 100
    timeout: 30000
  development:
    rate_limit: 1000
    timeout: 60000' > cascade.yaml

# Production deployment
USER_ID=prod-123 TENANT_ID=tenant-prod mcp-http-bridge \
  --spec ./api.yaml \
  --cascade-file ./cascade.yaml \
  --cascade '%PROFILE:production' \
  --mcp-config prod-api

# Development deployment  
USER_ID=dev-456 TENANT_ID=tenant-dev mcp-http-bridge \
  --spec ./api.yaml \
  --cascade-file ./cascade.yaml \
  --cascade '%PROFILE:development' \
  --mcp-config dev-api
```

## 🔐 Auth File Behavior

The `--auth-file` option provides secure, dynamic authentication:

### **Dynamic Reading**
- Auth files are read **fresh on every API call**, not cached at startup
- Enables token rotation without restarting the MCP server
- Missing or unreadable files are handled gracefully (logged but don't crash)

### **Supported Formats**
```bash
# Any of these formats work in your auth file:
Bearer your-jwt-token-here          # Bearer token (preferred)
Basic dXNlcjpwYXNzd29yZA==          # Basic authentication  
your-raw-token-here                 # Raw token (auto-prefixed with "Bearer ")
```

### **Security Benefits**
- Tokens never appear in command line arguments (hidden from `ps` output)
- Supports external token management systems
- Enables automatic token refresh workflows
- File permissions can restrict access (e.g., `chmod 600 token.txt`)

### **Usage Examples**
```bash
# Create secure token file in home directory
mkdir -p ~/.majk
echo "Bearer sk-your-secret-token" > ~/.majk/.majk.token
chmod 600 ~/.majk/.majk.token

# Generate MCP config with tilde path (expands to full path)
mcp-http-bridge --spec ./api.yaml --auth-file ~/.majk/.majk.token --mcp-config my-api

# Or use relative paths
echo "Bearer sk-token" > ./token.txt
chmod 600 ./token.txt
mcp-http-bridge --spec ./api.yaml --auth-file ./token.txt --mcp-config my-api
```

## 🔍 Tool Discovery & Testing

### Discover Available Tools
Before deploying your MCP server, you can explore all available tools generated from your OpenAPI spec:

```bash
# Human-readable discovery output
mcp-http-bridge --spec ./api.yaml --discover

# JSON output for programmatic use  
mcp-http-bridge --spec ./api.yaml --discover --discover-format json

# MCP format output
mcp-http-bridge --spec ./api.yaml --discover --discover-format mcp
```

Example output (human format):
```
📋 Discovered 6 tools from OpenAPI specification

🔧 getPosts
   Description: Get all posts
   Parameters: _limit (integer, optional) - Limit the number of results

🔧 createPost  
   Description: Create a new post
   Parameters: title (string, required), body (string, required), userId (integer, required)

🔧 getPost
   Description: Get a post by ID
   Parameters: id (integer, required) - Post ID
   
... (additional tools)
```

### Command-line Tool Invocation
Test individual API endpoints directly from the command line:

```bash
# Invoke with key-value parameters
mcp-http-bridge --spec ./api.yaml --invoke getUser --param id=1

# Invoke with JSON parameters
mcp-http-bridge --spec ./api.yaml --invoke createPost --invoke-params '{"title":"Test","body":"Content","userId":1}'

# Mix both parameter styles
mcp-http-bridge --spec ./api.yaml --invoke updatePost --param id=1 --invoke-params '{"title":"Updated Title"}'

# With authentication
mcp-http-bridge --spec ./api.yaml --auth-file ./token.txt --invoke getUser --param id=1
```

This is perfect for:
- Testing API endpoints before deploying the MCP server
- Debugging authentication and parameter issues
- Validating OpenAPI spec compatibility
- Quick API exploration and development

## 🎯 Tool Filtering

Control which tools are available to prevent unwanted API access:

### Whitelist Mode (Recommended for Security)
Only allow specific tools to be available:

```bash
# Allow only safe read operations
mcp-http-bridge --spec ./api.yaml --allowed-tools "getUser,getPost,getPosts"

# Allow user management operations
mcp-http-bridge --spec ./api.yaml --allowed-tools "getUser,createUser,updateUser"
```

### Blacklist Mode
Block specific dangerous operations:

```bash
# Block all delete operations
mcp-http-bridge --spec ./api.yaml --disallowed-tools "deleteUser,deletePost,deleteComment"

# Block admin operations
mcp-http-bridge --spec ./api.yaml --disallowed-tools "deleteUser,updateUserRole,systemReset"
```

### Combined with Discovery
Use discovery to identify tool names, then filter appropriately:

```bash
# 1. Discover all available tools
mcp-http-bridge --spec ./api.yaml --discover --discover-format json > tools.json

# 2. Review the tools and identify safe ones
cat tools.json | jq '.tools[].name'

# 3. Create a filtered MCP config with only safe tools
mcp-http-bridge --spec ./api.yaml --allowed-tools "getUser,getPost" --mcp-config safe-api
```

**Security Note**: Tool filtering happens at both discovery time and runtime, preventing unauthorized tool access even if the tool names are known.

## 📁 Custom Tool Mappings

Customize tool behavior with mappings files to transform parameters, modify responses, or rename tools:

### Generate Initial Mappings File
```bash
# Generate a starter mappings file based on your OpenAPI spec
mcp-http-bridge --spec ./api.yaml --generate-mappings ./mappings.json
```

This creates a mappings file with all discovered tools that you can customize.

### Example Mappings File
```json
{
  "mappings": {
    "getUserById": {
      "name": "getUser",
      "description": "Retrieve user information by ID",
      "parameters": {
        "id": {
          "target": "path",
          "required": true
        },
        "include_profile": {
          "target": "query",
          "name": "include",
          "default": "profile"
        }
      },
      "headers": {
        "X-Client": "MCP-Bridge"
      },
      "responseTransform": "{{data.name}} ({{data.email}})"
    }
  },
  "globalDefaults": {
    "headers": {
      "User-Agent": "MCP-HTTP-Bridge/1.2.0"
    }
  }
}
```

### Use Custom Mappings
```bash
# Apply your custom mappings
mcp-http-bridge --spec ./api.yaml --mappings-file ./mappings.json

# Generate MCP config with custom mappings
mcp-http-bridge --spec ./api.yaml --mappings-file ./mappings.json --mcp-config custom-api
```

### Mappings Features
- **Rename tools**: Change tool names for better clarity
- **Transform parameters**: Map parameters to different locations (path, query, header, body)
- **Set defaults**: Provide default values for parameters
- **Custom headers**: Add tool-specific or global headers
- **Response formatting**: Transform API responses with Handlebars templates
- **Parameter validation**: Mark parameters as required/optional

## 🎯 Workflow-Oriented Tool Mappings (New!)

Create semantic, workflow-oriented tool names with pre-configured parameters using `--tool-mappings`. This powerful feature allows you to create multiple custom tools that call the same REST endpoint with different fixed parameters.

### 🌟 Key Benefits

- **Semantic Tool Names**: Replace auto-generated names like `get__api_projects_abc123` with workflow-oriented names like `current_project_read`
- **Fixed Parameters**: Pre-configure tools with specific parameters that are automatically injected
- **Multiple Tools Per Endpoint**: Create different tools that call the same API endpoint with different configurations
- **Mixed Mode**: Customize only the endpoints you need while keeping others auto-generated
- **Workflow Context**: Tools are pre-configured for specific business contexts and use cases

### 🚀 Basic Usage

```bash
# Create workflow-oriented tools with fixed parameters
mcp-http-bridge --spec ./api.yaml --tool-mappings '{
  "current_project_read": {
    "operation": "getProjectById",
    "fixedParams": "id=current-project&context=active",
    "description": "Read the project I am currently working on"
  },
  "client_project_read": {
    "operation": "getProjectById", 
    "fixedParams": "id=client-project&context=client",
    "description": "Read the client project details"
  }
}'
```

### 📖 Tool Mappings Schema

```typescript
interface ToolMapping {
  operation: string;           // OpenAPI operation ID to call
  fixedParams?: string;        // Query params always sent (URL encoded)
  description?: string;        // Override tool description
  parameters?: object;         // Override/extend tool parameters schema
}

interface ToolMappingsConfig {
  [customToolName: string]: ToolMapping;
}
```

### 🎛️ Real-World Examples

#### Multi-Tenant Application
```bash
mcp-http-bridge --spec ./api.yaml --tool-mappings '{
  "tenant_alpha_users": {
    "operation": "listUsers",
    "fixedParams": "tenantId=alpha",
    "description": "List users for tenant Alpha"
  },
  "tenant_beta_users": {
    "operation": "listUsers",
    "fixedParams": "tenantId=beta", 
    "description": "List users for tenant Beta"
  },
  "admin_users_list": {
    "operation": "listUsers",
    "fixedParams": "role=admin",
    "description": "List admin users across all tenants"
  }
}'
```

#### Development Workflow
```bash
mcp-http-bridge --spec ./api.yaml --tool-mappings '{
  "my_active_projects": {
    "operation": "listProjects",
    "fixedParams": "filter=active&assignee=me&limit=20",
    "description": "List my active projects"
  },
  "production_health_check": {
    "operation": "getSystemStatus",
    "fixedParams": "environment=production&detailed=true",
    "description": "Check production system health"
  }
}'
```

#### Multi-Environment Management
```bash
mcp-http-bridge --spec ./api.yaml --tool-mappings '{
  "prod_deploy_status": {
    "operation": "getDeploymentStatus",
    "fixedParams": "environment=production&includeMetrics=true",
    "description": "Production deployment status with metrics"
  },
  "staging_deploy_status": {
    "operation": "getDeploymentStatus",
    "fixedParams": "environment=staging&includeMetrics=false",
    "description": "Staging deployment status overview"
  }
}'
```

### 🔄 Parameter Precedence

Parameters are applied in this order:
```
Final Request = Base URL + Operation Path + Fixed Params + Cascade Params + User Params
                                              ↑ Highest precedence
```

- **Fixed Parameters** (from `fixedParams`): Highest precedence, cannot be overridden
- **Cascade Parameters** (from `--cascade`): Applied if no fixed parameter conflicts
- **User Parameters** (from Claude): Applied if no conflicts with fixed or cascade

### 🎯 Mixed Mode: Custom + Auto-Generated

Tool mappings work in **mixed mode** - you can customize specific endpoints while keeping others auto-generated:

```bash
# This creates:
# ✅ current_project_read (custom tool with fixed params)
# ✅ client_project_read (custom tool with fixed params)  
# ✅ createUser (auto-generated tool, unchanged)
# ✅ updateUser (auto-generated tool, unchanged)
# ✅ deleteUser (auto-generated tool, unchanged)
# ✅ ... all other auto-generated tools

mcp-http-bridge --spec ./api.yaml --tool-mappings '{
  "current_project_read": {
    "operation": "getProjectById",
    "fixedParams": "id=current",
    "description": "Read current project"
  },
  "client_project_read": {
    "operation": "getProjectById",
    "fixedParams": "id=client", 
    "description": "Read client project"
  }
}'
```

### 🛡️ Tool Filtering Integration

Tool mappings work seamlessly with existing filtering options:

```bash
# Allow only specific custom and auto-generated tools
mcp-http-bridge --spec ./api.yaml \
  --tool-mappings '{"current_project":"getProject","fixedParams":"id=current"}' \
  --allowed-tools "current_project,createUser,updateUser"

# Block specific custom or auto-generated tools
mcp-http-bridge --spec ./api.yaml \
  --tool-mappings '{"admin_tools":"getAdminData","fixedParams":"role=admin"}' \
  --disallowed-tools "deleteUser,admin_tools"
```

### 🔍 Discovery with Tool Mappings

```bash
# Discover your custom workflow tools
mcp-http-bridge --spec ./api.yaml \
  --tool-mappings '{"current_project":"getProject","fixedParams":"id=current"}' \
  --discover --discover-format human
```

### 📝 URL Encoding

Fixed parameters support URL encoding for special characters:

```bash
# URL encode special characters in fixedParams
mcp-http-bridge --spec ./api.yaml --tool-mappings '{
  "project_with_spaces": {
    "operation": "getProject", 
    "fixedParams": "id=project%20with%20spaces&context=test%26demo"
  }
}'
```

## 📊 Enhanced Logging & Debugging

Get comprehensive debugging information with the `--log` option:

```bash
# Enable detailed logging to file
mcp-http-bridge --spec ./api.yaml --auth-file ./token.txt --log debug.log

# With verbose output
mcp-http-bridge --spec ./api.yaml --verbose --debug --log debug.log
```

### What Gets Logged
The debug log captures everything needed for troubleshooting:

1. **Invocation Parameters**: Complete command line arguments and environment
2. **Spec Content**: Full OpenAPI specification content (from file, URL, or inline)
3. **Auth File Operations**: When auth files are read, including content and errors
4. **HTTP Requests**: Complete request details including headers, body, and URL
5. **HTTP Responses**: Full response data, headers, and status codes
6. **MCP Messages**: All MCP protocol messages sent and received
7. **Errors**: Detailed error information with stack traces

### Example Log Structure
```
========================================
MCP HTTP Bridge Debug Log
Started: 2024-01-15T10:30:00.000Z
========================================

[2024-01-15T10:30:00.123Z] Invocation Parameters
----------------------------------------
Command: node /path/to/index.js
Arguments: --spec ./api.yaml --auth-file ./token.txt --log debug.log
Full argv: ["node", "/path/to/index.js", "--spec", "./api.yaml", ...]
----------------------------------------

[2024-01-15T10:30:00.456Z] Spec File Content
----------------------------------------
Source: /full/path/to/api.yaml
Content Length: 2847 characters

Content:
openapi: 3.0.0
info:
  title: My API
...
----------------------------------------

[2024-01-15T10:30:05.789Z] HTTP Request
----------------------------------------
POST https://api.example.com/users HTTP/1.1

Headers:
  Authorization: Bearer sk-xxx...
  Content-Type: application/json
  User-Agent: MCP-HTTP-Bridge/1.2.0

Body:
{
  "name": "John Doe",
  "email": "john@example.com"
}
----------------------------------------
```

This logging is invaluable for:
- **Debugging authentication issues**: See exactly what tokens are being sent
- **Troubleshooting API calls**: View complete request/response cycles
- **Understanding tool behavior**: Track how MCP messages are processed
- **Performance analysis**: Monitor request timing and patterns
- **Security auditing**: Review all API interactions and parameters

## 📋 Ready-to-Use Examples

### Generating MCP Configurations

The easiest way to get started is by generating MCP configurations directly from your OpenAPI specs:

#### From a local file
```bash
mcp-http-bridge --spec ./api.yaml --mcp-config my-api
```

Output:
```json
{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "@majkapp/mcp-http-bridge",
        "--spec",
        "/full/path/to/api.yaml"
      ]
    }
  }
}
```

#### From a URL with authentication
```bash
mcp-http-bridge --spec-url https://api.github.com/openapi.json --auth-file ./github-token.txt --mcp-config github-api
```

Output:
```json
{
  "mcpServers": {
    "github-api": {
      "command": "npx",
      "args": [
        "@majkapp/mcp-http-bridge",
        "--spec-url",
        "https://api.github.com/openapi.json",
        "--auth-file",
        "/full/path/to/github-token.txt"
      ]
    }
  }
}
```

### Real API Examples

#### JSONPlaceholder API (Testing)
```json
{
  "mcpServers": {
    "jsonplaceholder": {
      "command": "npx",
      "args": [
        "@majkapp/mcp-http-bridge",
        "--spec-url",
        "https://jsonplaceholder.typicode.com/openapi.json"
      ]
    }
  }
}
```

#### OpenAI API (with auth file)
Create a secure token file:
```bash
# Create the token file with proper format
echo "Bearer sk-your-openai-api-key-here" > openai-token.txt
chmod 600 openai-token.txt  # Secure file permissions

# Generate MCP config
mcp-http-bridge --spec-url https://api.openai.com/v1/openapi.json --auth-file ./openai-token.txt --mcp-config openai
```

**Note**: The token will be read fresh from `openai-token.txt` on every API call, so you can update it anytime without restarting the MCP server.

#### Stripe API (with API key in header)
```json
{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": [
        "@majkapp/mcp-http-bridge",
        "--spec-url",
        "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json",
        "--auth-api-key",
        "Authorization:Bearer sk_test_your_stripe_key"
      ]
    }
  }
}
```

#### Local API Development
For APIs in development with custom authentication:
```json
{
  "mcpServers": {
    "my-local-api": {
      "command": "npx",
      "args": [
        "@majkapp/mcp-http-bridge",
        "--spec",
        "/path/to/local/api.yaml",
        "--base-url",
        "http://localhost:3000",
        "--auth-custom-headers",
        "{\"X-API-Key\":\"dev-key-123\",\"X-Tenant\":\"development\"}"
      ]
    }
  }
}
```

### Advanced Usage Examples

#### With tool filtering, validation, and cascade parameters
```bash
# Only include user and post related operations with fixed tenant isolation
mcp-http-bridge --spec ./api.yaml --tag-filter "users,posts" --validate-responses \
  --cascade 'tenant_id=secure-tenant!' --cascade 'user_id=${ENV.API_USER_ID}!' \
  --mcp-config filtered-api

# Include only specific operations with read-only enforcement
mcp-http-bridge --spec ./api.yaml --operation-filter "getUser,createUser,updateUser" \
  --cascade '@createUser:read_only=true!' --cascade '@updateUser:require_approval=true!' \
  --mcp-config user-api

# Whitelist only safe operations with audit trail
mcp-http-bridge --spec ./api.yaml --allowed-tools "getUser,getPost,getPosts" \
  --cascade 'audit_mode=enabled!' --cascade 'session_id=${ENV.SESSION_ID}!' \
  --mcp-config safe-api

# Blacklist dangerous operations with compliance settings
mcp-http-bridge --spec ./api.yaml --disallowed-tools "deleteUser,deletePost" \
  --cascade 'compliance_level=strict!' --cascade '@*:require_mfa=true!' \
  --mcp-config restricted-api
```

#### With custom mappings, cascade parameters, and logging
```bash
# Generate and use custom mappings with debug logging and cascade parameters
mcp-http-bridge --spec ./api.yaml --generate-mappings ./custom-mappings.json
# Edit the mappings file as needed...
mcp-http-bridge --spec ./api.yaml --mappings-file ./custom-mappings.json --log debug.log \
  --cascade 'environment=staging!' --cascade 'debug_mode=true' \
  --mcp-config custom-api

# Full-featured setup with filtering, mappings, cascade, and logging
mcp-http-bridge --spec ./api.yaml \
  --auth-file ~/.config/api-token.txt \
  --allowed-tools "getUser,createUser,updateUser" \
  --mappings-file ./user-mappings.json \
  --cascade-file ./production-cascade.yaml \
  --cascade '%PROFILE:production' \
  --cascade 'deployment_id=${ENV.DEPLOYMENT_ID}!' \
  --log production.log \
  --rate-limit 10 \
  --retries 3 \
  --validate-responses \
  --mcp-config production-user-api
```

#### Discovery and testing workflow with cascade parameters
```bash
# 1. Discover all available tools
mcp-http-bridge --spec ./api.yaml --discover

# 2. Test specific endpoints with cascade parameters
mcp-http-bridge --spec ./api.yaml --auth-file ./token.txt \
  --cascade 'user_id=test-123!' --cascade 'environment=testing!' \
  --invoke getUser --param id=1

# 3. Generate mappings and cascade configuration for customization
mcp-http-bridge --spec ./api.yaml --generate-mappings ./mappings.json
echo 'global:
  user_id: { value: "${USER_ID}", fixed: true }
  tenant_id: { value: "${TENANT_ID}", fixed: true }' > cascade.yaml

# 4. Deploy with filtering, custom mappings, and cascade parameters
mcp-http-bridge --spec ./api.yaml \
  --auth-file ./token.txt \
  --mappings-file ./mappings.json \
  --cascade-file ./cascade.yaml \
  --cascade 'deployment_env=production!' \
  --allowed-tools "getUser,createUser" \
  --mcp-config final-api
```

#### With rate limiting and retries
```bash
# Limit to 5 requests per second with 5 retries
mcp-http-bridge --spec ./api.yaml --rate-limit 5 --retries 5 --timeout 10000 --mcp-config robust-api
```

### Token Rotation Example

The auth file approach enables seamless token rotation:

```bash
# Start with initial token
echo "Bearer token-v1" > api-token.txt
mcp-http-bridge --spec ./api.yaml --auth-file ./api-token.txt &

# Later, rotate the token without stopping the server
echo "Bearer token-v2" > api-token.txt
# Next API call will automatically use the new token!

# You can even automate this with a cron job or external system
echo "Bearer $(get-fresh-token-from-vault)" > api-token.txt
```

## 🏗️ Development

```bash
# Clone the repository  
git clone https://github.com/your-username/mcp-http-bridge.git
cd mcp-http-bridge

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test
```

## 📝 Requirements

- Node.js >= 18.0.0
- OpenAPI 3.0+ specification
- MCP-compatible client (Claude Desktop, etc.)

## 📄 License

MIT License

## 🔗 Related

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [Claude Desktop](https://claude.ai/)
- [OpenAPI Specification](https://spec.openapis.org/oas/v3.0.3)