lamcp 0.1.0__py3-none-any.whl

lamcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

lamcp/server.py

@@ -0,0 +1,131 @@
+"""LAMCP: Lambda MCP server bridging LLMs to Grasshopper.
+
+Architecture::
+
+    Claude ──MCP stdio──▶ lamcp (this process, Python 3.10+)
+                              │
+                              │  HTTP POST /exec
+                              ▼
+                      LAMCP Bridge GH component (Rhino 8 CPython 3.9)
+                          ├─ http.server on 127.0.0.1:8765
+                          ├─ exec() with shared globals
+                          └─ returns stdout/stderr/repr(_)
+
+The bridge URL is read from the ``LAMCP_BRIDGE_URL`` env var
+(default ``http://127.0.0.1:8765``).
+"""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+from fastmcp import FastMCP
+
+BRIDGE_URL = os.environ.get("LAMCP_BRIDGE_URL", "http://127.0.0.1:8765")
+DEFAULT_TIMEOUT = 30.0
+
+mcp = FastMCP("lamcp")
+
+
+@mcp.tool()
+def run_python_script(code: str, timeout: float = DEFAULT_TIMEOUT) -> dict:
+    """Execute Python code inside the running Rhino 8 instance.
+
+    The code runs in Rhino 8's CPython 3.9 runtime with full access to
+    RhinoCommon and Grasshopper APIs (active document, GH component
+    lookup, slider mutation, etc.). A shared globals dict persists across
+    calls so state accumulates (e.g., ``import`` once, reuse the binding
+    on later calls).
+
+    To return a value, assign it to ``_`` — the bridge returns ``repr(_)``.
+
+    Parameters
+    ----------
+    code : str
+        Python source to execute inside Rhino.
+    timeout : float, optional
+        Max seconds to wait for the execution to complete.
+
+    Returns
+    -------
+    dict
+        ``{"stdout": str, "stderr": str, "result": str|None, "error": str|None}``.
+        ``result`` is ``repr(_)`` if ``_`` was assigned, else ``"None"``.
+        ``error`` is a formatted traceback if the script raised, else ``None``.
+    """
+    try:
+        with httpx.Client(base_url=BRIDGE_URL, timeout=timeout + 5) as client:
+            response = client.post("/exec", json={"code": code, "timeout": timeout})
+            response.raise_for_status()
+            return response.json()
+    except httpx.RequestError as exc:
+        return {
+            "stdout": "",
+            "stderr": "",
+            "result": None,
+            "error": "Failed to reach LAMCP bridge at {}: {!r}".format(BRIDGE_URL, exc),
+        }
+
+
+@mcp.tool()
+def unload_python_modules(prefix: str) -> dict:
+    """Unload every imported Python module whose name starts with ``prefix``.
+
+    Useful during dev iteration: after editing a Python module on disk
+    that's imported by Rhino-side code, Rhino's CPython runtime keeps the
+    old version cached in ``sys.modules``. This tool drops all cached
+    entries under ``prefix`` so the next import re-reads from disk.
+
+    Note: this only updates ``sys.modules``. If your Grasshopper script's
+    top-level ``from foo import bar`` already bound a name, that binding
+    is unaffected — you also need to re-save / re-run the script for the
+    import to be re-evaluated.
+
+    Parameters
+    ----------
+    prefix : str
+        Dotted module prefix (e.g. ``"compas_fab"``, ``"my_pkg.sub"``).
+        All modules with names equal to or starting with ``prefix + "."`` are
+        unloaded.
+
+    Returns
+    -------
+    dict
+        ``{"unloaded": [list of module names], "count": int}``.
+    """
+    code = (
+        "import sys\n"
+        "prefix = {!r}\n"
+        "to_drop = [n for n in list(sys.modules) if n == prefix or n.startswith(prefix + '.')]\n"
+        "for n in to_drop: del sys.modules[n]\n"
+        "_ = {{'unloaded': sorted(to_drop), 'count': len(to_drop)}}\n"
+    ).format(prefix)
+    return run_python_script(code)
+
+
+@mcp.tool()
+def bridge_health() -> dict:
+    """Check whether the LAMCP Bridge HTTP server is reachable.
+
+    Returns
+    -------
+    dict
+        ``{"reachable": bool, "url": str, "detail": str}``.
+    """
+    try:
+        with httpx.Client(base_url=BRIDGE_URL, timeout=5.0) as client:
+            response = client.get("/health")
+            response.raise_for_status()
+            return {"reachable": True, "url": BRIDGE_URL, "detail": response.text}
+    except httpx.RequestError as exc:
+        return {"reachable": False, "url": BRIDGE_URL, "detail": repr(exc)}
+
+
+def main():
+    """Run the MCP server on stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

lamcp-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+lamcp/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+lamcp/server.py,sha256=-KsaJF8J4SV8Q58tud6ysjeAogEAoH5Axy9ccIU6YiQ,4332
+lamcp-0.1.0.dist-info/METADATA,sha256=pxR2LTbwwMr2GiYT3aPHUT72OAi3F1YkKwoYQXBxRoE,7158
+lamcp-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+lamcp-0.1.0.dist-info/entry_points.txt,sha256=nrDqJK5nBBQVPyTitJWOfzLRp_1Rwh0CP72Y7DuEof0,44
+lamcp-0.1.0.dist-info/licenses/LICENSE,sha256=2MAz4e-_lRv_8QvIbqBa-99gRML-Gf3r-T_PNul1HlI,1094
+lamcp-0.1.0.dist-info/RECORD,,

lamcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

lamcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lamcp = lamcp.server:main

lamcp-0.1.0.dist-info/licenses/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.