NEXUS MCP Agent

Agentic OS — Zero required API keys for core startup, optional tokens unlock private GitHub and external services.

An autonomous AI agent MCP server with 150+ tools for advanced reasoning, multi-agent orchestration, persistent memory, filesystem, git, workflows, security scanning, GitHub integration, and more.

Quick Start

Via npx (recommended)

Add to your MCP client configuration:

{
  "mcpServers": {
    "nexus": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {}
    }
  }
}

Global install

npm install -g nexus-mcp-agent

Then in your MCP config:

{
  "mcpServers": {
    "nexus": {
      "command": "nexus",
      "env": {}
    }
  }
}

For browser automation (optional)

npm install -g playwright
npx playwright install chromium

Tools (150+)

Core = 52 Qwen-tuned tools; 130+ extended tools lazy-load via tool_search / tool_load.

The authoritative live tool list is available through the nexus://tools resource.

🌐 Web (5 tools)

web_search, web_search_dashscope, web_fetch, web_scrape, url_extract web_search, web_fetch, web_scrape, url_extract

📁 Filesystem (6 tools)

fs_read, fs_write, fs_list, fs_search, fs_delete, fs_info

💻 Terminal (2 tools)

cmd_execute, cmd_spawn (real streaming via spawn)

🔀 Git (10 tools)

git_status, git_log, git_diff, git_branches, git_commit, git_clone, git_push, git_pull, git_checkout, git_add

🧠 Memory — Basic (5 tools)

mem_store, mem_recall, mem_list, mem_delete, mem_stats

🧠 Memory — Advanced (14 tools)

Episodic (store complete experiences): memory_episodic_store, memory_episodic_recall, memory_episodic_stats

Semantic (vector search): memory_semantic_store, memory_semantic_search, memory_semantic_list

Procedural (reusable how-to knowledge): memory_procedural_save, memory_procedural_find, memory_procedural_execute, memory_procedural_list

Knowledge Graph (entities and relationships): memory_kg_add_entity, memory_kg_add_relation, memory_kg_query, memory_kg_stats

🧠 Reasoning (5 tools)

reason_tot (Tree-of-Thought: explore multiple reasoning paths) reason_react (ReAct Loop: Think → Act → Observe) reason_plan (Plan-and-Execute: decompose and execute complex goals) reason_reflect (Reflection: analyze failures and generate corrections) reason_reflect_single (Quick correction for a single failure)

🤖 Multi-Agent Orchestration (5 tools)

agent_route (Route tasks to specialized agents) agent_pipeline (Sequential agent execution) agent_parallel (Concurrent agent execution) agent_fanout (Decompose + parallel execution) agent_hierarchical (Manager-worker delegation)

🎭 Agents (8 tools)

agent_catalog, agent_search, agent_load, agent_domains, agent_create, agent_delegate, agent_list, agent_delete

⚙️ System (4 tools)

sys_info, sys_env, sys_health, sys_echo

🛠️ Dev Intelligence (21 tools)

Workflows: workflow_create, workflow_execute, workflow_step_done, workflow_status, workflow_list Tasks: task_start, task_checkpoint, task_restore, task_list Skills: skill_save, skill_search, skill_load, skill_list, skill_crystalize Chains: chain_create, chain_execute, chain_step_done, chain_status, chain_list Review: review_code

🚀 Autopilot (4 tools)

autopilot_start (goal → persisted multi-step plan + auto-execution via bg_agent + checkpoints), autopilot_resume, autopilot_status, autopilot_cancel

📦 Sandbox (4 tools)

sandbox_run (isolated execution, use_docker: auto|on|off — Docker container when available, local fallback otherwise), sandbox_node, sandbox_python, sandbox_status

📊 Intelligence (6 tools)

status, status_loop_check, status_summarize, status_history, context_save, context_restore

💾 Session (5 tools)

session_save, session_auto_save, session_resume, session_list, session_restore

🧠 Context (3 tools)

context_summarize, context_trim, context_status

👁️ Vision (1 tool)

vision_analyze (Qwen-VL via DashScope, optional key)

📐 Project (4 tools)

project_analyze, project_scan, project_pack, project_suggest

🐙 GitHub (4 tools)

github_issues, github_pr, github_search, github_content (Set GITHUB_TOKEN env var for private repos)

🔒 Security (3 tools)

scan_secrets, scan_injection, scan_deps

🔌 MCP Connect (6 tools)

mcp_connect (stdio or HTTP(S)), mcp_servers, mcp_tools, mcp_call, mcp_disconnect, mcp_proxy_status (stdio commands are allowlisted — see NEXUS_ALLOWED_MCP_COMMANDS)

📦 Catalog (3 tools)

catalog_fetch, catalog_search, catalog_status

🌐 Browser Automation (3 engines, 17 tools)

