IOWrapper

A Go application that wraps stdio-based programs and exposes them via HTTP. Originally built to enable remote access to MCP (Model Context Protocol) servers when only stdio transport was available.

Use Cases

• Run MCP servers remotely over HTTP
• Containerize any stdio-based JSON-RPC application
• Add HTTP interface to CLI tools without modifying them
• Bridge legacy stdio protocols to modern HTTP APIs

Quick Start

Using Docker

docker run -p 8222:8222 \
  -e CLI_TOOL_COMMAND="npx" \
  -e CLI_TOOL_ARGS="-y @modelcontextprotocol/server-memory" \
  ghcr.io/kirha-ai/iowrapper:latest

From Source

# Clone and build
git clone https://github.com/kirha-ai/iowrapper.git
cd iowrapper
go build -o iowrapper cmd/main.go

# Run
export CLI_TOOL_COMMAND="npx"
export CLI_TOOL_ARGS="-y @modelcontextprotocol/server-memory"
./iowrapper server

Configuration

Environment Variable	Description	Default
CLI_TOOL_COMMAND	The command to execute	(required)
CLI_TOOL_ARGS	Arguments for the command	(empty)
SERVER_PORT	HTTP server port	8222

Usage

Send JSON-RPC requests to the HTTP endpoint:

curl -X POST http://localhost:8222 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'

How It Works

┌─────────┐     HTTP      ┌───────────┐     stdio     ┌───────────┐
│  Client │ ──────────>   │ IOWrapper │ ──────────>   │ MCP Server│
│         │ <──────────   │           │ <──────────   │  (stdio)  │
└─────────┘               └───────────┘               └───────────┘

1. IOWrapper starts your program as a child process
2. Captures stdin/stdout/stderr pipes
3. Exposes an HTTP endpoint for JSON-RPC requests
4. Translates HTTP requests to stdin writes
5. Reads responses from stdout and returns via HTTP

Parallel Request Handling

IOWrapper supports concurrent HTTP requests over a single stdio stream by:

• Assigning internal UUIDs to track each request
• Using a concurrent map to store pending request channels
• Matching responses to requests when they arrive on stdout

Docker

Pre-built Image

docker pull ghcr.io/kirha-ai/iowrapper:latest

Custom Image

Create a Dockerfile to wrap your specific tool:

FROM ghcr.io/kirha-ai/iowrapper:latest

# Install your MCP server or tool
RUN npm install -g @your/mcp-server

ENV CLI_TOOL_COMMAND="your-command"
ENV CLI_TOOL_ARGS="your args here"

EXPOSE 8222

Build Arguments

When building from source, pass GH_TOKEN for private dependencies:

docker build --build-arg GH_TOKEN=your_token -t iowrapper .

Architecture

├── cmd/                    # CLI entry point
├── di/                     # Dependency injection
├── internal/
│   ├── adapters/
│   │   ├── executors/     # stdio wrapper implementation
│   │   └── handlers/      # HTTP/JSON-RPC handler
│   ├── applications/      # Business logic
│   └── core/
│       └── ports/         # Interfaces

Examples

MCP Memory Server

docker run -p 8222:8222 \
  -e CLI_TOOL_COMMAND="npx" \
  -e CLI_TOOL_ARGS="-y @modelcontextprotocol/server-memory" \
  ghcr.io/kirha-ai/iowrapper:latest

MCP Filesystem Server

docker run -p 8222:8222 \
  -v /path/to/data:/data \
  -e CLI_TOOL_COMMAND="npx" \
  -e CLI_TOOL_ARGS="-y @modelcontextprotocol/server-filesystem /data" \
  ghcr.io/kirha-ai/iowrapper:latest

Development

Prerequisites

• Go 1.24+
• Wire (for dependency injection)

Build

go build -o iowrapper cmd/main.go

Generate Wire

cd di && wire

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.