Resolved

Build Script Misalignment with Integrated MCP Architecture

DevOps
Build System
Integration
Microservices
Architecture
Debugging

Build script errors due to incorrect assumption of standalone MCP microservice, when MCP is actually integrated as a subprocess within the API container.

Issue

The build script produced misleading errors indicating a missing MCP directory and non-existent Docker image (name/mcp:latest). This occurred because the script was designed for a standalone MCP microservice architecture, but the actual implementation integrates MCP as a subprocess within the API container, eliminating the need for a separate MCP service or directory.

Culprit

Architectural Mismatch

The script assumed:

  • A separate MCP directory (k3s/mcp/).
  • A standalone MCP Docker image (name/mcp:latest).
  • Independent MCP service deployment.

In reality, the architecture:

  • MCP runs as a subprocess via a dedicated server script (name_mcp_server.py).
  • Uses JSON-RPC 2.0 over stdin/stdout for communication.
  • No separate MCP directory or image exists.

Evidence of Integration

  • MCP implementation located in mcp_integration.py and name_mcp_server.py.
  • Tools integrated directly into the API container, including:
    • find_horse
    • get_user_context
    • create_booking

Solution

Updated Build Script

The build script was revised to:

  1. Remove MCP directory checks and separate build steps.
  2. Clarify messaging to reflect the integrated architecture: 
    echo "Building API server image (with integrated MCP server)..."
  3. Eliminate references to non-existent MCP Docker images.
  4. Update push instructions to reference only the API image (name/api:latest).

Architecture Verification

  • Confirmed MCP implementation adheres to the FastMCP 1.14.1 specification.
  • Verified stdio-based JSON-RPC 2.0 transport between API and MCP subprocess.
  • Ensured proper lifecycle management for the MCP subprocess.

Files Modified

  • Primary fix: build-images.sh script to align with integrated architecture.
  • Documentation: Updated to reflect the current design.

Result: The build process now accurately represents the integrated architecture, eliminating developer confusion about MCP deployment and resolving misleading error messages.