nimbus-mcp 0.1.0__tar.gz

nimbus_mcp-0.1.0/.gitignore

@@ -0,0 +1 @@
+dist/

nimbus_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: nimbus-mcp
+Version: 0.1.0
+Summary: MCP server bridging AI agents to Nimbus BCI pipelines (local backend)
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=2.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: ruff>=0.6; extra == 'test'
+Description-Content-Type: text/markdown
+
+# nimbus-mcp
+
+MCP server that lets AI agents (Claude Code, Cursor, Claude Desktop) build, validate,
+run, and analyze Nimbus BCI pipelines — and (explicitly confirmed) drive live EEG
+streaming sessions — through your **local** Nimbus backend.
+
+## Install
+
+```bash
+pip install nimbus-mcp   # or: uvx nimbus-mcp
+```
+
+(Also installable from the repo: `pip install -e nimbus-studio/mcp`.)
+
+## Requirements
+
+- A Nimbus backend running locally: the **desktop app**, or the dev server
+  (`cd nimbus-studio/backend-py && python -m nimbus_backend.server.app`) with `DEBUG=1`.
+- The backend started with `MCP_LOCAL_KEY=<some-secret>` (never set this on Fly — it is
+  refused there).
+
+## Configure the backend
+
+Desktop/dev env (e.g. `backend-py/data/.env` or the dev shell):
+
+```bash
+MCP_LOCAL_KEY=choose-a-long-random-string
+DEBUG=1   # dev server only; the desktop app qualifies automatically
+```
+
+When enabling `MCP_LOCAL_KEY` on a machine connected to an untrusted network, also set
+`HOST=127.0.0.1` on the backend — the default bind is `0.0.0.0`, so the key would
+otherwise be accepted from the LAN.
+
+## Run the server
+
+```bash
+cd nimbus-studio/mcp
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[test]"
+NIMBUS_MCP_KEY=choose-a-long-random-string python -m nimbus_mcp
+```
+
+Env vars: `NIMBUS_API_URL` (default `http://127.0.0.1:8080`), `NIMBUS_MCP_KEY`
+(must match `MCP_LOCAL_KEY`), `NIMBUS_EXPORT_DIR` (default `~/nimbus-exports`).
+
+## Claude Code
+
+```bash
+claude mcp add nimbus -- <path-to-mcp-venv>/bin/python -m nimbus_mcp \
+  --env NIMBUS_MCP_KEY=choose-a-long-random-string
+```
+
+## Cursor / Claude Desktop (stdio)
+
+```json
+{
+  "mcpServers": {
+    "nimbus": {
+      "command": "<path-to-mcp-venv>/bin/python",
+      "args": ["-m", "nimbus_mcp"],
+      "env": { "NIMBUS_MCP_KEY": "choose-a-long-random-string" }
+    }
+  }
+}
+```
+
+## Tools (20)
+
+Discovery: `list_nodes`, `get_node_schema`, `list_templates`, `get_template`, `list_datasets`
+Build: `validate_pipeline`, `validate_node_config`
+Run: `run_pipeline` (non-blocking), `get_execution`, `list_executions`, `get_results`, `cancel_execution`
+Artifacts: `list_artifacts`, `download_artifact`, `export_python`
+Live: `list_devices`, `test_device`, `start_stream` (needs `confirm=true`),
+`stream_status`, `stop_stream`
+
+## Safety
+
+`start_stream` refuses to run without `confirm=true` — it connects an EEG device and
+starts a live session on a human. The `X-MCP-Key` path is machine-local only
+(never accepted on Fly deployments).

nimbus_mcp-0.1.0/README.md

