# Fast Context MCP

AI-driven semantic code search via reverse-engineered Windsurf protocol (Python implementation).

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-1.1%2B-green)](https://modelcontextprotocol.io)

## Overview

Fast Context MCP provides an AI-powered semantic code search tool through the Model Context Protocol (MCP). It leverages a reverse-engineered Windsurf protocol to deliver intelligent code context retrieval for LLMs and development workflows.

## Features

- **AI-Powered Semantic Search**: Natural language queries to find relevant code
- **MCP Server Integration**: Compatible with MCP-enabled clients (Claude Desktop, etc.)
- **Protobuf Protocol**: Efficient binary communication with Windsurf API
- **Tree-based Context**: Includes directory structure for better code understanding
- **Multi-language Support**: Works with any codebase (Python, JavaScript, Go, etc.)

## Installation

### From PyPI (Recommended)

```bash
pip install fast-context-mcp
```

### From Source

```bash
git clone https://github.com/YOUR_USERNAME/fast-context-mcp-py.git
cd fast-context-mcp-py
pip install -e .
```

## Usage

### As an MCP Server

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "fast-context": {
      "command": "python",
      "args": ["-m", "fast_context_mcp.server"]
    }
  }
}
```

### Programmatic Usage

```python
from fast_context_mcp.search import search_with_content

result = search_with_content(
    query="Find the authentication middleware",
    project_root="/path/to/your/project"
)
print(result)
```

### Available Tools

#### `search_code`

Search for relevant code in a codebase using AI-powered semantic search.

**Parameters:**
- `query` (string): Natural language description of what you're looking for
- `project_root` (string): Absolute path to the project root directory

**Returns:** JSON-formatted search results with relevant file paths and line ranges.

## Architecture

```
fast_context_mcp/
├── core.py        # Core search implementation & API communication
├── search.py      # Search orchestration and result formatting
├── server.py      # MCP server implementation
├── protobuf.py    # Protobuf encoding/decoding
├── executor.py    # Tool execution with context management
└── rg_installer.py # Ripgrep auto-installer
```

## Protocol Details

The project implements a reverse-engineered version of Windsurf's internal protocol:

1. **Connect Frame**: Binary protobuf handshake with magic bytes (`0x0001`)
2. **Session Management**: UUID-based session tracking
3. **Tool Definitions**: JSON Schema-based tool specifications
4. **Response Streaming**: Chunked protobuf responses with gzip compression

## Development

### Setup

```bash
# Install development dependencies
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

### Linting

```bash
ruff check .
ruff format .
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Acknowledgments

- Inspired by [Windsurf](https://www.codeium.com/windsurf)'s Cascade feature
- Built with the [Model Context Protocol](https://modelcontextprotocol.io)

## Disclaimer

This project is a reverse-engineered implementation for educational purposes. It is not affiliated with or endorsed by Codeium/Windsurf.