opencode-codebase-index 0.4.1 → 0.5.1

package/README.md

@@ -8,7 +8,7 @@
 
 > **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?
 
@@ -17,6 +17,7 @@
 - 🌿 **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.
+- 🌐 **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.
@@ -131,6 +178,7 @@ graph TD
 - **Native speed**: Core logic written in Rust for maximum performance
 - **Memory efficient**: F16 vector quantization reduces index size by 50%
 - **Branch-aware**: Automatically tracks which chunks exist on each git branch
+- **Provider validation**: Detects embedding provider/model changes and requires rebuild to prevent garbage results
 
 ## 🌿 Branch-Aware Indexing
 
@@ -267,7 +315,7 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `embeddingProvider` | `"auto"` | Which AI to use: `auto`, `github-copilot`, `openai`, `google`, `ollama` |
+| `embeddingProvider` | `"auto"` | Which AI to use: `auto`, `github-copilot`, `openai`, `google`, `ollama`, `custom` |
 | `scope` | `"project"` | `project` = index per repo, `global` = shared index across repos |
 | **indexing** | | |
 | `autoIndex` | `false` | Automatically index on plugin load |
@@ -303,6 +351,8 @@ The plugin automatically detects available credentials in this order:
 3. **Google** (Gemini Embeddings)
 4. **Ollama** (Local/Private - requires `nomic-embed-text`)
 
+You can also use **Custom** to connect any OpenAI-compatible embedding endpoint (llama.cpp, vLLM, text-embeddings-inference, LiteLLM, etc.).
+
 ### Rate Limits by Provider
 
 Each provider has different rate limits. The plugin automatically adjusts concurrency and delays:
@@ -313,6 +363,7 @@ Each provider has different rate limits. The plugin automatically adjusts concur
 | **OpenAI** | 3 | 500ms | Medium codebases |
 | **Google** | 5 | 200ms | Medium-large codebases |
 | **Ollama** | 5 | None | Large codebases (10k+ files) |
+| **Custom** | 3 | 1s | Any OpenAI-compatible endpoint |
 
 **For large codebases**, use Ollama locally to avoid rate limits:
 
@@ -412,6 +463,7 @@ Use this decision tree to pick the right embedding provider:
 | **GitHub Copilot** | Slow (rate limited) | Free* | Cloud | Small codebases, existing subscribers |
 | **OpenAI** | Medium | ~$0.0001/1K tokens | Cloud | General use |
 | **Google** | Fast | Free tier available | Cloud | Medium-large codebases |
+| **Custom** | Varies | Varies | Varies | Self-hosted or third-party endpoints |
 
 *Requires active Copilot subscription
 
@@ -447,6 +499,23 @@ No setup needed if you have an active Copilot subscription.
 { "embeddingProvider": "github-copilot" }
 ```
 
+**Custom (OpenAI-compatible)**
+Works with any server that implements the OpenAI `/v1/embeddings` API format (llama.cpp, vLLM, text-embeddings-inference, LiteLLM, etc.).
+```json
+{
+  "embeddingProvider": "custom",
+  "customProvider": {
+    "baseUrl": "http://localhost:11434/v1",
+    "model": "nomic-embed-text",
+    "dimensions": 768,
+    "apiKey": "optional-api-key",
+    "maxTokens": 8192,
+    "timeoutMs": 30000
+  }
+}
+```
+Required fields: `baseUrl`, `model`, `dimensions` (positive integer). Optional: `apiKey`, `maxTokens`, `timeoutMs` (default: 30000).
+
 ## ⚠️ Tradeoffs
 
 Be aware of these characteristics:
@@ -493,6 +562,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
@@ -520,6 +591,20 @@ The Rust native module handles performance-critical operations:
 
 Rebuild with: `npm run build:native` (requires Rust toolchain)
 
+### Platform Support
+
+Pre-built native binaries are published for:
+
+| Platform | Architecture | SIMD Acceleration |
+|----------|-------------|--------------------|
+| macOS | x86_64 | ✅ simsimd |
+| macOS | ARM64 (Apple Silicon) | ✅ simsimd |
+| Linux | x86_64 (GNU) | ✅ simsimd |
+| Linux | ARM64 (GNU) | ✅ simsimd |
+| Windows | x86_64 (MSVC) | ❌ scalar fallback |
+
+Windows builds use scalar distance functions instead of SIMD — functionally identical, marginally slower for very large indexes. This is due to MSVC lacking support for certain AVX-512 intrinsics used by simsimd.
+
 ## License
 
 MIT