@majkapp/mcp-http-bridge

v1.6.0

Published

6 months ago

A generic stdio MCP to HTTP API bridge that exposes OpenAPI endpoints as MCP tools

Downloads

132

0High
0Medium
0Low

juleswhite

mcp openapi http api bridge stdio model-context-protocol claude ai anthropic rest-api swagger

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)

npm install -g @majkapp/mcp-http-bridge

Local Installation

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):

# 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:

# 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

# 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

# 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)

# 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:

# 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

# 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

# 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)

# 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

{
  "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):

Agent-provided parameters (for non-fixed params only)
Route-specific cascade from command line (--cascade '@route:param=value')
Route-specific cascade from config file (routes.routeName.param)
Global cascade from command line (--cascade 'param=value')
Global cascade from config file (global.param)
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

# 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

# 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

# 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

# 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:

# 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:

# 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 protected]

# The cascade parameters will be automatically applied and protected

💡 Best Practices

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

🔧 Advanced Examples

Complete Multi-Environment Setup

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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

{
  "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

# 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

# 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

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

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

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

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:

# 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:

# 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

# 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:

# 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:

# 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:

Invocation Parameters: Complete command line arguments and environment
Spec Content: Full OpenAPI specification content (from file, URL, or inline)
Auth File Operations: When auth files are read, including content and errors
HTTP Requests: Complete request details including headers, body, and URL
HTTP Responses: Full response data, headers, and status codes
MCP Messages: All MCP protocol messages sent and received
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": "[email protected]"
}
----------------------------------------

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

mcp-http-bridge --spec ./api.yaml --mcp-config my-api

Output:

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

From a URL with authentication

mcp-http-bridge --spec-url https://api.github.com/openapi.json --auth-file ./github-token.txt --mcp-config github-api