@@ -0,0 +1,81 @@
+# nimbus-mcp
+
+MCP server that lets AI agents (Claude Code, Cursor, Claude Desktop) build, validate,
+run, and analyze Nimbus BCI pipelines — and (explicitly confirmed) drive live EEG
+streaming sessions — through your **local** Nimbus backend.
+
+## Install
+
+```bash
+pip install nimbus-mcp   # or: uvx nimbus-mcp
+```
+
+(Also installable from the repo: `pip install -e nimbus-studio/mcp`.)
+
+## Requirements
+
+- A Nimbus backend running locally: the **desktop app**, or the dev server
+  (`cd nimbus-studio/backend-py && python -m nimbus_backend.server.app`) with `DEBUG=1`.
+- The backend started with `MCP_LOCAL_KEY=<some-secret>` (never set this on Fly — it is
+  refused there).
+
+## Configure the backend
+
+Desktop/dev env (e.g. `backend-py/data/.env` or the dev shell):
+
+```bash
+MCP_LOCAL_KEY=choose-a-long-random-string
+DEBUG=1   # dev server only; the desktop app qualifies automatically
+```
+
+When enabling `MCP_LOCAL_KEY` on a machine connected to an untrusted network, also set
+`HOST=127.0.0.1` on the backend — the default bind is `0.0.0.0`, so the key would
+otherwise be accepted from the LAN.
+
+## Run the server
+
+```bash
+cd nimbus-studio/mcp
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[test]"
+NIMBUS_MCP_KEY=choose-a-long-random-string python -m nimbus_mcp
+```
+
+Env vars: `NIMBUS_API_URL` (default `http://127.0.0.1:8080`), `NIMBUS_MCP_KEY`
+(must match `MCP_LOCAL_KEY`), `NIMBUS_EXPORT_DIR` (default `~/nimbus-exports`).
+
+## Claude Code
+
+```bash
+claude mcp add nimbus -- <path-to-mcp-venv>/bin/python -m nimbus_mcp \
+  --env NIMBUS_MCP_KEY=choose-a-long-random-string
+```
+
+## Cursor / Claude Desktop (stdio)
+
+```json
+{
+  "mcpServers": {
+    "nimbus": {
+      "command": "<path-to-mcp-venv>/bin/python",
+      "args": ["-m", "nimbus_mcp"],
+      "env": { "NIMBUS_MCP_KEY": "choose-a-long-random-string" }
+    }
+  }
+}
+```
+
+## Tools (20)
+
+Discovery: `list_nodes`, `get_node_schema`, `list_templates`, `get_template`, `list_datasets`
+Build: `validate_pipeline`, `validate_node_config`
+Run: `run_pipeline` (non-blocking), `get_execution`, `list_executions`, `get_results`, `cancel_execution`
+Artifacts: `list_artifacts`, `download_artifact`, `export_python`
+Live: `list_devices`, `test_device`, `start_stream` (needs `confirm=true`),
+`stream_status`, `stop_stream`
+
+## Safety
+
+`start_stream` refuses to run without `confirm=true` — it connects an EEG device and
+starts a live session on a human. The `X-MCP-Key` path is machine-local only
+(never accepted on Fly deployments).

nimbus_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nimbus-mcp"
+version = "0.1.0"
+description = "MCP server bridging AI agents to Nimbus BCI pipelines (local backend)"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastmcp>=2.3",
+    "httpx>=0.27",
+    "pydantic>=2.7",
+]
+
+[project.scripts]
+nimbus-mcp = "nimbus_mcp.server:main"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nimbus_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

