MCP Nexus

MCP Nexus ist ein lokaler, intelligent arbeitender Router für das Model Context Protocol. Deine KI-Umgebung verbindet sich mit einem einzigen MCP-Endpunkt — Nexus — während Nexus alle deine echten MCP-Server im Hintergrund verwaltet: Es indexiert deren Tools, entdeckt Fähigkeiten bei Bedarf, startet Server verzögert, führt geroutete Aufrufe aus und lernt aus lokaler Nutzung, um Ergebnisse im Laufe der Zeit besser zu ranken.

Before                                With MCP Nexus

AI Harness                            AI Harness
  ├── GitHub MCP   (30 tools)           └── mcp-nexus (4 control tools)
  ├── Jira MCP      (25 tools)              ├── search_capabilities
  ├── Slack MCP     (20 tools)              ├──── describe_capabilities
  ├── Figma MCP     (18 tools)              ├──── execute_capability
  ...                                   └──── search_servers
  ~90+ tool schemas in context                  │
                                     (everything else stays indexed
                                      on disk until actually needed)

Warum

Jeder verbundene MCP-Server trägt Tool-Schemas zum Kontext des Modells bei. Nach zehn Servern verbrennst du zig Tausende Tokens für Definitionen, die das Modell selten nutzt, und die Qualität der Tool-Auswahl nimmt ab.

Nexus dreht das Modell um: Statt jedes nachgelagerte Schema in den Kontext zu schieben, hält Nexus einen schlanken Fähigkeitsindex auf der Festplatte und stellt eine winzige Steuerungsebene bereit. Der Agent entdeckt Fähigkeiten bei Bedarf (search_capabilities), prüft exakte Schemas nur für das, was er ausgewählt hat (describe_capabilities), und führt über Nexus aus (execute_capability). Der gesamte Zustand — Konfiguration, Index, Analysen, gelernte Sequenzen — liegt lokal in .mcp-nexus/.

Related MCP server: Master MCP Server

Schnellstart

# 1. Scaffold a project config
npx @fyrlabs/mcp-nexus init

# 2. Add downstream MCP servers (anything runnable over stdio)
npx @fyrlabs/mcp-nexus add github -- npx -y @modelcontextprotocol/server-github
#    or import an existing config:
npx @fyrlabs/mcp-nexus import --from claude

# 3. Point your harness at Nexus (see docs/harness-setup.md)

Konfiguration der Umgebung (Claude Code, Cursor, Codex und andere MCP-Clients):

{
  "mcpServers": {
    "mcp-nexus": {
      "command": "npx",
      "args": ["-y", "@fyrlabs/mcp-nexus"]
    }
  }
}

Nexus findet project-mcp.json automatisch, indem es vom Arbeitsverzeichnis aus nach oben geht, oder du übergibst --config ./path/to/nexus.json.

Dann, aus Sicht des Agents:

search_capabilities  { "query": "find comments people left on my PR" }
→ github.review_comments.list  score=0.94 ...

describe_capabilities { "capabilityIds": ["github.review_comments.list"] }
→ exact input schema

execute_capability   { "capabilityId": "github.review_comments.list",
                       "arguments":  { ... } }
→ forwarded verbatim to the right server, started on demand

Was offengelegt wird vs. was verborgen bleibt

Highlights

• Lokal zuerst. Kein Cloud-Dienst, kein Konto, keine Telemetrie. Lösche .mcp-nexus/ und der gesamte gelernte Zustand ist weg.

• Verzögerter Lebenszyklus. Nachgelagerte Server starten nur, wenn eine Aufgabe sie braucht, und stoppen nach abgestuften Inaktivitäts-Timeout (heiß / warm / kalt).

• Hybride Suche. BM25-lexikalisches Ranking über gewichtete Felder, exakte id/tool-Übereinstimmung, Alias-Erweiterung (pr → pull request, konfigurierbar) und ein steckbares EmbeddingProvider-Interface für optionale semantische Ebenen.

• Adaptives Ranking mit Erklärungen. Jedes Ergebnis trägt seine Signal-Aufschlüsselung; gepinnte Fähigkeiten übertreffen gelernte Beliebtheit; blockierte Fähigkeiten werden nie vorgeschlagen.

• Sequenzvorhersage. Wiederholte Tool-Übergänge werden lokal gelernt und genutzt, um wahrscheinliche nächste Fähigkeiten zu verstärken — Vorhersage führt nie automatisch aus.

• Null native Abhängigkeiten. Speicherung nutzt Node's eingebautes node:sqlite; die Installation dieses Pakets kompiliert nie etwas.

• Umgebungsunabhängig. Alles, was MCP stdio spricht, kann vor Nexus sitzen.

Anforderungen

• Node.js >= 22.5 (24 LTS empfohlen)

Dokumentation

• Konfigurationsreferenz — jedes Feld, Auflösungsreihenfolge, Umgebungs-Substitution

• CLI-Referenz — alle Befehle und Flags

• Architektur — Module, Scoring-Modell, Speicherschema

• Umgebungs-Setup — Claude Code, Cursor, Codex, generische MCP-Clients

• examples/project-mcp.json — kommentierte Startkonfiguration

Entwicklung

git clone https://github.com/fyrlabs/mcp-nexus && cd mcp-nexus
npm install
npm run build       # tsc -> dist/
npm run test        # vitest (unit + integration, mirrors src/ structure under src/tests/)
npm run typecheck   # strict tsc, no emit
npm run lint        # eslint

Integrationstests starten das echte @modelcontextprotocol/server-everything-Paket als nachgelagerten stdio-Server und führen Ausführungen durch eine vollständige Laufzeit aus — sie überspringen automatisch, wenn das Paket nicht aufgelöst werden kann.

Siehe AGENTS.md für Beitragskonventionen (Commits, Versionierung, Struktur).

Datenschutz

Nexus speichert Konfigurations-Caches, Indizes und Analysen in .mcp-nexus/ (oder deinem XDG-Datenverzeichnis). Nichts wird vom Router selbst irgendwohin gesendet. Wenn du einen externen Embedding-Anbieter konfigurierst, werden nur Fähigkeitstexte (Titel/Beschreibungen/Schlüsselwörter) dorthin gesendet — nie Argumente, Geheimnisse oder Analysen. Rohe Tool-Argumente werden nie gespeichert.

Lizenz

Apache-2.0