# Oli Docs MCP

Local MCP server for querying the official Oli / LimX documentation from Claude Code or OpenCode.

The repo ships with:
- Clean markdown sources for the three official docs.
- A SQLite FTS index at `index/corpus.sqlite`.
- A local vector index at `index/vectors.npz`.
- MCP tools: `list_docs`, `search`, `get_section`, `cite`.

## Install

Clone the repo, then create a local Python virtual environment. Python 3.10 or newer is required.

```bash
git clone https://github.com/33may/oli-docs-mcp.git
cd oli-docs-mcp

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
```

The first vector query may load the bundled embedding model from the local Hugging Face cache if already present, or download `sentence-transformers/all-MiniLM-L6-v2` if it is not cached yet.

## Quick Test

```bash
source .venv/bin/activate
python -c "from oli_corpus_mcp.tools import search; print(search('MCP tool interface', mode='hybrid', top_k=3))"
```

Expected: at least one result with `doc_id == "sdk-guide"` and a citation starting with `oli-corpus://sdk-guide#`.

## Claude Code Setup

Install the repo first, then register the local MCP server with Claude Code. Installation alone does not automatically add the server to Claude Code.

Find the executable path:

```bash
source .venv/bin/activate
which oli-docs-mcp
```

Register it globally for your Claude Code user:

```bash
claude mcp add --scope user oli-docs-mcp -- "$PWD/.venv/bin/oli-docs-mcp"
```

Check it:

```bash
claude mcp list
```

Restart Claude Code if the tools do not appear in an already-open session.

If an agent is setting this up for you, ask it to clone the repo, run the install commands above, run the quick test, register Claude Code with the `claude mcp add` command above, and verify with `claude mcp list`.

## OpenCode Setup

Add this to `~/.config/opencode/opencode.jsonc`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "oli-docs-mcp": {
      "type": "local",
      "command": ["/absolute/path/to/oli-docs-mcp/.venv/bin/oli-docs-mcp"],
      "enabled": true
    }
  }
}
```

Restart OpenCode after editing config.

## Tools

### `list_docs()`

Returns the three bundled official docs.

### `search(query, top_k=10, doc_id=None, include_notes=False, mode="fts")`

Modes:
- `fts`: SQLite FTS5/BM25 keyword search. This is the default.
- `vector`: local semantic search over `index/vectors.npz`.
- `hybrid`: deterministic fusion of FTS and vector rankings.

Example:

```python
search(query="how can an assistant control Oli through tools", mode="vector", top_k=5)
```

### `get_section(doc_id, section, part=None)`

Returns the full markdown chunk and citation.

Example:

```python
get_section(doc_id="sdk-guide", section="3.3")
```

### `cite(doc_id, section, part=None)`

Returns the canonical citation URI and source file path.

Example:

```python
cite(doc_id="sdk-guide", section="3.3")
```

## Citation Rule

When using this MCP for Oli facts, cite the returned `oli-corpus://...` URI. If no supporting source is found, say that no source was found.

The citation URI is intentionally still `oli-corpus://...` because it is the stable source contract for this documentation corpus, even though this GitHub repo and MCP server are named `oli-docs-mcp`.

## Rebuild Index

The repo includes a prebuilt index, so this is optional:

```bash
source .venv/bin/activate
python scripts/build_index.py
```