neo-docs-mcp
MCP server that lets an AI assistant search the NEO docs (docs.neo.crowdar.com) while it works.
It runs locally (stdio), like the other MCP servers NEO uses. The search index is not
shipped in the package: the site build publishes it as a static file
(https://docs.neo.crowdar.com/neo-docs-index.json), and the server downloads it at startup and
caches it. Publishing the docs updates what the server answers, with no new package release.
Use
{ "mcpServers": { "neo-docs": { "command": "uvx", "args": ["neo-docs-mcp"] } } }
Tools: search_docs, get_section, get_page, list_toc. Each one takes lang (es by default, or en).
Search. Every query runs BM25 and semantic search (multilingual-e5-small) and fuses them
(Reciprocal Rank Fusion). The model (~470 MB) is downloaded on the first run, in the background:
until it's loaded the server answers with BM25, then switches to hybrid on its own. --mode bm25
skips the model, for networks where it can't be downloaded.
The package is on PyPI: uvx downloads it on first use, no install step. You only need
uv.
| Option | Environment | Default |
|---|---|---|
--index |
NEO_DOCS_INDEX |
The published index (path or URL) |
--lang |
NEO_DOCS_LANG |
es |
--mode |
NEO_DOCS_SEARCH_MODE |
hybrid (BM25 until the model is loaded; bm25 skips the model) |
--cache-dir |
NEO_DOCS_CACHE_DIR |
~/.cache/neo-docs-mcp (%LOCALAPPDATA%\neo-docs-mcp on Windows) |
--http |
— | stdio; --http serves Streamable HTTP on /mcp |
| — | NEO_DOCS_MODEL_CACHE |
<cache-dir>/models (where the semantic model is stored) |
Try an unreleased version
Nothing to clone: uvx installs the package from a branch of this repository. You need
access to docs-neo on Crowdar's GitLab. To search docs that aren't in production yet, point
--index at the dev site.
# Claude Code (then open a new conversation and check /mcp)
claude mcp add -s user neo-docs -- uvx \
--from "neo-docs-mcp @ git+https://gitlab.crowdaronline.com/lippia/products/neo/docs-neo.git@develop#subdirectory=tools" \
neo-docs-mcp --index https://docs.neo.dev.crowdar.com/neo-docs-index.json
To try a feature branch, replace @develop with @<branch>. In .mcp.json (Copilot: .vscode/mcp.json,
root key servers) it's the same command split into command: "uvx" and args.
Develop locally
From the root of docs-neo (Python 3.10+):
python -m venv .venv-mcp
. .venv-mcp/bin/activate # Windows: .venv-mcp\Scripts\Activate.ps1
pip install -r requirements.txt # the site (mkdocs + i18n), to build and check pages
pip install -e "./tools[dev]" # the package, editable, plus pytest
# 1. Build the index from your local docs (both languages)
python tools/build_index.py --no-embeddings --out .cache-mcp/neo-docs-index.json # fast, BM25 only
python tools/build_index.py --out .cache-mcp/neo-docs-index.json # with embeddings (~2-3 min)
# 2. Run the server against it
neo-docs-mcp --index .cache-mcp/neo-docs-index.json # stdio, as an assistant would launch it
neo-docs-mcp --index .cache-mcp/neo-docs-index.json --http # http://127.0.0.1:8000/mcp, handy for scripts
# 3. Tests and search quality
pytest tools/tests
python tools/eval/evaluate.py --index .cache-mcp/neo-docs-index.json --misses # needs embeddings
To use your checkout from Claude Code while you work on it:
claude mcp add neo-docs-dev -- uvx --refresh --from ./tools neo-docs-mcp --index .cache-mcp/neo-docs-index.json
Gotchas
uvxcaches local builds. With--from ./toolsit may keep running an old build after you edit the code: keep--refresh(as above) or run the editable install from your venv instead.- Windows console: set
PYTHONUTF8=1if a script fails withUnicodeEncodeErrorwhile printing. - Logs go to stderr. In stdio mode stdout is the MCP channel: never
print()from the server code, uselogging. - Anchors must match the site. If you touch the chunker, rebuild the site (
mkdocs build -d .cache-mcp/site) and check that everyurl#anchorin the index exists in the generated HTML.
How it fits together
| Piece | Where | What it does |
|---|---|---|
| Index builder | build_index.py, neo_docs_search/indexer.py, blocks.py |
docs/ + mkdocs.yml → page > section > fragment, per language; anchors via Python-Markdown's toc |
| Publishing | ../Dockerfile |
mkdocs build, then build_index.py → site/neo-docs-index.json, served by nginx with the site |
| Index loading | neo_docs_search/index_source.py |
Local path or URL; user cache with ETag revalidation; works offline from the cache |
| Search | neo_docs_search/search.py, bm25.py, text.py |
BM25 (Spanish stemming + identifiers) and cosine similarity, fused with RRF; auto-merges sibling fragments |
| Semantic model | neo_docs_search/embedder.py |
multilingual-e5-small over ONNX, loaded in the background |
| MCP server | neo_docs_search/server.py, cli.py |
The four tools, stdio or Streamable HTTP |
| Evaluation | eval/questions.yaml, eval/evaluate.py |
Recall@5 per mode (BM25, dense, hybrid) |
Contributing
- Work on a branch from
developand open the MR againstdevelop. pytest tools/testsmust pass. If you change the search, runeval/evaluate.pyand put the recall numbers before/after in the MR.- Evaluation questions are the most useful contribution. Add real questions to
eval/questions.yaml(the way a user would ask, without looking at the docs) with the sections that answer them. - Bump
versioninpyproject.tomlwhen the package changes; the index format (formatin the index) only changes when the server must be updated to read it.
Metadata
Release files for neo-docs-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| neo_docs_mcp-0.1.0.tar.gz | 25.8 kB | Without provenance | Details for neo_docs_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| neo_docs_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for neo_docs_mcp-0.1.0-py3-none-any.whl |
Total release size: 51.1 kB
Release files / neo_docs_mcp-0.1.0.tar.gz
| Download URL | neo_docs_mcp-0.1.0.tar.gz |
|---|---|
| Size | 25.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5a33cf9accba3c9ff53ad57e09829fa09a066c87e4ed27eb0b9acb40bdbb8f9f
|
|
BLAKE2b-256 checksum How to use checksums |
b906de67a25c72b6b75606c9ca2f0549eff6992eb3b99e29c5915732acd2f2b1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / neo_docs_mcp-0.1.0-py3-none-any.whl
| Download URL | neo_docs_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 25.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
544a562f853fbe45ab2cdd288ad6312fbcfb40ec33865da2aa12f3a5f5ae57d3
|
|
BLAKE2b-256 checksum How to use checksums |
7825670ebe0a23ed258f6ccda0a838d53a84877da69d3dc630c5768380aa55a9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for neo-docs-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.