@sammysnake/fast-context-mcp 1.2.0 → 1.3.0-beta.2

package/README.md

@@ -10,25 +10,36 @@ Any MCP-compatible client (Claude Code, Claude Desktop, Cursor, etc.) can use th
 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
-└─────────────────────────┘
+┌──────────────────────────────────────────────────────┐
+│  Fast Context MCP (local MCP server)                 │
+│                                                      │
+│  Phase 1: Bootstrap (optional)                       │
+│    1. Mini-tree scan → Devstral API                  │
+│    2. Returns hot directories + rg patterns          │
+│                                                      │
+│  Phase 2: Directory Scoring                          │
+│    3. BM25F + Probe grep + Git RFM + File Agg       │
+│    4. RRF fusion → adaptive topK selection           │
+│       (Kneedle gap + entropy + tail threshold)       │
+│    5. Path spine extraction (scored file hints)      │
+│                                                      │
+│  Phase 3: Main Search (N rounds)                     │
+│    6. Query + optimized repo map → Devstral API      │
+│       (tree + hotspot subtrees + path spines)        │
+│    7. AI generates rg/readfile/tree/ls commands      │
+│    8. Execute locally (built-in rg) → return results │
+│    9. Repeat for N rounds                            │
+│   10. Final answer: 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)
+Found 5 relevant files.
+  [1/5] /project/src/auth/handler.py (L10-60)
+  [2/5] /project/src/middleware/jwt.py (L1-40)
+  [3/5] /project/src/models/user.py (L20-80)
+  [4/5] /project/src/routes/login.py (L5-35)
+  [5/5] /project/src/utils/token.py (L1-25)
 
 Suggested search keywords:
   authenticate, jwt.*verify, session.*token
@@ -43,6 +54,18 @@ No need to install ripgrep — it's bundled via `@vscode/ripgrep`.
 
 ## Installation
 
