1.5.4 • Published 9h agoCLI

@philau2512/fast-context-mcp

Licence

MIT

Version

1.5.4

Deps

Size

195 kB

Vulns

Weekly

Install scriptsThis package runs scripts during installation (preinstall/install/postinstall)

Summary Dependency Versions

Fast Context MCP

AI-driven semantic code search as an MCP tool — powered by Windsurf's reverse-engineered SWE-grep protocol.

Repository: github.com/philau2512/devin-fast-context-mcp
npm package: @philau2512/devin-fast-context-mcp
CLI binary: fast-context-mcp

Thank to: https://github.com/awei84/fast-context-mcp and https://github.com/SammySnake-d/fast-context-mcp

Based on the open-source Fast Context MCP lineage (SammySnake / awei84 and contributors), with continued maintenance here.

Any MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.) can use this to search codebases with natural language queries. All tools are bundled via npm — no system-level dependencies needed (ripgrep via @vscode/ripgrep, tree via Node.js fs). Works on macOS, Windows, and Linux.

How It Works

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

Prerequisites

Node.js >= 18
Windsurf / Devin account — free tier works (needed for API key)

No need to install ripgrep — it's bundled via @vscode/ripgrep.

Installation

Option A: npm (after publish)

npx -y @philau2512/fast-context-mcp
# or
npm install -g @philau2512/fast-context-mcp

Package name is scoped (@philau2512/...) so it does not conflict with the community fast-context-mcp package on npm.

Option B: from GitHub (no npm publish required)

npx -y github:philau2512/fast-context-mcp

Option C: clone from source

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

Setup

1. Get Your Windsurf / Devin API Key

The server auto-extracts the API key from your local Windsurf / Devin installation. You can also use the extract_windsurf_key MCP tool after setup, or set WINDSURF_API_KEY manually.

Lookup order:

Linux/WSL: Devin CLI credentials at ~/.local/share/devin/credentials.toml (run devin login if missing)
Local SQLite DB candidates (Windsurf / Devin only)

Platform	SQLite path candidates
macOS	`~/Library/Application Support/{Windsurf,Devin}/User/globalStorage/state.vscdb`
Windows	`%APPDATA%/{Windsurf,Devin}/User/globalStorage/state.vscdb`
Linux	`~/.config/{Windsurf,devin,Devin}/User/globalStorage/state.vscdb`

On WSL/Linux, if a Windows-extracted key returns 403, run devin login inside WSL so ~/.local/share/devin/credentials.toml exists, then retry.

2. Configure MCP Client

Cursor

Add to Cursor MCP settings (mcp.json):

WINDSURF_API_KEY is optional if Devin / Windsurf is installed and logged in on this machine (auto-extract from local SQLite). Set it only when auto-discovery fails or you want a fixed key.

{
  "mcpServers": {
    "fast-context": {
      "command": "npx",
      "args": ["-y", "@philau2512/fast-context-mcp"],
      "env": {
        "WINDSURF_API_KEY": "sk-ws-01-xxxxx",
        "FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL": "1"
      }
    }
  }
}

Before npm publish, use GitHub:

{
  "mcpServers": {
    "fast-context": {
      "command": "npx",
      "args": ["-y", "github:philau2512/fast-context-mcp"],
      "env": {
        "WINDSURF_API_KEY": "sk-ws-01-xxxxx",
        "FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL": "1"
      }
    }
  }
}

From a local clone (dev):

{
  "mcpServers": {
    "fast-context": {
      "command": "node",
      "args": ["C:/path/to/fast-context-mcp/src/server.mjs"],
      "env": {
        "WINDSURF_API_KEY": "sk-ws-01-xxxxx",
        "FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL": "1"
      }
    }
  }
}

Claude Code

Add to ~/.claude.json under mcpServers (same env rules as Cursor):

{
  "fast-context": {
    "command": "npx",
    "args": ["-y", "@philau2512/fast-context-mcp"],
    "env": {
      "WINDSURF_API_KEY": "sk-ws-01-xxxxx",
      "FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL": "1"
    }
  }
}

Or if installed from source:

