lamcp 0.1.0__tar.gz

lamcp-0.1.0/.github/workflows/build.yml

@@ -0,0 +1,57 @@
+name: build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Format check
+        run: ruff format --check .
+      - name: Import smoke test
+        run: |
+          python -c "from lamcp.server import mcp, run_python_script, bridge_health, unload_python_modules"
+
+  build-ghpython-component:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install componentizer deps
+        # The action's `componentize_cpy.py` does `import clr` (Python.NET)
+        # but doesn't install pythonnet itself, so we pre-install it here.
+        run: pip install pythonnet
+      - name: Build Lamcp_Bridge.ghuser
+        # `target` must be a single-segment path: the action uses `os.mkdir`
+        # (not `makedirs`), so nested paths like `dist/ghuser/` fail because
+        # the parent doesn't exist yet.
+        uses: compas-dev/compas-actions.ghpython_components@v5
+        with:
+          source: grasshopper
+          target: dist
+          interpreter: cpython
+      - uses: actions/upload-artifact@v5
+        with:
+          name: Lamcp_Bridge-ghuser
+          path: dist/*.ghuser
+          if-no-files-found: error

lamcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,98 @@
+name: release
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+jobs:
+  build-python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - uses: actions/upload-artifact@v5
+        with:
+          name: python-dist
+          path: dist/*
+          if-no-files-found: error
+
+  build-ghpython-component:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install componentizer deps
+        # The action's `componentize_cpy.py` does `import clr` (Python.NET)
+        # but doesn't install pythonnet itself, so we pre-install it here.
+        run: pip install pythonnet
+      - name: Build Lamcp_Bridge.ghuser
+        # `target` must be a single-segment path: the action uses `os.mkdir`
+        # (not `makedirs`), so nested paths like `dist/ghuser/` fail because
+        # the parent doesn't exist yet.
+        uses: compas-dev/compas-actions.ghpython_components@v5
+        with:
+          source: grasshopper
+          target: dist
+          interpreter: cpython
+      - uses: actions/upload-artifact@v5
+        with:
+          name: ghpython-dist
+          path: dist/*.ghuser
+          if-no-files-found: error
+
+  publish-pypi:
+    # Only publish on actual tag pushes, not on workflow_dispatch.
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build-python
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/lamcp
+    permissions:
+      id-token: write   # required for OIDC trusted publishing
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          name: python-dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [build-python, build-ghpython-component, publish-pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/download-artifact@v5
+        with:
+          name: python-dist
+          path: dist/
+      - uses: actions/download-artifact@v5
+        with:
+          name: ghpython-dist
+          path: dist/
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+            dist/*.ghuser
+          generate_release_notes: true
+          body: |
+            Install the Python MCP server: `pip install lamcp==${{ github.ref_name }}` (drop the leading `v`).
+
+            For Rhino 8 / Grasshopper users: download `Lamcp_Bridge.ghuser` below and drop it into your Grasshopper Libraries folder
+            (Grasshopper menu → File → Special Folders → Components Folder).

lamcp-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Tooling
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.tox/
+
+# Editor / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Project-local Claude state
+.claude/settings.local.json
+
+# Built Grasshopper user objects (these are release artifacts, not source)
+*.ghuser
+grasshopper/**/__pycache__/

lamcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## [0.1.0] - 2026-05-31
+
+### Added
+
+* Initial release.
+* `lamcp` FastMCP server with three tools:
+  * `run_python_script(code, timeout)` — exec arbitrary Python inside the
+    bridge process, captures stdout / stderr / `repr(_)` / traceback.
+  * `unload_python_modules(prefix)` — drop `sys.modules[prefix.*]` to
+    pick up on-disk module edits without restarting Rhino.
+  * `bridge_health()` — ping the bridge over loopback HTTP.
+* `LAMCP Bridge` Grasshopper component (Rhino 8, CPython 3.9) that
+  hosts an `http.server` on `127.0.0.1:8765` (configurable port) and
+  `exec()`s incoming code against a shared globals dict so state
+  persists across calls.
+* GitHub release ships the pre-built `Lamcp_Bridge.ghuser` alongside
+  the Python wheel/sdist, so users can drop the component into their
+  Grasshopper Libraries folder without a manual paste-and-configure
+  step.

lamcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gramazio Kohler Research, ETH Zürich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lamcp-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: lamcp
+Version: 0.1.0
+Summary: Lambda MCP: teach your LLM to do Grasshopper tricks.
+Author: Gramazio Kohler Research, ETH Zürich
+License: MIT License
+        
+        Copyright (c) 2026 Gramazio Kohler Research, ETH Zürich
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: bridge,claude,grasshopper,llm,mcp,rhino
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=0.4
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# LAMCP
+
+**LA**mbda **MCP**: teach your LLM to do Grasshopper tricks.
+
+Lets Claude Code (or any MCP client) introspect and mutate a
+live Grasshopper session in real time: inspect the canvas,
+wire components, read/write slider values, run `RhinoCommon`
+calls, hot-reload modules -all from inside an AI agent loop, without rebuilding userobjects or restarting Rhino.
+
+## Architecture
+
+```text
+LLM ──MCP stdio──▶ lamcp (Python 3.10+)
+                          │
+                          │  HTTP POST /exec  {"code": "...", "timeout": 30}
+                          ▼
+                  LAMCP Bridge GH component (Rhino 8 CPython 3.9)
+                     ├─ http.server on 127.0.0.1:8765
+                     ├─ exec() with shared globals
+                     └─ returns {stdout, stderr, result, error}
+```
+
+Why split: Rhino 8's CPython runtime is pinned to 3.9. `fastmcp` and the
+underlying `mcp` SDK require 3.10+. So the MCP-speaking half runs in a
+system Python and forwards over loopback HTTP to a stdlib-only HTTP server
+living inside Rhino as a regular Grasshopper component.
+
+## Setup
+
+### 1. Install the MCP server
+
+```bash
+git clone https://github.com/gramaziokohler/lamcp.git
+cd lamcp
+uv pip install -e .
+# or: pip install -e .
+```
+
+### 2. Register with Claude Code (or whatever LLM you use)
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "lamcp": {
+      "command": "lamcp"
+    }
+  }
+}
+```
+
+If `lamcp` isn't on `PATH`, use the absolute path to the venv's script:
+
+```json
+{
+  "mcpServers": {
+    "lamcp": {
+      "command": "/absolute/path/to/.venv/bin/lamcp"
+    }
+  }
+}
+```
+
+Restart Claude Code so it discovers the new MCP server.
+
+### 3. Install the bridge in Grasshopper
+
+**Option A — drop the pre-built userobject (recommended).**
+
+1. Download `Lamcp_Bridge.ghuser` from the [latest release](https://github.com/gramaziokohler/lamcp/releases/latest).
+2. In Grasshopper: *File → Special Folders → Components Folder*. Move the
+   `.ghuser` file there.
+3. Restart Grasshopper. `LAMCP Bridge` appears under the `LAMCP` tab.
+4. Drop it on the canvas, wire a `Boolean Toggle` (set to `True`) into
+   `enable`. The `status` output reads `listening on http://127.0.0.1:8765`.
+
+**Option B — paste the source manually (for hacking).**
+
+1. Drop a Python 3 Script component on the canvas. Paste the contents of
+   [`grasshopper/Lamcp_Bridge/code.py`](grasshopper/Lamcp_Bridge/code.py) in.
+2. Add two inputs: `enable` (bool) and `port` (int). Add one output: `status`.
+3. Wire a `Boolean Toggle` (set to `True`) into `enable`.
+4. The `status` output should read `listening on http://127.0.0.1:8765`.
+
+Either way, your MCP client now has a `run_python_script` tool that
+exec()s code inside your live Rhino session.
+
+## Tools exposed
+
+| Tool                    | Purpose                                                                  |
+| ----------------------- | ------------------------------------------------------------------------ |
+| `run_python_script`     | exec() arbitrary Python inside Rhino, capture stdout / stderr / repr(_)  |
+| `unload_python_modules` | drop `sys.modules[prefix.*]` so the next import re-reads from disk       |
+| `bridge_health`         | ping the bridge to verify it's reachable                                 |
+
+### Return contract for `run_python_script`
+
+```json
+{
+  "stdout": "...",            // captured stdout
+  "stderr": "...",            // captured stderr
+  "result": "repr of _",      // assign to `_` to return a value
+  "error": null               // formatted traceback if exception raised
+}
+```
+
+Globals persist between calls, so you can `import` once and reuse:
+
+```python
+# call 1
+import scriptcontext as sc; doc = sc.doc.ActiveDoc
+# call 2
+print(doc.Name)   # `doc` is still bound
+```
+
+## Environment variables
+
+| Variable           | Default                  | Purpose                          |
+| ------------------ | ------------------------ | -------------------------------- |
+| `LAMCP_BRIDGE_URL` | `http://127.0.0.1:8765`  | URL of the bridge's HTTP server  |
+
+## Caveats
+
+- **UI thread**: code runs on the HTTP server thread, not the Rhino UI
+  thread. Most read-only `RhinoCommon` / `Grasshopper` access works
+  cross-thread, but heavy mutations (bulk `RemoveObject`, etc.) can crash
+  Rhino. Eto-based UI marshalling is a planned addition.
+- **`isinstance` doesn't always work**: in Rhino 8 CPython, `isinstance`
+  against concrete .NET types often returns False due to interface interop.
+  Use `obj.GetType().Name == "..."` instead.
+- **`RemoveSource(IGH_Param)` is a silent no-op**: use the
+  `RemoveSource(Guid)` overload.
+- **`float(System.Decimal)` raises**: wrap with `System.Convert.ToDouble(x)`
+  or `float(str(x))`.
+
+## Security
+
+The bridge listens on `127.0.0.1` only and accepts no auth: it runs
+arbitrary Python in your Rhino with no sandboxing. **Never expose it
+beyond localhost**, and stop it (`enable=False`) when you're done.
+
+## Development
+
+Install with the `dev` extra to pull in `ruff`:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Lint + format checks (same commands CI runs):
+
+```bash
+ruff check .                # lint
+ruff format --check .       # formatting (non-destructive)
+```
+
+Auto-fix:
+
+```bash
+ruff check . --fix          # fix lint issues
+ruff format .               # reformat
+```
+
+For one-off runs without installing into your env, `uvx ruff ...` works
+identically.
+
+Releases are tag-driven — see [RELEASING.md](RELEASING.md).
+
+## License
+
+MIT

