convez.ai
MCP Server
Masterplanner25

nodus-mcp-server

Masterplanner25/nodus-mcp-server

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server powered by the Nodus orchestration runtime — memory, goals, workflows, and sandboxed execution for Claude Desktop and MCP hosts

Instalação

$npx convez-ai Masterplanner25/nodus-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 dias
Versão
v0.2.1
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

nodus-mcp-server

An MCP server that connects AI assistants to the Nodus language runtime — giving them persistent memory, sandboxed code execution, and checkpoint/resume orchestration workflows, all powered by .nd scripts running on the Nodus VM.

Supports Claude Desktop (stdio) and ChatGPT Desktop (HTTP/SSE).

Tools

ToolWhat it does
nodus_rememberStore a fact in persistent memory with optional tags
nodus_recallSearch memory by free-text query and/or tags
nodus_forgetDelete a memory entry by ID
nodus_run_goalRun a built-in Nodus goal (structured multi-step result)
nodus_run_workflowRun a built-in Nodus workflow (returns a graph_id for resuming)
nodus_resume_workflowResume a workflow from a checkpoint using its graph_id
nodus_execExecute arbitrary Nodus code in a sandbox (no file I/O, no network, no subprocess, 10 s timeout)

Requirements

  • Python ≥ 3.10
  • pipx (recommended — keeps the server in its own isolated environment)
  • Claude Desktop or ChatGPT Desktop (the downloadable apps, not browser versions)

Install

pipx install nodus-mcp-server

Claude Desktop setup

1. Find your config file

SetupConfig path
Standard install%APPDATA%\Claude\claude_desktop_config.json
Windows Store app%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json
macOS~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the server

{
  "mcpServers": {
    "nodus": {
      "command": "nodus-mcp-server",
      "args": ["--stdio"]
    }
  }
}

If nodus-mcp-server isn't on your PATH, use the full path to the executable. On Windows with pipx that's typically C:\Users\<you>\.local\bin\nodus-mcp-server.exe.

3. Restart Claude Desktop

The seven nodus_* tools will appear when you click the tools icon (the + button or tool picker) in a new conversation.

How to use

Memory

Store anything you want Claude to remember across conversations:

Use nodus_remember to store: "Project deadline is 2026-07-01" with tags ["project", "deadlines"]

Retrieve it later:

Use nodus_recall to find memories tagged "deadlines"

Or search by content:

Use nodus_recall to find memories about "deadline"

Memory is stored in a local SQLite database at ~/.nodus-mcp-server/data/memory.db and persists across upgrades.

Sandboxed code execution

Run Nodus (.nd) code in a fully sandboxed runtime:

Use nodus_exec to run: print("Hello from Nodus!")

The sandbox enforces: no file I/O, no network, no subprocess. Use print() to surface results — top-level return values are not captured.

Goals (structured multi-step tasks)

Goals run a fixed sequence of named steps and return each step's result:

Use nodus_run_goal with name "summarize" and params {"text": "your text here"}

Built-in goals:

GoalParamsWhat it does
summarize{text}Counts characters, classifies size (short/medium/long)
pipeline{items, label}Validates a list and produces a labelled report

Workflows (checkpoint/resume orchestration)

Workflows are like goals but support checkpoints — they can be paused and resumed from a saved state:

Use nodus_run_workflow with name "research" and params {"topic": "LLM context windows"}

The response includes a graph_id. Use it to resume the workflow later:

Use nodus_resume_workflow with graph_id "g_abc123" (and optionally a checkpoint label)

Built-in workflows:

WorkflowParamsWhat it does
research{topic}Two-step plan + execute workflow with checkpoints at each step

Adding your own goals and workflows

Goals and workflows are .nd files (Nodus source) placed in the goals/ or workflows/ directory of the installed package. The file should only define the goal or workflow — the server calls it for you.

// goals/my_goal.nd
goal my_goal {
    step process {
        if (input_text == nil) { throw "missing required param: input_text" }
        let result = len(input_text)
        return {"length": result, "has_content": result > 0i}
    }
}

Then call it:

{"name": "my_goal", "params": {"input_text": "hello"}}

Input params are injected as top-level variables in the .nd execution context. Check nil before using them — missing params surface as nil, not an error, unless you throw explicitly.

See the Nodus language guide for the full .nd syntax reference.

About Nodus

The goals, workflows, and nodus_exec sandbox all run on the Nodus VM — a lightweight, embeddable language runtime designed for AI-native orchestration. Nodus scripts (.nd files) define the step logic; the MCP server wires them to Claude over the Model Context Protocol.

Architecture

server.py          — MCP tool definitions, NodusRuntime setup, request dispatch
runner.py          — goal/workflow execution via ModuleLoader + VM
memory_store.py    — SQLite-backed thread-safe memory store
goals/             — .nd goal definitions (bundled + custom)
workflows/         — .nd workflow definitions (bundled + custom)
~/.nodus-mcp-server/data/memory.db  — SQLite DB (persists across upgrades)

ChatGPT Desktop setup

ChatGPT uses HTTP/SSE transport. Start the server in HTTP mode, then point ChatGPT at the URL.

1. Start the HTTP server

nodus-mcp-server --http --port 8765

This prints:

[nodus-mcp-server] HTTP/SSE listening on http://127.0.0.1:8765/sse
[nodus-mcp-server] Point ChatGPT / your MCP client at: http://127.0.0.1:8765/sse

Keep this terminal open while using ChatGPT.

2. Connect in ChatGPT Desktop

  1. Click your profile icon → Settings → Apps
  2. Go to Advanced Settings → enable Developer Mode
  3. Click Create App (or Connect more)
  4. Enter a name (e.g. Nodus), description, and base URL: http://127.0.0.1:8765/sse

3. Use in a chat

Open a new chat → click + → More → Developer Mode → enable your Nodus app. The seven nodus_* tools are now available.

Note: The HTTP server must be running before you open the chat. Memory is shared with the Claude Desktop instance (same SQLite database at ~/.nodus-mcp-server/data/memory.db).


Upgrading

Stop-Process -Name "nodus-mcp-server" -Force   # Windows — close before reinstalling
pipx install nodus-mcp-server --force

Then restart Claude Desktop / ChatGPT Desktop.

License

MIT

Ver o original no GitHub

Bom para

Relacionados