nimbus_mcp-0.1.0/src/nimbus_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""nimbus-mcp: MCP tools for Nimbus BCI pipelines (local backend bridge)."""
+
+__version__ = "0.1.0"

nimbus_mcp-0.1.0/src/nimbus_mcp/__main__.py

@@ -0,0 +1,4 @@
+from nimbus_mcp.server import main
+
+if __name__ == "__main__":
+    main()

nimbus_mcp-0.1.0/src/nimbus_mcp/client.py

@@ -0,0 +1,98 @@
+"""Thin HTTP client for the Nimbus backend, authenticated with X-MCP-Key."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .config import McpConfig
+
+_BACKEND_DOWN_HINT = (
+    "Cannot reach the Nimbus backend at {url}. "
+    "Start the desktop app (or the dev backend on :8080) and retry."
+)
+_AUTH_HINT = (
+    "Nimbus rejected the MCP key ({status}). Check that MCP_LOCAL_KEY on the backend "
+    "matches NIMBUS_MCP_KEY for this server, and that the backend runs locally "
+    "(desktop app or DEBUG=1) — the key is never accepted on Fly deployments."
+)
+
+
+class McpToolError(Exception):
+    """Actionable error surfaced to the MCP client (agent-visible)."""
+
+
+class NimbusClient:
+    """Blocking HTTP client; tools run in FastMCP's worker threads."""
+
+    def __init__(self, config: McpConfig, transport: httpx.BaseTransport | None = None) -> None:
+        if not config.mcp_key:
+            raise McpToolError(
+                "NIMBUS_MCP_KEY is not set. Configure this MCP server with the same "
+                "value as MCP_LOCAL_KEY on the backend."
+            )
+        self.config = config
+        self._http = httpx.Client(
+            base_url=config.api_url,
+            headers={"X-MCP-Key": config.mcp_key},
+            timeout=300.0,
+            transport=transport,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        return self._request("GET", path, params=params)
+
+    def post(self, path: str, json: dict[str, Any] | None = None) -> Any:
+        return self._request("POST", path, json=json)
+
+    def get_bytes(self, path: str) -> bytes:
+        return self._request("GET", path, content=True)
+
+    def post_bytes(self, path: str, json: dict[str, Any] | None = None) -> bytes:
+        return self._request("POST", path, json=json, content=True)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        content: bool = False,
+    ) -> Any:
+        try:
+            resp = self._http.request(method, path, params=params, json=json)
+        except httpx.HTTPError as err:
+            raise McpToolError(_BACKEND_DOWN_HINT.format(url=self.config.api_url)) from err
+        # 401 = the key was rejected by the auth layer. 403 is a policy denial
+        # (e.g. freemium limits) — let it fall through to the generic path so
+        # the backend's detail message surfaces.
+        if resp.status_code == 401:
+            raise McpToolError(_AUTH_HINT.format(status=resp.status_code))
+        if resp.status_code >= 400:
+            raise McpToolError(self._backend_error(resp))
+        return resp.content if content else self._json(resp)
+
+    @staticmethod
+    def _json(resp: httpx.Response) -> Any:
+        try:
+            return resp.json()
+        except ValueError:
+            return {"ok": False, "raw": resp.text[:500]}
+
+    @staticmethod
+    def _backend_error(resp: httpx.Response) -> str:
+        body: Any = None
+        try:
+            body = resp.json()
+        except ValueError:
+            pass
+        detail = body.get("detail") if isinstance(body, dict) else None
+        if isinstance(detail, dict):
+            msg = detail.get("detail") or detail.get("title") or str(detail)
+        else:
+            msg = str(detail) if detail else resp.text[:300]
+        return f"Nimbus API error {resp.status_code}: {msg}"

nimbus_mcp-0.1.0/src/nimbus_mcp/config.py

@@ -0,0 +1,28 @@
+"""Environment-driven configuration for the nimbus-mcp server."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_API_URL = "http://127.0.0.1:8080"
+DEFAULT_EXPORT_DIR = Path.home() / "nimbus-exports"
+
+
+@dataclass(frozen=True)
+class McpConfig:
+    api_url: str
+    mcp_key: str
+    export_dir: Path
+
+
+def load_config(env: Mapping[str, str] | None = None) -> McpConfig:
+    """Resolve config from ``env`` (defaults to ``os.environ``)."""
+    env = os.environ if env is None else env
+    return McpConfig(
+        api_url=env.get("NIMBUS_API_URL", DEFAULT_API_URL).rstrip("/"),
+        mcp_key=env.get("NIMBUS_MCP_KEY", ""),
+        export_dir=Path(env.get("NIMBUS_EXPORT_DIR", str(DEFAULT_EXPORT_DIR))).expanduser(),
+    )

nimbus_mcp-0.1.0/src/nimbus_mcp/server.py

@@ -0,0 +1,32 @@
+"""FastMCP server assembly: one client, five tool modules, stdio transport."""
+
+from __future__ import annotations
+
+from fastmcp import FastMCP
+
+from .client import NimbusClient
+from .config import load_config
+from .tools import artifacts, build, discovery, live, run
+
+INSTRUCTIONS = """Nimbus Studio BCI tools. Typical flows:
+1) Explore: list_nodes / get_node_schema / list_templates / get_template / list_datasets.
+2) Build: compose a train graph ({nodes: [{id, type, config}], connections: [{from, to}]}),
+   validate_pipeline it, then run_pipeline (non-blocking) and poll get_execution.
+3) Results: get_results (kappa, ITR, confusion matrix), list_artifacts / download_artifact,
+   export_python for a standalone zip.
+4) Live (use with care): list_devices, test_device, then start_stream(confirm=true) only with
+   the user's explicit go-ahead — it connects an EEG device to a human session.
+Note: expect filter/ASR warm-up periods and confidence to start low; signal quality matters."""
+
+
+def build_server(client: NimbusClient | None = None) -> FastMCP:
+    if client is None:
+        client = NimbusClient(load_config())
+    mcp = FastMCP("nimbus", instructions=INSTRUCTIONS)
+    for module in (discovery, build, run, artifacts, live):
+        module.register(mcp, client)
+    return mcp
+
+
+def main() -> None:
+    build_server().run()  # stdio transport

nimbus_mcp-0.1.0/src/nimbus_mcp/tools/__init__.py

@@ -0,0 +1 @@
+"""Tool modules for nimbus-mcp. Each exposes register(mcp, client)."""

nimbus_mcp-0.1.0/src/nimbus_mcp/tools/_guards.py

@@ -0,0 +1,15 @@
+"""Shared input guards for tool parameters interpolated into request paths."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..client import McpToolError
+
+
+def safe_segment(value: str, *, label: str = "execution id") -> str:
+    """Validate a value used as a single path/URL segment (e.g. execution id)."""
+    # Path(value).name != value also rejects "." and any residual separator trick.
+    if not value or "/" in value or "\\" in value or ".." in value or Path(value).name != value:
+        raise McpToolError(f"Invalid {label} '{value}'.")
+    return value

