Skip to content

Commit 7495cba

Browse files
miharpmiharp
committed
Add local MCP server for the docs corpus
Add tools/mcp: a local, stdio Model Context Protocol server that exposes the OpenVox documentation to MCP-aware tools (Claude Code, Cursor, Claude Desktop) so an assistant can search and read the docs in-workflow. It is the self-hosted counterpart to a hosted "Ask AI" widget: no third party, no API key, no quota, and queries stay on the machine. The corpus is the site's llms.txt / llms-full.txt files, which already ship as machine-readable plain text with stable per-project and per-doc delimiters, so the server parses them into one document per page without scraping HTML. - corpus.py: fetch llms.txt / llms-full.txt from the live site (default) with on-disk caching and conditional requests, falling back to the last good copy when offline; OPENVOX_DOCS_SOURCE reads a local _site build instead. Parses both into structured Doc records. - search.py: BM25 keyword search (rank-bm25) over the parsed bodies, with the title weighted and a query-centered snippet. - server.py: FastMCP app exposing list_projects, list_docs, search_docs, get_doc, and refresh_corpus. Exclude tools/ from the Jekyll build so the server isn't published with the site. Signed-off-by: Michael Harp <mike@mikeharp.com>
1 parent a4a95d6 commit 7495cba

17 files changed

Lines changed: 1373 additions & 0 deletions

File tree

‎.github/workflows/mcp.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
name: MCP server
3+
4+
on:
5+
pull_request:
6+
paths:
7+
- 'tools/mcp/**'
8+
workflow_call: {}
9+
10+
permissions:
11+
contents: read
12+
13+
jobs:
14+
test:
15+
name: Python tests (${{ matrix.python-version }})
16+
runs-on: ubuntu-24.04
17+
strategy:
18+
fail-fast: false
19+
matrix:
20+
python-version: ['3.10', '3.13']
21+
defaults:
22+
run:
23+
working-directory: tools/mcp
24+
steps:
25+
- name: Checkout current PR
26+
uses: actions/checkout@v7
27+
- name: Install Python ${{ matrix.python-version }}
28+
uses: actions/setup-python@v5
29+
with:
30+
python-version: ${{ matrix.python-version }}
31+
cache: pip
32+
cache-dependency-path: tools/mcp/pyproject.toml
33+
- name: Install with dev extras
34+
run: pip install -e '.[dev]'
35+
- name: Run pytest
36+
run: pytest
37+
- name: Run the stdio smoke test
38+
run: python smoke_test.py

‎_config.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,7 @@ exclude:
173173
- Rakefile
174174
- README_WRITING.markdown
175175
- README.markdown
176+
- tools
176177
- util
177178
- vendor
178179
- WORKFLOW.md

‎tools/mcp/.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.venv/
2+
.sample-corpus/
3+
__pycache__/
4+
.pytest_cache/
5+
*.egg-info/
6+
dist/
7+
build/
8+
.coverage
9+
htmlcov/

