@philau2512/fast-context-mcp 1.5.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,306 @@
+# Fast Context MCP
+
+AI-driven semantic code search as an MCP tool — powered by Windsurf's reverse-engineered SWE-grep protocol.
+
+Maintained fork: [philau2512/fast-context-mcp](https://github.com/philau2512/fast-context-mcp)  
+Upstream lineage: SammySnake / awei84 contributions (bootstrap hotspot, Devin auth, etc.)
+
+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: from GitHub (recommended for this fork)
+
+```bash
+# run latest from this repo (no global install)
+npx -y github:philau2512/fast-context-mcp
+```
+
+### Option B: clone from source
+
+```bash
+git clone https://github.com/philau2512/fast-context-mcp.git
+cd fast-context-mcp
+npm install
+```
+
+### Option C: npm (after you publish)
+
+```bash
+npx -y fast-context-mcp
+# or: npm install -g fast-context-mcp
+```
+
+## 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`):
+
+```json
+{
+  "mcpServers": {
+    "fast-context": {
+      "command": "npx",
+      "args": ["-y", "github:philau2512/fast-context-mcp"],
+      "env": {
+        "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": {
+        "FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL": "1"
+      }
+    }
+  }
+}
+```
+
+#### Claude Code
+
+Add to `~/.claude.json` under `mcpServers`:
+
+```json
+{
+  "fast-context": {
+    "command": "npx",
+    "args": ["-y", "github:philau2512/fast-context-mcp"],
+    "env": {
+      "WINDSURF_API_KEY": "sk-ws-01-xxxxx"
+    }
+  }
+}
+```
+
+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"
+    }
+  }
+}
+```
+
+#### Claude Desktop
+
+Add to `claude_desktop_config.json` under `mcpServers`:
+
+```json
+{
+  "fast-context": {
+    "command": "npx",
+    "args": ["-y", "github:philau2512/fast-context-mcp"],
+    "env": {
+      "WINDSURF_API_KEY": "sk-ws-01-xxxxx"
+    }
+  }
+}
+```
+
+> If `WINDSURF_API_KEY` is omitted, the server auto-discovers it from your local Windsurf / Devin installation.
+
+## 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
+├── 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)
+│   └── protobuf.mjs      # Protobuf encoder/decoder + Connect-RPC frames
+├── 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's local SQLite DB |
+| `zod` | Schema validation (MCP SDK requirement) |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@philau2512/fast-context-mcp",
+  "version": "1.5.3",
+  "description": "AI-driven semantic code search MCP server (Node.js) — Windsurf/Devin protocol",
+  "type": "module",
+  "main": "src/server.mjs",
+  "bin": {
+    "fast-context-mcp": "src/server.mjs"
+  },
+  "files": [
+    "src/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/server.mjs",
+    "postinstall": "node scripts/link-local-bin.mjs",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/philau2512/fast-context-mcp.git"
+  },
+  "homepage": "https://github.com/philau2512/fast-context-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/philau2512/fast-context-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "code-search",
+    "semantic-search",
+    "windsurf",
+    "devin",
+    "devstral",
+    "ripgrep",
+    "claude",
+    "cursor",
+    "ai"
+  ],
+  "author": "philau2512",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@vscode/ripgrep": "^1.15.9",
+    "scule": "^1.3.0",
+    "sql.js": "^1.14.0",
+    "zod": "^3.23.0"
+  },
+  "license": "MIT"
+}

package/scripts/link-local-bin.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * 为源码仓库创建本地 bin 自链接。
+ *
+ * npm/npx 在当前目录的 package 名称与请求包名相同时，会优先使用当前包。
+ * 这种情况下不会像安装依赖那样自动生成 node_modules/.bin/fast-context-mcp，
+ * 导致在本仓库根目录执行 `npx fast-context-mcp@x` 时出现 command not found。
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const initCwd = process.env.INIT_CWD ? resolve(process.env.INIT_CWD) : repoRoot;
+if (initCwd !== repoRoot) {
+  process.exit(0);
+}
+
+const packageJsonPath = join(repoRoot, "package.json");
+const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+
+const binTarget = pkg.bin?.["fast-context-mcp"];
+if (!binTarget) {
+  process.exit(0);
+}
+
+const binDir = join(repoRoot, "node_modules", ".bin");
+const entryPath = join(repoRoot, binTarget);
+const linkPath = join(binDir, "fast-context-mcp");
+
+mkdirSync(binDir, { recursive: true });
+chmodSync(entryPath, 0o755);
+
+if (process.platform === "win32") {
+  writeFileSync(
+    `${linkPath}.cmd`,
+    `@ECHO off\r\nnode "%~dp0\\..\\..\\${binTarget.replaceAll("/", "\\")}" %*\r\n`,
+    "utf8",
+  );
+} else {
+  const relativeTarget = relative(binDir, entryPath);
+  try {
+    rmSync(linkPath, { force: true });
+    symlinkSync(relativeTarget, linkPath);
+  } catch {
+    writeFileSync(linkPath, `#!/bin/sh\nexec node "${relativeTarget}" "$@"\n`, "utf8");
+  }
+  chmodSync(linkPath, 0o755);
+}