# NEXUS — God-Tier MCP Server for Agentic Coding Agents

**The most powerful, advanced, and robust MCP server for CLI coding agents.**

NEXUS gives your AI coding agent capabilities it structurally lacks:
deep code understanding, change-impact awareness, persistent memory,
engineered context, verified execution, and deterministic orchestration.

> **32 tools · 10 families · 20+ languages · zero native dependencies**

---

## Quick Install (Cline CLI / Claude Desktop / Cursor / etc.)

```bash
git clone https://github.com/Senpai-Sama7/nexus-mcp-server.git
cd nexus-mcp-server
npm install
npm run build

# Install MCP config for all detected clients (Cline CLI, Claude Desktop, Cursor, Windsurf, Gemini, OpenCode)
./install-mcp.sh /path/to/project1 /path/to/project2
```

The `install-mcp.sh` script writes a `cline_mcp_settings.json` (and equivalents for other clients) that registers one NEXUS MCP server instance per workspace. Each instance points at a different `NEXUS_WORKSPACE` so you get a separate code index per project.

---

## Manual Configuration

### Cline CLI (`~/.cline/cline_mcp_settings.json`)
```json
{
  "mcpServers": {
    "nexus": {
      "command": "node",
      "args": ["/path/to/nexus-mcp-server/dist/server.js"],
      "env": { "NEXUS_WORKSPACE": "/path/to/your/project" },
      "disabled": false
    },
    "nexus-other-project": {
      "command": "node",
      "args": ["/path/to/nexus-mcp-server/dist/server.js"],
      "env": { "NEXUS_WORKSPACE": "/path/to/another/project" },
      "disabled": false
    }
  }
}
```

### Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS)
Same `mcpServers` format as above.

### Cline VSCode extension
`~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` — same format.

### Claude Code (`.mcp.json` in your project root)
```json
{
  "mcpServers": {
    "nexus": {
      "command": "node",
      "args": ["./nexus-mcp-server/dist/server.js"],
      "env": { "NEXUS_WORKSPACE": "${workspaceFolder}" }
    }
  }
}
```

---

### OpenCode (`~/.config/opencode/opencode.jsonc`)
OpenCode uses a different MCP schema — `mcp` keyed by server name, `command`
as an array, environment under `environment`, plus `enabled`/`timeout`:

```jsonc
{
  "mcp": {
    "nexus": {
      "type": "local",
      "command": ["node", "/path/to/nexus-mcp-server/dist/server.js"],
      "environment": {
        "NEXUS_WORKSPACE": "/path/to/your/project",
        "NEXUS_LOG_LEVEL": "info"
      },
      "enabled": true,
      "timeout": 15000
    },
    "nexus-other-project": {
      "type": "local",
      "command": ["node", "/path/to/nexus-mcp-server/dist/server.js"],
      "environment": {
        "NEXUS_WORKSPACE": "/path/to/another/project",
        "NEXUS_LOG_LEVEL": "info"
      },
      "enabled": true,
      "timeout": 15000
    }
  }
}
```

### Gemini CLI (`~/.gemini/settings.json`)
Same `mcpServers` shape as Cline CLI:

```json
{
  "mcpServers": {
    "nexus": {
      "command": "node",
      "args": ["/path/to/nexus-mcp-server/dist/server.js"],
      "env": { "NEXUS_WORKSPACE": "/path/to/your/project", "NEXUS_LOG_LEVEL": "info" }
    },
    "nexus-other-project": {
      "command": "node",
      "args": ["/path/to/nexus-mcp-server/dist/server.js"],
      "env": { "NEXUS_WORKSPACE": "/path/to/another/project", "NEXUS_LOG_LEVEL": "info" }
    }
  }
}
```

### Cursor (`~/.cursor/mcp.json`)
### Windsurf (`~/.codeium/windsurf/mcp_config.json`)
Both use the same `mcpServers` format as Cline CLI above.

---

## Why NEXUS?

Every current coding agent has 10 structural gaps. NEXUS fills all 10:

