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.
- lamcp_archicad-0.1.0/.github/workflows/build.yml +30 -0
- lamcp_archicad-0.1.0/.github/workflows/release.yml +74 -0
- lamcp_archicad-0.1.0/.gitignore +7 -0
- lamcp_archicad-0.1.0/CHANGELOG.md +9 -0
- lamcp_archicad-0.1.0/LICENSE +21 -0
- lamcp_archicad-0.1.0/PKG-INFO +285 -0
- lamcp_archicad-0.1.0/README.md +240 -0
- lamcp_archicad-0.1.0/lamcp_archicad/__init__.py +3 -0
- lamcp_archicad-0.1.0/lamcp_archicad/server.py +475 -0
- lamcp_archicad-0.1.0/pyproject.toml +43 -0
- lamcp_archicad-0.1.0/tests/test_server.py +181 -0
- lamcp_archicad-0.1.0/uv.lock +2350 -0
|
@@ -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,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
|