nodus-mcp-server 0.1.0__tar.gz

nodus_mcp_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shawn Knight
+
+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.

nodus_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: nodus-mcp-server
+Version: 0.1.0
+Summary: MCP server powered by the Nodus orchestration runtime
+Author-email: Shawn Knight <shawnknight@the-master-plan.com>
+License: MIT License
+        
+        Copyright (c) 2026 Shawn Knight
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/Masterplanner25/nodus-mcp-server
+Project-URL: Repository, https://github.com/Masterplanner25/nodus-mcp-server
+Project-URL: Issues, https://github.com/Masterplanner25/nodus-mcp-server/issues
+Keywords: mcp,nodus,orchestration,agents,llm,claude
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: nodus-lang<5.0.0,>=4.0.4
+Requires-Dist: nodus-mcp>=0.1.0
+Dynamic: license-file
+
+# nodus-mcp-server
+
+An MCP (Model Context Protocol) server that exposes the [Nodus](https://github.com/Masterplanner25/Nodus) orchestration runtime as tools for Claude Desktop and other MCP-compatible hosts.
+
+## What it does
+
+Six tools over a single server process:
+
+| Tool | Description |
+|------|-------------|
+| `nodus.remember` | Store a fact in persistent SQLite memory with optional tags |
+| `nodus.recall` | Search memory by free-text query and/or tags |
+| `nodus.forget` | Delete a memory entry by ID |
+| `nodus.run_goal` | Run a Nodus goal (sandboxed, structured step results) |
+| `nodus.run_workflow` | Run a Nodus workflow (checkpoint/resume capable) |
+| `nodus.exec` | Execute arbitrary `.nd` code (10 s timeout, no file I/O) |
+
+## Requirements
+
+- Python ≥ 3.10
+- `nodus-lang >= 4.0.4`
+- `nodus-mcp >= 0.1.0`
+
+## Install
+
+```
+pip install nodus-lang nodus-mcp nodus-mcp-server
+```
+
+## Claude Desktop setup
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "nodus": {
+      "command": "nodus-mcp-server",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The six `nodus.*` tools will appear in the tool list.
+
+Memory persists at `~/.nodus-mcp-server/data/memory.db` and survives upgrades.
+
+## HTTP mode
+
+For remote or multi-client use:
+
+```
+nodus-mcp-server --http --port 8080
+nodus-mcp-server --http --port 8080 --bearer-token <secret>
+```
+
+## Built-in goals and workflows
+
+### Goals
+
+**`summarize`** — `params: {text: string}`
+
+Counts characters and classifies text size (short / medium / long).
+
+```json
+{
+  "name": "summarize",
+  "params": {"text": "Your text here"}
+}
+```
+
+Returns:
+```json
+{
+  "steps": {
+    "measure": 14,
+    "classify": {"chars": 14, "size": "short", "empty": false}
+  }
+}
+```
+
+**`pipeline`** — `params: {items: list, label: string}`
+
+Validates an item list and produces a labelled report.
+
+```json
+{
+  "name": "pipeline",
+  "params": {"items": [1, 2, 3], "label": "batch-1"}
+}
+```
+
+Returns:
+```json
+{
+  "steps": {
+    "validate": 3,
+    "report": {"label": "batch-1", "item_count": 3, "has_items": true, "status": "complete"}
+  }
+}
+```
+
+### Workflows
+
+**`research`** — `params: {topic: string}`
+
+Two-step planning + execution workflow with checkpoints at each step.
+
+```json
+{
+  "name": "research",
+  "params": {"topic": "LLM context windows"}
+}
+```
+
+Returns:
+```json
+{
+  "steps": {
+    "plan": {"query": "LLM context windows", "strategy": "step-by-step"},
+    "execute": {"topic": "LLM context windows", "query": "LLM context windows", "strategy": "step-by-step", "status": "complete"}
+  }
+}
+```
+
+## Adding your own goals and workflows
+
+Drop a `.nd` file into `goals/` or `workflows/`. The file should **only define** the goal or workflow — do not call `run_goal()` or `run_workflow()` at the bottom (the server calls it for you).
+
+```nodus
+// goals/my_goal.nd  — input variable injected via params
+goal my_goal {
+    step process {
+        let result = len(input_text)
+        return {"length": result, "has_content": result > 0i}
+    }
+}
+```
+
+Then call it:
+```json
+{"name": "my_goal", "params": {"input_text": "hello"}}
+```
+
+## Sandbox
+
+`.nd` scripts run with:
+- No file system access (`allowed_paths=[]`)
+- No network access
+- Goal timeout: 30 s
+- Workflow timeout: 60 s
+- `nodus.exec` timeout: 10 s
+
+## Architecture
+
+```
+server.py          — NodusRuntime, tool registration, MCP transport
+runner.py          — goal/workflow execution via ModuleLoader + VM
+memory_store.py    — SQLite-backed thread-safe memory store
+goals/             — .nd goal definitions
+workflows/         — .nd workflow definitions
+~/.nodus-mcp-server/data/memory.db  — SQLite DB (persists across upgrades)
+```
+
+## License
+
+MIT

nodus_mcp_server-0.1.0/README.md

@@ -0,0 +1,168 @@
+# nodus-mcp-server
+
+An MCP (Model Context Protocol) server that exposes the [Nodus](https://github.com/Masterplanner25/Nodus) orchestration runtime as tools for Claude Desktop and other MCP-compatible hosts.
+
+## What it does
+
+Six tools over a single server process:
+
+| Tool | Description |
+|------|-------------|
+| `nodus.remember` | Store a fact in persistent SQLite memory with optional tags |
+| `nodus.recall` | Search memory by free-text query and/or tags |
+| `nodus.forget` | Delete a memory entry by ID |
+| `nodus.run_goal` | Run a Nodus goal (sandboxed, structured step results) |
+| `nodus.run_workflow` | Run a Nodus workflow (checkpoint/resume capable) |
+| `nodus.exec` | Execute arbitrary `.nd` code (10 s timeout, no file I/O) |
+
+## Requirements
+
+- Python ≥ 3.10
+- `nodus-lang >= 4.0.4`
+- `nodus-mcp >= 0.1.0`
+
+## Install
+
+```
+pip install nodus-lang nodus-mcp nodus-mcp-server
+```
+
+## Claude Desktop setup
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "nodus": {
+      "command": "nodus-mcp-server",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The six `nodus.*` tools will appear in the tool list.
+
+Memory persists at `~/.nodus-mcp-server/data/memory.db` and survives upgrades.
+
+## HTTP mode
+
+For remote or multi-client use:
+
+```
+nodus-mcp-server --http --port 8080
+nodus-mcp-server --http --port 8080 --bearer-token <secret>
+```
+
+## Built-in goals and workflows
+
+### Goals
+
+**`summarize`** — `params: {text: string}`
+
+Counts characters and classifies text size (short / medium / long).
+
+```json
+{
+  "name": "summarize",
+  "params": {"text": "Your text here"}
+}
+```
+
+Returns:
+```json
+{
+  "steps": {
+    "measure": 14,
+    "classify": {"chars": 14, "size": "short", "empty": false}
+  }
+}
+```
+
+**`pipeline`** — `params: {items: list, label: string}`
+
+Validates an item list and produces a labelled report.
+
+```json
+{
+  "name": "pipeline",
+  "params": {"items": [1, 2, 3], "label": "batch-1"}
+}
+```
+
+Returns:
+```json
+{
+  "steps": {
+    "validate": 3,
+    "report": {"label": "batch-1", "item_count": 3, "has_items": true, "status": "complete"}
+  }
+}
+```
+
+### Workflows
+
+**`research`** — `params: {topic: string}`
+
+Two-step planning + execution workflow with checkpoints at each step.
+
+```json
+{
+  "name": "research",
+  "params": {"topic": "LLM context windows"}
+}
+```
+
+Returns:
+```json
+{
+  "steps": {
+    "plan": {"query": "LLM context windows", "strategy": "step-by-step"},
+    "execute": {"topic": "LLM context windows", "query": "LLM context windows", "strategy": "step-by-step", "status": "complete"}
+  }
+}
+```
+
+## Adding your own goals and workflows
+
+Drop a `.nd` file into `goals/` or `workflows/`. The file should **only define** the goal or workflow — do not call `run_goal()` or `run_workflow()` at the bottom (the server calls it for you).
+
+```nodus
+// goals/my_goal.nd  — input variable injected via params
+goal my_goal {
+    step process {
+        let result = len(input_text)
+        return {"length": result, "has_content": result > 0i}
+    }
+}
+```
+
+Then call it:
+```json
+{"name": "my_goal", "params": {"input_text": "hello"}}
+```
+
+## Sandbox
+
+`.nd` scripts run with:
+- No file system access (`allowed_paths=[]`)
+- No network access
+- Goal timeout: 30 s
+- Workflow timeout: 60 s
+- `nodus.exec` timeout: 10 s
+
+## Architecture
+
+```
+server.py          — NodusRuntime, tool registration, MCP transport
+runner.py          — goal/workflow execution via ModuleLoader + VM
+memory_store.py    — SQLite-backed thread-safe memory store
+goals/             — .nd goal definitions
+workflows/         — .nd workflow definitions
+~/.nodus-mcp-server/data/memory.db  — SQLite DB (persists across upgrades)
+```
+
+## License
+
+MIT

nodus_mcp_server-0.1.0/nodus_mcp_server/goals/pipeline.nd

@@ -0,0 +1,20 @@
+// Pipeline goal — input: items (list), label (string)
+// Validates input, then produces a report. Steps run in dependency order;
+// validate is a prerequisite for both report branches.
+
+goal pipeline {
+    step validate {
+        let count = len(items)
+        checkpoint "validated"
+        return count
+    }
+
+    step report after validate {
+        return {
+            "label": label,
+            "item_count": validate,
+            "has_items": validate > 0i,
+            "status": "complete"
+        }
+    }
+}

nodus_mcp_server-0.1.0/nodus_mcp_server/goals/summarize.nd

@@ -0,0 +1,17 @@
+// Summarize goal — input: text (string)
+// Measures character count then classifies the text by size.
+
+goal summarize {
+    step measure {
+        let char_count = len(text)
+        checkpoint "measured"
+        return char_count
+    }
+
+    step classify after measure {
+        let size = "short"
+        if (measure > 500i) { size = "medium" }
+        if (measure > 2000i) { size = "long" }
+        return {"chars": measure, "size": size, "empty": measure == 0i}
+    }
+}

nodus_mcp_server-0.1.0/nodus_mcp_server/memory_store.py

@@ -0,0 +1,75 @@
+"""SQLite-backed persistent memory store."""
+from __future__ import annotations
+
+import sqlite3
+import threading
+import time
+import uuid
+
+
+class MemoryStore:
+    def __init__(self, db_path: str) -> None:
+        import os
+        os.makedirs(os.path.dirname(db_path), exist_ok=True)
+        self._path = db_path
+        self._lock = threading.Lock()
+        self._init_db()
+
+    def _conn(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self._path, check_same_thread=False)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _init_db(self) -> None:
+        with self._lock, self._conn() as conn:
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS memories (
+                    id TEXT PRIMARY KEY,
+                    content TEXT NOT NULL,
+                    tags TEXT NOT NULL DEFAULT '',
+                    created_at REAL NOT NULL
+                )
+            """)
+
+    def remember(self, content: str, tags: list[str]) -> dict:
+        mem_id = str(uuid.uuid4())[:8]
+        tags_str = ",".join(t.strip() for t in tags if t.strip())
+        with self._lock, self._conn() as conn:
+            conn.execute(
+                "INSERT INTO memories (id, content, tags, created_at) VALUES (?, ?, ?, ?)",
+                (mem_id, content, tags_str, time.time()),
+            )
+        return {"id": mem_id, "stored": True}
+
+    def recall(self, query: str, tags: list[str], limit: int) -> list[dict]:
+        with self._lock, self._conn() as conn:
+            rows = conn.execute(
+                "SELECT id, content, tags, created_at FROM memories ORDER BY created_at DESC LIMIT 200"
+            ).fetchall()
+
+        results = []
+        query_lower = query.lower()
+        filter_tags = {t.strip().lower() for t in tags if t.strip()}
+
+        for row in rows:
+            content = row["content"]
+            row_tags = {t for t in row["tags"].split(",") if t}
+            if query_lower and query_lower not in content.lower():
+                continue
+            if filter_tags and not filter_tags.intersection(row_tags):
+                continue
+            results.append({
+                "id": row["id"],
+                "content": content,
+                "tags": list(row_tags),
+                "created_at": row["created_at"],
+            })
+            if len(results) >= limit:
+                break
+
+        return results
+
+    def forget(self, memory_id: str) -> dict:
+        with self._lock, self._conn() as conn:
+            cursor = conn.execute("DELETE FROM memories WHERE id = ?", (memory_id,))
+        return {"id": memory_id, "deleted": cursor.rowcount > 0}

nodus_mcp_server-0.1.0/nodus_mcp_server/runner.py

@@ -0,0 +1,100 @@
+"""Goal and workflow execution helpers."""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from nodus.vm.vm import VM
+from nodus.runtime.module_loader import ModuleLoader
+from nodus.tooling.sandbox import capture_output, configure_vm_limits
+from nodus.tooling.runner import _resolve_goal_from_vm, _resolve_workflow_from_vm
+from nodus.support.config import MAX_STEPS, MAX_STDOUT_CHARS
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+GOALS_DIR = os.path.join(_HERE, "goals")
+WORKFLOWS_DIR = os.path.join(_HERE, "workflows")
+
+
+def _load(directory: str, name: str, kind: str) -> tuple[str, str]:
+    safe = os.path.basename(name)  # prevent path traversal
+    path = os.path.join(directory, f"{safe}.nd")
+    if not os.path.isfile(path):
+        raise FileNotFoundError(f"{kind} '{safe}' not found (looked in {directory})")
+    with open(path, encoding="utf-8") as fh:
+        return fh.read(), path
+
+
+def _load_into_vm(code: str, path: str, params: dict, timeout_ms: int) -> tuple[VM, str]:
+    """Compile and execute module-level code (goal/workflow definition) into a sandboxed VM.
+
+    host_globals must be passed to ModuleLoader — passing them only to the VM constructor
+    is not enough because _execute_module overwrites vm.host_globals via reset_program.
+    """
+    vm = VM([], {}, code_locs=[], source_path=path, allowed_paths=[])
+    configure_vm_limits(vm, max_steps=MAX_STEPS, timeout_ms=timeout_ms)
+    loader = ModuleLoader(vm=vm, host_globals=params)
+    module_name = os.path.abspath(path)
+    base_dir = os.path.dirname(module_name)
+    with capture_output(max_stdout_chars=MAX_STDOUT_CHARS) as (stdout, _):
+        loader.load_module_from_source(code, module_name=module_name, base_dir=base_dir)
+    return vm, stdout.getvalue()
+
+
+def run_goal(runtime: Any, name: str, params: dict) -> dict:
+    try:
+        code, path = _load(GOALS_DIR, name, "goal")
+    except FileNotFoundError as exc:
+        return {"ok": False, "error": str(exc)}
+    try:
+        vm, def_stdout = _load_into_vm(code, path, params, timeout_ms=30_000)
+    except Exception as exc:
+        return {"ok": False, "error": str(exc)}
+    try:
+        goal = _resolve_goal_from_vm(vm, name)
+        with capture_output(max_stdout_chars=MAX_STDOUT_CHARS) as (run_out, _):
+            goal_result = vm.builtin_run_goal(goal)
+    except Exception as exc:
+        return {"ok": False, "error": str(exc)}
+    combined_stdout = (def_stdout + run_out.getvalue()).strip()
+    goal_data = goal_result if isinstance(goal_result, dict) else {}
+    steps = goal_data.get("steps", {})
+    out: dict = {"ok": True, "goal": name, "steps": steps}
+    if combined_stdout:
+        out["stdout"] = combined_stdout
+    return out
+
+
+def run_workflow(runtime: Any, name: str, params: dict) -> dict:
+    try:
+        code, path = _load(WORKFLOWS_DIR, name, "workflow")
+    except FileNotFoundError as exc:
+        return {"ok": False, "error": str(exc)}
+    try:
+        vm, def_stdout = _load_into_vm(code, path, params, timeout_ms=60_000)
+    except Exception as exc:
+        return {"ok": False, "error": str(exc)}
+    try:
+        workflow = _resolve_workflow_from_vm(vm, name)
+        with capture_output(max_stdout_chars=MAX_STDOUT_CHARS) as (run_out, _):
+            wf_result = vm.builtin_run_workflow(workflow)
+    except Exception as exc:
+        return {"ok": False, "error": str(exc)}
+    combined_stdout = (def_stdout + run_out.getvalue()).strip()
+    wf_data = wf_result if isinstance(wf_result, dict) else {}
+    steps = wf_data.get("steps", {})
+    out: dict = {"ok": True, "workflow": name, "steps": steps}
+    if combined_stdout:
+        out["stdout"] = combined_stdout
+    return out
+
+
+def exec_code(runtime: Any, code: str) -> dict:
+    result = runtime.run_source(code, timeout_ms=10_000)
+    if not result["ok"]:
+        err = result.get("error") or {}
+        return {"ok": False, "error": err.get("message", "execution failed")}
+    return {
+        "ok": True,
+        "result": result.get("result"),
+        "stdout": result.get("stdout", "").strip(),
+    }