Fast Context MCP

Семантический поиск по коду на базе ИИ в виде MCP-инструмента — на основе реверс-инжиниринга протокола SWE-grep от Windsurf.

Любой MCP-совместимый клиент (Claude Code, Claude Desktop, Cursor и т.д.) может использовать его для поиска по кодовым базам с помощью запросов на естественном языке. Все инструменты поставляются через npm — системные зависимости не требуются (ripgrep через @vscode/ripgrep, tree через tree-node-cli). Работает на macOS, Windows и Linux.

Как это работает

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

Предварительные требования

• Node.js >= 18

• Учётная запись Windsurf — бесплатного тарифа достаточно (нужен для API-ключа)

Устанавливать ripgrep не нужно — он поставляется вместе с @vscode/ripgrep.

Установка

Вариант 1: npm (рекомендуется)

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

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

Вариант 2: из исходников

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

Настройка

1. Получите свой API-ключ Windsurf/Devin

Сервер автоматически извлекает API-ключ из Devin CLI/Desktop или из устаревшей установки Windsurf. Также вы можете использовать MCP-инструмент extract_windsurf_key после настройки или задать WINDSURF_API_KEY вручную.

Учётные данные Desktop обнаруживаются в следующем порядке: Devin, устаревший Deviv, затем Windsurf.

В WSL/Linux сервер сначала проверяет учётные данные Devin CLI в ~/.local/share/devin/credentials.toml. Если ключ, извлечённый в Windows, возвращает 403 внутри WSL, выполните devin login внутри WSL и повторите попытку.

2. Настройка MCP-клиента

Claude Code

Добавьте в ~/.claude.json в раздел mcpServers:

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

Для бета/следующего релиза:

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

Claude Desktop

Добавьте в claude_desktop_config.json в раздел mcpServers:

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

Для бета/следующего релиза:

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

Если WINDSURF_API_KEY не задан, сервер автоматически определит его из вашей локальной установки Windsurf.

Переменные окружения

Доступные модели

Модель можно изменить, задав WS_MODEL (см. переменные окружения выше).

По умолчанию: MODEL_SWE_1_6_FAST — максимальная скорость, самые богатые ключевые слова grep, наилучшая гранулярность местоположений.

MCP-инструменты

fast_context_search

Семантический поиск по коду на базе ИИ с настраиваемыми параметрами.

Возвращает:

1. Релевантные файлы с диапазонами строк

2. Предлагаемые ключевые слова для поиска (паттерны rg, использованные при ИИ-поиске)

3. Диагностические метаданные (строка [config], показывающая фактическую использованную tree_depth, размер дерева и произошёл ли откат)

Пример вывода:

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

Вывод ошибок содержит подсказки, зависящие от статуса:

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

Извлекает API-ключ Windsurf из локальной установки. Без параметров.

Установите FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL=1 при запуске MCP-сервера, чтобы скрыть этот инструмент из tools/list. Это не отключает внутреннее автоматическое определение API-ключа для fast_context_search.

Структура проекта

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

Как работает поиск

1. Каталог проекта сопоставляется с виртуальным путём /codebase

2. Дерево каталогов генерируется на запрошенной глубине (по умолчанию L=3), с автоматическим откатом на меньшую глубину, если дерево превышает 250 КБ

3. Запрос + дерево каталогов отправляются модели Devstral от Windsurf через Connect-RPC/Protobuf

4. Devstral генерирует команды инструментов (ripgrep, чтение файлов, tree, ls, glob)

5. Команды выполняются локально параллельно (до FC_MAX_COMMANDS за раунд)

6. Результаты отправляются обратно Devstral для следующего раунда

7. После max_turns раундов Devstral возвращает пути к файлам + диапазоны строк

8. Все паттерны rg, использованные во время поиска, собираются как предлагаемые ключевые слова

9. Добавляются диагностические метаданные, чтобы помочь вызывающему ИИ настроить параметры

Технические детали

• Протокол: Connect-RPC через HTTP/1.1, кодирование Protobuf, сжатие gzip

• Модель: Devstral (MODEL_SWE_1_6_FAST, настраивается)

• Локальные инструменты: rg (поставляется через @vscode/ripgrep), readfile (Node.js fs), tree (tree-node-cli), ls (Node.js fs), glob (Node.js fs)

• Аутентификация: API-ключ → JWT (автоматически получается для каждой сессии)

• Среда выполнения: Node.js >= 18 (ESM)

Зависимости

Дружественные ссылки

• LINUX DO

Лицензия

MIT