How greyhoundforty/code-engine-mcp works
Project type and purpose
• This is a standalone, Docker-ready Python microservice (an “MCP server”) that exposes a small set of tools (list_projects, list_applications, get_application) over an API for Claude to manage IBM Code Engine resources.
• It is not a full-stack web app with UI—rather it’s an open-source toolkit/server that sits between Claude (the LLM orchestrator) and the IBM Cloud Code Engine API.
File structure
• Top-level scripts:
• ce_mcp_server.py: the main server/entrypoint
• healthcheck.py: readiness/liveness probe
• utils.py & validate_schemas.py: modular helper code (auth, request building, response validation)
• Infrastructure:
• Dockerfile / .dockerignore: container definition
• mise.toml / pre-commit / pylintrc / secrets baseline: dev workflows, linting, security
• Tests:
• pytest tests in tests/ + standalone test_*.py scripts
Extract architecture insights from the README
• The server receives tool‐call requests from Claude, routes them to handlers, uses utility functions to call IBM Cloud IAM & Code Engine APIs, then formats and returns results.
• It can run locally or in Docker, configured by env vars (IBMCLOUD_API_KEY, REGION, etc.).
Main components and their interactions
A. User & Claude Interface
• External actor: Claude (or any LLM orchestrator) submits “tool calls”
• Optional: direct CLI invocation for local testing
B. MCP Server Layer (ce_mcp_server.py)
• HTTP or socket server that listens for tool calls
• Routing logic dispatches calls to specific handlers (list_projects, etc.)
C. Handler & Validation Layer
• validate_schemas.py ensures incoming parameters conform to expected schemas
• Each handler maps a tool name to a utility function
D. Utility Layer (utils.py)
• IAM authentication with IBM Cloud (via environment API key)
• API client calls to Code Engine (projects, applications)
• Data formatting & error handling
E. External Service
• IBM Cloud IAM endpoint: returns access tokens
• IBM Code Engine API: returns resource data
F. Healthcheck Endpoint (healthcheck.py)
• Simple probe for container orchestrators (Kubernetes, Docker)
G. Dev & Ops
• Docker build & run (Dockerfile)
• Dev workflows (mise, pre-commit)
• Automated tests (pytest)
Architectural patterns and design principles
• Layered architecture: Entry → Routing/Handlers → Utilities → External API
• Single-Responsibility: Each script/module has a clear role
• Configurable via environment variables for 12-factor compliance
• Container-first design for portability
a. Components & Groups
• “MCP Server” subdivided into:
• Server Entrypoint (ce_mcp_server.py)
• Schema Validation (validate_schemas.py)
• Handlers (tool functions)
• Utilities (utils.py)
• External Services: IBM Cloud IAM, Code Engine API
• Infrastructure: Docker container boundary, Healthcheck process
• DevOps & QA (side-band): Test suite, pre-commit hooks
b. Relationships & Data Flow
• Healthcheck: orchestration tool → healthcheck.py
c. Tech & Libraries
• Python 3.10+ runtime
• HTTP framework (Flask/FastAPI or custom) inside ce_mcp_server.py
• IBM Cloud SDK (requests or ibm-cloud-sdk-core)
• pytest for tests
• Docker for containerization
• mise for task automation
d. Visual Styling