# Archicad Tapir MCP

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

## Project continuity

- [`PRD.md`](PRD.md) — product requirements and architecture direction.
- [`docs/PROJECT_STATE.md`](docs/PROJECT_STATE.md) — current implementation,
  verification, gaps, and next work.
- [`docs/DECISIONS.md`](docs/DECISIONS.md) — architectural decision log.
- [`docs/EXPERIMENTS.md`](docs/EXPERIMENTS.md) — live Archicad/Tapir evidence.
- [`docs/TARGET_CONTEXTS.md`](docs/TARGET_CONTEXTS.md) — sticky per-task target
  binding and nickname contract.
- [`docs/OPENCODE.md`](docs/OPENCODE.md) — OpenCode as the local end-to-end MCP
  agent harness (operator runs OpenCode; OpenCode must invent the MCP sequence).
- [`AGENTS.md`](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_spatial_map` — character-grid orientation for a sheet/marquee/zone.
- `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

```bash
npm install
npm run build
npm test
```

## Probe Archicad

Start Archicad completely, then run:

```bash
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:

```bash
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:

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

Example local MCP configuration:

```json
{
  "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`](docs/OPENCODE.md).

```powershell
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.