# ZAP RAG MCP Server

Standalone **Model Context Protocol (MCP)** server that exposes **only** ZAP’s RAG search modes for other agents (Kilo, Cursor, Claude Desktop, Continue, etc.).

Works with the SQLite index built by the [ZAP IntelliJ plugin](https://github.com/RaviTeja-438/intellij-code-rag-plugin) (`rag.db`).

| Tool | Description |
|------|-------------|
| `zap_rag_status` | DB health, chunk/embedding counts, models, modes |
| `zap_rag_search` | Semantic search: **PLAIN** / **HYBRID** / **HYBRID_RERANK** |

**Read-only.** No write tools, no agent loop — retrieval only.

## Modes

| Mode | Behavior | Needs |
|------|----------|--------|
| **PLAIN** | Cosine over code-chunk embeddings | Index + embeddings |
| **HYBRID** | Weighted class summaries + code | Class summaries at index time |
| **HYBRID_RERANK** | Hybrid pool → LLM rerank | Chat API key |

## Install

```powershell
cd zap-rag-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

## Environment

| Variable | Required | Description |
|----------|----------|-------------|
| `ZAP_DB_PATH` | **Yes** | Absolute path to ZAP `rag.db` |
| `ZAP_EMBEDDING_BASE_URL` | Yes* | OpenAI-compatible embeddings base URL |
| `ZAP_EMBEDDING_API_KEY` | Yes* | API key (`ollama` ok for local) |
| `ZAP_EMBEDDING_MODEL` | Yes* | Must match model used when indexing |
| `ZAP_CHAT_BASE_URL` | Rerank | Chat completions base |
| `ZAP_CHAT_API_KEY` | Rerank | Chat API key |
| `ZAP_CHAT_MODEL` | Rerank | Chat model name |
| `ZAP_RETRIEVAL_MODE` | No | Default mode (`PLAIN`) |
| `ZAP_TOP_K` | No | Default top_k (10) |
| `ZAP_PROJECT_PATH` | No | Scope to this project path |
| `ZAP_SEARCH_ENTIRE_DATABASE` | No | `true` = no project filter |

\* Falls back to `OPENAI_BASE_URL` / `OPENAI_API_KEY` if set.

Find the DB path in IntelliJ: **Settings → ZAP → Database path**.

## Run

```powershell
$env:ZAP_DB_PATH = "C:\path\to\rag.db"
$env:ZAP_EMBEDDING_BASE_URL = "http://127.0.0.1:11434/v1"
$env:ZAP_EMBEDDING_API_KEY = "ollama"
$env:ZAP_EMBEDDING_MODEL = "nomic-embed-text"
python server.py
```

MCP over **stdio** (no HTTP port).

## MCP host config (Kilo / Cursor / Claude Desktop)

See [`mcp.example.json`](mcp.example.json). Example:

```json
{
  "mcpServers": {
    "zap-rag": {
      "command": "C:\\path\\to\\zap-rag-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\zap-rag-mcp\\server.py"],
      "env": {
        "ZAP_DB_PATH": "C:\\path\\to\\rag.db",
        "ZAP_EMBEDDING_BASE_URL": "http://127.0.0.1:11434/v1",
        "ZAP_EMBEDDING_API_KEY": "ollama",
        "ZAP_EMBEDDING_MODEL": "nomic-embed-text"
      }
    }
  }
}
```

## Agent skill

See [`.grok/skills/searching-zap-rag/SKILL.md`](.grok/skills/searching-zap-rag/SKILL.md) (Anthropic Agent Skills: third-person description, progressive `references/`) for how coding agents should call the tools.

## Related

- IntelliJ plugin (indexing + chat UI): [intellij-code-rag-plugin](https://github.com/RaviTeja-438/intellij-code-rag-plugin)

## License

Apache-2.0