Transport Selection Hardening for MCP Runtime

[ak15]

Problem

MCP stdio clients were intermittently failing handshake because runtime transport selection was ambiguous across environment variables and container defaults.

Observed failure mode:

• Client expected stdio.
• Server sometimes started in HTTP mode.
• MCP initialize/handshake then failed due to transport mismatch.

Root Cause

Transport resolution had multiple overlapping knobs over time (TRANSPORT, MCP_MODE, MODE, CLI flags), and historical Docker defaults previously forced HTTP unexpectedly.

Even after documentation updates, multiple env aliases still left room for drift and operator confusion.

Decision

Standardize on a single environment variable for transport:

• Canonical env: TRANSPORT
• Supported values: stdio, http, sse (sse remains deprecated)
• Runtime precedence: CLI args > TRANSPORT > default(stdio)

Removed runtime dependence on MCP_MODE and MODE to eliminate ambiguity.

Code Changes

1. Added dedicated resolver:

   • lib/transport-mode.js
   • Normalizes/validates transport mode.
   • Enforces deterministic precedence.

2. Updated startup integration:

   • mcpServer.js now consumes resolver output.
   • Startup logs include mode source (cli, TRANSPORT, default).
   • sse remains deprecated but is routed through HTTP server path for compatibility.

3. Container and config alignment:

   • Dockerfile: removed hidden transport default; runtime no longer silently forces HTTP.
   • docker-compose.yml: standardized on TRANSPORT.
   • .env.example: only TRANSPORT documented.

4. Metadata/docs alignment:

   • README.md: updated precedence and examples to single-env model.
   • tools-manifest.json: optional env vars aligned with code.

5. Regression tests:

   • tests/transport-mode.test.js covers default behavior, CLI precedence, canonical env behavior, and legacy-ignore expectation.

Why this scope is enterprise-appropriate

• Solves the production issue directly without broad refactor.
• Removes ambiguous configuration paths (operational simplicity).
• Keeps behavior explicit and testable.
• Preserves HTTP/SSE capabilities while making stdio startup predictable for MCP clients.

Validation

• Module syntax checks passed.
• tests/transport-mode.test.js passes.
• Full repository test suite could not be executed in this workspace due to missing dependencies (node_modules not installed), which is environment-related.