Merge pull request #4 from Helweg/feature/mcp-server

feat: add MCP server for Cursor, Claude Code, and Windsurf support

Author: Helweg

AGENTS.md

@@ -36,6 +36,8 @@ cd native && cargo build --release && napi build --release --platform
 ```
 src/
 ├── index.ts              # Plugin entry: exports tools + slash commands
+├── mcp-server.ts         # MCP server: wraps Indexer for Cursor/Claude Code/Windsurf
+├── cli.ts                # CLI entry point for MCP stdio transport
 ├── config/               # Config schema (Zod) + parsing
 ├── embeddings/           # Provider detection (auto/github/openai/google/ollama)
 ├── indexer/              # Core: Indexer class, delta tracking
@@ -72,6 +74,7 @@ skill/                    # OpenCode skill guidance
 | Add database operation | `native/src/db.rs` + expose in `lib.rs` |
 | Add slash command | `commands/` + register in `src/index.ts` config() |
 
+| Add/modify MCP tool | `src/mcp-server.ts` (createMcpServer) |
 ## CODE MAP
 
 ### TypeScript Exports (`src/index.ts`)
@@ -87,6 +90,16 @@ skill/                    # OpenCode skill guidance
 | `index_metrics` | Tool | Get performance metrics (requires debug.enabled + debug.metrics) |
 | `index_logs` | Tool | Get debug logs (requires debug.enabled) |
 
+
+### MCP Server Exports (`src/mcp-server.ts`)
+| Symbol | Type | Purpose |
+|--------|------|---------|
+| `createMcpServer` | fn | Creates MCP Server with 8 tools + 4 prompts, lazy Indexer init |
+
+### CLI Entry (`src/cli.ts`)
+| Symbol | Type | Purpose |
+|--------|------|---------|
+| `main` | fn | Parses --project/--config args, starts stdio transport, handles shutdown |
 ### Rust NAPI Exports (`native/src/lib.rs`)
 | Symbol | Type | Purpose |
 |--------|------|---------|
@@ -204,6 +217,7 @@ afterEach(() => { fs.rmSync(tempDir, { recursive: true, force: true }); });
 | `commands.test.ts` | Slash command loader, frontmatter parsing |
 | `logger.test.ts` | Logger utility, metrics collection |
 
+| `mcp-server.test.ts` | MCP server: tool/prompt registration, execution via InMemoryTransport |
 ### Benchmarks
 ```bash
 npx tsx benchmarks/run.ts   # Performance testing for native operations

README.md

@@ -8,15 +8,16 @@
 
 > **Stop grepping for concepts. Start searching for meaning.**
 
-**opencode-codebase-index** brings semantic understanding to your [OpenCode](https://opencode.ai) workflow. Instead of guessing function names or grepping for keywords, ask your codebase questions in plain English.
+**opencode-codebase-index** brings semantic understanding to your [OpenCode](https://opencode.ai) workflow — and now to any MCP-compatible client like Cursor, Claude Code, and Windsurf. Instead of guessing function names or grepping for keywords, ask your codebase questions in plain English.
 
 ## 🚀 Why Use This?
 
 - 🧠 **Semantic Search**: Finds "user authentication" logic even if the function is named `check_creds`.
 - ⚡ **Blazing Fast Indexing**: Powered by a Rust native module using `tree-sitter` and `usearch`. Incremental updates take milliseconds.
 - 🌿 **Branch-Aware**: Seamlessly handles git branch switches — reuses embeddings, filters stale results.
 - 🔒 **Privacy Focused**: Your vector index is stored locally in your project.
-- 🔌 **Model Agnostic**: Works out-of-the-box with GitHub Copilot, OpenAI, Gemini, or local Ollama models.
+ 🔌 **Model Agnostic**: Works out-of-the-box with GitHub Copilot, OpenAI, Gemini, or local Ollama models.
+ 🌐 **MCP Server**: Use with Cursor, Claude Code, Windsurf, or any MCP-compatible client — index once, search from anywhere.
 
 ## ⚡ Quick Start
 
@@ -39,6 +40,52 @@
    Ask:
    > "Find the function that handles credit card validation errors"
 
+## 🌐 MCP Server (Cursor, Claude Code, Windsurf, etc.)
+
+Use the same semantic search from any MCP-compatible client. Index once, search from anywhere.
+
+1. **Install dependencies**
+   ```bash
+   npm install opencode-codebase-index @modelcontextprotocol/sdk zod
+   ```
+
+2. **Configure your MCP client**
+
+   **Cursor** (`.cursor/mcp.json`):
+   ```json
+   {
+     "mcpServers": {
+       "codebase-index": {
+         "command": "npx",
+         "args": ["opencode-codebase-index-mcp", "--project", "/path/to/your/project"]
+       }
+     }
+   }
+   ```
+
+   **Claude Code** (`claude_desktop_config.json`):
+   ```json
+   {
+     "mcpServers": {
+       "codebase-index": {
+         "command": "npx",
+         "args": ["opencode-codebase-index-mcp", "--project", "/path/to/your/project"]
+       }
+     }
+   }
+   ```
+
+3. **CLI options**
+   ```bash
+   npx opencode-codebase-index-mcp --project /path/to/repo    # specify project root
+   npx opencode-codebase-index-mcp --config /path/to/config   # custom config file
+   npx opencode-codebase-index-mcp                            # uses current directory
+   ```
+
+The MCP server exposes all 8 tools (`codebase_search`, `codebase_peek`, `find_similar`, `index_codebase`, `index_status`, `index_health_check`, `index_metrics`, `index_logs`) and 4 prompts (`search`, `find`, `index`, `status`).
+
+The MCP dependencies (`@modelcontextprotocol/sdk`, `zod`) are optional peer dependencies — they're only needed if you use the MCP server.
+
 ## 🔍 See It In Action
 
 **Scenario**: You're new to a codebase and need to fix a bug in the payment flow.
@@ -494,6 +541,8 @@ CI will automatically run tests and type checking on your PR.
 ```
 ├── src/
 │   ├── index.ts              # Plugin entry point
+│   ├── mcp-server.ts         # MCP server (Cursor, Claude Code, Windsurf)
+│   ├── cli.ts                # CLI entry for MCP stdio transport
 │   ├── config/               # Configuration schema
 │   ├── embeddings/           # Provider detection and API calls
 │   ├── indexer/              # Core indexing logic + inverted index