MCP Passthrough Server

A Node.js passthrough server that forwards JSON-RPC messages from stdin to HTTP endpoints. This is a JavaScript port of a Java passthrough server, maintaining the same functionality and behavior.

Features

• ✅ Reads JSON messages from stdin
• ✅ Forwards messages via HTTP POST to configurable endpoint
• ✅ Optional HTTP Basic Authentication support
• ✅ JSON validation and error handling
• ✅ Proper JSON-RPC error responses
• ✅ Keep-alive connection support
• ✅ Command-line interface
• ✅ Npm package ready for publishing

Installation

Global Installation

npm install -g mcp-passthrough-server

Local Installation

npm install mcp-passthrough-server

From Source

git clone <repository-url>
cd mcp-connector
npm install

Usage

Command Line Interface

# Basic usage (defaults to http://localhost:8080/invoke)
mcp-passthrough

# Specify target URL
mcp-passthrough http://your-server.com/api/endpoint

# With HTTP Basic Authentication
mcp-passthrough http://your-server.com/api/endpoint username password

Programmatic Usage

const PassthroughServer = require('mcp-passthrough-server');

const server = new PassthroughServer();

// Run with default settings
server.run();

// Run with custom arguments
server.run(['http://localhost:3000/api', 'user', 'pass']);

Direct Execution

# Run directly from source
node index.js
node index.js http://localhost:3000/api
node index.js http://localhost:3000/api username password

How It Works

1. Input: The server reads JSON messages from stdin (one per line)
2. Processing: Each message is validated and forwarded via HTTP POST
3. Output: Responses are written to stdout, errors to stderr
4. Authentication: Optional HTTP Basic Auth using username/password
5. Error Handling: Invalid JSON or HTTP errors generate JSON-RPC error responses

Example Session

# Start the server
$ mcp-passthrough http://localhost:8080/invoke

🚀 Node.js passthrough server running for: http://localhost:8080/invoke

# Input a JSON-RPC message
{"jsonrpc":"2.0","method":"test","params":{},"id":1}

⬅️ Incoming: {"jsonrpc":"2.0","method":"test","params":{},"id":1}
➡️ Response: {"jsonrpc":"2.0","result":"success","id":1}
{"jsonrpc":"2.0","result":"success","id":1}

Error Handling

The server handles various error conditions and returns appropriate JSON-RPC error responses:

Invalid JSON Response from Backend

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32700,
    "message": "Unexpected token in JSON"
  }
}

HTTP Request Errors

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32603,
    "message": "Connection refused"
  }
}

Logging

The server uses stderr for logging, keeping stdout clean for JSON responses:

• 🚀 Server startup
• 🔑 Authentication status
• ⬅️ Incoming messages
• ➡️ Outgoing responses
• ⚠️ Warnings
• ❌ Errors

Configuration

Environment Variables

Currently, all configuration is done via command-line arguments. Future versions may support environment variables.

Command Line Arguments

1. Target URL (optional): HTTP endpoint to forward messages to

   • Default: http://localhost:8080/invoke

2. Username (optional): HTTP Basic Auth username

3. Password (optional): HTTP Basic Auth password

Requirements

• Node.js 14.0.0 or higher
• No external dependencies (uses only Node.js built-in modules)

Development

Local Development

# Clone and install
git clone <repository-url>
cd mcp-connector
npm install

# Run locally
node index.js

# Test with sample input
echo '{"jsonrpc":"2.0","method":"test","id":1}' | node index.js

Testing

npm test

Publishing

To publish this package to npm:

# Login to npm
npm login

# Publish
npm publish

Comparison with Java Version

This Node.js implementation maintains feature parity with the original Java version:

| Feature | Java | Node.js | |---------|------|---------| | stdin input processing | ✅ | ✅ | | HTTP POST forwarding | ✅ | ✅ | | Basic authentication | ✅ | ✅ | | JSON validation | ✅ | ✅ | | Error handling | ✅ | ✅ | | Keep-alive connections | ✅ | ✅ | | Command-line interface | ✅ | ✅ |

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Changelog

v1.0.0

• Initial release
• Complete port from Java version
• Command-line interface
• HTTP Basic Authentication support
• JSON-RPC error handling