nimbus_mcp-0.1.0/src/nimbus_mcp/tools/artifacts.py

@@ -0,0 +1,61 @@
+"""Artifact + export tools: list/download trained artifacts, export standalone Python."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from fastmcp import FastMCP
+
+from ..client import NimbusClient
+from ._guards import safe_segment
+
+
+def _safe_name(name: str) -> str:
+    # Same rejection rules as a path segment, labelled for artifact names.
+    return safe_segment(name, label="artifact name")
+
+
+def register(mcp: FastMCP, client: NimbusClient) -> None:
+    @mcp.tool
+    def list_artifacts(execution_id: str) -> dict[str, Any]:
+        """Trained artifacts (models/filters, e.g. *.pkl) saved by an execution."""
+        exec_id = safe_segment(execution_id)
+        payload = client.get(f"/api/executions/{exec_id}/artifacts")
+        return {
+            "executionId": execution_id,
+            "artifacts": [
+                {"name": a.get("name"), "size": a.get("size"), "subject": a.get("subject")}
+                for a in payload.get("artifacts", [])
+            ],
+        }
+
+    @mcp.tool
+    def download_artifact(execution_id: str, artifact_name: str) -> dict[str, Any]:
+        """Download one artifact file to NIMBUS_EXPORT_DIR/executions/<id>/ and return its path."""
+        exec_id = safe_segment(execution_id)
+        artifact = _safe_name(artifact_name)
+        data = client.get_bytes(f"/api/executions/{exec_id}/artifacts/{artifact}")
+        dest_dir = client.config.export_dir / "executions" / exec_id
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        dest = dest_dir / artifact
+        dest.write_bytes(data)
+        return {"path": str(dest), "size": len(data)}
+
+    @mcp.tool
+    def export_python(train_graph: dict[str, Any], name: str | None = None) -> dict[str, Any]:
+        """Export the pipeline as a standalone runnable Python bundle (zip saved locally)."""
+        body: dict[str, Any] = {"train": train_graph}
+        if name is not None:
+            body["name"] = name
+        data = client.post_bytes("/api/export/python", json=body)
+        out_dir = client.config.export_dir / "exports"
+        out_dir.mkdir(parents=True, exist_ok=True)
+        stamp = time.strftime("%Y%m%d-%H%M%S")
+        dest = out_dir / f"{stamp}-nimbus-export.zip"
+        suffix = 0
+        while dest.exists():
+            suffix += 1
+            dest = out_dir / f"{stamp}-nimbus-export-{suffix}.zip"
+        dest.write_bytes(data)
+        return {"path": str(dest), "size": len(data)}

nimbus_mcp-0.1.0/src/nimbus_mcp/tools/build.py

@@ -0,0 +1,29 @@
+"""Build tools: graph and node-config validation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastmcp import FastMCP
+
+from ..client import NimbusClient
+
+GRAPH_HELP = (
+    "ExecGraphSnapshot: {nodes: [{id, type, config}], connections: [{from, to}]}. "
+    "Build it from get_template(id).train or from scratch using list_nodes()."
+)
+
+
+def register(mcp: FastMCP, client: NimbusClient) -> None:
+    # NOTE: description is passed to @mcp.tool explicitly because
+    # `"""doc""" + GRAPH_HELP` is not a string literal and would not become __doc__.
+    @mcp.tool(description="Validate a pipeline graph before running. " + GRAPH_HELP)
+    def validate_pipeline(train_graph: dict[str, Any]) -> dict[str, Any]:
+        return client.post("/api/validate-pipeline", json={"train": train_graph})
+
+    @mcp.tool
+    def validate_node_config(node_type: str, config: dict[str, Any]) -> dict[str, Any]:
+        """Validate one node's config object against its schema (get_node_schema)."""
+        return client.post(
+            "/api/validate-node-config", json={"nodeType": node_type, "config": config}
+        )

