# grzegorzwilk/tapir-archicad-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/grzegorzwilk/tapir-archicad-mcp
- Repository: https://github.com/grzegorzwilk/tapir-archicad-mcp

## Overview

##### Project Type & Purpose
- This is a middleware “MCP Server” tool written in Python.
- It bridges an AI agent (e.g., Claude for Desktop) with running Archicad instances by exposing the Tapir JSON API as Model Context Protocol (MCP) tools.
- Its core function is to auto-generate ~80 MCP tools (from Tapir API schema) and dispatch calls to one or more Archicad instances.

##### Main System Components
a. AI Agent (e.g., Claude)
b. MCP Client (Claude for Desktop)
c. Archicad Tapir MCP Server (this project)
- **Entry Point**: `tapir_archicad_mcp.server`
- **App Definition**: `tapir_archicad_mcp.app`
- **Context/Connection Manager**: `tapir_archicad_mcp.context`
- **Tools Layer**:
- Generated Tools: `tools/generated/*.py`
- Custom Extensions: `tools/custom/*.py`
- **Code-gen Script**: `scripts/generate_tools.py`
d. multiconn_archicad Library (handles low-level HTTP communication)
e. One or More Archicad Instances w/ Tapir Add-On

##### Relationships & Data Flow
1. AI Agent → MCP Client (invokes tool calls)
2. MCP Client ↔ MCP Server (over MCP/JSON-RPC via stdin/stdout)
3. MCP Server → multiconn_archicad (invokes low-level API calls)
4. multiconn_archicad → Archicad Instances (HTTP calls via Tapir add-on)
5. Responses flow back up the chain to the AI Agent.

##### Architectural Patterns & Design Principles
- **Modular Tool Architecture**: Generated vs. custom tools separated under `tools/generated` and `tools/custom`.
- **Configuration & Code Generation**: The `scripts/generate_tools.py` script runs at build time to reflect the Tapir API schema.
- **Strong Typing**: Pydantic models ensure all tool inputs/results follow strict schemas.
- **Multi-Instance Management**: The context module tracks and routes calls to multiple Archicad instances in parallel.

##### Relevant Technologies & Frameworks
- Python 3.10+
- `uv` package for virtual environments and run commands
- Pydantic (data validation and modeling)
- multiconn_archicad (underlying communication library)
- Tapir JSON API (hosted inside Archicad via Add-On)

##### Essential Details to Capture
- The fact that the server can handle **multiple Archicad instances** concurrently.
- The **build-time generation** of tools, not handwritten.
- The **layered dispatch** (server → registry → Pydantic models → multiconn_archicad).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    AiAgent["AI Agent"]:::external
    MCPClient["MCP Client (Claude for Desktop)"]:::external

    %% MCP Server Core
    subgraph "TapirArchicadMCP Server"
        direction TB
        Entry["Entry Point"]:::servercore
        App["App Definition"]:::servercore
        Context["Context / Connection Manager"]:::servercore

        subgraph "Tools Layer"
            direction TB
            Registration["Tool Registration"]:::servercore
            Generated["Generated Tools"]:::generated
            Custom["Custom Extensions"]:::custom
        end
    end

    %% Code Generation & Config
    Script["Code-Gen Script"]:::script
    Config["Project Configuration\n(pyproject.toml)"]:::config
    Docs1["MCP Docs"]:::docs
    Docs2["Python SDK README"]:::docs
    Docs3["Project Brief"]:::docs

    %% Downstream Libraries & Instances
    Multiconn["multiconn_archicad Library"]:::external
    subgraph "Archicad Instances"
        ArchInst["Archicad Instance(s)\nwith Tapir Add-On"]:::external
    end

    %% Data Flows
    AiAgent -->|"invokes tool calls"| MCPClient
    MCPClient -->|"MCP JSON-RPC"| Entry
    Entry -->|"initializes App"| App
    App -->|"loads Registry"| Registration
    Registration --> Generated
    Registration --> Custom
    App -->|"uses Context"| Context
    Context -->|"routes calls"| Multiconn
    App -->|"invokes low-level API"| Multiconn
    Multiconn -->|"HTTP/JSON"| ArchInst
    ArchInst -->|"HTTP/JSON Response"| Multiconn
    Multiconn -->|"returns results"| App
    App -->|"MCP JSON-RPC Response"| MCPClient
    MCPClient -->|"sends response"| AiAgent

    Script -.->|"build-time generation"| Generated
    Config -.-> Entry
    Docs1 -.-> Context
    Docs2 -.-> Context
    Docs3 -.-> Context

    %% Click Events
    click Entry "https://github.com/grzegorzwilk/tapir-archicad-mcp/blob/master/src/tapir_archicad_mcp/server.py"
    click App "https://github.com/grzegorzwilk/tapir-archicad-mcp/blob/master/src/tapir_archicad_mcp/app.py"
    click Context "https://github.com/grzegorzwilk/tapir-archicad-mcp/blob/master/src/tapir_archicad_mcp/context.py"
    click Generated "https://github.com/grzegorzwilk/tapir-archicad-mcp/tree/master/src/tapir_archicad_mcp/tools/generated/"
    click Custom "https://github.com/grzegorzwilk/tapir-archicad-mcp/tree/master/src/tapir_archicad_mcp/tools/custom/"
    click Registration "https://github.com/grzegorzwilk/tapir-archicad-mcp/blob/master/src/tapir_archicad_mcp/tools/registration.py"
    click Script "https://github.com/grzegorzwilk/tapir-archicad-mcp/blob/master/scripts/generate_tools.py"
    click Config "https://github.com/grzegorzwilk/tapir-archicad-mcp/blob/master/pyproject.toml"
    click Docs1 "https://github.com/grzegorzwilk/tapir-archicad-mcp/blob/master/context/MCP-docs.txt"
    click Docs2 "https://github.com/grzegorzwilk/tapir-archicad-mcp/blob/master/context/MCP-pythonsdk-README.md"
    click Docs3 "https://github.com/grzegorzwilk/tapir-archicad-mcp/blob/master/context/project-brief-for-AI.md"

    %% Styles
    classDef external fill:#c2f0c2,stroke:#2d7a2d,color:#000
    classDef servercore fill:#d9e8fb,stroke:#3b64a6,color:#000
    classDef generated fill:#fff2b2,stroke:#b58500,color:#000
    classDef custom fill:#ffdab2,stroke:#cc7000,color:#000
    classDef script fill:#e5d3f2,stroke:#7a3b92,color:#000
    classDef config fill:#f0f0f0,stroke:#888888,color:#000
    classDef docs fill:#f7f7f7,stroke:#bbbbbb,color:#000
```