Playwright (natif, headless, rapide) : browser_pw_navigate, browser_pw_screenshot, browser_pw_extract, browser_pw_status

Chrome DevTools MCP (Google, debugging, performance) : browser_devtools_navigate, browser_devtools_screenshot, browser_devtools_performance, browser_devtools_status

browser-act (anti-bot, stealth, multi-session) : browser_act_status, browser_act_navigate, browser_act_extract, browser_act_screenshot, browser_act_list, browser_act_state, browser_act_click, browser_act_input

🤖 Automation (6 tools)

browse, browse_status, browse_screenshot, browse_click, schedule, schedule_list

Resources (9)

nexus://info, nexus://filesystem/{path}, nexus://memory, nexus://project, nexus://system, nexus://workflows, nexus://skills, nexus://tasks, nexus://tools

Prompts (7)

prompt_nexus_system, prompt_code_review, prompt_debug, prompt_audit, prompt_setup, prompt_skill_crystalize, prompt_plan

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | NEXUS_DATA_DIR | Where to store state files | ~/.nexus/ | | WORKSPACE_DIR | Default workspace path | process.cwd() | | NEXUS_ALLOWED_DIRS | Semicolon/comma-separated allowlist for filesystem access | workspace + home | | NEXUS_ALLOW_OUTSIDE_WORKSPACE | Set to 1 to allow filesystem access outside the workspace without an explicit allowlist entry | unset | | NEXUS_ALLOW_SHELL | Set to 1 to explicitly allow shell execution for cmd_*, bg_*, agent_loop | 0 | | NEXUS_ALLOWED_ENV | Comma-separated allowlist for extra environment variables readable via sys_env | safe defaults only | | NEXUS_ALLOWED_MCP_COMMANDS | Semicolon/comma-separated allowlist for extra MCP server commands (mcp_connect stdio) | common local commands | | NEXUS_TOOL_TIMEOUT_MS | Global anti-hang timeout per tool call (long-running tools get 20 min) | 120000 | | NEXUS_LOG_FILE | Optional log file path (redacted secrets, 5 MiB rotation) | none (stderr only) | | NEXUS_STDOUT_GUARD | Set to 0 to disable the stdout JSON-RPC purity guard | 1 (enabled) | | NEXUS_CONTEXT_COMPACT | Set to 1 to use reduced context defaults (project_pack ~12K tokens, tighter summarize/trim windows) | unset | | NEXUS_CONTEXT_TRACK | Set to 0 to disable context history tracking | 1 (enabled) | | NEXUS_REASONING | native (default, Qwen reasons itself — simulated reason_* tools stay lazy) or simulated (restore reason_* as core tools) | native | | DASHSCOPE_API_KEY | Optional DashScope key enabling vision_analyze (Qwen-VL) and web_search_dashscope (Qwen integrated search) | none | | NEXUS_VISION_MODEL | Vision model used by vision_analyze | qwen-vl-max | | NEXUS_SEARCH_MODEL | Model used by web_search_dashscope | qwen3-max | | GITHUB_TOKEN | GitHub API token for private repos (github_*, cicd_*) | none | | GH_TOKEN | Alias for GITHUB_TOKEN | none | | DEFAULT_LLM_PROVIDER | LLM provider (informational, for agent tooling) | ollama | | DEFAULT_LLM_MODEL | Default model (informational, for agent tooling) | qwen2.5-coder:7b |

Features

• Zero required API keys — starts instantly for local/core workflows; optional tokens unlock private GitHub and external services
• Qwen3.8-Max ready — cache-aware stable prefix, context sliding window, token-budgeted project packing, native reasoning passthrough, optional Qwen-VL vision & integrated web search
• Advanced reasoning — Tree-of-Thought, ReAct loops, Plan-and-Execute, Reflection (legacy/lazy by default — Qwen reasons natively)
• Multi-agent orchestration — Route, pipeline, parallel, fanout, and hierarchical agent coordination
• Autopilot missions — persisted multi-step goals with checkpoints, resume after restart
• Isolated sandbox — run code in Docker containers when available, local fallback otherwise
• MCP proxy — connect to external MCP servers over stdio or HTTP(S) and call their tools
• Persistent memory — Episodic, semantic (vector search), procedural, and knowledge graph
• Workflow engine — DAG-based multi-step execution with checkpoints
• Skill crystallization — learn from experience, reuse patterns
• Agent chains — pipeline multiple AI agents in sequence
• Anti-loop detection — detects and warns about repeated tool calls
• Security scanning — find secrets, injection risks, and vulnerable deps
• MCP proxy — connect to other MCP servers and use their tools
• Cross-platform — works on Windows, macOS, and Linux
• Session save/restore — persist entire state (memory, workflows, tasks) to disk
• Triple browser engine — Playwright (fast), Chrome DevTools (debug/performance), browser-act (anti-bot/stealth)
• 100% free browser automation — no API keys required for any browser engine
• Rate monitoring — sliding window rate tracker warns on excessive tool usage (120 RPM default)
• Circuit breaker — automatically stops calling failing tools after 3 consecutive errors, resets after 30s
• Fully async I/O — all memory operations are async, never block the event loop on long sessions

