Fast Context MCP

Búsqueda semántica de código impulsada por IA como herramienta MCP — basada en el protocolo SWE-grep de Windsurf, diseñado mediante ingeniería inversa.

Cualquier cliente compatible con MCP (Claude Code, Claude Desktop, Cursor, etc.) puede usarlo para buscar en bases de código con consultas en lenguaje natural. Todas las herramientas se agrupan mediante npm — no se necesitan dependencias a nivel de sistema (ripgrep a través de @vscode/ripgrep, tree mediante tree-node-cli). Funciona en macOS, Windows y Linux.

Cómo funciona

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

Requisitos previos

• Node.js >= 18

• Cuenta de Windsurf — el plan gratuito funciona (necesaria para la clave de API).

No es necesario instalar ripgrep — viene incluido a través de @vscode/ripgrep.

Instalación

Opción 1: npm (recomendada)

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

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

Opción 2: desde el código fuente

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

Configuración

1. Obtén tu clave de API de Windsurf/Devin

El servidor extrae automáticamente la clave de API de Devin CLI/Desktop o de una instalación heredada de Windsurf. También puedes usar la herramienta MCP extract_windsurf_key después de la configuración, o establecer WINDSURF_API_KEY manualmente.

Las credenciales de escritorio se descubren en este orden: Devin, Deviv heredado y luego Windsurf.

En WSL/Linux, el servidor comprueba primero las credenciales de Devin CLI en ~/.local/share/devin/credentials.toml. Si una clave extraída en Windows devuelve 403 dentro de WSL, ejecuta devin login dentro de WSL y reinténtalo.

2. Configura el cliente MCP

Claude Code

Añade a ~/.claude.json en mcpServers:

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

Para la versión beta/siguiente:

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

Claude Desktop

Añade a claude_desktop_config.json en mcpServers:

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

Para la versión beta/siguiente:

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

Si se omite WINDSURF_API_KEY, el servidor la descubre automáticamente desde tu instalación local de Windsurf.

Variables de entorno

Modelos disponibles

El modelo se puede cambiar estableciendo WS_MODEL (consulta las variables de entorno anteriores).

Por defecto: MODEL_SWE_1_6_FAST — máxima velocidad, las palabras clave grep más ricas y la granularidad de ubicación más fina.

Herramientas MCP

fast_context_search

Búsqueda semántica de código impulsada por IA con parámetros ajustables.

Devuelve:

1. Archivos relevantes con rangos de líneas

2. Palabras clave de búsqueda sugeridas (patrones rg utilizados durante la búsqueda con IA)

3. Metadatos de diagnóstico (línea [config] que muestra el tree_depth real utilizado, el tamaño del árbol y si se produjo la reducción)

Ejemplo de salida:

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

La salida de error incluye pistas específicas según el estado:

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

Extrae la clave de API de Windsurf de la instalación local. Sin parámetros.

Establece FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL=1 al iniciar el servidor MCP para ocultar esta herramienta de tools/list. Esto no desactiva el descubrimiento automático interno de la clave de API para fast_context_search.

Estructura del proyecto

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

Cómo funciona la búsqueda

1. El directorio del proyecto se asigna a la ruta virtual /codebase

2. Se genera el árbol de directorios con la profundidad solicitada (por defecto L=3), con reducción automática a una profundidad menor si el árbol supera los 250KB

3. La consulta y el árbol de directorios se envían al modelo Devstral de Windsurf mediante Connect-RPC/Protobuf

4. Devstral genera comandos de herramientas (ripgrep, lectura de archivos, tree, ls, glob)

5. Los comandos se ejecutan localmente en paralelo (hasta FC_MAX_COMMANDS por ronda)

6. Los resultados se envían de vuelta a Devstral para la siguiente ronda

7. Después de max_turns rondas, Devstral devuelve rutas de archivo y rangos de líneas

8. Todos los patrones rg utilizados durante la búsqueda se recopilan como palabras clave sugeridas

9. Se añaden metadatos de diagnóstico para ayudar a la IA llamante a ajustar parámetros

Detalles técnicos

• Protocolo: Connect-RPC sobre HTTP/1.1, codificación Protobuf, compresión gzip

• Modelo: Devstral (MODEL_SWE_1_6_FAST, configurable)

• Herramientas locales: rg (incluido a través de @vscode/ripgrep), readfile (fs de Node.js), tree (tree-node-cli), ls (fs de Node.js), glob (fs de Node.js)

• Autenticación: clave de API → JWT (se obtiene automáticamente por sesión)

• Entorno de ejecución: Node.js >= 18 (ESM)

Dependencias

Enlaces amigos

• LINUX DO

Licencia

MIT