# marioluciofjr/mapas_mentais_mcp architecture

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

- Interactive diagram: https://gitdiagram.com/marioluciofjr/mapas_mentais_mcp
- Repository: https://github.com/marioluciofjr/mapas_mentais_mcp

## Overview

##### Project type and purpose
- This is a Python‐based MCP-Server tool (“mapas_mentais”) that acts as a parent MCP server. It dynamically launches and manages child MCP servers (one per mental-map operation) and integrates directly with Claude Desktop via the Model Context Protocol. Its core functionality is to generate six types of automated mental maps by invoking Anthropic’s Claude models through the FastMCP SDK and the uv command-line wrapper.

##### File structure
Top-level files only—no nested “frontend” or “backend” folders—indicate a single‐process, CLI-driven microservice:
- pyproject.toml + uv.lock → build and dependency management via UV (Astral)
- main.py → likely the script to bootstrap or delegate to server.py
- server.py → the MCP server implementation registering six mental map handlers
- README.md, LICENSE, .gitignore, .python-version → supporting and configuration files

There are no separate “lib” or “tests” directories, so the architecture revolves around one runtime component.

##### README for additional insights
- Uses Python ≥3.10, the `uv` package, and `mcp[cli]` (Anthropic’s Python SDK)
- Describes six commands (“apresenta”, “compara”, etc.) registered with FastMCP
- Integrates with Claude Desktop by adding an entry in `claude_desktop_config.json` that calls `uv run ... server.py`
- Runtime flow: user selects a tool in Claude Desktop → UV spawns the MCP server → commands get dispatched → each handler calls the Claude model → returns a structured mental map

##### Final recommendations
- Deployment context: annotate that everything runs locally under the .venv and is launched by Claude Desktop
- Validate with code: cross-check the imports in server.py and main.py to ensure you’ve included all critical libraries and flows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    CD["Claude Desktop"]:::external

    %% Runner and Runtime
    CLI["CLI Launcher (uv run main.py)"]:::runner
    PR["Python Runtime (.venv)"]:::runner

    %% Core Service
    MCP["Parent MCP Server"]:::internal

    %% Handlers Subgraph
    subgraph "Mental-Map Handlers"
        H1["apresenta Handler"]:::internal
        H2["compara Handler"]:::internal
        H3["sintetiza Handler"]:::internal
        H4["analisa Handler"]:::internal
        H5["explora Handler"]:::internal
        H6["resume Handler"]:::internal
    end

    %% External Model API
    API["Anthropic Claude API"]:::external

    %% Project Config Files
    subgraph "Project Files"
        PY["pyproject.toml"]:::config
        UVL["uv.lock"]:::config
        RD["README.md"]:::config
        LIC["LICENSE"]:::config
        PV[".python-version"]:::config
        GI[".gitignore"]:::config
    end

    %% Data Flows
    CD -->|"executes CLI command"| CLI
    CLI -->|"spawns Python process"| PR
    PR -->|"loads server.py"| MCP
    MCP -->|"registers handlers"| H1
    MCP -->|"registers handlers"| H2
    MCP -->|"registers handlers"| H3
    MCP -->|"registers handlers"| H4
    MCP -->|"registers handlers"| H5
    MCP -->|"registers handlers"| H6
    H1 -->|"HTTPS via FastMCP"| API
    H2 -->|"HTTPS via FastMCP"| API
    H3 -->|"HTTPS via FastMCP"| API
    H4 -->|"HTTPS via FastMCP"| API
    H5 -->|"HTTPS via FastMCP"| API
    H6 -->|"HTTPS via FastMCP"| API
    API -->|"model response"| H1
    API -->|"model response"| H2
    API -->|"model response"| H3
    API -->|"model response"| H4
    API -->|"model response"| H5
    API -->|"model response"| H6
    MCP -->|"streams result via MCP protocol"| CD

    %% Click Events
    click CLI "https://github.com/marioluciofjr/mapas_mentais_mcp/blob/main/main.py"
    click MCP "https://github.com/marioluciofjr/mapas_mentais_mcp/blob/main/server.py"
    click PY "https://github.com/marioluciofjr/mapas_mentais_mcp/blob/main/pyproject.toml"
    click UVL "https://github.com/marioluciofjr/mapas_mentais_mcp/blob/main/uv.lock"
    click RD "https://github.com/marioluciofjr/mapas_mentais_mcp/blob/main/README.md"
    click LIC "https://github.com/marioluciofjr/mapas_mentais_mcp/tree/main/LICENSE"
    click PV "https://github.com/marioluciofjr/mapas_mentais_mcp/blob/main/.python-version"
    click GI "https://github.com/marioluciofjr/mapas_mentais_mcp/blob/main/.gitignore"

    %% Styles
    classDef external fill:#c2f0c2,stroke:#333,stroke-width:1px
    classDef runner fill:#ffd966,stroke:#333,stroke-width:1px
    classDef internal fill:#9fc5e8,stroke:#333,stroke-width:1px
    classDef config fill:#f4cccc,stroke:#333,stroke-width:1px

    class CD,API external
    class CLI,PR runner
    class MCP,H1,H2,H3,H4,H5,H6 internal
    class PY,UVL,RD,LIC,PV,GI config
```