1. Agents read raw text → **NEXUS builds a semantic symbol/reference/dependency graph**
2. Agents edit blind → **NEXUS computes blast radius before changes**
3. Agents forget everything between sessions → **NEXUS persists namespaced memory**
4. Agents fetch context greedily → **NEXUS ranks and budgets context (repo map, context packs)**
5. Agents can't verify structurally → **NEXUS parses test/lint/typecheck output into structured diagnostics**
6. Agents do serial work → **NEXUS runs deterministic parallel fan-out + persistent task DAGs**
7. Agents leak secrets / touch sensitive files → **NEXUS scans, jails, and warns**
8. Agents get huge unreadable tool dumps → **NEXUS paginates with cursors + head/tail truncation**
9. Agents lose state on crash → **NEXUS snapshots files and checkpoints task state**
10. Agents can't see the project at a glance → **NEXUS workspace health + map on demand**

---

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `NEXUS_WORKSPACE` | `process.cwd()` | Workspace root (the jail boundary) |
| `NEXUS_LOG_LEVEL` | `info` | One of: `debug`, `info`, `warn`, `error`, `silent` |

---

## The 32 Tools

### A. Workspace (3)
- `nexus_workspace_overview` — languages, LOC, git state, index health
- `nexus_search` — regex/literal/glob content search
- `nexus_read_span` — line-range read with encoding + injection detection

### B. Code Intelligence (6)
- `nexus_index_build` — build/refresh the code index
- `nexus_file_symbols` — symbol outline of a file
- `nexus_find_symbols` — fuzzy workspace-wide symbol search
- `nexus_references` — all reference sites of a symbol
- `nexus_call_graph` — callers/callees, depth-N
- `nexus_dependency_graph` — import graph: deps / dependents

### C. Context Engineering (2) ⭐
- `nexus_repo_map` — **ranked repo map within a token budget** (Aider-style)
- `nexus_context_pack` — task-focused context bundle

### D. Change Safety (4)
- `nexus_impact_analysis` — blast radius before editing
- `nexus_git_diff` — smart diff with stats + paginated hunks
- `nexus_snapshot` / `nexus_restore` — checkpoint and rollback

### E. Execution & Verification (4)
- `nexus_exec` — run commands with timeout + secret redaction
- `nexus_exec_poll` — poll/kill background jobs
- `nexus_test_run` — detect framework (jest/vitest/pytest/cargo/go) → structured failures
- `nexus_diagnose` — tsc/eslint → parsed `{file, line, col, severity, rule, message}`

### F. Memory (3)
- `nexus_memory_write` / `nexus_memory_search` / `nexus_memory_forget` — persistent knowledge

### G. Orchestration (4)
- `nexus_task_submit` / `nexus_task_update` / `nexus_task_status` — DAG task management
- `nexus_fanout` — parallel map with concurrency limit

### H. Security & Hygiene (2)
- `nexus_secret_scan` — scan for AWS/GitHub/OpenAI/JWT/keys
- `nexus_audit_manifest` — dependency risk heuristics (typosquat, unpinned)

### I. Refactor (1)
- `nexus_rename_symbol` — dry-run-by-default, graph-scoped, identifier-aware rename.
  Never matches inside strings or comments. `apply:true` writes the changes and
  first takes a snapshot, so `nexus_restore <snapshotId>` reverts the rename.

### J. Meta (3)
- `nexus_server_status` — self-diagnostics
- `nexus_guide` — on-demand playbook for workflows
- `nexus_audit_log` — read the record of destructive operations performed

---

## Safety model — what is and isn't guaranteed

Read this before granting NEXUS write or exec access.

