# Install dependencies
npm install

# Copy environment file
cp .env.example .env

# Build
npm run build

# Start with stdio transport (default, for Claude Desktop)
npm run start:stdio

# Start with HTTP transport
npm run start:http

# .env
NODE_ENV=development
LOG_LEVEL=debug

# Server
MCP_SERVER_PORT=3000
HEALTH_CHECK_PORT=8080

# Redis (optional — in-memory rate limiting used if not configured)
REDIS_HOST=localhost
REDIS_PORT=6379

# Monitoring
METRICS_ENABLED=true

npm run dev

# .env
NODE_ENV=production
LOG_LEVEL=info

# Server
MCP_SERVER_PORT=3000
HEALTH_CHECK_PORT=8080

# Redis (required for distributed rate limiting)
REDIS_HOST=redis.internal
REDIS_PORT=6379
REDIS_PASSWORD=your-secure-password

# MCP server authentication (protect the /mcp endpoint)
MCP_SERVER_AUTH_ENABLED=true
MCP_SERVER_AUTH_TYPE=bearer
MCP_SERVER_AUTH_TOKEN_ENV=MCP_AUTH_TOKEN
MCP_AUTH_TOKEN=your-secret-token-here

# Service authentication tokens
USER_SERVICE_TOKEN=your_user_service_token
PAYMENT_API_KEY=your_payment_api_key
ANALYTICS_CLIENT_SECRET=your_oauth_client_secret

# OAuth2 (if using oauth2 auth strategy)
OAUTH2_CLIENT_ID=your_client_id
OAUTH2_CLIENT_SECRET=your_client_secret
OAUTH2_TOKEN_URL=https://auth.example.com/oauth/token

# Monitoring
METRICS_ENABLED=true
PROMETHEUS_PORT=9090

docker build -t mcp-proxy .
docker run -p 3000:3000 -p 8080:8080 \
  -v ./config:/app/config:ro \
  --env-file .env \
  mcp-proxy

docker-compose up

# Stdio with custom config
node dist/server/unified-server.js --transport stdio --config ./config/my-services.yaml

# HTTP with custom config
node dist/server/unified-server.js --transport http --port 3000 --config /absolute/path/to/services.yaml

version: "1.0"

settings:
  log_level: "info"
  metrics_enabled: true
  health_check_port: 8080

services:
  - name: "jsonplaceholder"
    description: "JSONPlaceholder - Free fake REST API"
    base_url: "https://jsonplaceholder.typicode.com"

    tools:
      - name: "get_post"
        description: "Get a blog post by ID"
        method: "GET"
        path: "/posts/{id}"
        parameters:
          - name: "id"
            type: "number"
            required: true
            description: "Post ID (1-100)"
            in: "path"

      - name: "list_posts"
        description: "List all blog posts"
        method: "GET"
        path: "/posts"

      - name: "get_user"
        description: "Get user by ID"
        method: "GET"
        path: "/users/{id}"
        parameters:
          - name: "id"
            type: "number"
            required: true
            description: "User ID (1-10)"
            in: "path"

version: "1.0"

settings:
  log_level: "info"
  metrics_enabled: true
  health_check_port: 8080
  mcp_server_port: 3000

