SolidOC (solidoc-solidjs-mcp)

High-performance, local FastEmbed ONNX vector + SQLite FTS5 Model Context Protocol (MCP) server for SolidJS documentation and @solid-primitives.

• Hybrid search: 384-dim BAAI/bge-small-en-v1.5 embeddings + SQLite FTS5 BM25, fixed candidate pools, deterministic rankings.
• Clean chunks: heading-aware splitting, version-badge stripping, tiny-section merging, cross-doc dedupe; every chunk fully inside the model's 512-token window (zero silent truncation).
• Native stdio: local execution, zero network ports.
• Additive-only installer: never rewrites your existing MCPs or settings.

Install (Windows and WSL — same package, simultaneously)

One wheel (py3-none-any) serves both OSes: pip resolves each platform's binaries automatically. There are no intermediate steps — upload once to PyPI, then on each OS:

pipx install solidoc-solidjs-mcp
# or: pip install solidoc-solidjs-mcp
# or: uv tool install solidoc-solidjs-mcp
solidoc install --global

pipx install solidoc-solidjs-mcp
solidoc install --global

Close OpenCode first. It holds locks on the server executable and the database; installing, uninstalling, or reinstalling while it runs will fail or half-finish.

Each OS keeps its own database, model cache, and config (see paths below). Never point the DB across the Windows/WSL boundary (/mnt/...): SQLite locking is unreliable there and both sides will corrupt or stall.

The PyPI wheel bundles a prebuilt documentation database, so there is nothing to build after install — first run copies it into place automatically. The embedding model (~130 MB) downloads itself on first use.

Per-OS paths

Usage (commands run standalone — no uv/pip prefix needed)

solidoc serve                    # boot the MCP stdio server (what OpenCode launches)
solidoc search "createSignal"    # test hybrid search in the terminal
solidoc search "query" --category primitives --limit 3
solidoc install                  # cwd-aware: repo dir -> ./opencode.jsonc, home/root -> global
solidoc install --global         # global config, from anywhere
solidoc install <path>           # explicit directory, from anywhere
solidoc uninstall                # remove entry + wipe DB + model cache (asks first)
solidoc uninstall --global --yes # same, global scope, no prompt
solidoc build --docs ./assets    # rebuild the vector DB from markdown (rare)

install is additive-only: sibling MCPs, comments, and formatting in your config are preserved (verified by test_installer.py). If your main config file is unparseable, it is backed up, left untouched, and the entry goes into a sibling opencode.json that OpenCode merges automatically.

uninstall is a full wipe of solidoc artifacts only: our config entry, the SQLite database, and our model-cache subtree. Everything else is left byte-identical. Removing the package itself is a second, separate step — and order matters: solidoc uninstall first (it needs the CLI present), pip uninstall solidoc-solidjs-mcp second. Reversed order strands the database with no tool to remove it.

Rebuilding the database

Only needed when the documentation sources change. From the source tree (assets/ lives in this repo, so clones can rebuild anywhere):

uv run solidoc build --docs ./assets --db solidoc/solidoc.db   # ~40 min, single process

Expect per-batch log lines (batch 12/57 ... rate=1.5/s); a flat 0% for the first minutes is normal (model load), but any batch stalled >5 min is not — stop it with Ctrl+C (workers exit with the terminal) and report it.

WSL validation (post-clone, no Windows crossover)

The wheel bundles one OS-portable database (relative paths, float32 blobs, cross-platform SQLite), and first run copies it into ~/.solidoc/ automatically. Inside WSL, after git clone:

pipx install solidoc-solidjs-mcp
solidoc install --global
solidoc search "createSignal" --limit 1   # warms the model (~130 MB), answers

No build, no manual copy. What stays forbidden is running two servers against one shared file across /mnt (locking) — each OS keeps its own copy. If the bundled DB ever misbehaves, fall back to a native WSL rebuild from the cloned assets/ instead.

Troubleshooting

• First search is slow: the embedding model downloads once (~130 MB), then everything is local.
• Install/uninstall errors about locked files: quit OpenCode first.
• solidoc not recognized: the install target's Scripts/bin dir is not on PATH (pipx handles this; plain pip install may need a new shell).
• Unparseable config: the installer backs it up, leaves it alone, and prints the exact block to paste manually.

Release checklist (maintainers)

1. Commit + push code to GitHub (WSL clones from here).
2. solidoc build --docs ./assets --db solidoc/solidoc.db (~40 min; the shippable DB; filepaths stored relative, no machine paths leak).
3. Commit the DB + assets/ (yes, the 35 MB binary lives in git — it is the release artifact) and push.
4. uv run python solidoc/tests/test_determinism.py
5. uv run python solidoc/tests/test_installer.py
6. uv build, then audit: wheel must contain solidoc/solidoc.db, must not contain __pycache__ (tests/ shipping inside is accepted house practice).
7. Clean-venv trial: pip install dist/*.whl in a fresh venv, solidoc serve --help exits 0, first search copies the bundled DB to the user path and answers.
8. Publish, bump version.