jsonrpc-stdio-proxy

JSON-RPC Stdio Proxy is an efficient and lightweight tool designed to facilitate seamless communication between JSON-RPC clients (such as Claude Code and VS Code) and JSON-RPC servers, including the Model Context Protocol (MCP), Language Server Protocol (LSP), and Debug Adapter Protocol (DAP). This zero-configuration proxy effectively forwards stdio streams while capturing and logging JSON payloads directly into Apple Unified Logging (OSLog).

Key Features

• Universal Framing: Detects and parses both Newline-Delimited (MCP) and Header-Delimited (LSP/DAP with Content-Length) JSON-RPC streams automatically.
• Native Observability: Logs all incoming requests and outgoing responses to Apple Unified Logging, enabling detailed insights.
• Performance Metrics: Monitors session duration, byte counts, message counts, and computes Round-Trip Time (RTT) latency, providing minimum, maximum, and average metrics.
• Single Binary Distribution: Compiles into a compact, statically-linked executable using Rust/Tokio, without any external runtime dependencies.
• Efficient Process Management: Correctly handles end-of-file signals and process terminations (like SIGINT/Ctrl-C) to avoid creating zombie processes.

Usage Examples

To utilize the proxy, commands can be executed as follows:

Usage: jsonrpc-stdio-proxy [OPTIONS] -- <COMMAND>...

Arguments:
  <COMMAND>...  Command and arguments to execute and proxy (must follow '--')

Options:
  -s, --subsystem <SUBSYSTEM>  macOS OSLog subsystem identifier for log filtering
  -c, --category <CATEGORY>    macOS OSLog category identifier

Command Line Examples

• To proxy an MCP server with a custom subsystem identifier:

  jsonrpc-stdio-proxy --subsystem com.example.mcp -- bunx -y mongodb-mcp-server@latest
  

• To proxy a Language Server Protocol server:

  jsonrpc-stdio-proxy -- rust-analyzer
  

Log Viewing

Real-time monitoring of proxy logs can be achieved via the log CLI tool or the native Console.app on macOS. Use the following commands to stream or filter logs:

# Stream proxy logs in real-time
log stream --predicate 'subsystem == "com.paaloeye.jsonrpc-proxy"' --debug --info

# Filter logs by a custom subsystem
log stream --predicate 'subsystem == "com.example.mcp.memory"' --debug --info

# Display past session logs
log show --predicate 'subsystem == "com.paaloeye.jsonrpc-proxy"' --debug --info --last 1h

Performance Summary

Upon shutdown, the proxy automatically outputs a performance metrics summary:

--- Performance Metrics Summary ---
Session Duration: 24.5s
Client -> Server: 14 msgs, 2048 bytes
Server -> Client: 14 msgs, 45120 bytes
RTT Latency: Min 1.2ms, Max 45.1ms, Avg 12.4ms
Errors: 0

Development and Contributions

Guidelines for contributing and setting up the development environment can be found in the CONTRIBUTING.md file. This includes instructions for running pre-commit hooks, tests, and building the release binary.

References include links to libraries and tools leveraged in the project, such as Tokio, Clap, and the OSLog crate.

For questions or contributions, additional information can be sought on various platforms or through issues and pull requests in the repository.