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.

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.

Related MCP server: ragi

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

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:

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

Register it globally for your Claude Code user:

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

Check it:

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:

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

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