Nexus — MCP Aggregator with a Memory Layer

Nexus connects many MCP servers (Jira, GitHub, Postgres, …) behind a single MCP gateway, and (in a later phase) adds a memory layer so repeated or semantically similar tool calls are served from memory instead of re-invoking the underlying tools every time.

Status (v0.1): the aggregation layer, memory layer (per-tool TTL, semantic cache, gray-zone verifier), and encrypted secret storage (OS keychain) are built and tested. Memory caches cacheable (read-only/idempotent) tool results — exact-key and high-similarity hits serve with no tool call; misses forward and store. See Memory layer and Secrets.

📖 Full user guide & roadmap: docs/Nexus_Guide.md. 📚 Command handbook (every command/flag/transport): docs/Nexus_Handbook.md. 🧪 How to install, use, and test it: docs/Testing_Guide.md.

Shape (decided)

Nexus is an MCP gateway/proxy: it is itself an MCP server. A downstream client (Claude Desktop, Cursor, any MCP client) connects to Nexus; Nexus fans out to the child MCP servers you configure, merges their tools into one namespaced manifest, and forwards tools/call to the owning server.

• Runtime: local daemon + CLI. Config and (later) memory DB live in NEXUS_HOME (default ~/.nexus). Secrets via OS keychain in a later phase.
• Tool namespacing: <server>.<tool> (dots are allowed in MCP tool names, per SEP-986). Example: jira.get_issue, github.search.
• Live reload: adding/removing a server re-runs discovery and emits notifications/tools/list_changed.

Quick start

npm install
npm run typecheck      # tsc --noEmit
npm test               # unit + end-to-end (in-memory MCP transports)
npm run build          # → dist/index.js (the `nexus` binary)

Add a server from the curated catalog, then run the gateway:

# Catalog install (prompts for required env if missing)
nexus add memory                       # knowledge-graph MCP, no auth — good first test
nexus add github                      # errors until you pass GITHUB_PERSONAL_ACCESS_TOKEN
nexus add github --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx

# Freeform install (use `--` before dash-leading args like npx's -y)
nexus add mygit --transport stdio --command npx \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx -- -y @modelcontextprotocol/server-github

# Remote server
nexus add remotething --transport streamable-http --url https://example.com/mcp \
  --header Authorization=Bearer xyz

nexus list-servers                    # show configured child servers
nexus list-tools                      # connect live + print the merged manifest
nexus serve                           # run the MCP gateway on stdio

Point a client at it

Add Nexus to your MCP client config as a stdio server, e.g. for Claude Desktop:

{
  "mcpServers": {
    "nexus": { "command": "node", "args": ["/abs/path/to/nexus/dist/index.js", "serve"] }
  }
}

All child servers' tools then appear under the nexus.* (well, <server>.*) namespace in that client.

CLI reference

nexus serve                                  Run the MCP gateway over stdio
nexus list-servers [--json|-j]               Show configured child servers
nexus list-tools [--json|-j]                 Connect + show the merged tool manifest
nexus add <catalog-name> [--env K=V]...      Install from the curated catalog
nexus add <name> --transport <t> [...]       Freeform install (stdio|sse|streamable-http)
nexus remove <name>                          Remove a configured server
nexus help

All logs go to stderr; stdout is reserved for the MCP wire protocol while serving.

Project structure

src/
  aggregation/   connectionManager · discovery · namespace · manifest · registry
  config/        schema (zod) · store · catalog · paths
  server/        gateway.ts — Nexus-as-MCP-server (merged tools/list + tools/call)
  cli/           index (router) · commands
  types.ts · logging.ts · version.ts · index.ts (public API)
catalog/servers.json   curated install specs (extend at ~/.nexus/catalog.json)
tests/                 namespace · manifest · end-to-end (in-memory transports)

Key design notes (for contributors)

• Tool namespacing & routing: the merged tools/list rewrites each tool name to <server>.<original>. A separate route table maps each namespaced name back to (server, originalName) — the client never sees routing metadata.
• Cacheability seam: isCacheableTool(tool) derives from MCP annotations (readOnlyHint/idempotentHint → cacheable; destructiveHint → never). The memory layer will consume this; it is not used to filter the manifest.
• ConnectionManager supports stdio, sse, and streamable-http. Stdio child stderr is surfaced in Nexus logs. A transport factory is injectable for tests (see tests/registry.integration.test.ts).
• Validation: zod handles shape/defaults; transport-conditional rules (stdio needs command, remote needs url) live in validateServerConfig.

Memory layer

Opt-in. On nexus serve, enable it with one of:

• OPENAI_API_KEY → OpenAI text-embedding-3-small (1536-dim).
• NEXUS_EMBEDDING=hash → offline deterministic embedder (testing / air-gapped; not semantically meaningful).

With memory on, a tools/call to a cacheable tool (MCP annotations readOnlyHint/idempotentHint, not destructiveHint) is intercepted:

1. Exact args-fingerprint hit → served from memory, no child call (the fast path — no embedding needed).
2. Otherwise embed the call and run a nearest-neighbor search (sqlite-vec):
   • similarity ≥ 0.92 → served (semantic hit)
   • 0.85–0.92 → gray zone → an LLM verifier decides (accept serves cached; reject refetches). No verifier/key → refetch.
   • below → miss
3. Miss → forward to the child; store the result if it isn't an error.

Structurally distinct args (env:"staging" vs "production") have different fingerprints → separate entries, so the staging/production trap is avoided before similarity is even consulted.

Store: SQLite (~/.nexus/memory.db) + sqlite-vec, via Node's built-in node:sqlite (no native build). Removing a server drops its cache entries.

Per-tool TTL (entity snapshots)

By default cacheable results never expire (stable knowledge). Override volatile tools in ~/.nexus/config.json:

{
  "ttl": {
    "jira.get_issue": "1d",   // ticket status refreshes daily
    "github.*": "12h",        // all tools from a server
    "*": "30s"                // global fallback
  }
}

Precedence: exact <server>.<tool> > <server>.* > * > Infinity. Values are durations (30s, 5m, 12h, 1d, ms number) or never. Expired entries are refetched on next call.

Secrets

Secrets (tokens, API keys) are stored encrypted in the OS keychain — never in config.json. On nexus add:

• --env K=V → stored in the keychain (recorded as secretEnv in config).
• --plain-env K=V → plaintext in config (for non-secrets like base URLs).

At nexus serve, each server's secretEnv is resolved from the keychain and injected into the child's spawn env. nexus remove purges that server's secrets. If the OS keychain is unavailable, --env falls back to plaintext config with a warning.

Current limitations (deliberate, v0.1)

• TTL defaults to infinite — stable tools cache forever; volatile tools need an explicit override (above). No automatic "this tool looks time-sensitive" heuristic.
• No "serve stale + freshness signal" — expired entries are treated as misses (refetched), not returned with a staleness flag. This deviates from PRD §4.2's confirm-to-refetch flow, which doesn't fit a non-interactive gateway.
• LLM verifier needs a key — without OPENAI_API_KEY, gray-zone matches refetch (no verify).

See docs/Nexus_MCP_PRD.md for the full design rationale.