moderngl-docs-mcp

moderngl-docs-mcp

A hybrid (FTS5 keyword + vector semantic) MCP search server for ModernGL documentation (legaly take from context7 👀 , pls don't sue me). Combines SQLite FTS5 and sqlite-vec k-NN search, fused via Reciprocal Rank Fusion, behind a single search_docs MCP tool.

Why hybrid search

A keyword index (FTS5/BM25) finds documents that share literal words with the query. A vector index (embedding similarity) finds documents that are semantically close, even with no shared vocabulary. Real documentation questions span both. This project runs both signals on every query and fuses their rankings.

What you get

• search_docs(query, limit=5, doc_type=None) — hybrid search tool. doc_type="code" restricts to runnable examples, doc_type="info" restricts to conceptual/API explanations.
• docs://index — a resource listing every indexed section and its id.
• docs://{doc_id} — a resource fetching one section's full content by id.
• build_moderngl_app — a guided prompt that walks an agent through searching docs before writing code.

Install

pip install -e .

This installs the moderngl-docs-mcp command (the MCP server itself) and the ingestion CLI as a Python module.

First run: build the database

The server needs an ingested SQLite database before it can answer queries. Point the ingestion CLI at your dump file(s):

python -m moderngl_docs_mcp.ingestion.cli moderngl_code_docs.txt code moderngl_info_docs.txt info

This bootstraps moderngl_docs.db in the current directory, downloads the embedding model on first run (mixedbread-ai/mxbai-embed-xsmall-v1, ~30MB, cached locally afterward), and ingests both dump files.

Run the server directly (for testing)

moderngl-docs-mcp

MCP servers communicate over stdin/stdout with a client. Use an MCP client or MCP Inspector for manual testing:

npx @modelcontextprotocol/inspector moderngl-docs-mcp

Configure your MCP client

VS Code

Workspace-scoped: create .vscode/mcp.json in the project root:

{
  "servers": {
    "moderngl-docs": {
      "type": "stdio",
      "command": "moderngl-docs-mcp"
    }
  }
}

If moderngl-docs-mcp isn't on your system PATH (e.g. installed inside a virtualenv), use the full interpreter path instead:

{
  "servers": {
    "moderngl-docs": {
      "type": "stdio",
      "command": "/full/path/to/your/venv/bin/moderngl-docs-mcp"
    }
  }
}

Claude Desktop

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "moderngl-docs": {
      "command": "moderngl-docs-mcp"
    }
  }
}

Cursor

Add to .cursor/mcp.json (project) or your global Cursor MCP settings:

{
  "mcpServers": {
    "moderngl-docs": {
      "command": "moderngl-docs-mcp"
    }
  }
}

Development

pip install -e .
pip install pytest pytest-asyncio sqlite-vec sentence-transformers pyyaml
pytest -v

Run benchmarks

python scripts/run_benchmarks.py

Re-runs the labeled query set in docs/benchmarks/queries.yaml against your real, ingested database.

python scripts/run_benchmarks.py --diagnose "your query" --expected-title "Exact Section Title"

Project structure

src/moderngl_docs_mcp/
├── ingestion/    parser.py + ingest.py + cli.py
├── retrieval/    query.py + fusion.py
├── services/     search.py
├── storage/      schema.sql + db.py
└── server.py     FastMCP tool/resource/prompt registration

docs/
├── architecture/ARCHITECTURE.md
├── benchmarks/BENCHMARKS.md
└── benchmarks/FUTURE-RERANKING.md

scripts/run_benchmarks.py
tests/

License

MIT