# @philau2512/fast-context-mcp

> AI-driven semantic code search MCP server (Node.js) — Windsurf/Devin protocol

Latest version **1.5.4** (published 2026-09-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @philau2512/fast-context-mcp
pnpm add @philau2512/fast-context-mcp
yarn add @philau2512/fast-context-mcp
bun add @philau2512/fast-context-mcp
```

Provides the command `fast-context-mcp`.

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.5.4 |
| Published | 2026-09-24 |
| First published | 2026-07-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 5 |
| Unpacked size | 194.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | yes |
| GitHub stars | 0 |
| Author | philau2512 |
| Maintainers | philau2512 |
| Keywords | mcp, code-search, semantic-search, windsurf, devin, devstral, ripgrep, claude, cursor, ai |

## Links

- npm: https://www.npmjs.com/package/@philau2512/fast-context-mcp
- Repository: https://github.com/philau2512/fast-context-mcp
- Homepage: https://github.com/philau2512/fast-context-mcp#readme
- Issues: https://github.com/philau2512/fast-context-mcp/issues
- npm.io page: https://npm.io/package/@philau2512/fast-context-mcp

## Dependencies (5)

- [zod](https://npm.io/package/zod.md) ^3.23.0
- [scule](https://npm.io/package/scule.md) ^1.3.0
- [sql.js](https://npm.io/package/sql.js.md) ^1.14.0
- [@vscode/ripgrep](https://npm.io/package/@vscode/ripgrep.md) ^1.15.9
- [@modelcontextprotocol/sdk](https://npm.io/package/@modelcontextprotocol/sdk.md) ^1.0.0

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 1.5.4 (latest) — 2026-09-24
- 1.5.3 — 2026-07-23

## README

# 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](https://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)

```bash
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)

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

### Option C: clone from source

```bash
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:
1. **Linux/WSL**: Devin CLI credentials at `~/.local/share/devin/credentials.toml` (run `devin login` if missing)
2. 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.

```json
{
  "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:

```json
{
  "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):

```json
{
  "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):

```json
{
  "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:

```json
{
  "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`:

```json
{
  "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](docs/models.png)

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:
1. **Relevant files** with line ranges
2. **Suggested search keywords** (rg patterns used during AI search)
3. **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

1. Project directory is mapped to virtual `/codebase` path
2. Directory tree generated at requested depth (default L=3), with **automatic fallback** to lower depth if tree exceeds 250KB
3. Query + directory tree sent to Windsurf's Devstral model via Connect-RPC/Protobuf
4. Devstral generates tool commands (ripgrep, file reads, tree, ls, glob)
5. Commands executed locally in parallel (up to `FC_MAX_COMMANDS` per round)
6. Results sent back to Devstral for the next round
7. After `max_turns` rounds, Devstral returns file paths + line ranges
8. All rg patterns used during search are collected as suggested keywords
9. 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

---
_Source: https://npm.io/package/@philau2512/fast-context-mcp · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._