# greyhoundforty/code-engine-mcp architecture

> Architecture diagram of the GitHub repository greyhoundforty/code-engine-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/greyhoundforty/code-engine-mcp
- Repository: https://github.com/greyhoundforty/code-engine-mcp

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        User["User / Claude"]:::external
    end

    %% Docker Container Boundary
    subgraph "Docker Container: ibm-code-engine-mcp"
        subgraph "MCP Server"
            Entrypoint["ce_mcp_server.py\n(Entrypoint & Router)"]:::server
            Validation["validate_schemas.py\n(Schema Validation)"]:::server
            Handlers["Handlers:\nlist_projects, list_applications,\nget_application"]:::server
            Utils["utils.py\n(IAM Auth, CE API Calls,\nData Formatting)"]:::util
            Health["healthcheck.py\n(Healthcheck Endpoint)"]:::server
        end
    end

    %% External Services
    IBM_IAM["IBM Cloud IAM"]:::external
    CodeEngine["IBM Code Engine API"]:::external
    Orchestrator["Container Orchestrator\n(K8s/Docker)"]:::external

    %% Dev & Ops
    subgraph "Dev & Ops"
        Dockerfile["Dockerfile"]:::dev
        Dockerignore[".dockerignore"]:::dev
        Mise[".mise.toml"]:::dev
        PreCommit[".pre-commit-config.yaml"]:::dev
        Pylintrc[".pylintrc"]:::dev
        Secrets[".secrets.baseline"]:::dev
        Requirements["requirements.txt"]:::dev
        Readme["README.md"]:::dev
        subgraph "Documentation"
            Docs["docs/"]:::dev
        end
        subgraph "Tests"
            Test1["tests/test_server.py"]:::dev
            Test2["test_ce_client.py"]:::dev
            Test3["test_mcp.py"]:::dev
            Test4["test_mcp_imports.py"]:::dev
        end
    end

    %% Data Flows
    User -->|"Tool Calls"| Entrypoint
    Entrypoint -->|"Validate Schema"| Validation
    Validation -->|"Dispatch to Handler"| Handlers
    Handlers -->|"Call Utility"| Utils
    Utils -->|"IAM Auth Request"| IBM_IAM
    IBM_IAM -->|"Access Token"| Utils
    Utils -->|"List Projects / Apps Call"| CodeEngine
    CodeEngine -->|"Resource Data"| Utils
    Utils -->|"Formatted JSON"| Handlers
    Handlers -->|"Response"| Entrypoint
    Entrypoint -->|"Return Result"| User

    Orchestrator -->|"Health Probe"| Health

    %% Click Events
    click Entrypoint "https://github.com/greyhoundforty/code-engine-mcp/blob/main/ce_mcp_server.py"
    click Validation "https://github.com/greyhoundforty/code-engine-mcp/blob/main/validate_schemas.py"
    click Handlers "https://github.com/greyhoundforty/code-engine-mcp/blob/main/ce_mcp_server.py"
    click Utils "https://github.com/greyhoundforty/code-engine-mcp/blob/main/utils.py"
    click Health "https://github.com/greyhoundforty/code-engine-mcp/blob/main/healthcheck.py"
    click Dockerfile "https://github.com/greyhoundforty/code-engine-mcp/tree/main/Dockerfile"
    click Dockerignore "https://github.com/greyhoundforty/code-engine-mcp/blob/main/.dockerignore"
    click Mise "https://github.com/greyhoundforty/code-engine-mcp/blob/main/.mise.toml"
    click PreCommit "https://github.com/greyhoundforty/code-engine-mcp/blob/main/.pre-commit-config.yaml"
    click Pylintrc "https://github.com/greyhoundforty/code-engine-mcp/blob/main/.pylintrc"
    click Secrets "https://github.com/greyhoundforty/code-engine-mcp/blob/main/.secrets.baseline"
    click Requirements "https://github.com/greyhoundforty/code-engine-mcp/blob/main/requirements.txt"
    click Readme "https://github.com/greyhoundforty/code-engine-mcp/blob/main/README.md"
    click Docs "https://github.com/greyhoundforty/code-engine-mcp/tree/main/docs/"
    click Test1 "https://github.com/greyhoundforty/code-engine-mcp/blob/main/tests/test_server.py"
    click Test2 "https://github.com/greyhoundforty/code-engine-mcp/blob/main/test_ce_client.py"
    click Test3 "https://github.com/greyhoundforty/code-engine-mcp/blob/main/test_mcp.py"
    click Test4 "https://github.com/greyhoundforty/code-engine-mcp/blob/main/test_mcp_imports.py"

    %% Styles
    classDef server fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef util fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef dev fill:#D3D3D3,stroke:#333,stroke-width:1px
```
