Skip to main content

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

  • uvx caches local builds. With --from ./tools it 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=1 if a script fails with UnicodeEncodeError while printing.
  • Logs go to stderr. In stdio mode stdout is the MCP channel: never print() from the server code, use logging.
  • Anchors must match the site. If you touch the chunker, rebuild the site (mkdocs build -d .cache-mcp/site) and check that every url#anchor in 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 develop and open the MR against develop.
  • pytest tools/tests must pass. If you change the search, run eval/evaluate.py and 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 version in pyproject.toml when the package changes; the index format (format in 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)

Source distribution for neo-docs-mcp 0.1.0
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)

Table of built distributions (wheels) for neo-docs-mcp 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page