lamcp-0.1.0/README.md

@@ -0,0 +1,172 @@
+# LAMCP
+
+**LA**mbda **MCP**: teach your LLM to do Grasshopper tricks.
+
+Lets Claude Code (or any MCP client) introspect and mutate a
+live Grasshopper session in real time: inspect the canvas,
+wire components, read/write slider values, run `RhinoCommon`
+calls, hot-reload modules -all from inside an AI agent loop, without rebuilding userobjects or restarting Rhino.
+
+## Architecture
+
+```text
+LLM ──MCP stdio──▶ lamcp (Python 3.10+)
+                          │
+                          │  HTTP POST /exec  {"code": "...", "timeout": 30}
+                          ▼
+                  LAMCP Bridge GH component (Rhino 8 CPython 3.9)
+                     ├─ http.server on 127.0.0.1:8765
+                     ├─ exec() with shared globals
+                     └─ returns {stdout, stderr, result, error}
+```
+
+Why split: Rhino 8's CPython runtime is pinned to 3.9. `fastmcp` and the
+underlying `mcp` SDK require 3.10+. So the MCP-speaking half runs in a
+system Python and forwards over loopback HTTP to a stdlib-only HTTP server
+living inside Rhino as a regular Grasshopper component.
+
+## Setup
+
+### 1. Install the MCP server
+
+```bash
+git clone https://github.com/gramaziokohler/lamcp.git
+cd lamcp
+uv pip install -e .
+# or: pip install -e .
+```
+
+### 2. Register with Claude Code (or whatever LLM you use)
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "lamcp": {
+      "command": "lamcp"
+    }
+  }
+}
+```
+
+If `lamcp` isn't on `PATH`, use the absolute path to the venv's script:
+
+```json
+{
+  "mcpServers": {
+    "lamcp": {
+      "command": "/absolute/path/to/.venv/bin/lamcp"
+    }
+  }
+}
+```
+
+Restart Claude Code so it discovers the new MCP server.
+
+### 3. Install the bridge in Grasshopper
+
+**Option A — drop the pre-built userobject (recommended).**
+
+1. Download `Lamcp_Bridge.ghuser` from the [latest release](https://github.com/gramaziokohler/lamcp/releases/latest).
+2. In Grasshopper: *File → Special Folders → Components Folder*. Move the
+   `.ghuser` file there.
+3. Restart Grasshopper. `LAMCP Bridge` appears under the `LAMCP` tab.
+4. Drop it on the canvas, wire a `Boolean Toggle` (set to `True`) into
+   `enable`. The `status` output reads `listening on http://127.0.0.1:8765`.
+
+**Option B — paste the source manually (for hacking).**
+
+1. Drop a Python 3 Script component on the canvas. Paste the contents of
+   [`grasshopper/Lamcp_Bridge/code.py`](grasshopper/Lamcp_Bridge/code.py) in.
+2. Add two inputs: `enable` (bool) and `port` (int). Add one output: `status`.
+3. Wire a `Boolean Toggle` (set to `True`) into `enable`.
+4. The `status` output should read `listening on http://127.0.0.1:8765`.
+
+Either way, your MCP client now has a `run_python_script` tool that
+exec()s code inside your live Rhino session.
+
+## Tools exposed
+
+| Tool                    | Purpose                                                                  |
+| ----------------------- | ------------------------------------------------------------------------ |
+| `run_python_script`     | exec() arbitrary Python inside Rhino, capture stdout / stderr / repr(_)  |
+| `unload_python_modules` | drop `sys.modules[prefix.*]` so the next import re-reads from disk       |
+| `bridge_health`         | ping the bridge to verify it's reachable                                 |
+
+### Return contract for `run_python_script`
+
+```json
+{
+  "stdout": "...",            // captured stdout
+  "stderr": "...",            // captured stderr
+  "result": "repr of _",      // assign to `_` to return a value
+  "error": null               // formatted traceback if exception raised
+}
+```
+
+Globals persist between calls, so you can `import` once and reuse:
+
+```python
+# call 1
+import scriptcontext as sc; doc = sc.doc.ActiveDoc
+# call 2
+print(doc.Name)   # `doc` is still bound
+```
+
+## Environment variables
+
+| Variable           | Default                  | Purpose                          |
+| ------------------ | ------------------------ | -------------------------------- |
+| `LAMCP_BRIDGE_URL` | `http://127.0.0.1:8765`  | URL of the bridge's HTTP server  |
+
+## Caveats
+
+- **UI thread**: code runs on the HTTP server thread, not the Rhino UI
+  thread. Most read-only `RhinoCommon` / `Grasshopper` access works
+  cross-thread, but heavy mutations (bulk `RemoveObject`, etc.) can crash
+  Rhino. Eto-based UI marshalling is a planned addition.
+- **`isinstance` doesn't always work**: in Rhino 8 CPython, `isinstance`
+  against concrete .NET types often returns False due to interface interop.
+  Use `obj.GetType().Name == "..."` instead.
+- **`RemoveSource(IGH_Param)` is a silent no-op**: use the
+  `RemoveSource(Guid)` overload.
+- **`float(System.Decimal)` raises**: wrap with `System.Convert.ToDouble(x)`
+  or `float(str(x))`.
+
+## Security
+
+The bridge listens on `127.0.0.1` only and accepts no auth: it runs
+arbitrary Python in your Rhino with no sandboxing. **Never expose it
+beyond localhost**, and stop it (`enable=False`) when you're done.
+
+## Development
+
+Install with the `dev` extra to pull in `ruff`:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Lint + format checks (same commands CI runs):
+
+```bash
+ruff check .                # lint
+ruff format --check .       # formatting (non-destructive)
+```
+
+Auto-fix:
+
+```bash
+ruff check . --fix          # fix lint issues
+ruff format .               # reformat
+```
+
+For one-off runs without installing into your env, `uvx ruff ...` works
+identically.
+
+Releases are tag-driven — see [RELEASING.md](RELEASING.md).
+
+## License
+
+MIT

