vulnmatter-mcp-proxy

Streaming-safe MCP wrapper supporting SSE and WebSocket with header authentication from environment variables.

💡 Works seamlessly with the VulnMatter VS Code Extension - Install both for the complete VulnMatter experience in your development workflow!

Features

• 🔒 Secure: API key and URLs only from environment variables
• 🌐 Dual Transport: Supports both SSE (Server-Sent Events) and WebSocket connections
• 🔄 JSON-RPC Interception: Handles resource methods automatically
• 🧹 Clean Arguments: Filters out conflicting transport and auth arguments
• 📡 Streaming: Full stdio streaming support with buffering
• 🎯 Auto-detection: Automatically selects transport based on available URLs
• 🛡️ Sanitization: Removes unsupported capabilities from server responses

VS Code Integration

This package is designed to work seamlessly with the VulnMatter VS Code Extension.

The VS Code extension provides:

• 🎨 Syntax highlighting and IntelliSense for vulnerability data
• 🔍 Interactive vulnerability exploration within your IDE
• ⚡ Real-time vulnerability scanning and reporting
• 📊 Dashboard and analytics directly in VS Code

Install both the CLI proxy and VS Code extension for the complete VulnMatter development experience!

Installation

npm install -g vulnmatter-mcp-proxy

Quick Start

SSE Mode (Server-Sent Events)

export VULNMATTER_API_KEY="your-api-key"
export VULNMATTER_MCP_URL="https://api.example.com/sse/endpoint"
vulnmatter-mcp

WebSocket Mode

export VULNMATTER_API_KEY="your-api-key" 
export VULNMATTER_WS_URL="wss://api.example.com/ws/endpoint"
vulnmatter-mcp

Mixed Mode (Auto-detection)

export VULNMATTER_API_KEY="your-api-key"
export VULNMATTER_MCP_URL="https://api.example.com/sse/endpoint" 
export VULNMATTER_WS_URL="wss://api.example.com/ws/endpoint"
export VM_TRANSPORT="ws"  # Force WebSocket, or "sse" for SSE
vulnmatter-mcp

Environment Variables

Required

• VULNMATTER_API_KEY: Your API authentication key

Transport URLs (at least one required)

• VULNMATTER_MCP_URL: SSE endpoint URL
• VULNMATTER_WS_URL: WebSocket endpoint URL

Optional Configuration

• VM_TRANSPORT: Force transport mode ("sse" or "ws")
• VM_HEADER: Custom auth header name (default: "X-API-Key")
• VM_DEBUG: Enable debug logging ("1" or "true")
• VM_SG_DEBUG: Enable supergateway debug logging ("1" or "true")

Transport Selection

The proxy automatically selects the transport method:

1. Explicit: If VM_TRANSPORT is set to "ws" or "sse"
2. WebSocket Priority: If VM_TRANSPORT is unset and both URLs exist, but VULNMATTER_WS_URL is available
3. SSE Fallback: Uses SSE mode in all other cases

JSON-RPC Features

Resource Method Interception

The proxy automatically handles these MCP resource methods:

• resources/list → Returns empty array
• resources/subscribe → Returns success
• resources/get → Returns "not implemented" error

Capability Sanitization

Removes resources capability from server initialize responses to prevent client confusion.

Advanced Usage

Custom Headers

export VM_HEADER="Authorization"
export VULNMATTER_API_KEY="Bearer your-jwt-token"
vulnmatter-mcp

Debug Mode

export VM_DEBUG=1
export VM_SG_DEBUG=1  # For SSE mode supergateway logs
vulnmatter-mcp --logLevel debug

Pass-through Arguments

All unrecognized arguments are passed to the underlying transport:

vulnmatter-mcp --timeout 30000 --custom-flag value

Architecture

Client ←→ vulnmatter-mcp-proxy ←→ Transport ←→ MCP Server
                   ↑
            [JSON-RPC Interception]
            [Capability Sanitization]  
            [Environment Auth]

SSE Mode

Uses supergateway as the underlying SSE client with stdio streaming.

WebSocket Mode

Direct WebSocket connection using the ws library with custom headers.

Error Handling

• Missing API key: Exits with error message
• Missing transport URL: Exits with error message
• Transport connection errors: Propagated to client
• Signal forwarding: SIGINT/SIGTERM properly forwarded to child processes

Requirements

• Node.js ≥ 18
• npm or yarn

License

MIT