Summary

Fast Context MCP provides AI-driven semantic code search capabilities integrated as an MCP tool, leveraging Windsurf's reverse-engineered SWE-grep protocol. It empowers users of MCP-compatible clients like Claude Code, Claude Desktop, and Cursor to query codebases using natural language. The tool translates these queries into executable commands, performs local searches, and returns precise file paths, line ranges, and AI-generated keyword suggestions, significantly enhancing code navigation and understanding.

How It Works

The project maps the target codebase to a virtual /codebase path and generates a directory tree representation, with automatic fallback for excessively large projects. This information, along with the user's natural language query, is sent to Windsurf's Devstral AI model via Connect-RPC/Protobuf. Devstral then intelligently generates a series of local commands (e.g., ripgrep, readfile, tree) which are executed in parallel by the Fast Context MCP server. The results are iteratively fed back to Devstral over a configurable number of rounds (max_turns) to refine the search. Upon completion, the tool outputs the most relevant file paths with line ranges and suggested search patterns used during the AI's process.

Quick Start & Requirements

• Primary Install: Use npm: npm install @sammysnake/fast-context-mcp for the latest stable release, or npm install @sammysnake/fast-context-mcp@next for beta/next releases.
• Prerequisites: Node.js version 18 or higher, and a Windsurf account (a free tier is sufficient) with an API key.
• Dependencies: ripgrep is bundled via @vscode/ripgrep and tree via tree-node-cli, eliminating the need for system-level installations.
• Setup: Obtain a Windsurf API key (which can be auto-discovered from the local Windsurf installation or set via the WINDSURF_API_KEY environment variable). Configure your MCP-compatible client (e.g., Claude Code, Claude Desktop) by adding fast-context to its mcpServers configuration, specifying npx as the command and providing the package name.
• Links: Installation and configuration examples are provided within the README for various clients.

Highlighted Details

• AI-driven semantic code search powered by Windsurf's Devstral model (MODEL_SWE_1_6_FAST by default).
• Bundles essential command-line tools (ripgrep, tree) as npm packages for a dependency-free setup.
• Cross-platform compatibility across macOS, Windows, and Linux.
• Highly configurable search parameters, including maximum search rounds (FC_MAX_TURNS), command concurrency (FC_MAX_COMMANDS), and result line limits (FC_RESULT_MAX_LINES).

Maintenance & Community

The provided README does not contain specific details regarding notable contributors, sponsorships, community channels (like Discord or Slack), or a public roadmap.

Licensing & Compatibility

• License: MIT.
• Compatibility: The MIT license is permissive, allowing for commercial use and integration within closed-source projects without significant restrictions.

Limitations & Caveats

A Windsurf API key is mandatory for operation. The directory tree generation process may automatically reduce its depth if the generated tree exceeds 250KB, which could impact search context for extremely large codebases. Users may need to tune parameters like tree_depth and max_turns to achieve optimal search performance and relevance for specific projects. Error messages provide diagnostic hints for common issues like authentication failures or payload size limits.