docchat-server 0.0.1__tar.gz

docchat_server-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+# Triggered by pushing a semver tag. Example:
+#   git tag v0.0.1
+#   git push --tags
+#
+# Pre-req: PyPI trusted publisher is registered for this repo
+# (https://pypi.org/manage/account/publishing/). For the very first
+# release, register a "pending publisher" before pushing the tag so
+# PyPI knows to accept the OIDC token before the project exists.
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+  id-token: write   # required for PyPI trusted publishing (OIDC)
+
+jobs:
+  release:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/docchat-server/
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: latest
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Sync project (so smoke tests can import the package)
+        run: uv sync --frozen --no-dev
+
+      - name: Build wheel + sdist
+        run: uv build
+
+      - name: Verify the build artifacts exist
+        run: ls -la dist/
+
+      - name: Publish to PyPI via trusted publishing
+        run: uv publish --trusted-publishing always

docchat_server-0.0.1/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.whl
+*.tar.gz
+.venv/
+venv/
+
+# Editor / OS
+.vscode/settings.json
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Secrets
+.env
+.env.*
+!.env.example
+
+# Runtime data (per-user managed Qdrant + caches)
+.docchat-mcp-cache/

docchat_server-0.0.1/.python-version

@@ -0,0 +1 @@
+3.11