Security model

NEXUS keeps agent autonomy while avoiding unsafe shell patterns by default:

• cmd_execute, cmd_spawn, and bg_start parse command strings into executable + arguments instead of running a shell.
• Shell mode is disabled unless NEXUS_ALLOW_SHELL=1 is set explicitly.
• Filesystem tools resolve paths against allowed roots (WORKSPACE_DIR, current directory, home, and NEXUS_ALLOWED_DIRS).
• sys_env only exposes safe environment variables unless NEXUS_ALLOWED_ENV explicitly allows more.
• Tool history redacts secrets before writing .nexus/tool_history.json.
• mcp_connect only allows common local MCP commands unless NEXUS_ALLOWED_MCP_COMMANDS adds more.
• Persistence uses atomic JSON writes for core state files.

Qwen3.8-Max cache-aware mode (v1.7.0)

Qwen3.8-Max bills input tokens per call, but a byte-identical prefix is cached across calls in the same session — hitting the cache drops input cost by up to −90%. NEXUS is designed to maximize that hit rate:

• Stable system prefix: use prompt_nexus_system and pin its output verbatim at the start of every conversation. It never contains timestamps, paths, or other dynamic content, so the cache always matches.
• Context tools: context_summarize / context_trim keep the window tight during long agent loops — smaller working set, higher cache hit rate.
• Compact mode: set NEXUS_CONTEXT_COMPACT=1 to cut defaults — project_pack targets ~12K tokens instead of 28K, summarize/trim keep fewer entries.
• Token-aware packing: project_pack reports its own size (chars/4 ≈ tokens) so you can size prompts deliberately instead of overflowing.

Cost rule of thumb: keep the prefix short but identical, and compress the middle — never the prefix. A 500-token stable prefix + cache ≈ 50 billed tokens per subsequent call.

Qwen3.8-Max adaptation (v1.7.0)

NEXUS is tuned for Qwen3.8-Max's ~1M context and native capabilities:

• Cache-aware prompting (see above): stable prompt_nexus_system prefix, context tools, compact mode.
• Context management: context_summarize (compress older history into a summary block), context_trim (hard drop), context_status — persisted in ~/.nexus/context.json. Run context_summarize every ~30 tool calls to keep the window tight.
• Project packing: project_pack returns a token-budgeted tree + key files (default 28K tokens, 12K with NEXUS_CONTEXT_COMPACT=1).
• Native reasoning: Qwen3.8-Max reasons natively, so the simulated reason_plan / reason_react / reason_reflect / reason_tree_of_thought loops are legacy: lazy-loadable but not core. Set NEXUS_REASONING=simulated to restore them for models without native reasoning.
• Multimodal: vision_analyze sends a local image, URL, or data: URI to Qwen-VL (DashScope OpenAI-compatible API, DASHSCOPE_API_KEY). browse_screenshot already returns data:image/jpeg;base64,... — feed it straight into vision_analyze.
• Web search: web_search (DuckDuckGo, no key) stays the default; web_search_dashscope uses Qwen's integrated search when DASHSCOPE_API_KEY is present.

Phase C expansion (v1.8.0)

• Autopilot missions: autopilot_start turns a goal into a persisted multi-step plan executed through bg_agent, with checkpoints and crash-safe resume (autopilot_resume after restart). Interrupted missions auto-heal: steps are re-run idempotently, not lost.
• Real multi-agent tools: agent_pipeline, agent_parallel, agent_fanout (N parallel workers via background tasks, {index} templating), and agent_hierarchical now execute real work (managed sessions, status/aggregate actions) instead of canned text. reason_plan, reason_react, reason_reflect, reason_tot are fully functional with bug fixes (nil dependsOn, reflection thresholds).
• Docker sandbox: sandbox_run executes code in an isolated container (docker run --rm --network none, node:22-alpine / python:3.12-alpine) when Docker is available; use_docker: auto|on|off controls it, sandbox_status reports Docker presence.
• Skill crystallization: skill_crystalize turns a solved task into a reusable structured skill (prompt template + tools + pattern, persisted in skills.json); 3 example skills are seeded on first run and shown in catalog_status.
• Wider MCP proxy: mcp_connect now supports HTTP(S) transports (transport="http" url="http://host:port/mcp") in addition to stdio; new mcp_proxy_status gives the full proxy health view (transports, endpoints, tool counts).

Phase D rebuild (v2.0.0)