‎tools/mcp/README.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# OpenVox Docs MCP server
2+
3+
A local [Model Context Protocol](https://modelcontextprotocol.io/) server that
4+
exposes the OpenVox documentation to MCP-aware tools (Claude Code, Cursor, Claude
5+
Desktop, …) so an assistant can search and read the docs in-workflow.
6+
7+
It is the local, self-hosted counterpart to a hosted "Ask AI" widget: no third
8+
party, no API key, no usage quota, and queries never leave your machine.
9+
10+
![Claude Code answering a question by calling the openvox-docs MCP server](demo/demo.gif)
11+
12+
> Recorded with [VHS](https://github.com/charmbracelet/vhs) from
13+
> [`demo/demo.tape`](demo/demo.tape); regenerate with `vhs tools/mcp/demo/demo.tape`.
14+
15+
## How it works
16+
17+
The server's corpus is the two machine-readable files the docs site publishes
18+
(see the repository README's "LLM-friendly documentation files" section):
19+
20+
- [`llms.txt`](https://docs.openvoxproject.org/llms.txt) — the index of pages,
21+
grouped by project.
22+
- [`llms-full.txt`](https://docs.openvoxproject.org/llms-full.txt) — the full
23+
text of every current ("latest") page, including the generated reference pages
24+
(configuration, function, type, man pages).
25+
26+
On first use it fetches both from `https://docs.openvoxproject.org`, caches them
27+
under `~/.cache/openvox-docs-mcp/` with conditional requests (so refreshes are
28+
cheap and it still works offline from the last copy), parses them into one
29+
document per page, and builds a BM25 keyword index.
30+
31+
## Tools
32+
33+
| Tool | Purpose |
34+
|------|---------|
35+
| `list_projects` | List the documentation projects (openvox, openvox-server, …). |
36+
| `list_docs(project?)` | List pages as `{project, title, url}`, optionally filtered to one project. |
37+
| `search_docs(query, project?, limit=5)` | BM25 keyword search; returns `{title, url, project, score, snippet}`. |
38+
| `get_doc(ref, max_chars=40000)` | Full text of one page, resolved by URL, URL path, or exact title. The body is capped at `max_chars` (the single-page function/type references are very large); raise it to fetch more. |
39+
| `refresh_corpus()` | Force a re-fetch of the llms files and rebuild the index. |
40+
41+
## Install
42+
43+
Requires Python 3.10+.
44+
45+
```console
46+
cd tools/mcp
47+
python -m venv .venv && . .venv/bin/activate
48+
pip install -e .
49+
```
50+
51+
## Register with an MCP client
52+
53+
All clients launch the same stdio entry point. Use the **absolute path** to the
54+
installed executable — `tools/mcp/.venv/bin/openvox-docs-mcp` after the install
55+
above (substitute your checkout path). Each client's config also accepts an `env`
56+
block if you want to set the variables from [Configuration](#configuration)
57+
(for example `OPENVOX_DOCS_SOURCE`).
58+
59+
### Claude Code
60+
61+
```console
62+
claude mcp add openvox-docs -- /path/to/tools/mcp/.venv/bin/openvox-docs-mcp
63+
```
64+
65+
Or add it to a project-scoped `.mcp.json`:
66+
67+
```json
68+
{
69+
"mcpServers": {
70+
"openvox-docs": {
71+
"command": "/path/to/tools/mcp/.venv/bin/openvox-docs-mcp"
72+
}
73+
}
74+
}
75+
```
76+
77+
### Cursor
78+
79+
Add it to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project). Cursor
80+
uses the same `mcpServers` schema as Claude Code:
81+
82+
```json
83+
{
84+
"mcpServers": {
85+
"openvox-docs": {
86+
"command": "/path/to/tools/mcp/.venv/bin/openvox-docs-mcp"
87+
}
88+
}
89+
}
90+
```
91+
92+
### GitHub Copilot (VS Code)
93+
94+
Add it to `.vscode/mcp.json` in your workspace (or run **MCP: Add Server** from
95+
the Command Palette). VS Code uses a top-level `servers` key, and stdio is the
96+
default for a `command`:
97+
98+
```json
99+
{
100+
"servers": {
101+
"openvox-docs": {
102+
"type": "stdio",
103+
"command": "/path/to/tools/mcp/.venv/bin/openvox-docs-mcp"
104+
}
105+
}
106+
}
107+
```
108+
109+
Or from the command line:
110+
111+
```console
112+
code --add-mcp '{"name":"openvox-docs","command":"/path/to/tools/mcp/.venv/bin/openvox-docs-mcp"}'
113+
```
114+
115+
### Codex CLI
116+
117+
Add it to `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`).
118+
Codex uses a `mcp_servers` TOML table:
119+
120+
```toml
121+
[mcp_servers.openvox-docs]
122+
command = "/path/to/tools/mcp/.venv/bin/openvox-docs-mcp"
123+
```
124+
125+
## Testing
126+
127+
Install the dev extras, then run the suite:
128+
129+
```console
130+
pip install -e '.[dev]'
131+
pytest
132+
```
133+
134+
The unit tests cover corpus parsing, remote fetch/caching (offline fallback and
135+
304 reuse), BM25 ranking, and every tool. For an end-to-end check that launches
136+
the server over stdio and exercises all five tools against a throwaway corpus
137+
(network- and model-free):
138+
139+
```console
140+
python smoke_test.py
141+
```
142+
143+
## Configuration
144+
145+
The server is configured entirely through environment variables:
146+
147+
| Variable | Default | Effect |
148+
|----------|---------|--------|
149+
| `OPENVOX_DOCS_BASE_URL` | `https://docs.openvoxproject.org` | Site to fetch the llms files from. |
150+
| `OPENVOX_DOCS_SOURCE` | _(unset)_ | Read `llms.txt` / `llms-full.txt` from a local directory instead of fetching. Point it at a Jekyll `_site/` build for offline or pre-release use. |
151+
152+
For example, to run against a local build of this repo:
153+
154+
```console
155+
bundle exec jekyll build
156+
OPENVOX_DOCS_SOURCE="$PWD/_site" openvox-docs-mcp
157+
```
158+
159+
> **Note:** until the `llms.txt` / `llms-full.txt` feature is deployed to the live
160+
> site, set `OPENVOX_DOCS_SOURCE` to a local `_site/` build — the live URLs will
161+
> 404 otherwise.

‎tools/mcp/demo/demo.gif‎

364 KB
Loading

‎tools/mcp/demo/demo.tape‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# VHS tape: the OpenVox docs MCP server used live from Claude Code.
2+
#
3+
# Prereqs:
4+
# - vhs installed (https://github.com/charmbracelet/vhs)
5+
# - the server registered with Claude Code (see ../README.md), e.g. pointing at
6+
# a local corpus via OPENVOX_DOCS_SOURCE
7+
# - the mcp__openvox-docs__* tools allowed (so the run isn't blocked on a
8+
# permission prompt)
9+
#
10+
# Render from the repo root:
11+
# vhs tools/mcp/demo/demo.tape
12+
13+
Output tools/mcp/demo/demo.gif
14+
15+
Require claude
16+
17+
Set Shell zsh
18+
Set FontSize 16
19+
Set Width 1200
20+
Set Height 860
21+
Set Padding 18
22+
Set Theme "Catppuccin Mocha"
23+
Set Framerate 12
24+
Set TypingSpeed 50ms
25+
26+
# Quietly land in the repo root with a clean screen.
27+
Hide
28+
Type "cd /Users/michaelharp/projects/openvox-docs && clear"
29+
Enter
30+
Sleep 1s
31+
Show
32+
33+
Type "claude"
34+
Sleep 1s
35+
Enter
36+
Sleep 8s
37+
38+
Type@35ms "Using the openvox-docs MCP server's search_docs tool, find the OpenVoxDB PostgreSQL configuration page. Reply with only the page title and URL on one line."
39+
Sleep 1s
40+
Enter
41+
42+
# Wait for the model to call search_docs and write its (one-line) answer.
43+
Sleep 35s
44+
45+
# Hold on the finished answer.
46+
Sleep 3s

‎tools/mcp/openvox_docs_mcp/__init__.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
"""Local MCP server exposing the OpenVox documentation corpus."""
2+
3+
from .server import main, mcp
4+
5+
__all__ = ["main", "mcp"]

‎tools/mcp/openvox_docs_mcp/__main__.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
from .server import main
2+
3+
if __name__ == "__main__":
4+
main()

0 commit comments

Comments
 (0)