Metadata-Version: 2.4
Name: neo-docs-mcp
Version: 0.1.0
Summary: MCP server to search the NEO docs (docs.neo.crowdar.com) from an AI assistant.
Author: Crowdar
License-Expression: MIT
Project-URL: Homepage, https://docs.neo.crowdar.com
Project-URL: Documentation, https://docs.neo.crowdar.com/MCP/docs-neo/
Keywords: mcp,model-context-protocol,documentation,search,neo,crowdar
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<3,>=2.3
Requires-Dist: snowballstemmer>=2.2
Requires-Dist: numpy>=1.26
Requires-Dist: fastembed>=0.9
Provides-Extra: build
Requires-Dist: pyyaml>=6.0; extra == "build"
Requires-Dist: markdown>=3.6; extra == "build"
Requires-Dist: pymdown-extensions>=10.0; extra == "build"
Provides-Extra: semantic
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: neo-docs-mcp[build]; extra == "dev"
Dynamic: license-file

# 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

```json
{ "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](https://docs.astral.sh/uv/getting-started/installation/).

| 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.

```bash
# 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+):

```bash
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:

```bash
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.