docchat_server-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashwin Ugale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docchat_server-0.0.1/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: docchat-server
+Version: 0.0.1
+Summary: Version-pinned documentation retrieval as a Model Context Protocol server. Gives Claude Code / Cursor / any MCP-aware AI grounded answers from the docs of the exact library version your lockfile pins.
+Project-URL: Homepage, https://github.com/AshwinUgale/docchat-mcp
+Project-URL: Repository, https://github.com/AshwinUgale/docchat-mcp
+Project-URL: Issues, https://github.com/AshwinUgale/docchat-mcp/issues
+Author-email: Ashwin Ugale <ugaleashwin@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: claude,cursor,docs,llm,mcp,model-context-protocol,rag,version-pinned
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=0.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=1.40
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: qdrant-client>=1.12
+Description-Content-Type: text/markdown
+
+# docchat-server
+
+> Version-pinned documentation retrieval as a Model Context Protocol server. Gives Claude Code / Cursor / any MCP-aware AI grounded answers from the docs of the exact library version your lockfile pins.
+
+[![status](https://img.shields.io/badge/status-alpha-orange)](#)
+[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+[![version](https://img.shields.io/badge/version-0.0.1-blue)](./pyproject.toml)
+
+**Status:** v0.0 — initial scaffold. v0.1 ships PyPI + Smithery registration once the FastMCP server is locally verified.
+
+---
+
+## What it is
+
+Claude Code, Cursor, and other AI coding assistants answer library questions from training data. If your project pins `react@18.2.0` and the latest is `19.1.0`, you get React 19 APIs in your React 18 file — the model has no way to know which version actually matters.
+
+`docchat-server` is an MCP server that fixes that. Index a library at the version you pin once. Register the server with your MCP host. Now every query to your coding assistant can be grounded in the docs for the *exact pinned version*, with hard refusal when the docs don't cover the question.
+
+It's the [DocChat VS Code extension](https://github.com/AshwinUgale/docchat) stripped of its agent + chat UI, exposed as an MCP tool surface instead. The retrieval logic, version-aware routing, and per-library cosine score floors are identical (and identically eval-tuned).
+
+---
+
+## Install
+
+```bash
+pip install docchat-server        # or: uvx --from docchat-server docchat-server
+```
+
+Requires Python 3.11+ and an `OPENAI_API_KEY` env var (used for query + index-time embeddings). The Qdrant vector store runs *embedded* — no Docker, no separate server.
+
+---
+
+## Use (3 steps)
+
+### 1. Index the libraries you care about
+
+```bash
+export OPENAI_API_KEY=sk-...
+
+docchat-server index react 18.2.0
+docchat-server index fastapi 0.100.0
+docchat-server index vue 3.4.0
+```
+
+Each index takes ~30–60 seconds and a few cents of embedding cost. Stored at `~/.docchat-server/qdrant/`.
+
+### 2. Verify
+
+```bash
+docchat-server list
+```
+
+```
+Indexed collections:
+  - react_18_2_0    (47 chunks)
+  - fastapi_0_100_0 (38 chunks)
+  - vue_3_4_0       (62 chunks)
+
+Supported libraries: fastapi, react, vue
+```
+
+### 3. Register with your MCP host
+
+Claude Desktop / Claude Code: add to your MCP config (`~/.config/claude/mcp-config.json` on Mac/Linux, `%APPDATA%\Claude\mcp-config.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "docchat": {
+      "command": "docchat-server",
+      "args": ["serve"],
+      "env": {
+        "OPENAI_API_KEY": "sk-..."
+      }
+    }
+  }
+}
+```
+
+Restart your MCP host. The `docchat` server should appear with two tools: `search_docs` and `list_indexed`.
+
+---
+
+## The tools
+
+### `search_docs(library, version, query, api_name?, top_k?)`
+
+Retrieves top-K chunks from the indexed docs of the exact pinned version. Returns the chunks with citations, or `"No relevant chunks found"` if nothing clears the per-library cosine floor (a hard signal to the model that it should refuse rather than guess).
+
+### `list_indexed()`
+
+Returns the collections currently populated locally. Useful as a session-start probe — your assistant can call this once to know what's available before answering anything.
+
+---
+
+## Sibling project
+
+The same retrieval engine ships as a [VS Code extension on the Marketplace](https://marketplace.visualstudio.com/items?itemName=AshwinUgale.docchat). Source: https://github.com/AshwinUgale/docchat. If you want a chat panel instead of MCP-tool integration, install that.
+
+---
+
+## Roadmap
+
+- **v0.1** — PyPI publish, Smithery listing, README screenshots from real Claude Code session
+- **v0.2** — `detect_pinned_libraries(workspace_path)` tool (parse package.json / pyproject.toml / requirements.txt and report pinned versions to the assistant)
+- **v0.3** — `--repo` / `--paths` flags for arbitrary library indexing (extend beyond the built-in react / fastapi / vue)
+- **v0.4** — local embeddings via sentence-transformers (drop the OpenAI dependency for the embed step)
+
+---
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

docchat_server-0.0.1/README.md

@@ -0,0 +1,113 @@
+# docchat-server
+
+> Version-pinned documentation retrieval as a Model Context Protocol server. Gives Claude Code / Cursor / any MCP-aware AI grounded answers from the docs of the exact library version your lockfile pins.
+
+[![status](https://img.shields.io/badge/status-alpha-orange)](#)
+[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+[![version](https://img.shields.io/badge/version-0.0.1-blue)](./pyproject.toml)
+
+**Status:** v0.0 — initial scaffold. v0.1 ships PyPI + Smithery registration once the FastMCP server is locally verified.
+
+---
+
+## What it is
+
+Claude Code, Cursor, and other AI coding assistants answer library questions from training data. If your project pins `react@18.2.0` and the latest is `19.1.0`, you get React 19 APIs in your React 18 file — the model has no way to know which version actually matters.
+
+`docchat-server` is an MCP server that fixes that. Index a library at the version you pin once. Register the server with your MCP host. Now every query to your coding assistant can be grounded in the docs for the *exact pinned version*, with hard refusal when the docs don't cover the question.
+
+It's the [DocChat VS Code extension](https://github.com/AshwinUgale/docchat) stripped of its agent + chat UI, exposed as an MCP tool surface instead. The retrieval logic, version-aware routing, and per-library cosine score floors are identical (and identically eval-tuned).
+
+---
+
+## Install
+
+```bash
+pip install docchat-server        # or: uvx --from docchat-server docchat-server
+```
+
+Requires Python 3.11+ and an `OPENAI_API_KEY` env var (used for query + index-time embeddings). The Qdrant vector store runs *embedded* — no Docker, no separate server.
+
+---
+
+## Use (3 steps)
+
+### 1. Index the libraries you care about
+
+```bash
+export OPENAI_API_KEY=sk-...
+
+docchat-server index react 18.2.0
+docchat-server index fastapi 0.100.0
+docchat-server index vue 3.4.0
+```
+
+Each index takes ~30–60 seconds and a few cents of embedding cost. Stored at `~/.docchat-server/qdrant/`.
+
+### 2. Verify
+
+```bash
+docchat-server list
+```
+
+```
+Indexed collections:
+  - react_18_2_0    (47 chunks)
+  - fastapi_0_100_0 (38 chunks)
+  - vue_3_4_0       (62 chunks)
+
+Supported libraries: fastapi, react, vue
+```
+
+### 3. Register with your MCP host
+
+Claude Desktop / Claude Code: add to your MCP config (`~/.config/claude/mcp-config.json` on Mac/Linux, `%APPDATA%\Claude\mcp-config.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "docchat": {
+      "command": "docchat-server",
+      "args": ["serve"],
+      "env": {
+        "OPENAI_API_KEY": "sk-..."
+      }
+    }
+  }
+}
+```
+
+Restart your MCP host. The `docchat` server should appear with two tools: `search_docs` and `list_indexed`.
+
+---
+
+## The tools
+
+### `search_docs(library, version, query, api_name?, top_k?)`
+
+Retrieves top-K chunks from the indexed docs of the exact pinned version. Returns the chunks with citations, or `"No relevant chunks found"` if nothing clears the per-library cosine floor (a hard signal to the model that it should refuse rather than guess).
+
+### `list_indexed()`
+
+Returns the collections currently populated locally. Useful as a session-start probe — your assistant can call this once to know what's available before answering anything.
+
+---
+
+## Sibling project
+
+The same retrieval engine ships as a [VS Code extension on the Marketplace](https://marketplace.visualstudio.com/items?itemName=AshwinUgale.docchat). Source: https://github.com/AshwinUgale/docchat. If you want a chat panel instead of MCP-tool integration, install that.
+
+---
+
+## Roadmap
+
+- **v0.1** — PyPI publish, Smithery listing, README screenshots from real Claude Code session
+- **v0.2** — `detect_pinned_libraries(workspace_path)` tool (parse package.json / pyproject.toml / requirements.txt and report pinned versions to the assistant)
+- **v0.3** — `--repo` / `--paths` flags for arbitrary library indexing (extend beyond the built-in react / fastapi / vue)
+- **v0.4** — local embeddings via sentence-transformers (drop the OpenAI dependency for the embed step)
+
+---
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

docchat_server-0.0.1/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "docchat-server"
+version = "0.0.1"
+description = "Version-pinned documentation retrieval as a Model Context Protocol server. Gives Claude Code / Cursor / any MCP-aware AI grounded answers from the docs of the exact library version your lockfile pins."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Ashwin Ugale", email = "ugaleashwin@gmail.com" }]
+keywords = ["mcp", "model-context-protocol", "llm", "rag", "docs", "version-pinned", "claude", "cursor"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+    "fastmcp>=0.4",
+    "qdrant-client>=1.12",
+    "openai>=1.40",
+    "httpx>=0.27",
+    "python-dotenv>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/AshwinUgale/docchat-mcp"
+Repository = "https://github.com/AshwinUgale/docchat-mcp"
+Issues = "https://github.com/AshwinUgale/docchat-mcp/issues"
+
+[project.scripts]
+docchat-server = "docchat_server.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docchat_server"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+    "mypy>=1.10",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

docchat_server-0.0.1/src/docchat_server/__init__.py

@@ -0,0 +1,12 @@
+"""docchat-server - version-pinned documentation retrieval as an MCP server.
+
+Stripped-down sibling of docchat (https://github.com/AshwinUgale/docchat).
+Exposes ``search_docs`` and ``list_indexed`` MCP tools that Claude Code,
+Cursor, Cline, or any other MCP-aware client can call to ground library
+questions in the exact pinned-version docs instead of training data.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.0.1"
+__all__ = ["__version__"]

docchat_server-0.0.1/src/docchat_server/cli.py

@@ -0,0 +1,111 @@
+"""docchat-server CLI.
+
+Subcommands:
+- ``docchat-server serve``                  - run the MCP server on stdio.
+- ``docchat-server index <library> <ver>``  - populate the local Qdrant.
+- ``docchat-server list``                   - show indexed collections.
+
+The ``serve`` subcommand is what an MCP host (Claude Code, Cursor, Cline)
+spawns. The ``index`` and ``list`` subcommands are for the user, run
+manually to set up before pointing an MCP host at the server.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from dotenv import load_dotenv
+
+from docchat_server import __version__
+
+
+def _cmd_serve(_args: argparse.Namespace) -> int:
+    # Import inside the handler so `docchat-server index` doesn't pull in
+    # FastMCP (which checks OPENAI_API_KEY at import time in server.py).
+    from docchat_server.server import main as serve_main
+
+    serve_main()
+    return 0
+
+
+def _cmd_index(args: argparse.Namespace) -> int:
+    load_dotenv()
+    if not os.environ.get("OPENAI_API_KEY"):
+        print(
+            "ERROR: OPENAI_API_KEY is not set. docchat-server uses OpenAI's "
+            "embeddings API. Set it in your shell or a .env file.",
+            file=sys.stderr,
+        )
+        return 2
+
+    from openai import OpenAI
+
+    from docchat_server.indexer import DocIndexer, open_qdrant
+
+    qdrant = open_qdrant()
+    indexer = DocIndexer(qdrant=qdrant, openai=OpenAI())
+
+    def _progress(msg: str) -> None:
+        print(f"[indexer] {msg}", file=sys.stderr, flush=True)
+
+    try:
+        total = indexer.index(args.library, args.version, progress=_progress)
+    except ValueError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+    except RuntimeError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+    print(f"indexed {total} chunks into {args.library}@{args.version}")
+    return 0
+
+
+def _cmd_list(_args: argparse.Namespace) -> int:
+    from docchat_server.indexer import open_qdrant
+    from docchat_server.library_config import LIBRARY_CONFIG
+
+    qdrant = open_qdrant()
+    collections = qdrant.get_collections().collections
+    print("Indexed collections:")
+    if not collections:
+        print("  (none yet - run `docchat-server index <library> <version>`)")
+    for c in collections:
+        try:
+            count = qdrant.count(collection_name=c.name).count
+        except Exception:
+            count = "?"
+        print(f"  - {c.name}  ({count} chunks)")
+    print()
+    print(f"Supported libraries: {', '.join(sorted(LIBRARY_CONFIG.keys()))}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="docchat-server",
+        description="Version-pinned doc retrieval as an MCP server.",
+    )
+    parser.add_argument("--version", action="version", version=f"docchat-server {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_serve = sub.add_parser("serve", help="run the MCP server on stdio")
+    p_serve.set_defaults(func=_cmd_serve)
+
+    p_index = sub.add_parser(
+        "index", help="fetch + embed + upsert docs for one (library, version)"
+    )
+    p_index.add_argument("library", help="e.g. react, fastapi, vue")
+    p_index.add_argument("version", help="e.g. 18.2.0, 0.100.0, 3.4.0")
+    p_index.set_defaults(func=_cmd_index)
+
+    p_list = sub.add_parser("list", help="show indexed collections")
+    p_list.set_defaults(func=_cmd_list)
+
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())