@philau2512/fast-context-mcp 1.5.3 → 1.5.5

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025
+Copyright (c) 2025–2026 philau2512 and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,8 +2,13 @@
 
 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.)
+**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.
 
@@ -46,26 +51,28 @@ No need to install ripgrep — it's bundled via `@vscode/ripgrep`.
 
 ## Installation
 
-### Option A: from GitHub (recommended for this fork)
+### Option A: npm (after publish)
 
 ```bash
-# run latest from this repo (no global install)
-npx -y github:philau2512/fast-context-mcp
+npx -y @philau2512/fast-context-mcp
+# or
+npm install -g @philau2512/fast-context-mcp
 ```
 
-### Option B: clone from source
+> 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
-git clone https://github.com/philau2512/fast-context-mcp.git
-cd fast-context-mcp
-npm install
+npx -y github:philau2512/fast-context-mcp
 ```
 
-### Option C: npm (after you publish)
+### Option C: clone from source
 
 ```bash
-npx -y fast-context-mcp
-# or: npm install -g fast-context-mcp
+git clone https://github.com/philau2512/fast-context-mcp.git
+cd fast-context-mcp
+npm install
 ```
 
 ## Setup
@@ -92,6 +99,25 @@ On WSL/Linux, if a Windows-extracted key returns **403**, run `devin login` insi
 
 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": {
@@ -99,6 +125,7 @@ Add to Cursor MCP settings (`mcp.json`):
       "command": "npx",
       "args": ["-y", "github:philau2512/fast-context-mcp"],
       "env": {
+        "WINDSURF_API_KEY": "sk-ws-01-xxxxx",
         "FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL": "1"
       }
     }
@@ -115,6 +142,7 @@ From a local clone (dev):
       "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"
       }
     }
@@ -124,15 +152,16 @@ From a local clone (dev):
 
 #### Claude Code
 
-Add to `~/.claude.json` under `mcpServers`:
+Add to `~/.claude.json` under `mcpServers` (same env rules as Cursor):
 
 ```json
 {
   "fast-context": {
     "command": "npx",
-    "args": ["-y", "github:philau2512/fast-context-mcp"],
+    "args": ["-y", "@philau2512/fast-context-mcp"],
     "env": {
-      "WINDSURF_API_KEY": "sk-ws-01-xxxxx"
+      "WINDSURF_API_KEY": "sk-ws-01-xxxxx",
+      "FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL": "1"
     }
   }
 }
@@ -146,7 +175,8 @@ Or if installed from source:
     "command": "node",
     "args": ["/absolute/path/to/fast-context-mcp/src/server.mjs"],
     "env": {
-      "WINDSURF_API_KEY": "sk-ws-01-xxxxx"
+      "WINDSURF_API_KEY": "sk-ws-01-xxxxx",
+      "FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL": "1"
     }
   }
 }
@@ -160,15 +190,16 @@ Add to `claude_desktop_config.json` under `mcpServers`:
 {
   "fast-context": {
     "command": "npx",
-    "args": ["-y", "github:philau2512/fast-context-mcp"],
+    "args": ["-y", "@philau2512/fast-context-mcp"],
     "env": {
-      "WINDSURF_API_KEY": "sk-ws-01-xxxxx"
+      "WINDSURF_API_KEY": "sk-ws-01-xxxxx",
+      "FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL": "1"
     }
   }
 }
 ```
 
-> If `WINDSURF_API_KEY` is omitted, the server auto-discovers it from your local Windsurf / Devin installation.
+> 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
 
@@ -261,13 +292,19 @@ Set `FC_HIDE_EXTRACT_WINDSURF_KEY_TOOL=1` at MCP server startup to hide this too
 
 ```
 fast-context-mcp/
-├── package.json
+├── 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 API Key extraction (SQLite)
-│   └── protobuf.mjs      # Protobuf encoder/decoder + Connect-RPC frames
+│   ├── 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
 ```
@@ -298,9 +335,16 @@ fast-context-mcp/
 |---------|---------|
 | `@modelcontextprotocol/sdk` | MCP server framework |
 | `@vscode/ripgrep` | Bundled ripgrep binary (cross-platform) |
-| `sql.js` | Read Windsurf's local SQLite DB |
+| `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@philau2512/fast-context-mcp",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "description": "AI-driven semantic code search MCP server (Node.js) — Windsurf/Devin protocol",
   "type": "module",
   "main": "src/server.mjs",
@@ -49,5 +49,8 @@
     "sql.js": "^1.14.0",
     "zod": "^3.23.0"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "license": "MIT"
 }