**Enforced:**
- **Path jail.** Every filesystem touch resolves symlinks and must land inside
  the workspace root. Caller-supplied path lists (including `nexus_secret_scan`'s
  `paths` and `nexus_rename_symbol`'s `file`) are jailed; rejected paths are
  reported, not silently skipped.
- **Sensitive files.** `.env*`, `*.pem`, `*.key`, `id_rsa*`, `credentials*` and
  similar are blocked for reads without `allowSensitive:true`, and are never
  written.
- **Dry run by default** on the tools that can destroy work: `nexus_rename_symbol`
  (`apply:false`) and `nexus_memory_forget` (`dryRun:true`). `nexus_restore`
  accepts `dryRun:true` to preview.
- **Checkpoints are honest.** `nexus_snapshot` reports every file it could NOT
  capture (binary, oversized, unreadable) in `skipped[]`. A rename refuses to
  apply if any target could not be checkpointed, so an applied change is always
  reversible.
- **Audit trail.** Destructive operations are appended to `.nexus/audit.log`.

**Explicitly NOT guaranteed:**
- **The dangerous-command filter is a guardrail, not a sandbox.** It blocks
  common catastrophic shapes (`rm -rf` against absolute/home/parent paths,
  `mkfs`, `dd` to devices, fork bombs, curl-pipe-to-shell, force pushes,
  `git reset --hard`). It cannot stop an obfuscated command. Do not rely on it
  as a security boundary — it exists to catch accidents.
- **The audit log is evidence, not proof.** Anything that can write the
  workspace can rewrite `.nexus/audit.log`. It is not a tamper-evident ledger.
- **Parsing is lexical, not a real parse.** See the parser note below.

## Known limitations

- **No tree-sitter backend.** All 20+ languages are handled by pure-JS lexical
  tokenizers with comment/string masking. This is accurate enough for symbol
  outlines, import graphs, and ranked repo maps, but it is heuristic: heavy
  macro use, unusual generics, and dynamically-constructed names will be missed.
  Every file reports `parseBackend: 'lexical'`.
- **Ambiguity is surfaced, not resolved.** `nexus_call_graph` and
  `nexus_impact_analysis` return an `AMBIGUOUS_SYMBOL` error listing candidates
  rather than guessing which `log` you meant. Pass a `file::qualname` to
  disambiguate.
- **`nexus_search` re-reads files from disk** on each call; content is not
  indexed. Fine at repo scale, slower on very large trees.
- **`nexus_audit_manifest` covers npm, PyPI, Go, and Cargo** manifests with
  heuristics (unpinned versions, non-registry sources, typosquat edit-distance
  against a popular-package list). It is not a CVE scanner.

---

## Recommended Workflows

### New Feature
```
1. nexus_workspace_overview
2. nexus_repo_map
3. nexus_context_pack focusFiles:[...]
4. nexus_dependency_graph file:...
5. nexus_snapshot (checkpoint)
6. Implement (using nexus_read_span, nexus_search)
7. nexus_test_run + nexus_diagnose
8. nexus_secret_scan
9. nexus_memory_write (record decisions)
```

### Refactor
```
1. nexus_index_build force:true
2. nexus_find_symbols name:"oldName"
3. nexus_impact_analysis target:"oldName" mode:"symbol"
4. nexus_snapshot
5. nexus_rename_symbol (preview!)
6. nexus_test_run
```

### Debug
```
1. nexus_diagnose
2. nexus_test_run
3. nexus_search pattern:"error message"
4. nexus_call_graph symbol:... direction:callers
5. nexus_memory_write (record the fix)
```

---

## Architecture Highlights

- **Zero native dependencies** — pure JS regex-based parser works on any platform
- **20+ languages supported** — TS/JS/Python/Go/Rust/Java/C/C++/C#/Ruby/PHP/Swift/Kotlin/Lua/Shell/...
- **Path jail** — every file op goes through symlink-resolved boundary check
- **Sensitive file protection** — `.env`, keys, credentials blocked by default
- **Indirect prompt injection guard** — file contents/command outputs scanned for attack patterns
- **Secret redaction** — 15+ detectors (AWS, GitHub, OpenAI, Anthropic, JWT, etc.)
- **Process-group kill** — timeouts kill entire process trees, no leaks
- **Atomic persistence** — tmp-file + rename for index, memory, snapshots
- **LRU memory caps** — never unbounded growth
- **Tool annotations** — truthful `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`
- **Multi-workspace** — run multiple NEXUS instances, each indexing a different project

---

## Testing

```bash
npm run test:client
```

Validates all 32 tools via the full JSON-RPC protocol end-to-end, including regression checks for the path jail, rename-apply, and dry-run gates. **100% pass rate.**

---

## License

MIT