# mrgoonie/human-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/mrgoonie/human-mcp
- Repository: https://github.com/mrgoonie/human-mcp

## Overview

##### Project type and purpose
- This is a standalone backend server (Human MCP Server v2.10.0) implemented in TypeScript/Node.js (supports Bun), exposing both stdio and HTTP/SSE transports.
- It implements the “Model Context Protocol” (MCP), hosting 27 multimodal “tools” (Eyes, Hands, Mouth, Brain) for AI agents (Claude Desktop, OpenCode, etc.) to call for vision, document processing, image/video generation & editing, speech generation, and advanced reasoning.

##### File structure
- Top-level “src” folder:
- src/server.ts – entry point that boots transports and the MCP core
- src/transports – HTTP server (file‐upload, /mcp API, SSE routes) and stdio transport
- src/tools – tool implementations grouped into “brain”, “eyes”, “hands”, “mouth” subfolders
- src/utils, src/types, src/prompts – shared utilities, type definitions, built-in prompt templates
- Config & scripts: Dockerfile, docker-compose.yaml, .env.example, Cloudflare R2 integration, GitHub Actions, Claude & OpenCode config scaffolding.
- Tests: unit, integration, e2e suites against HTTP and stdio transports.

##### README for additional insights
- Architecture section already outlines a 4×layer view:
AI Agent ←→ Human MCP Server ←→ Google Gemini & processing libs (Playwright, Jimp, rmbg, ffmpeg)
- Transport types and Cloudflare R2 for file uploads.
- Detailed MCP Tool breakdown reinforces the grouping of capabilities.

##### Detailed coverage
- Environment/config layer separately (port config, API key injection)
- Test harness interactions (tests/integration hitting HTTP API) if desired for clarity
- Don’t crowd—group tools by capability and annotate counts (4 Eyes, 16 Hands, 4 Mouth, 3 Brain)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Ingress"
        Client["MCP Clients"]:::external
        Client -->|requests| STDIO["STDIO Transport"]:::backend
        Client -->|HTTP/SSE requests| HTTP["HTTP/SSE Transport"]:::backend
    end

    HTTP --> FILEINT["File-Upload Interceptor"]:::backend
    FILEINT -->|optional upload| R2["Cloudflare R2"]:::storage
    R2 -.-> HTTP

    STDIO --> Core["MCP Core Router"]:::backend
    HTTP --> Core

    subgraph "Core & Config"
        Core --> Config["Config Loader"]:::util
    end

    subgraph "Shared Utilities"
        Config
        FS["File Storage Helper"]:::util
        IL["Image Loader"]:::util
        Logger["Logger"]:::util
        Errors["Error Definitions"]:::util
        RespFmt["HTTP/SSE Response Formatter"]:::util
    end

    subgraph "Types & Prompts"
        Types["Global Types"]:::util
        Prompts["Prompt Templates"]:::util
        DebugPrompts["Debugging Prompts"]:::util
    end

    subgraph "Tool Dispatcher"
        Core --> Dispatcher["Tool Dispatcher"]:::backend

        subgraph "Brain Tools"
            Brain["Brain Tools (3)"]:::tool
        end
        subgraph "Eyes Tools"
            Eyes["Eyes Tools (4)"]:::tool
        end
        subgraph "Hands Tools"
            Hands["Hands Tools (16)"]:::tool
        end
        subgraph "Mouth Tools"
            Mouth["Mouth Tools (4)"]:::tool
        end

        Dispatcher --> Brain
        Dispatcher --> Eyes
        Dispatcher --> Hands
        Dispatcher --> Mouth
    end

    subgraph "External Services"
        Gemini["Google Gemini APIs"]:::external
        Local["Local Processors\n(Jimp, rmbg, Playwright, ffmpeg)"]:::external
    end

    Brain -->|calls| Gemini
    Eyes -->|calls| Gemini
    Hands -->|calls| Gemini & Local
    Mouth -->|calls| Gemini

    Gemini --> Core
    Local --> Hands

    Core -->|response| STDIO
    Core -->|response| HTTP

    click STDIO "https://github.com/mrgoonie/human-mcp/blob/main/src/transports/stdio.ts"
    click HTTP "https://github.com/mrgoonie/human-mcp/blob/main/src/transports/http/server.ts"
    click FILEINT "https://github.com/mrgoonie/human-mcp/blob/main/src/transports/http/file-interceptor.ts"
    click R2 "https://github.com/mrgoonie/human-mcp/blob/main/src/utils/cloudflare-r2.ts"
    click Core "https://github.com/mrgoonie/human-mcp/blob/main/src/server.ts"
    click Dispatcher "https://github.com/mrgoonie/human-mcp/blob/main/src/index.ts"
    click Brain "https://github.com/mrgoonie/human-mcp/tree/main/src/tools/brain"
    click Eyes "https://github.com/mrgoonie/human-mcp/tree/main/src/tools/eyes"
    click Hands "https://github.com/mrgoonie/human-mcp/tree/main/src/tools/hands"
    click Mouth "https://github.com/mrgoonie/human-mcp/tree/main/src/tools/mouth"
    click Config "https://github.com/mrgoonie/human-mcp/blob/main/src/utils/config.ts"
    click FS "https://github.com/mrgoonie/human-mcp/blob/main/src/utils/file-storage.ts"
    click IL "https://github.com/mrgoonie/human-mcp/blob/main/src/utils/image-loader.ts"
    click Logger "https://github.com/mrgoonie/human-mcp/blob/main/src/utils/logger.ts"
    click Errors "https://github.com/mrgoonie/human-mcp/blob/main/src/utils/errors.ts"
    click RespFmt "https://github.com/mrgoonie/human-mcp/blob/main/src/utils/response-formatter.ts"
    click Types "https://github.com/mrgoonie/human-mcp/blob/main/src/types/index.ts"
    click Prompts "https://github.com/mrgoonie/human-mcp/blob/main/src/prompts/index.ts"
    click DebugPrompts "https://github.com/mrgoonie/human-mcp/blob/main/src/prompts/debugging-prompts.ts"

    classDef backend fill:#cee3f8,stroke:#3b7ea1,color:#0a2540;
    classDef tool fill:#d4f5d4,stroke:#4a8f4a,color:#254025;
    classDef external fill:#ffe0b2,stroke:#cc8b00,color:#663c00;
    classDef storage fill:none,stroke:#888,stroke-dasharray: 5 5,color:#555;
    classDef util fill:#f0f8ff,stroke:#8aa,stroke-width:1px,color:#336;
```
