How grzegorzwilk/tapir-archicad-mcp works
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).