services:
  - name: "user_service"
    description: "User management service"
    base_url: "https://api.example.com/v1/users"

    auth:
      type: "bearer"
      config:
        token_env: "USER_SERVICE_TOKEN"

    circuit_breaker:
      enabled: true
      timeout: 3000
      error_threshold: 50
      reset_timeout: 30000
      volume_threshold: 10

    rate_limit:
      enabled: true
      max_requests: 100
      window: 60000
      strategy: "sliding_window"

    access_control:
      enabled: true
      allowed_roles: ["admin", "user"]
      required_permissions: ["read:users"]

    retry:
      enabled: true
      max_attempts: 3
      backoff_ms: 1000

    timeout: 5000

    tools:
      - name: "create_user"
        description: "Create a new user account"
        method: "POST"
        path: "/"

        access_control:
          enabled: true
          required_permissions: ["write:users"]

        parameters:
          - name: "username"
            type: "string"
            required: true
            description: "Username for the new account"
            in: "body"
            validation:
              min_length: 3
              max_length: 50
              pattern: "^[a-zA-Z0-9_]+$"

          - name: "email"
            type: "string"
            required: true
            description: "Email address"
            in: "body"
            validation:
              format: "email"

        request_body:
          content_type: "application/json"
          template: |
            {
              "username": "{{username}}",
              "email": "{{email}}",
              "created_at": "{{$timestamp}}"
            }

        response:
          success_codes: [201]
          error_codes: [400, 409]
          transform: "json"

  - name: "payment_service"
    description: "Payment processing service"
    base_url: "https://api.payments.example.com/v2"

    auth:
      type: "api_key"
      config:
        key_env: "PAYMENT_API_KEY"
        header_name: "X-Payment-API-Key"

    circuit_breaker:
      enabled: true
      timeout: 5000
      error_threshold: 30
      reset_timeout: 60000
      volume_threshold: 5

    rate_limit:
      enabled: true
      max_requests: 50
      window: 60000
      strategy: "token_bucket"

    tools:
      - name: "create_payment"
        description: "Process a payment transaction"
        method: "POST"
        path: "/payments"

        parameters:
          - name: "amount"
            type: "number"
            required: true
            description: "Payment amount in cents"
            in: "body"
            validation:
              minimum: 1

          - name: "currency"
            type: "string"
            required: true
            description: "Currency code"
            in: "body"
            validation:
              enum: ["USD", "EUR", "GBP"]

  - name: "analytics_service"
    description: "Analytics and reporting service"
    base_url: "https://analytics.example.com/api"

    auth:
      type: "oauth2"
      config:
        client_id: "analytics_client"
        client_secret_env: "ANALYTICS_CLIENT_SECRET"
        token_url: "https://auth.example.com/oauth/token"
        scope: "analytics:read analytics:write"

    tools:
      - name: "get_report"
        description: "Generate analytics report"
        method: "GET"
        path: "/reports/{report_id}"

        parameters:
          - name: "report_id"
            type: "string"
            required: true
            description: "Report identifier"
            in: "path"

          - name: "format"
            type: "string"
            required: false
            description: "Report format"
            in: "query"
            validation:
              enum: ["json", "csv", "pdf"]

# Bearer token
MCP_SERVER_AUTH_ENABLED=true
MCP_SERVER_AUTH_TYPE=bearer
MCP_AUTH_TOKEN=your-secret-token-here

# API key
MCP_SERVER_AUTH_ENABLED=true
MCP_SERVER_AUTH_TYPE=api_key
MCP_API_KEY=your-api-key-here

# JWT (HMAC-SHA256)
MCP_SERVER_AUTH_ENABLED=true
MCP_SERVER_AUTH_TYPE=jwt
JWT_SECRET=your-jwt-secret-here

request_body:
  content_type: "application/json"
  template: |
    {
      "name": "{{name}}",
      "id": "{{$uuid}}",
      "timestamp": "{{$timestamp}}",
      "date": "{{$date}}"
    }

parameters:
  - name: "email"
    type: "string"
    required: true
    in: "body"
    validation:
      format: "email"              # email, url, uuid, date
      pattern: "^[a-z]+$"         # regex pattern
      min_length: 5
      max_length: 100
      enum: ["a", "b", "c"]       # allowed values

  - name: "count"
    type: "number"
    required: false
    in: "query"
    validation:
      minimum: 1
      maximum: 1000

response:
  success_codes: [200, 201]
  error_codes: [400, 404, 500]
  transform: "json"               # json | text | xml

# Generate from an OpenAPI spec
npm run cli -- generate \
  -i ./specs/petstore.yaml \
  -n pet_service \
  -u https://api.petstore.example.com \
  -o ./config/pet-service.yaml

# With auth and filtering
npm run cli -- generate \
  -i ./specs/api.yaml \
  -n my_service \
  -u https://api.example.com \
  --auth-type bearer \
  --auth-token-env MY_SERVICE_TOKEN \
  --include-tags "users,orders" \
  --exclude-operations "deleteAll,purge" \
  -o ./config/my-service.yaml

# Validate a config file
npm run cli -- validate -c ./config/services.yaml

# Strict mode
npm run cli -- validate -c ./config/services.yaml --strict

npm run cli -- serve -c ./config/services.yaml -p 3000

# Using default config (config/services.yaml)
npm run start:stdio

# Using a custom config file
node dist/server/unified-server.js --transport stdio --config ./config/my-services.yaml

