How to log the MCP JSON protocol over stdio

|

The Minecraft Protocol (MCP) JSON logging over stdio (standard input/output) is a powerful technique for monitoring, debugging, or processing Minecraft-related communications between client and server. Whether you’re building bots, debugging modded servers, or integrating Minecraft with external tools, intercepting the JSON message stream via stdin and stdout allows fine-grained control and complete transparency.

In this article, we’ll walk through:

  • The basics of MCP JSON protocol and why to log it

  • Setting up a command-line wrapper to intercept and log MCP JSON via stdio

  • Implementing in multiple languages—with code examples

  • Best practices in logging, performance, and reliability

  • A comprehensive conclusion summarizing key takeaways and next steps

What Is the MCP JSON Protocol and Why Log It?

The MCP JSON protocol is the Minecraft server/client wire protocol, often used in modern integrations, especially with bots and proxies. Instead of binary frames, some implementations use JSON objects to represent requests, responses, notifications, and events. Logging this JSON protocol over standard streams is valuable because:

  • Debugging: Observe every message exchanged, spot errors, unexpected fields, or invalid JSON.

  • Testing: Simulate input/output flows, replay sequences, or validate responses.

  • Extensibility: Route logs into analysis tools, dashboards, or persist them in files or databases.

  • Transparency: Especially in headless or CI-based deployments, stdio logging gives you insight without GUIs.

Overview of stdio-Based Logging Approach

At a high level, intercepting MCP JSON over stdio involves creating a wrapper or proxy between the real MCP process and its consumer:

[ Minecraft Process ] ↔ stdio ↔ [ Your Logger Wrapper ] ↔ stdio ↔ [ Downstream Consumer ]

Your wrapper sits in the middle, reading from its stdin, logging messages, and forwarding them to stdout; likewise in the reverse direction if needed (client/server).

A generalized loop:

  1. Read incoming JSON message from stdin

  2. Parse (or just read as text)

  3. Log to file, console, or external sink

  4. Forward to stdout for continuation

We’ll implement this basic pattern in Python, Node.js (JavaScript/TypeScript), and Golang.

Python Example

Simple Python Logger Using sys.stdin and sys.stdout

import sys
import json
import timedef log_message(prefix, msg):
timestamp = time.strftime(‘%Y-%m-%d %H:%M:%S’)
print(f”{timestamp} {prefix}: {msg}“, file=sys.stderr)def main():
for line in sys.stdin:
line = line.strip()
if not line:
continue
# Log raw line
log_message(“RECV”, line)
# Optionally parse and reformat:
try:
obj = json.loads(line)
nice = json.dumps(obj, indent=2)
log_message(“PARSED”, nice)
except json.JSONDecodeError as e:
log_message(“ERROR”, f”Invalid JSON: {e}“)
# Forward line
print(line, flush=True)if __name__ == “__main__”:
main()

Explanation:

  • Reads line by line from stdin.

  • Logs to stderr (so as not to interfere with the stdio stream).

  • Parses JSON for pretty-printing.

  • Forwards the original line to stdout.

  • flush=True ensures low latency.

Two-Way Logging

If your wrapper needs to handle bidirectional JSON (client ↔ server), and standard io is just one direction at a time, you’d use two wrappers or explicit piping. But often MCP is just one-way JSON streams.

Node.js (JavaScript/TypeScript) Example

JavaScript Version

#!/usr/bin/env node

const readline = require(‘readline’);

function log(prefix, msg) {
const timestamp = new Date().toISOString();
console.error(`${timestamp} ${prefix}: ${msg}`);
}

const rl = readline.createInterface({
input: process.stdin,
output: process.stdout,
terminal: false
});

rl.on(‘line’, (line) => {
const trimmed = line.trim();
if (!trimmed) return;

log(‘RECV’, trimmed);

try {
const obj = JSON.parse(trimmed);
const pretty = JSON.stringify(obj, null, 2);
log(‘PARSED’, pretty);
} catch (e) {
log(‘ERROR’, `Invalid JSON: ${e.message}`);
}

console.log(trimmed);
});

Notes:

  • Uses readline for streaming input.

  • Logs to stderr via console.error.

  • Parses and pretty-prints JSON.

  • Forwards unchanged line to stdout.

TypeScript Variant

#!/usr/bin/env ts-node

import * as readline from ‘readline’;

const rl = readline.createInterface({
input: process.stdin,
output: process.stdout,
terminal: false
});

rl.on(‘line’, (line: string) => {
const trimmed = line.trim();
if (!trimmed) return;

console.error(new Date().toISOString(), ‘RECV:’, trimmed);

try {
const obj = JSON.parse(trimmed);
console.error(new Date().toISOString(), ‘PARSED:’, JSON.stringify(obj, null, 2));
} catch (e) {
console.error(new Date().toISOString(), ‘ERROR: Invalid JSON:’, e);
}

console.log(trimmed);
});

Go (Golang) Example

package main

import (
“bufio”
“encoding/json”
“fmt”
“io”
“os”
“time”
)

