Oli Docs MCP

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

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.

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

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

Find the executable path:

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

Register it globally for your Claude Code user:

claude mcp add --scope user oli-docs-mcp -- /absolute/path/to/oli-docs-mcp/.venv/bin/oli-docs-mcp

Check it:

claude mcp list

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

OpenCode / August Setup

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

{
  "$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/August 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:

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:

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:

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:

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