Archicad Tapir MCP

An agent-friendly, read-only-first MCP bridge for Archicad and the Tapir Add-On.

Project continuity

• PRD.md — product requirements and architecture direction.
• docs/PROJECT_STATE.md — current implementation, verification, gaps, and next work.
• docs/DECISIONS.md — architectural decision log.
• docs/EXPERIMENTS.md — live Archicad/Tapir evidence.
• docs/TARGET_CONTEXTS.md — sticky per-task target binding and nickname contract.
• docs/OPENCODE.md — OpenCode as the local end-to-end MCP agent harness (operator runs OpenCode; OpenCode must invent the MCP sequence).
• AGENTS.md — mandatory maintenance protocol for agent sessions.

The current read-only MCP surface includes:

• archicad_discover — low-level endpoint diagnostics.
• archicad_instances — human-readable project cards and stable runtime IDs.
• archicad_bind — sticky target context from a project hint, candidate, or witnessed foreground intent.
• archicad_capabilities — in-band workflow and coverage guidance.
• archicad_capture_context — fresh semantic observation with focus parts.
• archicad_inspect — progressive expand of snapshot-scoped handles.
• archicad_read — up to 20 safe low-level reads; returns/revalidates context.

Requirements

• Node.js 24+
• npm
• Windows production environment
• Archicad on the same Windows machine
• Tapir installed in Archicad

The current repository can still be developed and tested from WSL2, but the production MCP process is intended to run natively on Windows.

Setup

npm install
npm run build
npm test

Probe Archicad

Start Archicad completely, then run:

npm run probe

Discovery tries, in order:

1. ARCHICAD_HOST when explicitly configured for development;
2. 127.0.0.1, which is the normal Windows production route;
3. the default WSL2 gateway when running the development probe from WSL.

To force the Windows host during WSL development:

ARCHICAD_HOST=172.20.112.1 ARCHICAD_PORTS=19723-19743 npm run probe

The WSL gateway/LAN route is development-only. Do not make production behavior depend on it.

Run the MCP server

Run the production service from Windows PowerShell:

npm run build
node C:\path\to\archicad-tapir-mcp\dist\index.js

Example local MCP configuration:

{
  "mcpServers": {
    "archicad": {
      "command": "node",
      "args": [
        "C:\\path\\to\\archicad-tapir-mcp\\dist\\index.js"
      ]
    }
  }
}

The server writes protocol messages only to stdout and diagnostics to stderr.

End-to-end test with OpenCode

OpenCode is the local agent used to prove MCP tool descriptions are enough for discovery and observation. You play the engineer: give a task in plain language. OpenCode must choose the MCP calls. Full runbook, prompts, and pass/fail rules: docs/OPENCODE.md.

cd C:\Users\psxcode\Documents\Archicad
npm run build
opencode mcp list
opencode run -m lmstudio/openai/gpt-oss-20b --auto --title "e2e-smoke" "List open Archicad projects using only Archicad MCP tools."

Requires OpenCode (WinGet), LM Studio with a loaded model, and Archicad/Tapir on localhost. Record new live outcomes in docs/EXPERIMENTS.md.

Current read actions

archicad_read accepts a requests array with:

• product_info
• tapir_version
• project_info
• current_window
• selection_summary
• selected_elements
• all_elements

Every first operation may include a project hint or explicit instanceId. When the evidence is strong, the server binds and returns an opaque contextId in the same call. Reuse that context in later operations. With multiple weak or tied candidates, the server returns project cards and asks the agent to select a card or have the user foreground the intended Archicad; it never guesses from Z-order alone.

Scope

This version makes no changes to an Archicad project. Mutation tools, context snapshots, event indexing, rendering, and semantic operations will be added only after the live connection and Tapir response shapes are recorded and tested.