# grp-kb-mcp

Semantic search MCP server for the Acumatica KB Obsidian vault.  
Reuses the embeddings already computed by the Smart Connections plugin (`TaylorAI/bge-micro-v2`, 384-dim).

Published as `grp-kb-mcp` on PyPI (the import package stays `kb_mcp`). Note: unlike a
turnkey library, this still requires an Obsidian vault with Smart Connections embeddings
already computed — installing from PyPI saves you the `git clone` + editable-install step,
not the vault/index setup below.

## Tools

| Tool | What it does |
|------|-------------|
| `search_kb(query, top_k, source_only, guide_filter)` | Semantic search — embed query, cosine-search ~89k vectors, return top results with snippet |
| `read_kb_file(path)` | Read full content of a KB file by relative path |

## Setup

### 1. Install

```bash
cd path\to\kb-mcp
python -m venv .venv
.venv\Scripts\activate
pip install -e .
```

### 2. Build the index (run once, ~2 min)

```bash
# with .venv active, from the kb-mcp folder:
set KB_VAULT_DIR=path\to\Acumatica-KB
python -m kb_mcp.build_index
```

This creates `kb_index.npy` and `kb_meta.json` inside `src\kb_mcp\`.  
Re-run only if you add new notes to the vault (and re-index in Obsidian Smart Connections first).

#### Multiple vaults

The index can ingest extra Smart Connections vaults alongside the primary one via
`KB_EXTRA_VAULTS` — a `;`-separated list of `LABEL=PATH` pairs. Each extra vault's
records get `guide=LABEL` (so `search_kb(..., guide_filter="GRP")` isolates them)
and an absolute `vault_root` baked into the metadata, so **the server needs no extra
env** — it reads those files from the baked-in root. Records under `copilot/` are
skipped as plugin cruft.

```powershell
$env:KB_VAULT_DIR    = "C:\...\Acumatica-KB"
$env:KB_EXTRA_VAULTS = "GRP=C:\...\GRPUserManuals-Markdown"
python -m kb_mcp.build_index
```

Or just run `.\rebuild.ps1` (has both vault paths baked in). **Restart the kb-mcp
server afterward** — it loads the index once at startup.

### 3. Register with Claude Desktop

Add to `claude_desktop_config.json` (found at `%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "kb-mcp": {
      "command": "C:\\path\\to\\kb-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "kb_mcp.server"],
      "env": {
        "KB_VAULT_DIR": "C:\\path\\to\\Acumatica-KB"
      }
    }
  }
}
```

Restart Claude after adding.

### 4. First query (model download)

The `TaylorAI/bge-micro-v2` model (~45 MB) downloads automatically on the first `search_kb` call and is cached locally by HuggingFace.

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `KB_VAULT_DIR` | auto-detected | Path to the Acumatica-KB vault folder |
| `KB_MCP_INDEX_DIR` | `src/kb_mcp/` | Where `kb_index.npy` and `kb_meta.json` live |
| `KB_SNIPPET_LINES` | `30` | Lines to include in each result snippet |