Metadata-Version: 2.3
Name: solidoc-solidjs-mcp
Version: 0.2.0
Summary: High-performance, local FastEmbed vector MCP server for SolidJS documentation
Author: Nitin
Author-email: Nitin <pypi@600613017.xyz>
License: MIT
Requires-Dist: mcp>=1.2.0,<2.0.0
Requires-Dist: fastembed>=0.4.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pydantic>=2.7.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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:

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

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

| What                  | Windows                                            | WSL / Linux                          |
|-----------------------|----------------------------------------------------|--------------------------------------|
| Server executable     | pipx venv `Scripts\solidoc.EXE` (on PATH)          | pipx venv `bin/solidoc` (on PATH)    |
| Vector database       | `%USERPROFILE%\.solidoc\solidoc.db`                | `~/.solidoc/solidoc.db`              |
| Embedding model cache | `%TEMP%\fastembed_cache`                           | `$TMPDIR/fastembed_cache` or `~/.cache/fastembed` |
| Global MCP config     | `%USERPROFILE%\.config\opencode\opencode.jsonc`    | `~/.config/opencode/opencode.jsonc`  |
| Repo-local MCP config | `<repo>\opencode.jsonc`                            | `<repo>/opencode.jsonc`              |

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

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

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

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