nimbus_mcp-0.1.0/src/nimbus_mcp/tools/discovery.py

@@ -0,0 +1,106 @@
+"""Discovery tools: node catalog, templates, datasets."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastmcp import FastMCP
+
+from ..client import McpToolError, NimbusClient
+from ._guards import safe_segment
+
+
+def register(mcp: FastMCP, client: NimbusClient) -> None:
+    @mcp.tool
+    def list_nodes(category: str | None = None) -> dict[str, Any]:
+        """List Nimbus pipeline node types (data, preprocessing, features, models...).
+
+        Use get_node_schema(node_type) for one node's full config schema and ports.
+        """
+        payload = client.get("/api/node-types")
+        nodes = [
+            {
+                "id": n.get("id"),
+                "name": n.get("name"),
+                "category": n.get("category"),
+                "description": n.get("description", ""),
+                "inputs": [
+                    {"name": p.get("name"), "type": p.get("type")} for p in n.get("inputs", [])
+                ],
+                "outputs": [
+                    {"name": p.get("name"), "type": p.get("type")} for p in n.get("outputs", [])
+                ],
+            }
+            for n in payload.get("nodeTypes", [])
+            if category is None or n.get("category") == category
+        ]
+        return {"count": len(nodes), "nodes": nodes}
+
+    @mcp.tool
+    def get_node_schema(node_type: str) -> dict[str, Any]:
+        """Full config JSON schema + input/output ports for one node type."""
+        payload = client.get("/api/node-types")
+        for node in payload.get("nodeTypes", []):
+            if node.get("id") == node_type:
+                return {
+                    "id": node_type,
+                    "name": node.get("name"),
+                    "configSchema": node.get("configSchema", {}),
+                    "ports": {"inputs": node.get("inputs", []), "outputs": node.get("outputs", [])},
+                }
+        raise McpToolError(
+            f"Unknown node type '{node_type}'. Call list_nodes() for valid ids."
+        )
+
+    @mcp.tool
+    def list_templates() -> dict[str, Any]:
+        """List built-in starter pipelines (MI/P300/SSVEP...). get_template(id) for the graph."""
+        payload = client.get("/api/templates")
+        templates = [
+            {
+                "id": t.get("id"),
+                "name": t.get("name"),
+                "description": t.get("description", ""),
+                "category": t.get("category"),
+                "expectedAccuracy": t.get("expectedAccuracy"),
+            }
+            for t in payload.get("templates", [])
+        ]
+        return {"count": len(templates), "templates": templates}
+
+    @mcp.tool
+    def get_template(template_id: str) -> dict[str, Any]:
+        """Full template incl. the 'train' execGraph needed by run_pipeline/validate_pipeline."""
+        tid = safe_segment(template_id, label="template id")
+        payload = client.get(f"/api/templates/{tid}")
+        template = payload.get("template", {})
+        return {
+            "id": template.get("id"),
+            "name": template.get("name"),
+            "description": template.get("description", ""),
+            "train": template.get("train"),
+        }
+
+    @mcp.tool
+    def list_datasets(only_on_disk: bool = True) -> dict[str, Any]:
+        """Curated public EEG datasets (MOABB packs) available to pipelines."""
+        payload = client.get("/api/public-datasets/index")
+        datasets = []
+        for dataset_id, entry in payload.get("datasets", {}).items():
+            if only_on_disk and not entry.get("onDisk"):
+                continue
+            subjects = entry.get("subjects") or []
+            details = entry.get("details") or {}
+            datasets.append(
+                {
+                    "id": dataset_id,
+                    "label": entry.get("label"),
+                    "paradigm": entry.get("paradigm"),
+                    "onDisk": bool(entry.get("onDisk")),
+                    "defaultSubject": entry.get("defaultSubject"),
+                    "subjectsCount": len(subjects),
+                    "channels": details.get("channels"),
+                    "samplingRate": details.get("samplingRate"),
+                }
+            )
+        return {"count": len(datasets), "datasets": datasets}