func logMessage(prefix, msg string) {
timestamp := time.Now().Format(“2006-01-02 15:04:05”)
fmt.Fprintf(os.Stderr, “%s %s: %s\n”, timestamp, prefix, msg)
}

func main() {
reader := bufio.NewReader(os.Stdin)
writer := bufio.NewWriter(os.Stdout)
defer writer.Flush()

for {
line, err := reader.ReadString(‘\n’)
if err != nil {
if err == io.EOF {
break
}
logMessage(“ERROR”, “Read error: “+err.Error())
os.Exit(1)
}
trimmed := line[:len(line)-1] // strip newline
if trimmed == “” {
continue
}
logMessage(“RECV”, trimmed)

var obj interface{}
if err := json.Unmarshal([]byte(trimmed), &obj); err != nil {
logMessage(“ERROR”, “Invalid JSON: “+err.Error())
} else {
pretty, _ := json.MarshalIndent(obj, “”, ” “)
logMessage(“PARSED”, string(pretty))
}

writer.WriteString(trimmed + “\n”)
writer.Flush() // ensure prompt forwarding
}
}

Explanation of Code Patterns

  1. Stderr for Logging:
    Using stderr ensures logs don’t mix with the stdio JSON stream, which remains clean.

  2. Line-Oriented IO:
    MCP JSON messages often are single-line – so reading line-by-line is straightforward. If JSON might span multiple lines, use a framing or delimiter pattern.

  3. JSON Parsing:
    Optional, but helps validate message structure and allows pretty-printing for better human readability.

  4. Forwarding:
    Must forward exactly what was received (including whitespace or newlines as required by protocol) to avoid protocol mismatches.

  5. Performance:

    • Use buffered writer (Go) or flush calls.

    • Avoid overly heavy parsing (e.g. deep pretty-printing) in production; optionally make it configurable.

Advanced Features and Enhancements

a. Selective Logging

Add criteria to filter logs: only log messages containing specific keys or from certain message types.

Python example:

if 'player' in obj.get('type', ''):
log_message("PLAYER_MSG", nice)

b. Timestamps and Unique IDs

Append timestamps or even a generated unique ID to each message to correlate request/response pairs.

const id = Date.now().toString(36);
log('ID', id);

c. Output to Multiple Sinks

You might log to files, syslog, or send JSON to an analysis service.

Python extension:

with open('mcp.log', 'a') as f:
f.write(f"{timestamp} {prefix}: {msg}\n")

d. Structured Logging

Instead of free-form text, log structured JSON lines for easy ingestion:

logLine := map[string]interface{}{
"time": timestamp,
"prefix": prefix,
"message": msg,
}
j, _ := json.Marshal(logLine)
fmt.Fprintln(os.Stderr, string(j))

Putting It All Together: A Sample CLI Usage

Suppose you’re using a Minecraft bot or proxy that reads JSON from stdin and writes to stdout:

minecraft_proxy | python mcp_log_wrapper.py | downstream_consumer

  • minecraft_proxy emits JSON records

  • mcp_log_wrapper.py logs and forwards them

  • downstream_consumer processes them

You can also run bidirectional:

client_process | ./log_wrapper | server_process

Use two wrappers if both directions need logging, or write a more complex multiplexer.

Common Pitfalls and Best Practices

Pitfall Best Practice
Logging to stdout and mixing the stream Always log to stderr to keep stdout clean for downstream processing
Not flushing output Explicitly flush or use line-buffered IO to avoid message buffering
Failing to handle EOF Check for EOF to gracefully terminate instead of hanging or crashing
Overloading parsing in production Make parsing optional/configurable; skip pretty-printing if performance critical
Long-running memory leaks Avoid accumulating logs in memory; stream directly to files or roll logs

Real-World Use Cases

  • Bot development: Capture the exact JSON protocol exchange to troubleshoot commands, metadata, or handshake issues.

  • Proxying: When building chat or command proxies, log all messages for audit and debugging.

  • Integration: Feed the JSON traffic into machine learning pipelines, dashboards, or observability platforms (e.g. Elastic, Splunk).

  • Testing & QA: Replay recorded JSON traffic against staging servers, compare outputs, and run regression tests.

Conclusion

Logging the MCP JSON protocol over stdio is a simple yet powerful method to gain visibility into the communication between clients, servers, bots, or proxies. By writing a lightweight wrapper in languages such as Python, Node.js, or Go, you can intercept JSON lines from standard input, log them—optionally with parsing and pretty-printing—then forward them to standard output for continued processing.

Key principles include:

  • Always log to stderr so as to not interfere with the protocol stream.

  • Use line-by-line processing, unless messages span multiple lines.

  • Parse JSON optionally for readability and validation, but keep performance in mind.

  • Flush output promptly to avoid latency or stalls.

  • Build optional enhancements like filtering, structured JSON logging, multi-sink outputs, timestamps, and unique identifiers.

  • Avoid pitfalls like stdout contamination, buffering issues, and memory misuse.

Whether you’re debugging, testing, or integrating, this approach provides a transparent window into your MCP JSON exchanges. You can tailor the wrapper to your needs—for example, adding CLI flags to toggle pretty-printing or choose log destinations—and embed it within pipelines with a single, composable pattern.