lamcp-0.1.0/RELEASING.md

@@ -0,0 +1,62 @@
+# Releasing LAMCP
+
+## One-time setup
+
+### 1. Configure PyPI trusted publisher (OIDC)
+
+On the PyPI side, before the first release:
+
+1. Create the project page at <https://pypi.org/manage/account/publishing/>.
+2. Add a **pending publisher** with:
+    * PyPI Project Name: `lamcp`
+    * Owner: `gramaziokohler`
+    * Repository name: `lamcp`
+    * Workflow name: `release.yml`
+    * Environment name: `pypi`
+
+This lets the GitHub Actions workflow publish to PyPI without storing a
+token in the repo (OIDC short-lived credentials instead).
+
+### 2. Create the `pypi` environment in GitHub
+
+In the repo settings → Environments → New environment → `pypi`.
+
+Optionally add deployment protection rules (required reviewers, branch
+restrictions). The `publish-pypi` job in `.github/workflows/release.yml`
+runs in this environment.
+
+## Cutting a release
+
+1. Update `CHANGELOG.md`:
+    * Rename `## Unreleased` to `## [X.Y.Z] - YYYY-MM-DD`.
+    * Add a new empty `## Unreleased` section above it.
+
+2. Bump the version in `pyproject.toml` (`project.version`).
+
+3. Commit and push the bump:
+
+   ```bash
+   git add pyproject.toml CHANGELOG.md
+   git commit -m "Bump version to X.Y.Z"
+   git push
+   ```
+
+4. Tag and push:
+
+   ```bash
+   git tag vX.Y.Z
+   git push origin vX.Y.Z
+   ```
+
+5. Watch the `release` workflow under Actions. It:
+    * Builds the Python sdist + wheel
+    * Builds `Lamcp_Bridge.ghuser` on Windows via
+      `compas-dev/compas-actions.ghpython_components`
+    * Publishes the wheel + sdist to PyPI via OIDC
+    * Creates a GitHub release with auto-generated notes, attaching the
+      wheel, sdist, and `Lamcp_Bridge.ghuser` as downloadable assets
+
+## Versioning
+
+SemVer. `0.x` is unstable — API can break in any minor. `1.0` is the
+commitment to backward compatibility.