{
  "mcpServers": {
    "my-proxy": {
      "command": "node",
      "args": [
        "/path/to/mcp-proxy/dist/server/unified-server.js",
        "--transport", "stdio",
        "--config", "/path/to/mcp-proxy/config/services.yaml"
      ],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

from langchain_mcp_adapters.client import MultiServerMCPClient

server_configs = {
    "my_proxy": {
        "command": "node",
        "args": [
            "/path/to/mcp-proxy/dist/server/unified-server.js",
            "--transport", "stdio",
            "--config", "/path/to/mcp-proxy/config/services.yaml"
        ],
        "transport": "stdio",
    }
}

async with MultiServerMCPClient(server_configs) as client:
    tools = await client.get_tools()

# Using default config
npm run start:http

# With custom port, host, and config
node dist/server/unified-server.js --transport http --host 127.0.0.1 --port 8000 --config ./config/my-services.yaml

{
  "status": "healthy",
  "services": {
    "user_service": {
      "status": "up",
      "responseTime": 45,
      "circuitBreaker": "closed"
    }
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

# Deployment probe configuration
livenessProbe:
  httpGet:
    path: /live
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5

Input:  hello", "admin": true, "x": "y
Result: {"message": "hello\", \"admin\": true, \"x\": \"y"}
         ^--- injection neutralized, treated as literal string

# Unit tests
npm test

# Unit tests with coverage
npm run test:coverage

# Watch mode
npm run test:watch

# E2E tests (stdio transport + cancellation)
npm run test:e2e

# E2E: HTTP transport
npm run test:http

# E2E: HTTP with authentication
npm run test:http:auth

# All tests (unit + e2e)
npm run test:all

# Type checking only
npm run typecheck

mcp-proxy/
├── src/
│   ├── core/
│   │   └── mcp-engine.ts              # Transport-agnostic MCP protocol engine
│   ├── transport/
│   │   ├── index.ts                    # Transport exports
│   │   ├── types.ts                    # ITransport interface, configs, states
│   │   ├── factory.ts                  # Transport factory (createTransport)
│   │   ├── stdio-transport.ts          # Stdio transport implementation
│   │   └── http-transport.ts           # HTTP transport (Streamable HTTP + SSE)
│   ├── server/
│   │   ├── unified-server.ts           # Main entry: CLI arg parsing + bootstrap
│   │   └── tool-registry.ts            # Dynamic tool registration
│   ├── config/
│   │   ├── loader.ts                   # YAML/JSON configuration loader
│   │   ├── schema.ts                   # Zod validation schemas
│   │   └── openapi-parser.ts           # OpenAPI/Swagger → tool config parser
│   ├── rest/
│   │   ├── client.ts                   # Axios HTTP client with circuit breaker + retry
│   │   └── transformer.ts              # Response transformation (JSON, text, XML)
│   ├── auth/
│   │   ├── manager.ts                  # Auth strategy manager
│   │   ├── types.ts                    # Auth types
│   │   └── strategies/
│   │       ├── api-key.ts
│   │       ├── bearer.ts
│   │       ├── basic.ts
│   │       └── oauth2.ts
│   ├── middleware/
│   │   ├── rate-limiter.ts             # Rate limiting (fixed/sliding/token bucket)
│   │   ├── access-control.ts           # RBAC implementation
│   │   └── validator.ts                # Request parameter validation
│   ├── monitoring/
│   │   ├── metrics.ts                  # Prometheus-style metrics collector
│   │   ├── health.ts                   # Health checker (ping + circuit breaker)
│   │   └── http-server.ts             # Monitoring HTTP server (/health, /metrics)
│   ├── types/
│   │   └── config.ts                   # ProxyConfig, ServiceConfig, ToolConfig types
│   ├── utils/
│   │   ├── errors.ts                   # Custom error classes
│   │   └── logger.ts                   # Winston structured logging
│   └── cli/
│       ├── index.ts                    # CLI entry point (commander)
│       └── commands/
│           ├── generate.ts             # Generate config from OpenAPI
│           ├── validate.ts             # Validate configuration
│           └── serve.ts                # Start server
├── config/
│   ├── services.yaml                   # Active service configuration
│   ├── example-services.yaml           # Full-featured example
│   └── openapi/
│       └── example-user-api.yaml       # Example OpenAPI spec
├── tests/
│   ├── unit/                           # Unit tests (Jest)
│   └── e2e/                            # End-to-end tests
├── Dockerfile                          # Multi-stage production build
├── docker-compose.yaml                 # Docker Compose (proxy + Redis)
├── package.json
├── tsconfig.json
└── jest.config.js