Fast Context MCP

KI-gestützte semantische Codesuche als MCP-Tool – basierend auf Windsurfs reverse-engineertem SWE-grep-Protokoll.

Jeder MCP-kompatible Client (Claude Code, Claude Desktop, Cursor usw.) kann damit Codebasen mit natürlichsprachlichen Abfragen durchsuchen. Alle Tools werden über npm gebündelt – keine Systemabhängigkeiten erforderlich (ripgrep über @vscode/ripgrep, tree über tree-node-cli). Funktioniert unter macOS, Windows und Linux.

So funktioniert's

You: "where is the authentication logic?"
         │
         ▼
┌─────────────────────────┐
│  Fast Context MCP       │
│  (local MCP server)     │
│                         │
│  1. Maps project → /codebase
│  2. Sends query to Windsurf Devstral API
│  3. AI generates rg/readfile/tree commands
│  4. Executes commands locally (built-in rg)
│  5. Returns results to AI
│  6. Repeats for N rounds
│  7. Returns file paths + line ranges
│     + suggested search keywords
└─────────────────────────┘
         │
         ▼
Found 3 relevant files.
  [1/3] /project/src/auth/handler.py (L10-60)
  [2/3] /project/src/middleware/jwt.py (L1-40)
  [3/3] /project/src/models/user.py (L20-80)

Suggested search keywords:
  authenticate, jwt.*verify, session.*token

Related MCP server: code-rag

Voraussetzungen

• Node.js >= 18

• Windsurf-Konto – kostenlose Stufe funktioniert (für API-Schlüssel erforderlich)

ripgrep muss nicht installiert werden – es wird über @vscode/ripgrep gebündelt.

Installation

Option 1: npm (empfohlen)

# Latest stable release
npm install @sammysnake/fast-context-mcp

# Or beta/next release
npm install @sammysnake/fast-context-mcp@next

Option 2: Aus dem Quellcode

git clone https://github.com/SammySnake-d/fast-context-mcp.git
cd fast-context-mcp
npm install

Einrichtung

1. Holen Sie sich Ihren Windsurf/Devin-API-Schlüssel

Der Server extrahiert den API-Schlüssel automatisch aus Devin CLI/Desktop oder einer älteren Windsurf-Installation. Sie können nach der Einrichtung auch das MCP-Tool extract_windsurf_key verwenden oder WINDSURF_API_KEY manuell setzen.

Desktop-Anmeldedaten werden in dieser Reihenfolge erkannt: Devin, älteres Deviv, dann Windsurf.

Unter WSL/Linux prüft der Server zuerst die Devin-CLI-Anmeldedaten unter ~/.local/share/devin/credentials.toml. Wenn ein unter Windows extrahierter Schlüssel in WSL einen 403-Fehler zurückgibt, führen Sie devin login in WSL aus und versuchen Sie es erneut.

2. MCP-Client konfigurieren

Claude Code

Fügen Sie zu ~/.claude.json unter mcpServers hinzu:

{
  "fast-context": {
    "command": "npx",
    "args": ["-y", "--prefer-online", "@sammysnake/fast-context-mcp"],
    "env": {
      "WINDSURF_API_KEY": "sk-ws-01-xxxxx"
    }
  }
}

Für Beta/Next-Release:

{
  "fast-context": {
    "command": "npx",
    "args": ["-y", "--prefer-online", "@sammysnake/fast-context-mcp@next"],
    "env": {
      "WINDSURF_API_KEY": "sk-ws-01-xxxxx"
    }
  }
}

Claude Desktop

Fügen Sie zu claude_desktop_config.json unter mcpServers hinzu:

{
  "fast-context": {
    "command": "npx",
    "args": ["-y", "--prefer-online", "@sammysnake/fast-context-mcp"],
    "env": {
      "WINDSURF_API_KEY": "sk-ws-01-xxxxx"
    }
  }
}

Für Beta/Next-Release:

{
  "fast-context": {
    "command": "npx",
    "args": ["-y", "--prefer-online", "@sammysnake/fast-context-mcp@next"],
    "env": {
      "WINDSURF_API_KEY": "sk-ws-01-xxxxx"
    }
  }
}

Wenn WINDSURF_API_KEY weggelassen wird, erkennt der Server ihn automatisch aus Ihrer lokalen Windsurf-Installation.

Umgebungsvariablen

Verfügbare Modelle

Das Modell kann durch Setzen von WS_MODEL geändert werden (siehe Umgebungsvariablen oben).