• Core/extended split: 36 plugins classified (core = validated modules: fs, shell, git, memory, bg, session, web, vision, autopilot, sandbox, MCP proxy... ; extended = the rest, documented, still lazy-loadable). Zero fake tools — every tool runs real code or returns an honest error.
• Single source of truth: src/core/tool-manifest.ts snapshots the live SDK registry at startup (tools/list is the only truth). No hardcoded tool lists or counts anywhere — verified by tests.
• Comprehensive tests: 142 unit + integration tests (memory CRUD, session lifecycle, bg tasks, autopilot, sandbox, MCP proxy HTTP, registry coherence...) and npm test now includes the full E2E MCP harness.
• CI/CD: .github/workflows/ci.yml (typecheck → unit → build → E2E → Windows exe build+E2E) and release.yml (tag v* → npm publish + GitHub Release with nexus-server.exe).
• Docs: complete env-var table, docs/man.md (usage exe/npx/HTTP, CLI flags, troubleshooting), docs/qwen-tuning.md (Qwen3.8-Max cache/context/cost tuning).

Windows shell fix (v2.0.1)

• Shell resolution: cmd_execute/cmd_spawn/bg_start now resolve the best available Windows shell (pwsh first — supports &&/|| — then powershell.exe, then cmd.exe) instead of hardcoding powershell.exe, which broke && chains on PowerShell 5.1 and failed when powershell.exe was not on the client's PATH.
• Test stability: vitest now runs files sequentially with a 60s timeout (integration tests spawn real OS processes); fixed a restart race in the autopilot test (wait for disk persistence before reload). Suite is 144/144, stable across repeated runs.

Reliability (v1.7.0)

• Mono-binary: npm run build:exe produces nexus-server.exe (Bun-compiled) that runs with zero Node/npm/npx on the machine — immune to stale-global/npx-resolution failures. Run it directly from any MCP client.
• STDOUT Guardian: only well-formed JSON-RPC lines may reach stdout; stray writes are blocked and logged to stderr, so the MCP channel can never be corrupted.
• Global tool timeout: every tool call is guarded (NEXUS_TOOL_TIMEOUT_MS, default 120s; long-running tools get 20min). Runaway calls return a structured error instead of hanging the session.
• Input guard: frames over 1 MiB are rejected with -32000; requests before initialize get -32002 per spec.
• Write-Ahead Journal: background tasks and tool history are journaled to *.wal + compacted into snapshots, so a crash between writes never loses state.
• Redaction + rotation: logs redact API keys/tokens (incl. DASHSCOPE_API_KEY, Bearer); optional NEXUS_LOG_FILE with 5 MiB rotation.

Metrics & Monitoring

NEXUS includes built-in middleware for long-running sessions:

• Rate Monitor: sliding 60s window per tool, logs a warning at 120+ calls/minute. Does not block — observes and warns.
• Circuit Breaker: after 3 consecutive failures on any tool, it returns a graceful error message instead of calling the tool again. Resets automatically after 30s of no failures.
• Tool History: all tool calls are recorded into tool_history.json with timestamps, arguments (redacted), and success/failure status. Access via status_history tool.
• Global Timeout: any tool exceeding NEXUS_TOOL_TIMEOUT_MS (default 120s, 20min for long-running tools) is aborted with a structured error instead of hanging the connection.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    NEXUS MCP Server                          │
├─────────────────────────────────────────────────────────────┤
│  Middleware Layer                                            │
│  ├─ Rate Monitor (120 RPM per tool)    ├─ Circuit Breaker   │
│  └─ Call Logging + Metrics Collection                       │
├─────────────────────────────────────────────────────────────┤
│  Plugin Registry (auto-discover 27 tool modules)            │
├─────────────────────────────────────────────────────────────┤
│  Reasoning Layer                                            │
│  ├─ Tree-of-Thought    ├─ ReAct Loop                        │
│  ├─ Plan-and-Execute   └─ Reflection                        │
├─────────────────────────────────────────────────────────────┤
│  Multi-Agent Orchestration                                  │
│  ├─ Router             ├─ Pipeline                          │
│  ├─ Parallel           └─ Hierarchical                      │
├─────────────────────────────────────────────────────────────┤
│  Advanced Memory (fully async I/O)                          │
│  ├─ Episodic             ├─ Semantic (Vector DB)            │
│  ├─ Procedural           └─ Knowledge Graph                 │
├─────────────────────────────────────────────────────────────┤
│  Core Tools                                                 │
│  ├─ Filesystem    ├─ Git       ├─ Terminal    ├─ Web        │
│  ├─ GitHub        ├─ Security  ├─ Agents      └─ System     │
├─────────────────────────────────────────────────────────────┤
│  Dev Intelligence                                           │
│  ├─ Workflows     ├─ Tasks     ├─ Skills      ├─ Chains     │
│  └─ Session Save/Restore                                    │
└─────────────────────────────────────────────────────────────┘

License

MIT