cfunklabs-rag-react-docs 0.1.3__tar.gz → 0.1.4__tar.gz

{cfunklabs_rag_react_docs-0.1.3 → cfunklabs_rag_react_docs-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cfunklabs-rag-react-docs
-Version: 0.1.3
+Version: 0.1.4
 Summary: Retrieval-only MCP server over the indexed React documentation, with a prebuilt index downloaded on first run.
 Project-URL: Homepage, https://github.com/cfunklabs/rag-react-docs
 Project-URL: Repository, https://github.com/cfunklabs/rag-react-docs
@@ -150,12 +150,19 @@ collection.
 
 In addition to the CLI, the retrieval pipeline is exposed as an [MCP](https://modelcontextprotocol.io/)
 server over stdio, so MCP clients (Cursor, Claude Desktop, etc.) can pull grounding context
-directly. It exposes a single **retrieval-only** tool:
+directly. The server ships prescriptive metadata — a server-level instructions block plus a
+richly documented tool — so a consuming LLM knows when to reach for it (any React 19.2 API,
+hook, component, or pattern question) instead of relying on its own possibly-stale knowledge.
+It exposes a single **retrieval-only** tool:
 
-- `search_docs(question, k?)` — embeds the question with the same model used at ingestion,
+- `search_react_docs(question, k?)` — embeds the question with the same model used at ingestion,
   retrieves the most similar chunks from ChromaDB, and returns each chunk's `source` label,
   `content`, and retrieval `distance`. The client LLM generates the answer from those chunks,
   so no Anthropic key is needed to run the server.
+  - `question` should be a full natural-language question, not bare keywords.
+  - `k` defaults to `RAG_TOP_K` (5); use ~3 for a specific API lookup and ~8-10 for broad topics.
+  - `distance` is squared L2 over normalized embeddings, so **lower is more similar**. For this
+    corpus, `< ~1.0` is relevant and `> ~1.5` usually means off-topic / not covered.
 
 #### For end users (published package)
 
@@ -195,35 +202,72 @@ press Ctrl+C to stop.
 Run `uv run main.py` first — the dev server needs a populated collection. For interactive
 testing, launch the MCP Inspector with `uv run mcp dev mcp_server.py`.
 
-### Publishing to PyPI
+### Releasing
 
 The published package (`cfunklabs-rag-react-docs`) contains only the retrieval + MCP server
 (the import package `rag_react_docs` under `src/`). Ingestion/query tooling and `src/utils/*`
 are dev-only and excluded from the wheel.
 
-Two artifacts get published: the Python package (to PyPI) and the prebuilt index (to a GitHub
-Release). They version independently — the index version is pinned as `INDEX_VERSION` in
-[src/rag_react_docs/config.py](src/rag_react_docs/config.py).
+A release involves two independently-versioned artifacts:
 
-1. Build and upload the index archive (after `uv run main.py` has populated `rag_datastore`):
+- The **PyPI package**, published **automatically** by CI when you push a `v*` git tag. The
+  [.github/workflows/publish.yml](../.github/workflows/publish.yml) workflow builds the wheel/sdist
+  and uploads them to PyPI using [trusted publishing](https://docs.pypi.org/trusted-publishers/)
+  (OIDC) — no API tokens or secrets are involved.
+- The **prebuilt index**, uploaded **manually** to a GitHub Release, and only when the corpus
+  changes. Its version is `INDEX_VERSION` in [src/rag_react_docs/config.py](src/rag_react_docs/config.py),
+  independent of the package version.
+
+The `v*` tag drives PyPI and the `index-*` tag drives the index download; they never trigger each
+other (the workflow filters `v*`).
+
+#### Release checklist
+
+**Step 1 - Increment the package version.** Bump the version in BOTH
+[pyproject.toml](pyproject.toml) (`version`) and
+[src/rag_react_docs/__init__.py](src/rag_react_docs/__init__.py) (`__version__`), keeping them in
+sync. PyPI rejects re-uploads of an existing version, so this must change every release.
+
+**Step 2 - Build and upload the index (only if the docs, chunking, or embeddings changed).** Most
+code-only releases skip this step. If the index content changed, bump `REACT_VERSION` and/or
+`INDEX_REVISION` in [src/rag_react_docs/config.py](src/rag_react_docs/config.py) first, then:
 
 ```bash
+uv run main.py                     # repopulate rag_datastore (needs docs fetched + ANTHROPIC_API_KEY)
 uv run scripts/build_index_archive.py
 gh release create index-19-2-v1 dist/rag-index-19-2-v1.tar.gz dist/rag-index-19-2-v1.tar.gz.sha256
 ```
 
-2. Build and publish the package (test on TestPyPI first):
+Upload the index **before** publishing the package release, so the new package's `INDEX_URL`
+resolves for end users on first run.
+
+The index version follows the standard `index-<react-version>-v<incremental>` (e.g.
+`index-19-2-v1`), composed from `REACT_VERSION` and `INDEX_REVISION`. Bump `REACT_VERSION` when
+re-fetching the docs for a new React release, and bump `INDEX_REVISION` for re-chunk or
+embedding-model changes within the same React version. Either bump changes the release tag/asset
+name and the client cache path, so clients pull a fresh, compatible index instead of reusing a
+stale cache.
+
+**Step 3 - (Optional) Local build sanity check.** This verifies the wheel/sdist build; it is not
+the publish mechanism (CI builds too). Artifacts land in the gitignored `dist/`.
 
 ```bash
-uv build                                   # -> dist/ wheel + sdist (only rag_react_docs)
-uv publish --publish-url https://test.pypi.org/legacy/   # TestPyPI dry run
-uv publish                                 # PyPI
+uv build
 ```
 
-The index version follows the standard `index-<react-version>-v<incremental>` (e.g.
-`index-19-2-v1`), composed in [src/rag_react_docs/config.py](src/rag_react_docs/config.py) from
-`REACT_VERSION` and `INDEX_REVISION`. Bump `REACT_VERSION` when re-fetching the docs for a new
-React release, and bump `INDEX_REVISION` for re-chunk or embedding-model changes within the same
-React version. Either bump changes the release tag/asset name and cache path, so clients pull a
-fresh, compatible index instead of reusing a stale cache — re-release the archive under the new
-`index-<react-version>-v<incremental>` tag.
+**Step 4 - Publish by tagging.** Commit the version bump, then tag and push. The `v*` tag triggers
+CI, which builds and publishes to PyPI automatically:
+
+```bash
+git commit -am "Release v0.1.3"
+git tag -a v0.1.3 -m "Release v0.1.3"
+git push origin main --tags
+```
+
+After the workflow finishes, verify the new version at
+[pypi.org/project/cfunklabs-rag-react-docs](https://pypi.org/project/cfunklabs-rag-react-docs/), and
+(if you re-released the index) that the index asset URL returns `200`.
+
+> Manual publishing (`uv publish`) is not the standard path: trusted publishing is configured for
+> CI only, so a local upload would require a separate API token and bypass the pinned `pypi`
+> environment. Prefer the tag-driven flow above.

{cfunklabs_rag_react_docs-0.1.3 → cfunklabs_rag_react_docs-0.1.4}/README.md

@@ -129,12 +129,19 @@ collection.
 
 In addition to the CLI, the retrieval pipeline is exposed as an [MCP](https://modelcontextprotocol.io/)
 server over stdio, so MCP clients (Cursor, Claude Desktop, etc.) can pull grounding context
-directly. It exposes a single **retrieval-only** tool:
+directly. The server ships prescriptive metadata — a server-level instructions block plus a
+richly documented tool — so a consuming LLM knows when to reach for it (any React 19.2 API,
+hook, component, or pattern question) instead of relying on its own possibly-stale knowledge.
+It exposes a single **retrieval-only** tool:
 
-- `search_docs(question, k?)` — embeds the question with the same model used at ingestion,
+- `search_react_docs(question, k?)` — embeds the question with the same model used at ingestion,
   retrieves the most similar chunks from ChromaDB, and returns each chunk's `source` label,
   `content`, and retrieval `distance`. The client LLM generates the answer from those chunks,
   so no Anthropic key is needed to run the server.
+  - `question` should be a full natural-language question, not bare keywords.
+  - `k` defaults to `RAG_TOP_K` (5); use ~3 for a specific API lookup and ~8-10 for broad topics.
+  - `distance` is squared L2 over normalized embeddings, so **lower is more similar**. For this
+    corpus, `< ~1.0` is relevant and `> ~1.5` usually means off-topic / not covered.
 
 #### For end users (published package)
 
@@ -174,35 +181,72 @@ press Ctrl+C to stop.
 Run `uv run main.py` first — the dev server needs a populated collection. For interactive
 testing, launch the MCP Inspector with `uv run mcp dev mcp_server.py`.
 
-### Publishing to PyPI
+### Releasing
 
 The published package (`cfunklabs-rag-react-docs`) contains only the retrieval + MCP server
 (the import package `rag_react_docs` under `src/`). Ingestion/query tooling and `src/utils/*`
 are dev-only and excluded from the wheel.
 
-Two artifacts get published: the Python package (to PyPI) and the prebuilt index (to a GitHub
-Release). They version independently — the index version is pinned as `INDEX_VERSION` in
-[src/rag_react_docs/config.py](src/rag_react_docs/config.py).
+A release involves two independently-versioned artifacts:
 
-1. Build and upload the index archive (after `uv run main.py` has populated `rag_datastore`):
+- The **PyPI package**, published **automatically** by CI when you push a `v*` git tag. The
+  [.github/workflows/publish.yml](../.github/workflows/publish.yml) workflow builds the wheel/sdist
+  and uploads them to PyPI using [trusted publishing](https://docs.pypi.org/trusted-publishers/)
+  (OIDC) — no API tokens or secrets are involved.
+- The **prebuilt index**, uploaded **manually** to a GitHub Release, and only when the corpus
+  changes. Its version is `INDEX_VERSION` in [src/rag_react_docs/config.py](src/rag_react_docs/config.py),
+  independent of the package version.
+
+The `v*` tag drives PyPI and the `index-*` tag drives the index download; they never trigger each
+other (the workflow filters `v*`).
+
+#### Release checklist
+
+**Step 1 - Increment the package version.** Bump the version in BOTH
+[pyproject.toml](pyproject.toml) (`version`) and
+[src/rag_react_docs/__init__.py](src/rag_react_docs/__init__.py) (`__version__`), keeping them in
+sync. PyPI rejects re-uploads of an existing version, so this must change every release.
+
+**Step 2 - Build and upload the index (only if the docs, chunking, or embeddings changed).** Most
+code-only releases skip this step. If the index content changed, bump `REACT_VERSION` and/or
+`INDEX_REVISION` in [src/rag_react_docs/config.py](src/rag_react_docs/config.py) first, then:
 
 ```bash
+uv run main.py                     # repopulate rag_datastore (needs docs fetched + ANTHROPIC_API_KEY)
 uv run scripts/build_index_archive.py
 gh release create index-19-2-v1 dist/rag-index-19-2-v1.tar.gz dist/rag-index-19-2-v1.tar.gz.sha256
 ```
 
-2. Build and publish the package (test on TestPyPI first):
+Upload the index **before** publishing the package release, so the new package's `INDEX_URL`
+resolves for end users on first run.
+
+The index version follows the standard `index-<react-version>-v<incremental>` (e.g.
+`index-19-2-v1`), composed from `REACT_VERSION` and `INDEX_REVISION`. Bump `REACT_VERSION` when
+re-fetching the docs for a new React release, and bump `INDEX_REVISION` for re-chunk or
+embedding-model changes within the same React version. Either bump changes the release tag/asset
+name and the client cache path, so clients pull a fresh, compatible index instead of reusing a
+stale cache.
+
+**Step 3 - (Optional) Local build sanity check.** This verifies the wheel/sdist build; it is not
+the publish mechanism (CI builds too). Artifacts land in the gitignored `dist/`.
 
 ```bash
-uv build                                   # -> dist/ wheel + sdist (only rag_react_docs)
-uv publish --publish-url https://test.pypi.org/legacy/   # TestPyPI dry run
-uv publish                                 # PyPI
+uv build
 ```
 
-The index version follows the standard `index-<react-version>-v<incremental>` (e.g.
-`index-19-2-v1`), composed in [src/rag_react_docs/config.py](src/rag_react_docs/config.py) from
-`REACT_VERSION` and `INDEX_REVISION`. Bump `REACT_VERSION` when re-fetching the docs for a new
-React release, and bump `INDEX_REVISION` for re-chunk or embedding-model changes within the same
-React version. Either bump changes the release tag/asset name and cache path, so clients pull a
-fresh, compatible index instead of reusing a stale cache — re-release the archive under the new
-`index-<react-version>-v<incremental>` tag.
+**Step 4 - Publish by tagging.** Commit the version bump, then tag and push. The `v*` tag triggers
+CI, which builds and publishes to PyPI automatically:
+
+```bash
+git commit -am "Release v0.1.3"
+git tag -a v0.1.3 -m "Release v0.1.3"
+git push origin main --tags
+```
+
+After the workflow finishes, verify the new version at
+[pypi.org/project/cfunklabs-rag-react-docs](https://pypi.org/project/cfunklabs-rag-react-docs/), and
+(if you re-released the index) that the index asset URL returns `200`.
+
+> Manual publishing (`uv publish`) is not the standard path: trusted publishing is configured for
+> CI only, so a local upload would require a separate API token and bypass the pinned `pypi`
+> environment. Prefer the tag-driven flow above.

{cfunklabs_rag_react_docs-0.1.3 → cfunklabs_rag_react_docs-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cfunklabs-rag-react-docs"
-version = "0.1.3"
+version = "0.1.4"
 description = "Retrieval-only MCP server over the indexed React documentation, with a prebuilt index downloaded on first run."
 readme = "README.md"
 requires-python = ">=3.14"

{cfunklabs_rag_react_docs-0.1.3 → cfunklabs_rag_react_docs-0.1.4}/src/rag_react_docs/__init__.py

@@ -5,4 +5,4 @@ ChromaDB index is downloaded from a GitHub Release on first run (see `datastore.
 users never run the ingestion pipeline themselves.
 """
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"

{cfunklabs_rag_react_docs-0.1.3 → cfunklabs_rag_react_docs-0.1.4}/src/rag_react_docs/config.py

@@ -27,6 +27,10 @@ REACT_VERSION = "19-2"
 INDEX_REVISION = "v1"
 INDEX_VERSION = f"{REACT_VERSION}-{INDEX_REVISION}"
 
+# Human-readable React version (e.g. "19.2") for user/LLM-facing strings like the tool
+# description and server instructions. Derived from REACT_VERSION so there's one source of truth.
+REACT_VERSION_LABEL = REACT_VERSION.replace("-", ".")
+
 # The prebuilt index is published as a GitHub Release asset. A sibling `<archive>.sha256` file
 # is fetched alongside it to verify the download before extraction.
 _DEFAULT_INDEX_URL = (

cfunklabs_rag_react_docs-0.1.4/src/rag_react_docs/server.py

@@ -0,0 +1,138 @@
+"""MCP server exposing the RAG retrieval pipeline over stdio.
+
+Published as the `cfunklabs-rag-react-docs` console script (`uvx cfunklabs-rag-react-docs`). It
+exposes a single `search_react_docs` tool that performs *retrieval only* against the downloaded
+ChromaDB collection and returns the top-k chunks with their source/heading labels. The
+consuming LLM (Cursor, Claude Desktop, etc.) ingests those chunks and generates its own
+grounded answer, so no Anthropic API key or generation stack is needed server-side.
+"""
+
+import sys
+from typing import TypedDict
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+
+from .config import DEFAULT_TOP_K, INDEX_URL, INDEX_VERSION, REACT_VERSION_LABEL
+from .datastore import get_rag_collection
+from .retrieval import retrieve_chunks
+
+
+# Surfaced to MCP clients as the server's usage guidance. Kept prescriptive so a consuming LLM
+# reaches for this tool instead of relying on its own (possibly stale) React knowledge.
+SERVER_INSTRUCTIONS = f"""\
+Semantic search over the official React documentation (React {REACT_VERSION_LABEL}, index \
+{INDEX_VERSION}).
+
+Use the `search_react_docs` tool whenever a task touches React itself -- hooks, built-in \
+components, APIs, rendering/effects behavior, or idiomatic patterns -- instead of answering \
+from the model's own training data, which may be stale or version-mismatched. It is the \
+authoritative source for React {REACT_VERSION_LABEL} in this session.
+
+The server is retrieval-only: `search_react_docs` returns ranked documentation chunks and the \
+client composes the grounded answer. Always cite the `source` label of each chunk you rely on \
+so the user can trace claims back to the docs."""
+
+
+mcp = FastMCP("rag-react-docs", instructions=SERVER_INSTRUCTIONS)
+
+
+class SearchResult(TypedDict):
+    """One retrieved documentation chunk.
+
+    - source:   human-readable provenance label (file path > heading path) for citation
+    - content:  the raw chunk text to ground an answer on
+    - distance: retrieval distance (squared L2 over normalized embeddings; lower is more similar)
+    """
+
+    source: str
+    content: str
+    distance: float | None
+
+
+def _index_error() -> str | None:
+    """Return a human-readable reason the index is unavailable, or None if it's ready.
+
+    Distinguishes a real load/download failure (surfacing the underlying exception and the
+    URL it tried) from a genuinely empty collection, so callers report the actual cause rather
+    than a catch-all "index is empty" message.
+    """
+    try:
+        count = get_rag_collection().count()
+    except Exception as exc:
+        return (
+            f"Could not load the documentation index (downloaded from {INDEX_URL}): "
+            f"{type(exc).__name__}: {exc}"
+        )
+    if count == 0:
+        return "The documentation index loaded but contains no documents."
+    return None
+
+
+# Passed as the tool `description` (an f-string, so version numbers interpolate -- a plain
+# docstring can't). FastMCP uses this over the function docstring when both are present.
+_SEARCH_DESCRIPTION = f"""\
+Semantically search the official React documentation and return the most relevant chunks.
+
+When to use: reach for this on ANY question about React itself -- hooks (`useState`, \
+`useEffect`, ...), built-in components, APIs, rendering/effects/StrictMode behavior, migration, \
+or idiomatic patterns. Prefer it over answering from memory: it indexes React \
+{REACT_VERSION_LABEL} (index `{INDEX_VERSION}`), so it is more current and authoritative than \
+the model's own training data. It does NOT cover unrelated topics or third-party libraries.
+
+Args:
+    question: A full natural-language question, not bare keywords -- richer phrasing retrieves
+        better.
+        Good: "How do I run cleanup logic when a component unmounts with useEffect?"
+        Good: "What's the difference between useMemo and useCallback?"
+        Weak: "useEffect" (too terse; ambiguous intent)
+    k: How many chunks to return (default {DEFAULT_TOP_K}). Suggested by intent: ~3 for a
+        specific API/signature lookup, {DEFAULT_TOP_K} for a general question, ~8-10 for broad
+        or exploratory topics that likely span multiple doc pages.
+
+Returns a list of results ordered by relevance (closest first). Each item has:
+    - source:   human-readable provenance label (file path > heading path); cite this.
+    - content:  the raw chunk text to ground an answer on.
+    - distance: retrieval distance -- squared L2 over normalized embeddings, so LOWER is more
+        similar. As a rough guide for this corpus: < ~1.0 is relevant, and > ~1.5 usually means
+        the question is off-topic or not covered (no strong match). If every result is above
+        ~1.5, prefer saying the docs don't cover it over guessing."""
+
+
+@mcp.tool(
+    name="search_react_docs",
+    title="Search React Documentation",
+    description=_SEARCH_DESCRIPTION,
+    annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=False),
+)
+def search_react_docs(question: str, k: int = DEFAULT_TOP_K) -> list[SearchResult]:
+    """Retrieve the top-k React-docs chunks for `question` (see tool description for guidance)."""
+    error = _index_error()
+    if error:
+        print(f"[rag-react-docs] {error}", file=sys.stderr)
+        return [{"source": "rag-react-docs", "content": error, "distance": None}]
+
+    return retrieve_chunks(question, k)
+
+
+def main() -> None:
+    """Console-script entry point: start the MCP server on stdio."""
+    # Human-facing messages must go to stderr: the stdio transport reserves stdout for the
+    # JSON-RPC protocol, so anything printed there would corrupt the stream.
+    print(f"[rag-react-docs] MCP server starting on stdio (top_k={DEFAULT_TOP_K}).", file=sys.stderr)
+    print("[rag-react-docs] Ensuring documentation index is available...", file=sys.stderr)
+    error = _index_error()
+    if error:
+        print(f"[rag-react-docs] Warning: {error}", file=sys.stderr)
+    else:
+        print("[rag-react-docs] Index ready.", file=sys.stderr)
+
+    print("[rag-react-docs] Ready. Press Ctrl+C to stop.", file=sys.stderr)
+    try:
+        mcp.run()
+    except KeyboardInterrupt:
+        print("\n[rag-react-docs] Shutting down.", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

cfunklabs_rag_react_docs-0.1.3/src/rag_react_docs/server.py

@@ -1,82 +0,0 @@
-"""MCP server exposing the RAG retrieval pipeline over stdio.
-
-Published as the `cfunklabs-rag-react-docs` console script (`uvx cfunklabs-rag-react-docs`). It
-exposes a single `search_docs` tool that performs *retrieval only* against the downloaded
-ChromaDB collection and returns the top-k chunks with their source/heading labels. The
-consuming LLM (Cursor, Claude Desktop, etc.) ingests those chunks and generates its own
-grounded answer, so no Anthropic API key or generation stack is needed server-side.
-"""
-
-import sys
-
-from mcp.server.fastmcp import FastMCP
-
-from .config import DEFAULT_TOP_K, INDEX_URL
-from .datastore import get_rag_collection
-from .retrieval import retrieve_chunks
-
-
-mcp = FastMCP("rag-react-docs")
-
-
-def _index_error() -> str | None:
-    """Return a human-readable reason the index is unavailable, or None if it's ready.
-
-    Distinguishes a real load/download failure (surfacing the underlying exception and the
-    URL it tried) from a genuinely empty collection, so callers report the actual cause rather
-    than a catch-all "index is empty" message.
-    """
-    try:
-        count = get_rag_collection().count()
-    except Exception as exc:
-        return (
-            f"Could not load the documentation index (downloaded from {INDEX_URL}): "
-            f"{type(exc).__name__}: {exc}"
-        )
-    if count == 0:
-        return "The documentation index loaded but contains no documents."
-    return None
-
-
-@mcp.tool()
-def search_docs(question: str, k: int = DEFAULT_TOP_K) -> list[dict]:
-    """Search the indexed React documentation and return the most relevant chunks.
-
-    Args:
-        question: A natural-language question to search the React docs for.
-        k: How many chunks to return (defaults to `DEFAULT_TOP_K`).
-
-    Returns a list of results ordered by relevance. Each item has:
-        - source:   a human-readable provenance label (file path > heading path)
-        - content:  the raw chunk text to ground an answer on
-        - distance: the retrieval distance (lower is more similar)
-    """
-    error = _index_error()
-    if error:
-        print(f"[rag-react-docs] {error}", file=sys.stderr)
-        return [{"source": "rag-react-docs", "content": error, "distance": None}]
-
-    return retrieve_chunks(question, k)
-
-
-def main() -> None:
-    """Console-script entry point: start the MCP server on stdio."""
-    # Human-facing messages must go to stderr: the stdio transport reserves stdout for the
-    # JSON-RPC protocol, so anything printed there would corrupt the stream.
-    print(f"[rag-react-docs] MCP server starting on stdio (top_k={DEFAULT_TOP_K}).", file=sys.stderr)
-    print("[rag-react-docs] Ensuring documentation index is available...", file=sys.stderr)
-    error = _index_error()
-    if error:
-        print(f"[rag-react-docs] Warning: {error}", file=sys.stderr)
-    else:
-        print("[rag-react-docs] Index ready.", file=sys.stderr)
-
-    print("[rag-react-docs] Ready. Press Ctrl+C to stop.", file=sys.stderr)
-    try:
-        mcp.run()
-    except KeyboardInterrupt:
-        print("\n[rag-react-docs] Shutting down.", file=sys.stderr)
-
-
-if __name__ == "__main__":
-    main()