+### Option 1: npm (Recommended)
+
+```bash
+# Latest stable release
+npm install @sammysnake/fast-context-mcp
+
+# Or beta/next release
+npm install @sammysnake/fast-context-mcp@next
+```
+
+### Option 2: From Source
+
 ```bash
 git clone https://github.com/SammySnake-d/fast-context-mcp.git
 cd fast-context-mcp
@@ -72,8 +95,22 @@ Add to `~/.claude.json` under `mcpServers`:
 ```json
 {
   "fast-context": {
-    "command": "node",
-    "args": ["/absolute/path/to/fast-context-mcp/src/server.mjs"],
+    "command": "npx",
+    "args": ["-y", "--prefer-online", "@sammysnake/fast-context-mcp"],
+    "env": {
+      "WINDSURF_API_KEY": "sk-ws-01-xxxxx"
+    }
+  }
+}
+```
+
+For beta/next release:
+
+```json
+{
+  "fast-context": {
+    "command": "npx",
+    "args": ["-y", "--prefer-online", "@sammysnake/fast-context-mcp@next"],
     "env": {
       "WINDSURF_API_KEY": "sk-ws-01-xxxxx"
     }
@@ -88,8 +125,22 @@ Add to `claude_desktop_config.json` under `mcpServers`:
 ```json
 {
   "fast-context": {
-    "command": "node",
-    "args": ["/absolute/path/to/fast-context-mcp/src/server.mjs"],
+    "command": "npx",
+    "args": ["-y", "--prefer-online", "@sammysnake/fast-context-mcp"],
+    "env": {
+      "WINDSURF_API_KEY": "sk-ws-01-xxxxx"
+    }
+  }
+}
+```
+
+For beta/next release:
+
+```json
+{
+  "fast-context": {
+    "command": "npx",
+    "args": ["-y", "--prefer-online", "@sammysnake/fast-context-mcp@next"],
     "env": {
       "WINDSURF_API_KEY": "sk-ws-01-xxxxx"
     }
@@ -107,8 +158,18 @@ Add to `claude_desktop_config.json` under `mcpServers`:
 | `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_REPO_MAP_MODE` | `bootstrap_hotspot` | Repo map strategy (`classic` or `bootstrap_hotspot`) |
+| `FC_BOOTSTRAP_TREE_DEPTH` | `1` | Bootstrap mini-tree depth |
+| `FC_HOTSPOT_TOP_K` | `4` | Base hotspot dirs (adaptive topK overrides via Kneedle + entropy) |
+| `FC_HOTSPOT_TREE_DEPTH` | `2` | Tree depth for each hotspot subtree |
+| `FC_HOTSPOT_MAX_BYTES` | `122880` | Max bytes budget for optimized repo map |
+| `FC_BOOTSTRAP_ENABLED` | `true` | Enable standalone bootstrap phase |
+| `FC_BOOTSTRAP_MAX_TURNS` | `2` | Bootstrap phase turns |
+| `FC_BOOTSTRAP_MAX_COMMANDS` | `6` | Bootstrap commands per turn |
 | `FC_RESULT_MAX_LINES` | `50` | Max lines per command output (truncation) |
 | `FC_LINE_MAX_CHARS` | `250` | Max characters per output line (truncation) |
+| `FC_PROFILE_CACHE_TTL` | `120` | Directory profile cache TTL in seconds |
+| `FC_GIT_CACHE_TTL` | `300` | Git RFM analysis cache TTL in seconds |
 | `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) |
@@ -131,9 +192,18 @@ AI-driven semantic code search with tunable parameters.
 |-----------|------|----------|---------|-------------|
 | `query` | string | Yes | — | Natural language search query |
 | `project_path` | string | No | cwd | Absolute path to project root |
-| `tree_depth` | integer | No | `3` | Directory tree depth for repo map (1-6). 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. |
+| `tree_depth` | integer | No | `3` | Repo map depth for `classic` mode only (`0-6`, `0=auto`). Ignored in `bootstrap_hotspot` mode — use `bootstrap_tree_depth` and `hotspot_tree_depth` instead. |
+| `max_turns` | integer | No | `3` | Main-phase search rounds (`1-5`). More = deeper search but slower. |
+| `max_results` | integer | No | `10` | Maximum number of files to return (`1-30`). |
+| `exclude_paths` | string[] | No | `[]` | Extra exclude patterns merged with built-in default excludes (`node_modules`, `.git`, `dist`, `build`, `coverage`, `.venv`, ...). |
+| `repo_map_mode` | enum | No | `bootstrap_hotspot` | Repo map strategy: `classic` or `bootstrap_hotspot`. |
+| `bootstrap_tree_depth` | integer | No | `1` | Bootstrap phase mini-tree depth (`1-3`). |
+| `hotspot_top_k` | integer | No | `4` | Base hotspot dirs (`0-8`). Adaptive topK may expand this based on score distribution. |
+| `hotspot_tree_depth` | integer | No | `2` | Tree depth per hotspot subtree (`1-4`). |
+| `hotspot_max_bytes` | integer | No | `122880` | Max byte budget for optimized repo map (`16384-262144`). |
+| `bootstrap_enabled` | boolean | No | `true` | Enable standalone bootstrap phase before main search. |
+| `bootstrap_max_turns` | integer | No | `2` | Bootstrap turns (`1-3`). Independent from `max_turns`. |
+| `bootstrap_max_commands` | integer | No | `6` | Bootstrap commands per turn (`1-8`). Independent from main commands. |
 
 Returns:
 1. **Relevant files** with line ranges
@@ -178,11 +248,12 @@ Extract Windsurf API Key from local installation. No parameters.
 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
+│   ├── server.mjs           # MCP server entry point
+│   ├── core.mjs             # Auth, message building, streaming, search loop
+│   ├── executor.mjs         # Tool executor: rg, readfile, tree, ls, glob
+│   ├── directory-scorer.mjs # BM25F + Probe + Git RFM directory scoring
+│   ├── extract-key.mjs      # Windsurf API Key extraction (SQLite)
+│   └── protobuf.mjs         # Protobuf encoder/decoder + Connect-RPC frames
 ├── README.md
 └── LICENSE
 ```
@@ -190,14 +261,35 @@ fast-context-mcp/
 ## 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
+2. **Directory scoring** via 5-signal RRF fusion:
+   - **BM25F**: multi-field scoring (dir name, file paths, metadata, headers)
+   - **Probe grep**: single ripgrep call with regex alternation for content matching
+   - **Bootstrap keywords**: terms from optional bootstrap pre-scan
+   - **Git RFM**: Recency-Frequency-Modification model from git history
+   - **File aggregation**: file-level Log-Sum scoring per directory
+3. **Adaptive hotspot selection** based on IR literature:
+   - **Kneedle gap detection** (Taguchi 2025 Adaptive-k): finds the largest score drop as a natural cutoff
+   - **Entropy scaling** (CMU Selective Search): flat score distributions auto-expand K; peaked distributions keep K tight
+   - **Adaptive tail threshold**: includes strong dirs beyond cutoff based on score decay rate (replaces fixed 0.6 ratio)
+4. **Path spine extraction**: scored file paths as navigation hints, with source-code path boost and noise path penalty
+5. Query + optimized repo map (tree + hotspot subtrees + path spines) sent to Windsurf Devstral via Connect-RPC/Protobuf
+6. Devstral generates tool commands (ripgrep, file reads, tree, ls, glob)
+7. Commands executed locally in parallel (up to `FC_MAX_COMMANDS` per round)
+8. Results sent back to Devstral for the next round
+9. After `max_turns` rounds, Devstral returns file paths + line ranges
+10. All rg patterns used during search are collected as suggested keywords
+11. Diagnostic metadata appended to help the calling AI tune parameters
+
+### Caching
+
+Directory profiles and Git history analysis are cached at the process level to avoid redundant filesystem walks across repeated queries:
+
+| Cache | TTL | Configurable via |
+|-------|-----|------------------|
+| Directory profiles | 120s | `FC_PROFILE_CACHE_TTL` |
+| Git RFM analysis | 300s | `FC_GIT_CACHE_TTL` |
+
+Caches are scoped to the MCP server process lifetime and automatically expire. No manual invalidation needed for normal development workflows.
 
 ## Technical Details
 
@@ -214,7 +306,7 @@ fast-context-mcp/
 | `@modelcontextprotocol/sdk` | MCP server framework |
 | `@vscode/ripgrep` | Bundled ripgrep binary (cross-platform) |
 | `tree-node-cli` | Cross-platform directory tree (replaces system `tree`) |
-| `better-sqlite3` | Read Windsurf's local SQLite DB |
+| `sql.js` | Read Windsurf's local SQLite DB (WASM, no native deps) |
 | `zod` | Schema validation (MCP SDK requirement) |
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sammysnake/fast-context-mcp",
-  "version": "1.2.0",
+  "version": "1.3.0-beta.2",
   "description": "AI-driven semantic code search via reverse-engineered Windsurf protocol (Node.js)",
   "type": "module",
   "main": "src/server.mjs",
@@ -44,4 +44,4 @@
     "zod": "^3.23.0"
   },
   "license": "MIT"
-}
+}