Transport-level routing for MCP/ACP protocols
Reference Implementation
The C implementation of stdio Bus serves as the reference implementation for the protocol specification. This page describes its characteristics, current limitations, and conformance requirements for alternative implementations.
The C Implementation
The canonical stdio Bus implementation is written in C11 and serves as the reference for the protocol specification. It demonstrates the minimal, deterministic approach to transport-level routing that defines stdio Bus.
The reference implementation prioritizes correctness and simplicity over features. It implements the complete normative specification while maintaining a small, auditable codebase with no external dependencies.
Implementation Characteristics
The reference implementation embodies the core design principles of stdio Bus: minimal complexity, deterministic behavior, and zero external dependencies.
C11 Standard
Written in strict C11 with -Wall -Wextra -Werror. No compiler extensions or non-standard features.
Single-Threaded
All I/O handled in one event loop. No threading complexity, mutexes, or race conditions.
Platform I/O
Uses epoll on Linux and kqueue on macOS for efficient I/O multiplexing.
No Dependencies
Only libc and POSIX APIs. No external libraries to install, link, or update.
Build Requirements
| Requirement | Details |
|---|---|
| Compiler | GCC 4.9+ or Clang 3.4+ with C11 support |
| Build System | Make (primary) or CMake 3.10+ |
| Platform | Linux (epoll) or macOS (kqueue) |
| Dependencies | libc and POSIX APIs only |
Current Limitations
The reference implementation has known limitations. These are documented to help users understand the current scope and to guide alternative implementations that may address these constraints.
Resource Limits
- Maximum 1024 file descriptors (MAX_CONNECTIONS)
- Maximum 1024 concurrent sessions (STDIO_BUS_MAX_SESSIONS)
- Maximum 4096 pending requests (STDIO_BUS_MAX_PENDING_REQUESTS)
Missing Features
- No authentication—any connection is trusted
- No TLS—TCP mode uses plaintext only
- No metrics or health endpoints
- No hot reload—configuration changes require restart
- No worker health checks beyond exit monitoring
- No request timeouts—pending requests only cleaned on worker exit
Protocol Constraints
- Minimal JSON parsing—only routing fields extracted
- No JSON-RPC batch request handling
- String sessionId only—non-string values ignored
Known Issues
Restart backoff not enforced
The exponential backoff delay is calculated and logged but restarts occur immediately.
Stdio mode single client
In stdio mode, there is exactly one client connection. Reconnection is not possible.
Alternative Implementations
Alternative implementations of stdio Bus are permitted and encouraged. The protocol specification is designed to be implementation-agnostic, allowing implementations in any language or runtime environment.
Open Standard
stdio Bus is a protocol standard, not a product. Any implementation that conforms to the normative specification is a valid stdio Bus implementation. The C reference implementation is one such implementation, not the only permitted one.
Potential alternative implementations might include:
| Language/Runtime | Potential Benefits |
|---|---|
| Rust | Memory safety guarantees, async/await, cross-platform |
| Go | Goroutines for concurrency, simple deployment, cross-platform |
| Node.js | JavaScript ecosystem integration, rapid prototyping |
| Python | asyncio support, scripting flexibility, rapid development |
Conformance Requirements
To be considered a conforming stdio Bus implementation, an implementation must satisfy the following requirements. These are derived from the normative specification and represent the minimum behavioral guarantees that clients and workers can rely upon.
CONF-1
Support all three operating modes: stdio, Unix socket, and TCP
CONF-2
Implement NDJSON framing for all message I/O
CONF-3
Route messages by sessionId with worker affinity
CONF-4
Correlate responses to requests by id field
CONF-5
Spawn workers via fork/exec with stdin/stdout pipes
CONF-6
Handle SIGTERM for graceful shutdown
CONF-7
Implement backpressure when output queues exceed limits
CONF-8
Restart workers according to configured limits
Full Specification
The complete normative specification with RFC 2119 requirements is available on the Specification page. Implementers should refer to that document for the authoritative behavioral contracts.
Source Repository
The reference implementation source code is available on GitHub. The repository includes the C implementation, example workers, test suite, and documentation.
| Directory | Contents |
|---|---|
include/ | C header files (public API) |
src/ | C implementation source |
examples/ | Example workers and configurations |
spec/ | Normative specification documents |
docs/ | Developer documentation |
tests/ | Test suite |