Standard: MODEL_SWE_1_6_FAST – schnellste Geschwindigkeit, umfangreichste grep-Schlüsselwörter, feinste Granularität der Fundstellen.

MCP-Tools

fast_context_search

KI-gestützte semantische Codesuche mit einstellbaren Parametern.

Rückgabewerte:

1. Relevante Dateien mit Zeilenbereichen

2. Vorgeschlagene Suchschlüsselwörter (während der KI-Suche verwendete rg-Muster)

3. Diagnose-Metadaten ([config]-Zeile, die die tatsächlich verwendete tree_depth, die Baumgröße und das Auftreten eines Fallbacks anzeigt)

Beispielausgabe:

Found 3 relevant files.

  [1/3] /project/src/auth/handler.py (L10-60, L120-180)
  [2/3] /project/src/middleware/jwt.py (L1-40)
  [3/3] /project/src/models/user.py (L20-80)

grep keywords: authenticate, jwt.*verify, session.*token

[config] tree_depth=3, tree_size=12.5KB, max_turns=3

Fehlerausgabe enthält statusspezifische Hinweise:

Error: Request failed: HTTP 403

[hint] 403 Forbidden: Authentication failed. The API key may be expired or revoked.
Try re-extracting with extract_windsurf_key, or set a fresh WINDSURF_API_KEY env var.
If you are running inside WSL, run `devin login` inside WSL so `~/.local/share/devin/credentials.toml` exists.

Error: Request failed: HTTP 413

[diagnostic] tree_depth_used=3, tree_size=280.0KB (auto fell back from requested depth)
[hint] If the error is payload-related, try a lower tree_depth value.

extract_windsurf_key

Windsurf-API-Schlüssel aus der lokalen Installation extrahieren. Keine Parameter.

Setzen Sie FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL=1 beim Start des MCP-Servers, um dieses Tool aus tools/list auszublenden. Dies deaktiviert die interne automatische API-Schlüsselerkennung für fast_context_search nicht.

Projektstruktur

fast-context-mcp/
├── package.json
├── src/
│   ├── server.mjs        # MCP server entry point
│   ├── core.mjs          # Auth, message building, streaming, search loop
│   ├── executor.mjs      # Tool executor: rg, readfile, tree, ls, glob
│   ├── extract-key.mjs   # Windsurf API Key extraction (SQLite)
│   ├── path-safety.mjs   # Project-root confinement for model-selected paths
│   ├── response-repair.mjs # Malformed response repair and evidence salvage
│   ├── shared.mjs        # Repository map, answer parser, prompt builder
│   ├── cache.mjs         # In-memory search-result cache
│   └── protobuf.mjs      # Protobuf encoder/decoder + Connect-RPC frames
├── test/                 # Unit and MCP stdio integration tests
├── README.md
└── LICENSE

So funktioniert die Suche

1. Das Projektverzeichnis wird auf den virtuellen Pfad /codebase abgebildet

2. Der Verzeichnisbaum wird in der angeforderten Tiefe erstellt (Standard L=3), mit automatischem Fallback auf eine geringere Tiefe, falls der Baum 250 KB überschreitet

3. Abfrage + Verzeichnisbaum werden über Connect-RPC/Protobuf an das Devstral-Modell von Windsurf gesendet

4. Devstral generiert Tool-Befehle (ripgrep, Dateilesevorgänge, tree, ls, glob)

5. Befehle werden lokal parallel ausgeführt (bis zu FC_MAX_COMMANDS pro Runde)

6. Ergebnisse werden für die nächste Runde an Devstral zurückgesendet

7. Nach max_turns Runden gibt Devstral Dateipfade + Zeilenbereiche zurück

8. Alle während der Suche verwendeten rg-Muster werden als vorgeschlagene Schlüsselwörter gesammelt

9. Diagnose-Metadaten werden angehängt, um der aufrufenden KI beim Optimieren der Parameter zu helfen

Technische Details

• Protokoll: Connect-RPC über HTTP/1.1, Protobuf-Kodierung, gzip-Komprimierung

• Modell: Devstral (MODEL_SWE_1_6_FAST, konfigurierbar)

• Lokale Tools: rg (über @vscode/ripgrep gebündelt), readfile (Node.js fs), tree (tree-node-cli), ls (Node.js fs), glob (Node.js fs)

• Authentifizierung: API-Schlüssel → JWT (automatisch pro Sitzung abgerufen)

• Laufzeit: Node.js >= 18 (ESM)

Abhängigkeiten

Freundliche Links

• LINUX DO

Lizenz

MIT