# grp-kb

Semantic search MCP server for an Acumatica knowledge base. Single index over
one vault of markdown notes, embedded with the multilingual
`paraphrase-multilingual-MiniLM-L12-v2` — handles both English content and
Bahasa Malaysia content (e.g. GRP manuals) well, so a query in either
language can find the right doc in either language.

No Obsidian, no Smart Connections plugin, anywhere in this pipeline — the
index is built directly from plain `.md` files with `sentence-transformers`.

This package ships **code only**. It needs a real, pre-built vault + index
pair to do anything useful — either build your own (see below) or get one
shared from someone who already has it (just the `.md` vault + `kb_index.npy`
/ `kb_meta.json`, no re-embedding needed on the receiving end).

**Note on mixed-content corpora:** if your vault has a small, distinctly-tagged
subset (e.g. `guide: GRP-Manual` in frontmatter) mixed into a much larger
general corpus, that subset can get outranked by volume on any topic that
exists in both — unfiltered search may return zero of the small subset's
results even in the top 15, regardless of query wording. Use `guide_filter`
to force results from that subset when you know that's what you want; the
`search_kb` tool description already tells a calling LLM when to do this.

## Build an index

```bash
export KB_VAULT_DIR=/path/to/vault
export KB_MCP_INDEX_DIR=/path/to/index
python -m grp_kb.build_index
```

Optional env vars: `KB_FILE_GLOB` (default `*.md`) to scope which files get
indexed, `KB_EMBED_MODEL` (default `paraphrase-multilingual-MiniLM-L12-v2`) to
use a different sentence-transformers model.

## Run the server

```bash
export KB_VAULT_DIR=/path/to/vault
export KB_INDEX_DIR=/path/to/index
grp-kb
```

## Register with Claude Code

```bash
claude mcp add grp-kb -s user \
  -e KB_VAULT_DIR=/path/to/vault \
  -e KB_INDEX_DIR=/path/to/index \
  -- grp-kb
```

## Tools

- `search_kb(query, top_k=10, source_only=False, guide_filter="")` — returns a
  JSON array of results (score, path, heading, title, breadcrumb, forms,
  guide, snippet).
- `read_kb_file(path)` — full markdown content by relative path (as returned
  by `search_kb`).