package/scripts/link-local-bin.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 /**
- * 为源码仓库创建本地 bin 自链接。
+ * Create a local bin self-link for this source repo.
  *
- * npm/npx 在当前目录的 package 名称与请求包名相同时，会优先使用当前包。
- * 这种情况下不会像安装依赖那样自动生成 node_modules/.bin/fast-context-mcp，
- * 导致在本仓库根目录执行 `npx fast-context-mcp@x` 时出现 command not found。
+ * When the package name matches what npx resolves, npm may not create
+ * node_modules/.bin/fast-context-mcp automatically. That breaks local
+ * `npx @philau2512/fast-context-mcp` / bin resolution from the repo root.
  */
 
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
@@ -47,4 +47,4 @@ if (process.platform === "win32") {
     writeFileSync(linkPath, `#!/bin/sh\nexec node "${relativeTarget}" "$@"\n`, "utf8");
   }
   chmodSync(linkPath, 0o755);
-}
+}

package/src/server.mjs

@@ -91,11 +91,23 @@ export function buildFastContextSearchTool({
   const runSearchWithContent = deps.searchWithContent || searchWithContent;
   const validatePath = deps.validateProjectPath || validateProjectPath;
   const description =
-    "AI-driven semantic code search using Windsurf's Devstral model. " +
-    "Searches a codebase with natural language and returns relevant file paths with line ranges, " +
-    "plus suggested grep keywords for follow-up searches.\n" +
-    "For best semantic search quality, write the query primarily in English; add local-language business terms only when needed.\n" +
-    "Use tree_depth/max_turns/max_results for task-level tuning; use exclude_paths to reduce payload or noise.\n" +
+    "Primary tool for semantic codebase search, context discovery, and verifying logic existence. " +
+    "Locates relevant files, exact line ranges, and code regions from natural language or domain concepts in a single step, " +
+    "without needing manual grep trials or knowing exact filenames.\n\n" +
+    "MANDATORY REQUIREMENT:\n" +
+    "- 'project_path' is strictly REQUIRED. You MUST provide the absolute path to the project root directory when calling this tool.\n\n" +
+    "RECOMMENDED FOR:\n" +
+    "- Verifying feature/data existence: Checking whether a business rule, model, seed data, configuration, or API already exists (e.g. 'check if warrior coefficient seed data exists', 'has rate limiting been added').\n" +
+    "- Finding conceptual business logic: Locating where behavior lives across the codebase without guessing file names.\n" +
+    "- Tracing multi-file flows: Getting high-relevance entry points, line ranges, and suggested grep keywords before reading code.\n\n" +
+    "DO NOT USE WHEN (Avoid Overuse):\n" +
+    "- Target file is already known, opened, or specified by the user (use view_file / read_file directly).\n" +
+    "- Exact symbol search: Searching for an exact, known function/class/variable name (use grep instead).\n" +
+    "- Directory exploration: Simply listing files in a directory (use list_dir/glob instead).\n" +
+    "- Single-file localized edits or lint fixes.\n\n" +
+    "QUERY TIPS:\n" +
+    "- For best semantic search quality, write the query primarily in English; keep local-language domain terms when needed (e.g. 'seed data for sale he so chien binh').\n" +
+    "- Use tree_depth/max_turns/max_results for task-level tuning; use exclude_paths to reduce payload or noise.\n" +
     (config.includeSnippetsExplicitlySet
       ? `- include_code_snippets: Server-configured default is ${config.includeSnippets}. Do NOT override unless explicitly asked by the user.\n`
       : "- include_code_snippets: Default false (lightweight mode, ~2-5KB output). " +
@@ -104,11 +116,15 @@ export function buildFastContextSearchTool({
 
   const schema = {
     query: z.string().describe(
-      'Natural language search query. English is recommended for best semantic matching; add local-language business terms when useful (e.g. "where is user login authentication and JWT validation handled 登录鉴权", "database connection pool")'
+      'Natural language search query describing the feature, logic, architecture, or behavior to locate. ' +
+      'English is recommended for best semantic matching; describe what the code does rather than guessing exact variable names ' +
+      '(e.g. "where is user login authentication and JWT validation handled", "database connection pool retry logic"). ' +
+      'Add local-language business terms only when needed.'
     ),
     project_path: projectPathSchema.describe(
-      "Absolute path to project root directory (required). " +
-      "Example: /Users/username/projects/myproject or C:/Users/username/projects/myproject"
+      "MANDATORY: Absolute path to project root directory (required). " +
+      "You MUST supply this parameter explicitly on every call (e.g. /Users/username/projects/myproject or C:/Users/username/projects/myproject). " +
+      "Never leave empty or omit."
     ),
     tree_depth: z
       .number()