{
  "fast-context": {
    "command": "node",
    "args": ["/absolute/path/to/fast-context-mcp/src/server.mjs"],
    "env": {
      "WINDSURF_API_KEY": "sk-ws-01-xxxxx",
      "FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL": "1"
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json under mcpServers:

{
  "fast-context": {
    "command": "npx",
    "args": ["-y", "@philau2512/fast-context-mcp"],
    "env": {
      "WINDSURF_API_KEY": "sk-ws-01-xxxxx",
      "FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL": "1"
    }
  }
}

You can omit WINDSURF_API_KEY entirely when local Windsurf / Devin login works. You can omit FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL if you want the extract_windsurf_key tool visible.

Environment Variables

Variable	Default	Description
`WINDSURF_API_KEY`	(auto-discover)	Windsurf API key
`FC_MAX_TURNS`	`3`	Search rounds per query (more = deeper but slower)
`FC_MAX_COMMANDS`	`8`	Max parallel commands per round
`FC_TIMEOUT_MS`	`30000`	Connect-Timeout-Ms for streaming requests
`FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL`	`false`	Hide `extract_windsurf_key` from MCP tools when set to `1`/`true`/`yes`/`on`
`FC_RESULT_MAX_LINES`	`50`	Max lines per command output (truncation)
`FC_LINE_MAX_CHARS`	`250`	Max characters per output line (truncation)
`FC_INCLUDE_SNIPPETS`	`false`	Default for returning code snippets with search results
`FC_REPO_MAP_MODE`	`bootstrap_hotspot`	Repo-map strategy (`bootstrap_hotspot` or `classic`)
`FC_BOOTSTRAP_ENABLED`	`true`	Enable the standalone bootstrap phase for hotspot discovery
`FC_BOOTSTRAP_TREE_DEPTH`	`1`	Directory depth used by the bootstrap repo map (1-3)
`FC_BOOTSTRAP_MAX_TURNS`	`2`	Search turns used by the bootstrap phase (1-3)
`FC_BOOTSTRAP_MAX_COMMANDS`	`6`	Max commands per bootstrap turn (1-8)
`FC_HOTSPOT_TOP_K`	`4`	Number of hotspot top-level directories to append (0-8)
`FC_HOTSPOT_TREE_DEPTH`	`2`	Directory depth for each hotspot subtree (1-4)
`FC_HOTSPOT_MAX_BYTES`	`122880`	Byte budget for optimized repo-map output
`WS_MODEL`	`MODEL_SWE_1_6_FAST`	Windsurf model name
`WS_APP_VER`	`1.48.2`	Windsurf app version (protocol metadata)
`WS_LS_VER`	`1.9544.35`	Windsurf language server version (protocol metadata)

Available Models

The model can be changed by setting WS_MODEL (see environment variables above).

Available Models

Default: MODEL_SWE_1_6_FAST — fastest speed, richest grep keywords, finest location granularity.

MCP Tools

`fast_context_search`

AI-driven semantic code search with tunable parameters. For best semantic search quality, write queries primarily in English; add local-language business terms only when useful.

Parameter	Type	Required	Default	Description
`query`	string	Yes	—	Natural language search query. English is recommended for best semantic matching; add local-language business terms when useful.
`project_path`	string	Yes	—	Absolute path to project root directory
`tree_depth`	integer	No	`3`	Directory tree depth for repo map (0-6, 0 = auto). Higher = more context but larger payload. Auto falls back to lower depth if tree exceeds 250KB. Use 1-2 for huge monorepos (>5000 files), 3 for most projects, 4-6 for small projects.
`max_turns`	integer	No	`3`	Search rounds (1-5). More = deeper search but slower. Use 1-2 for simple lookups, 3 for most queries, 4-5 for complex analysis.
`max_results`	integer	No	`10`	Maximum number of files to return (1-30). Smaller = more focused, larger = broader exploration.
`exclude_paths`	string[]	No	`[]`	Directory/file patterns to exclude from repo map and search context. Useful for large repos or noisy generated files.
`include_code_snippets`	boolean	No	`false`	Include code snippets in the response. Defaults to file paths, line ranges, and grep keywords only.

Returns:

Relevant files with line ranges
Suggested search keywords (rg patterns used during AI search)
Diagnostic metadata ([config] line showing project_path, actual tree_depth used, tree size, and whether fallback occurred)

Example output:

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] project_path=/project, tree_depth=3, tree_size=12.5KB, max_turns=3

Error output includes status-specific hints:

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.

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`

Extract Windsurf / Devin API Key from local installation (CLI credentials.toml on Linux/WSL, then SQLite DBs). No parameters.

Set FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL=1 at MCP server startup to hide this tool from tools/list. Internal auto-discovery for fast_context_search is unaffected.

Project Structure

fast-context-mcp/
├── package.json          # @philau2512/fast-context-mcp
├── src/
│   ├── server.mjs        # MCP server entry point
│   ├── core.mjs          # Auth, message building, streaming, search loop
│   ├── directory-scorer.mjs
│   ├── executor.mjs      # Tool executor: rg, readfile, tree, ls, glob
│   ├── extract-key.mjs   # Windsurf / Devin API key extraction
│   ├── project-path.mjs
│   ├── protobuf.mjs      # Protobuf encoder/decoder + Connect-RPC frames
│   └── tree.mjs
├── scripts/
│   └── link-local-bin.mjs
├── tests/
├── README.md
└── LICENSE

How the Search Works

Project directory is mapped to virtual /codebase path
Directory tree generated at requested depth (default L=3), with automatic fallback to lower depth if tree exceeds 250KB
Query + directory tree sent to Windsurf's Devstral model via Connect-RPC/Protobuf
Devstral generates tool commands (ripgrep, file reads, tree, ls, glob)
Commands executed locally in parallel (up to FC_MAX_COMMANDS per round)
Results sent back to Devstral for the next round
After max_turns rounds, Devstral returns file paths + line ranges
All rg patterns used during search are collected as suggested keywords
Diagnostic metadata appended to help the calling AI tune parameters

Technical Details

Protocol: Connect-RPC over HTTP/1.1, Protobuf encoding, gzip compression
Model: Devstral (MODEL_SWE_1_6_FAST, configurable)
Local tools: rg (bundled via @vscode/ripgrep), readfile (Node.js fs), tree (Node.js fs), ls (Node.js fs), glob (Node.js fs)
Auth: API Key → JWT (auto-fetched per session)
Runtime: Node.js >= 18 (ESM)

Dependencies

Package	Purpose
`@modelcontextprotocol/sdk`	MCP server framework
`@vscode/ripgrep`	Bundled ripgrep binary (cross-platform)
`sql.js`	Read Windsurf / Devin local SQLite DB
`scule`	String utilities
`zod`	Schema validation (MCP SDK requirement)

Publishing

GitHub: push to https://github.com/philau2512/fast-context-mcp
npm: npm publish --access public (package @philau2512/fast-context-mcp; requires OTP/2FA)
Bare name fast-context-mcp on npm is owned by another maintainer — do not publish under that name.

License

MIT

Keywords

mcp code-search semantic-search windsurf devin devstral ripgrep claude cursor ai