lamcp-archicad 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,30 @@
1
+ name: build
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ jobs:
10
+ lint-and-test:
11
+ runs-on: ubuntu-latest
12
+ strategy:
13
+ fail-fast: false
14
+ matrix:
15
+ python: ['3.10', '3.11', '3.12', '3.13']
16
+ steps:
17
+ - uses: actions/checkout@v6
18
+ - uses: actions/setup-python@v5
19
+ with:
20
+ python-version: ${{ matrix.python }}
21
+ - name: Install
22
+ run: |
23
+ python -m pip install --upgrade pip
24
+ pip install -e ".[dev]"
25
+ - name: Lint
26
+ run: ruff check .
27
+ - name: Format check
28
+ run: ruff format --check .
29
+ - name: Test
30
+ run: pytest -q
@@ -0,0 +1,74 @@
1
+ name: release
2
+
3
+ on:
4
+ push:
5
+ tags: ['v*']
6
+ workflow_dispatch:
7
+
8
+ jobs:
9
+ build-python:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - uses: actions/checkout@v6
13
+ - uses: actions/setup-python@v5
14
+ with:
15
+ python-version: '3.11'
16
+ - name: Check tag matches package version
17
+ if: startsWith(github.ref, 'refs/tags/v')
18
+ run: |
19
+ TAG="${GITHUB_REF_NAME#v}"
20
+ PYPROJECT=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
21
+ INIT=$(python -c "import re; print(re.search(r'__version__\s*=\s*\"([^\"]+)\"', open('lamcp_archicad/__init__.py').read()).group(1))")
22
+ echo "tag=$TAG pyproject=$PYPROJECT __init__=$INIT"
23
+ if [ "$TAG" != "$PYPROJECT" ] || [ "$TAG" != "$INIT" ]; then
24
+ echo "::error::Tag v$TAG does not match pyproject ($PYPROJECT) / __init__ ($INIT)"
25
+ exit 1
26
+ fi
27
+ - name: Build sdist + wheel
28
+ run: |
29
+ python -m pip install --upgrade pip build twine
30
+ python -m build
31
+ twine check --strict dist/*
32
+ - uses: actions/upload-artifact@v5
33
+ with:
34
+ name: python-dist
35
+ path: dist/*
36
+ if-no-files-found: error
37
+
38
+ publish-pypi:
39
+ # Only publish on actual tag pushes, not on workflow_dispatch.
40
+ if: startsWith(github.ref, 'refs/tags/v')
41
+ needs: build-python
42
+ runs-on: ubuntu-latest
43
+ environment:
44
+ name: pypi
45
+ url: https://pypi.org/p/lamcp-archicad
46
+ permissions:
47
+ id-token: write # required for OIDC trusted publishing
48
+ steps:
49
+ - uses: actions/download-artifact@v5
50
+ with:
51
+ name: python-dist
52
+ path: dist/
53
+ - name: Publish to PyPI
54
+ uses: pypa/gh-action-pypi-publish@release/v1
55
+
56
+ github-release:
57
+ if: startsWith(github.ref, 'refs/tags/v')
58
+ needs: [build-python, publish-pypi]
59
+ runs-on: ubuntu-latest
60
+ permissions:
61
+ contents: write
62
+ steps:
63
+ - uses: actions/checkout@v6
64
+ - uses: actions/download-artifact@v5
65
+ with:
66
+ name: python-dist
67
+ path: dist/
68
+ - name: Create GitHub Release
69
+ uses: softprops/action-gh-release@v2
70
+ with:
71
+ files: |
72
+ dist/*.whl
73
+ dist/*.tar.gz
74
+ generate_release_notes: true
@@ -0,0 +1,7 @@
1
+ __pycache__/
2
+ *.egg-info/
3
+ .venv/
4
+ dist/
5
+ build/
6
+ .pytest_cache/
7
+ .ruff_cache/
@@ -0,0 +1,9 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 (2026-11-20)
4
+
5
+ ### Added
6
+
7
+ - First version: `bridge_health`, `list_instances`, `select_instance`,
8
+ `list_commands`, `describe_command`, `run_command`, `run_python_script`,
9
+ `capture_view`.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Gramazio Kohler Research, ETH Zürich
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,285 @@
1
+ Metadata-Version: 2.5
2
+ Name: lamcp-archicad
3
+ Version: 0.1.0
4
+ Summary: Lambda MCP for Archicad: teach your LLM to do Archicad tricks, via the Tapir Add-On.
5
+ Author: Gramazio Kohler Research, ETH Zürich
6
+ License: MIT License
7
+
8
+ Copyright (c) 2026 Gramazio Kohler Research, ETH Zürich
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+ License-File: LICENSE
28
+ Keywords: archicad,bim,bridge,claude,llm,mcp,tapir
29
+ Classifier: Development Status :: 3 - Alpha
30
+ Classifier: Intended Audience :: Developers
31
+ Classifier: License :: OSI Approved :: MIT License
32
+ Classifier: Operating System :: OS Independent
33
+ Classifier: Programming Language :: Python :: 3
34
+ Classifier: Programming Language :: Python :: 3.10
35
+ Classifier: Programming Language :: Python :: 3.11
36
+ Classifier: Programming Language :: Python :: 3.12
37
+ Classifier: Programming Language :: Python :: 3.13
38
+ Requires-Python: >=3.10
39
+ Requires-Dist: fastmcp>=2.3
40
+ Requires-Dist: httpx>=0.27
41
+ Provides-Extra: dev
42
+ Requires-Dist: pytest>=8; extra == 'dev'
43
+ Requires-Dist: ruff<0.16,>=0.7; extra == 'dev'
44
+ Description-Content-Type: text/markdown
45
+
46
+ # LAMCP-Archicad
47
+
48
+ **LA**mbda **MCP** for Archicad: teach your LLM to do Archicad tricks.
49
+
50
+ LAMCP-Archicad lets Claude Code (or any MCP client) work in a live
51
+ Archicad project: read elements and properties, draw walls, slabs, roofs,
52
+ doors and windows, change parameters, take screenshots, and run short Python
53
+ scripts that chain many commands in one go.
54
+
55
+ Everything goes through the
56
+ [Tapir Add-On](https://github.com/ENZYME-APD/tapir-archicad-automation) and
57
+ Archicad's own JSON API, so there is no bridge to install and nothing to
58
+ compile.
59
+
60
+ Sibling of [LAMCP](https://github.com/gramaziokohler/lamcp) for Grasshopper.
61
+
62
+ > **Try it on a copy first.** The tools can create, change and delete model
63
+ > elements. Archicad's Undo (Ctrl+Z) reverts model changes, but not file
64
+ > operations such as saving or Teamwork send.
65
+
66
+ ## What you need
67
+
68
+ | Requirement | Notes |
69
+ | ------------------------------ | --------------------------------------------------------------------- |
70
+ | **Archicad 25–30** | Windows or macOS. `capture_view` needs Archicad 30. |
71
+ | **Tapir Add-On** | The latest release. See step 1 below. |
72
+ | **uv** | Runs the server and fetches Python for you. See step 2 below. |
73
+ | **Claude Code** or another MCP client | Claude Code in the terminal, VS Code or the desktop app, Claude Desktop, etc. |
74
+
75
+ You don't need to install Python yourself, because uv takes care of it.
76
+
77
+ ## Installation
78
+
79
+ ### 1. Install the Tapir Add-On in Archicad
80
+
81
+ Download from the
82
+ [latest Tapir release](https://github.com/ENZYME-APD/tapir-archicad-automation/releases/latest).
83
+ Use either method:
84
+
85
+ - **Installer (Windows, easiest).** Close Archicad, then run
86
+ `TapirInstaller_Win.exe` from the release page. It asks for administrator
87
+ rights because it copies files into the Archicad folder.
88
+ - **Manual.** Download the `.apx` (Windows) or `.bundle` (macOS) file that
89
+ matches your Archicad version, for example `TapirAddOn_AC29_Win.apx`, and
90
+ save it somewhere permanent (not Downloads). In Archicad, go to
91
+ **Options → Add-On Manager → Edit List of Available Add-Ons → Add**, pick
92
+ the file, then click **OK**.
93
+
94
+ **Check:** after you restart Archicad, a **Tapir** menu appears in the menu
95
+ bar. **Tapir → Tapir Palette** shows the installed version.
96
+
97
+ ### 2. Install uv
98
+
99
+ Windows (PowerShell):
100
+
101
+ ```powershell
102
+ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
103
+ ```
104
+
105
+ macOS:
106
+
107
+ ```bash
108
+ curl -LsSf https://astral.sh/uv/install.sh | sh
109
+ ```
110
+
111
+ Afterwards, open a new terminal so `uv` and `uvx` are on your PATH. See the
112
+ [uv docs](https://docs.astral.sh/uv/getting-started/installation/) for
113
+ other options.
114
+
115
+ ### 3. Register the server with Claude Code
116
+
117
+ ```bash
118
+ claude mcp add lamcp-archicad --scope user -- uvx lamcp-archicad
119
+ ```
120
+
121
+ `--scope user` makes the tools available in every project. Restart Claude
122
+ Code, or in VS Code run **Developer: Reload Window**, then start a new chat.
123
+ Run `claude mcp list` to check that `lamcp-archicad` is listed.
124
+
125
+ <details>
126
+ <summary>Install the latest development version from GitHub instead</summary>
127
+
128
+ ```bash
129
+ claude mcp add lamcp-archicad --scope user -- uvx --from git+https://github.com/gramaziokohler/lamcp-archicad lamcp-archicad
130
+ ```
131
+
132
+ </details>
133
+
134
+ <details>
135
+ <summary>Other MCP clients (Claude Desktop, Cursor, …)</summary>
136
+
137
+ The server talks MCP over stdio. Add it to your client's MCP configuration,
138
+ for example in Claude Desktop's `claude_desktop_config.json`:
139
+
140
+ ```json
141
+ {
142
+ "mcpServers": {
143
+ "lamcp-archicad": {
144
+ "command": "uvx",
145
+ "args": ["lamcp-archicad"]
146
+ }
147
+ }
148
+ }
149
+ ```
150
+
151
+ </details>
152
+
153
+ ### 4. Open a project and try it
154
+
155
+ 1. Start Archicad and **open a project**. Archicad only serves its JSON API
156
+ while a project is open.
157
+ 2. Ask Claude something like:
158
+ - *"Use lamcp-archicad to check the connection to Archicad."*
159
+ - *"List the stories and count the walls on each."*
160
+ - *"Draw a 6 × 4 m room on the ground floor with a slab, a hip roof, a
161
+ door and a window in each wall."*
162
+
163
+ If the first request reports Archicad's version and the Tapir version,
164
+ you're set up.
165
+
166
+ ## Troubleshooting
167
+
168
+ | Symptom | Cause and fix |
169
+ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
170
+ | No Archicad found, or connection refused | Archicad isn't running or has no project open. Open a project. With several Archicads open, ask Claude to `list_instances` and `select_instance`. |
171
+ | `Invalid program status (ongoing user input)` (code 4001) | Archicad is in the middle of an input: a half-drawn element, an open dialog, or an edit mode (curtain wall, stair…). Press **Esc**, close dialogs, and try again. |
172
+ | Commands hang, then time out | A modal dialog is open in Archicad. Close it. |
173
+ | `Archicad does not have the registered Add-On command …` (code 4010) | Tapir isn't loaded, or the command is newer than your Tapir. Check the **Tapir** menu, then update Tapir. |
174
+ | `Invalid command parameters … additionalProperties … path '#/…/<field>'` (code 4002) | Your Tapir is older than the command reference `describe_command` reads, so it doesn't accept that field yet. Update Tapir, or leave the field out. |
175
+ | `capture_view`: `Available from Archicad 30` | Screenshots need Archicad 30 and an open 3D window. |
176
+ | `uvx` or `claude` is not recognized | Open a new terminal after installing, or add their install folder to your PATH. |
177
+
178
+ ## How it works
179
+
180
+ ```text
181
+ LLM ──MCP stdio──▶ lamcp-archicad (Python 3.10+)
182
+ │
183
+ │ HTTP POST {"command": "API.ExecuteAddOnCommand", ...}
184
+ ▼
185
+ Archicad JSON API on 127.0.0.1:19723 (+1 per extra instance)
186
+ ├─ official commands (API.*)
187
+ └─ Tapir Add-On (several hundred commands)
188
+ ```
189
+
190
+ Unlike LAMCP, this needs no bridge, because Archicad already serves a JSON
191
+ API and runs every command on its own main thread. The "lambda" part,
192
+ `run_python_script`, runs your code **in the MCP server's process** and
193
+ sends commands to Archicad. A broken script can't crash Archicad; only the
194
+ commands it sends reach Archicad.
195
+
196
+ ## Tools
197
+
198
+ | Tool | Purpose |
199
+ | ------------------- | -------------------------------------------------------------------------- |
200
+ | `bridge_health` | Checks that Archicad and Tapir are reachable, and reports their versions. |
201
+ | `list_instances` | Finds every running Archicad (ports 19723–19744). |
202
+ | `select_instance` | Sends further commands to the Archicad on a given port. |
203
+ | `list_commands` | Lists the commands the installed Tapir offers, filterable by text or group. |
204
+ | `describe_command` | Shows one command's description and input schema (optionally its output schema and an example). |
205
+ | `run_command` | Runs one Tapir command, or an official one as `API.<Name>`. |
206
+ | `run_python_script` | Runs Python with `tapir()` / `archicad()` helpers; globals persist between calls. |
207
+ | `capture_view` | Takes a screenshot of the 3D window as an inline image (Archicad 30+). |
208
+
209
+ ### `run_python_script`
210
+
211
+ These helpers are available in the script's globals:
212
+
213
+ | Name | Does |
214
+ | ----------------------------- | -------------------------------------------------------- |
215
+ | `tapir(name, params=None)` | Runs a Tapir command and returns its response dict. |
216
+ | `archicad(name, params=None)` | Runs an official command (`API.` is added when missing). |
217
+ | `run(name, params=None)` | Sends `API.*` to `archicad` and anything else to `tapir`. |
218
+ | `batched(items, size=1000)` | Splits long element lists into chunks. |
219
+ | `ArchicadError` | Raised by the helpers when a command fails. |
220
+
221
+ Assign to `_` to return a value. Globals persist between calls:
222
+
223
+ ```python
224
+ # call 1
225
+ walls = tapir("GetElementsByType", {"elementType": "Wall"})["elements"]
226
+ # call 2
227
+ _ = len(walls) # `walls` is still bound
228
+ ```
229
+
230
+ Every call returns `{"stdout", "stderr", "result", "error"}`. `result` is
231
+ `_` itself when it's JSON-serialisable, otherwise its `repr`. `error` is a
232
+ traceback, or `null` when the script succeeded.
233
+
234
+ ### Command reference vs. installed Add-On
235
+
236
+ `describe_command` reads the latest published Tapir reference (cached for a
237
+ day), while `list_commands` asks your installed Add-On. If a command is
238
+ described but not listed, or a field is rejected as an
239
+ `additionalProperties` error, your Tapir is older than the reference.
240
+ Update Tapir.
241
+
242
+ ## Configuration
243
+
244
+ | Variable | Default | Purpose |
245
+ | ----------------------------- | ----------------------------------------- | --------------------------------- |
246
+ | `LAMCP_ARCHICAD_URL` | `http://127.0.0.1:19723` | The Archicad JSON API to talk to. |
247
+ | `LAMCP_ARCHICAD_COMMANDS_URL` | `https://archicad-api.com/commands.json` | The Tapir command reference. |
248
+ | `LAMCP_ARCHICAD_CACHE` | `~/.cache/lamcp-archicad` | Where the reference is cached. |
249
+
250
+ To set one with Claude Code, use `-e`:
251
+
252
+ ```bash
253
+ claude mcp add lamcp-archicad --scope user -e LAMCP_ARCHICAD_URL=http://127.0.0.1:19724 -- uvx lamcp-archicad
254
+ ```
255
+
256
+ ## Security
257
+
258
+ `run_python_script` runs arbitrary Python with your user's rights, like any
259
+ code Claude Code runs. The Archicad JSON API listens on `127.0.0.1` only and
260
+ has no authentication; that is Archicad's design, not ours.
261
+
262
+ ## Development
263
+
264
+ ```bash
265
+ git clone https://github.com/gramaziokohler/lamcp-archicad
266
+ cd lamcp-archicad
267
+ uv venv && uv pip install -e ".[dev]"
268
+ ruff check . && ruff format --check .
269
+ pytest -q
270
+ ```
271
+
272
+ The tests run against a fake Archicad (`tests/`), so you don't need
273
+ Archicad to run them.
274
+
275
+ To point Claude Code at your working copy instead of the published package:
276
+
277
+ ```bash
278
+ claude mcp add lamcp-archicad --scope user -- uv run --directory /path/to/lamcp-archicad lamcp-archicad
279
+ ```
280
+
281
+ Releases are tag-driven: push a `v*` tag and CI publishes to PyPI.
282
+
283
+ ## License
284
+
285
+ MIT
@@ -0,0 +1,240 @@
1
+ # LAMCP-Archicad
2
+
3
+ **LA**mbda **MCP** for Archicad: teach your LLM to do Archicad tricks.
4
+
5
+ LAMCP-Archicad lets Claude Code (or any MCP client) work in a live
6
+ Archicad project: read elements and properties, draw walls, slabs, roofs,
7
+ doors and windows, change parameters, take screenshots, and run short Python
8
+ scripts that chain many commands in one go.
9
+
10
+ Everything goes through the
11
+ [Tapir Add-On](https://github.com/ENZYME-APD/tapir-archicad-automation) and
12
+ Archicad's own JSON API, so there is no bridge to install and nothing to
13
+ compile.
14
+
15
+ Sibling of [LAMCP](https://github.com/gramaziokohler/lamcp) for Grasshopper.
16
+
17
+ > **Try it on a copy first.** The tools can create, change and delete model
18
+ > elements. Archicad's Undo (Ctrl+Z) reverts model changes, but not file
19
+ > operations such as saving or Teamwork send.
20
+
21
+ ## What you need
22
+
23
+ | Requirement | Notes |
24
+ | ------------------------------ | --------------------------------------------------------------------- |
25
+ | **Archicad 25–30** | Windows or macOS. `capture_view` needs Archicad 30. |
26
+ | **Tapir Add-On** | The latest release. See step 1 below. |
27
+ | **uv** | Runs the server and fetches Python for you. See step 2 below. |
28
+ | **Claude Code** or another MCP client | Claude Code in the terminal, VS Code or the desktop app, Claude Desktop, etc. |
29
+
30
+ You don't need to install Python yourself, because uv takes care of it.
31
+
32
+ ## Installation
33
+
34
+ ### 1. Install the Tapir Add-On in Archicad
35
+
36
+ Download from the
37
+ [latest Tapir release](https://github.com/ENZYME-APD/tapir-archicad-automation/releases/latest).
38
+ Use either method:
39
+
40
+ - **Installer (Windows, easiest).** Close Archicad, then run
41
+ `TapirInstaller_Win.exe` from the release page. It asks for administrator
42
+ rights because it copies files into the Archicad folder.
43
+ - **Manual.** Download the `.apx` (Windows) or `.bundle` (macOS) file that
44
+ matches your Archicad version, for example `TapirAddOn_AC29_Win.apx`, and
45
+ save it somewhere permanent (not Downloads). In Archicad, go to
46
+ **Options → Add-On Manager → Edit List of Available Add-Ons → Add**, pick
47
+ the file, then click **OK**.
48
+
49
+ **Check:** after you restart Archicad, a **Tapir** menu appears in the menu
50
+ bar. **Tapir → Tapir Palette** shows the installed version.
51
+
52
+ ### 2. Install uv
53
+
54
+ Windows (PowerShell):
55
+
56
+ ```powershell
57
+ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
58
+ ```
59
+
60
+ macOS:
61
+
62
+ ```bash
63
+ curl -LsSf https://astral.sh/uv/install.sh | sh
64
+ ```
65
+
66
+ Afterwards, open a new terminal so `uv` and `uvx` are on your PATH. See the
67
+ [uv docs](https://docs.astral.sh/uv/getting-started/installation/) for
68
+ other options.
69
+
70
+ ### 3. Register the server with Claude Code
71
+
72
+ ```bash
73
+ claude mcp add lamcp-archicad --scope user -- uvx lamcp-archicad
74
+ ```
75
+
76
+ `--scope user` makes the tools available in every project. Restart Claude
77
+ Code, or in VS Code run **Developer: Reload Window**, then start a new chat.
78
+ Run `claude mcp list` to check that `lamcp-archicad` is listed.
79
+
80
+ <details>
81
+ <summary>Install the latest development version from GitHub instead</summary>
82
+
83
+ ```bash
84
+ claude mcp add lamcp-archicad --scope user -- uvx --from git+https://github.com/gramaziokohler/lamcp-archicad lamcp-archicad
85
+ ```
86
+
87
+ </details>
88
+
89
+ <details>
90
+ <summary>Other MCP clients (Claude Desktop, Cursor, …)</summary>
91
+
92
+ The server talks MCP over stdio. Add it to your client's MCP configuration,
93
+ for example in Claude Desktop's `claude_desktop_config.json`:
94
+
95
+ ```json
96
+ {
97
+ "mcpServers": {
98
+ "lamcp-archicad": {
99
+ "command": "uvx",
100
+ "args": ["lamcp-archicad"]
101
+ }
102
+ }
103
+ }
104
+ ```
105
+
106
+ </details>
107
+
108
+ ### 4. Open a project and try it
109
+
110
+ 1. Start Archicad and **open a project**. Archicad only serves its JSON API
111
+ while a project is open.
112
+ 2. Ask Claude something like:
113
+ - *"Use lamcp-archicad to check the connection to Archicad."*
114
+ - *"List the stories and count the walls on each."*
115
+ - *"Draw a 6 × 4 m room on the ground floor with a slab, a hip roof, a
116
+ door and a window in each wall."*
117
+
118
+ If the first request reports Archicad's version and the Tapir version,
119
+ you're set up.
120
+
121
+ ## Troubleshooting
122
+
123
+ | Symptom | Cause and fix |
124
+ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
125
+ | No Archicad found, or connection refused | Archicad isn't running or has no project open. Open a project. With several Archicads open, ask Claude to `list_instances` and `select_instance`. |
126
+ | `Invalid program status (ongoing user input)` (code 4001) | Archicad is in the middle of an input: a half-drawn element, an open dialog, or an edit mode (curtain wall, stair…). Press **Esc**, close dialogs, and try again. |
127
+ | Commands hang, then time out | A modal dialog is open in Archicad. Close it. |
128
+ | `Archicad does not have the registered Add-On command …` (code 4010) | Tapir isn't loaded, or the command is newer than your Tapir. Check the **Tapir** menu, then update Tapir. |
129
+ | `Invalid command parameters … additionalProperties … path '#/…/<field>'` (code 4002) | Your Tapir is older than the command reference `describe_command` reads, so it doesn't accept that field yet. Update Tapir, or leave the field out. |
130
+ | `capture_view`: `Available from Archicad 30` | Screenshots need Archicad 30 and an open 3D window. |
131
+ | `uvx` or `claude` is not recognized | Open a new terminal after installing, or add their install folder to your PATH. |
132
+
133
+ ## How it works
134
+
135
+ ```text
136
+ LLM ──MCP stdio──▶ lamcp-archicad (Python 3.10+)
137
+ │
138
+ │ HTTP POST {"command": "API.ExecuteAddOnCommand", ...}
139
+ ▼
140
+ Archicad JSON API on 127.0.0.1:19723 (+1 per extra instance)
141
+ ├─ official commands (API.*)
142
+ └─ Tapir Add-On (several hundred commands)
143
+ ```
144
+
145
+ Unlike LAMCP, this needs no bridge, because Archicad already serves a JSON
146
+ API and runs every command on its own main thread. The "lambda" part,
147
+ `run_python_script`, runs your code **in the MCP server's process** and
148
+ sends commands to Archicad. A broken script can't crash Archicad; only the
149
+ commands it sends reach Archicad.
150
+
151
+ ## Tools
152
+
153
+ | Tool | Purpose |
154
+ | ------------------- | -------------------------------------------------------------------------- |
155
+ | `bridge_health` | Checks that Archicad and Tapir are reachable, and reports their versions. |
156
+ | `list_instances` | Finds every running Archicad (ports 19723–19744). |
157
+ | `select_instance` | Sends further commands to the Archicad on a given port. |
158
+ | `list_commands` | Lists the commands the installed Tapir offers, filterable by text or group. |
159
+ | `describe_command` | Shows one command's description and input schema (optionally its output schema and an example). |
160
+ | `run_command` | Runs one Tapir command, or an official one as `API.<Name>`. |
161
+ | `run_python_script` | Runs Python with `tapir()` / `archicad()` helpers; globals persist between calls. |
162
+ | `capture_view` | Takes a screenshot of the 3D window as an inline image (Archicad 30+). |
163
+
164
+ ### `run_python_script`
165
+
166
+ These helpers are available in the script's globals:
167
+
168
+ | Name | Does |
169
+ | ----------------------------- | -------------------------------------------------------- |
170
+ | `tapir(name, params=None)` | Runs a Tapir command and returns its response dict. |
171
+ | `archicad(name, params=None)` | Runs an official command (`API.` is added when missing). |
172
+ | `run(name, params=None)` | Sends `API.*` to `archicad` and anything else to `tapir`. |
173
+ | `batched(items, size=1000)` | Splits long element lists into chunks. |
174
+ | `ArchicadError` | Raised by the helpers when a command fails. |
175
+
176
+ Assign to `_` to return a value. Globals persist between calls:
177
+
178
+ ```python
179
+ # call 1
180
+ walls = tapir("GetElementsByType", {"elementType": "Wall"})["elements"]
181
+ # call 2
182
+ _ = len(walls) # `walls` is still bound
183
+ ```
184
+
185
+ Every call returns `{"stdout", "stderr", "result", "error"}`. `result` is
186
+ `_` itself when it's JSON-serialisable, otherwise its `repr`. `error` is a
187
+ traceback, or `null` when the script succeeded.
188
+
189
+ ### Command reference vs. installed Add-On
190
+
191
+ `describe_command` reads the latest published Tapir reference (cached for a
192
+ day), while `list_commands` asks your installed Add-On. If a command is
193
+ described but not listed, or a field is rejected as an
194
+ `additionalProperties` error, your Tapir is older than the reference.
195
+ Update Tapir.
196
+
197
+ ## Configuration
198
+
199
+ | Variable | Default | Purpose |
200
+ | ----------------------------- | ----------------------------------------- | --------------------------------- |
201
+ | `LAMCP_ARCHICAD_URL` | `http://127.0.0.1:19723` | The Archicad JSON API to talk to. |
202
+ | `LAMCP_ARCHICAD_COMMANDS_URL` | `https://archicad-api.com/commands.json` | The Tapir command reference. |
203
+ | `LAMCP_ARCHICAD_CACHE` | `~/.cache/lamcp-archicad` | Where the reference is cached. |
204
+
205
+ To set one with Claude Code, use `-e`:
206
+
207
+ ```bash
208
+ claude mcp add lamcp-archicad --scope user -e LAMCP_ARCHICAD_URL=http://127.0.0.1:19724 -- uvx lamcp-archicad
209
+ ```
210
+
211
+ ## Security
212
+
213
+ `run_python_script` runs arbitrary Python with your user's rights, like any
214
+ code Claude Code runs. The Archicad JSON API listens on `127.0.0.1` only and
215
+ has no authentication; that is Archicad's design, not ours.
216
+
217
+ ## Development
218
+
219
+ ```bash
220
+ git clone https://github.com/gramaziokohler/lamcp-archicad
221
+ cd lamcp-archicad
222
+ uv venv && uv pip install -e ".[dev]"
223
+ ruff check . && ruff format --check .
224
+ pytest -q
225
+ ```
226
+
227
+ The tests run against a fake Archicad (`tests/`), so you don't need
228
+ Archicad to run them.
229
+
230
+ To point Claude Code at your working copy instead of the published package:
231
+
232
+ ```bash
233
+ claude mcp add lamcp-archicad --scope user -- uv run --directory /path/to/lamcp-archicad lamcp-archicad
234
+ ```
235
+
236
+ Releases are tag-driven: push a `v*` tag and CI publishes to PyPI.
237
+
238
+ ## License
239
+
240
+ MIT
@@ -0,0 +1,3 @@
1
+ """LAMCP-Archicad: teach your LLM to do Archicad tricks (via Tapir)."""
2
+
3
+ __version__ = "0.1.0"