revit-api-docs 0.1.0__py3-none-any.whl

revit_api_docs/server.py

@@ -0,0 +1,244 @@
+"""MCP server: two read-only tools over the Revit API reference.
+
+    search_revit_api(query, top_k)   -> API entries (signature, parameters, remarks)
+    get_code_examples(query, top_k)  -> C# snippets from the official SDK samples
+
+Everything is local once the data set is installed. On the first run the
+server answers immediately and downloads the data set (about 335 MB) in the
+background; tool calls made before it is ready get a short status message
+instead of a result. `revit-api-docs download` fetches it ahead of time.
+
+stdout is the MCP transport: all diagnostics go to stderr.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+import threading
+from typing import TYPE_CHECKING
+
+from mcp.server.mcpserver import MCPServer
+from mcp.types import ToolAnnotations
+
+from revit_api_docs import __version__, data
+from revit_api_docs.config import load_config
+
+if TYPE_CHECKING:
+    from revit_api_docs.retriever import RAGRetriever
+
+log = logging.getLogger("revit_api_docs.server")
+
+MAX_TOP_K = 50
+
+SERVER_INSTRUCTIONS = """\
+Revit API reference lookup (Revit 2026). Optional companion for models that do
+not know the Revit API well; it never touches a Revit session.
+
+- search_revit_api(query, top_k): find classes, methods, properties and enums
+  in the API reference. Ask with API names when you have them
+  ("Wall.Create", "FilteredElementCollector OfCategory") or with a short task
+  description ("create floor from boundary"). Results carry the signature,
+  parameters and remarks; trust them over memory.
+- get_code_examples(query, top_k): real C# from the Revit SDK samples that use
+  the APIs in question. Read one before writing code for an unfamiliar API.
+
+Use these before generating code that calls an API you are not certain about
+(exact method name, parameter order, required ElementIds, units).
+"""
+
+mcp = MCPServer(
+    "revit-api-docs",
+    version=__version__,
+    instructions=SERVER_INSTRUCTIONS,
+)
+
+_READ_ONLY = ToolAnnotations(readOnlyHint=True)
+
+
+# ── Retriever lifecycle ──────────────────────────────────────────────────────
+
+class _State:
+    """Data download + retriever construction, shared by the tools."""
+
+    def __init__(self) -> None:
+        self.lock = threading.Lock()
+        self.status = "idle"          # idle | downloading | loading | ready | failed
+        self.detail = ""
+        self.error: str | None = None
+        self.retriever: RAGRetriever | None = None
+        self._thread: threading.Thread | None = None
+
+    def _progress(self, name: str, done: int, total: int) -> None:
+        pct = 100 * done // total if total else 0
+        self.detail = f"{name} {pct}%"
+        data.stderr_progress(name, done, total)
+
+    def prepare(self) -> RAGRetriever:
+        """Blocking: install the data set if needed and build the retriever."""
+        with self.lock:
+            if self.retriever is not None:
+                return self.retriever
+            try:
+                self.status = "downloading" if data.missing() else "loading"
+                paths = data.ensure_data(progress=self._progress)
+                self.status = "loading"
+                from revit_api_docs.retriever import RAGRetriever
+
+                self.retriever = RAGRetriever(
+                    config=load_config(),
+                    api_db_path=str(paths.api_db),
+                    sdk_db_path=str(paths.sdk_db),
+                    chromadb_api_dir=str(paths.chromadb_api),
+                    chromadb_code_dir=str(paths.chromadb_code),
+                )
+                self.status = "ready"
+                self.error = None
+                log.info("ready: data in %s", paths.root)
+                return self.retriever
+            except Exception as e:  # reported to the caller, not raised into MCP
+                self.status = "failed"
+                self.error = f"{type(e).__name__}: {e}"
+                log.exception("preparing the data set failed")
+                raise
+
+    def start_background(self) -> bool:
+        """Start the preparation thread unless one is running; True if started."""
+        if self._thread is not None and self._thread.is_alive():
+            return False
+        self._thread = threading.Thread(target=self._prepare_quietly,
+                                        name="revit-api-docs-prepare", daemon=True)
+        self._thread.start()
+        return True
+
+    def _prepare_quietly(self) -> None:
+        try:
+            self.prepare()
+        except Exception:
+            pass
+
+    def message_if_not_ready(self) -> str | None:
+        """Text to return from a tool while the retriever is unavailable."""
+        if self.retriever is not None:
+            return None
+        if self.status == "failed":
+            # Let the next call retry (network hiccup, disk full and freed, ...),
+            # but only claim a retry when this call actually started one.
+            retrying = self.start_background()
+            how = ("Retrying in the background; call again in a moment"
+                   if retrying else "A retry is already running; call again in a moment")
+            return (f"revit-api-docs is not available: {self.error}. {how}, or run "
+                    f"`revit-api-docs download` in a terminal to see the full error.")
+        self.start_background()
+        if self.status == "downloading":
+            return (f"revit-api-docs is downloading its data set on first run "
+                    f"({data.TOTAL_DOWNLOAD_BYTES / 1e6:.0f} MB, currently {self.detail}). "
+                    f"Call again in a minute.")
+        return "revit-api-docs is loading its index. Call again in a few seconds."
+
+
+_state = _State()
+
+
+def _clamp_top_k(top_k: int, default: int) -> int:
+    try:
+        n = int(top_k)
+    except (TypeError, ValueError):
+        return default
+    return max(1, min(n, MAX_TOP_K))
+
+
+def search_api(retriever: RAGRetriever, query: str, top_k: int) -> str:
+    results = retriever.search(query, api_top_k=top_k, code_top_k=0, rewrite=False, rerank=True)
+    ctx = retriever.build_context(results)
+    return ctx.get("api_context") or f"No API entries found for {query!r}."
+
+
+def search_examples(retriever: RAGRetriever, query: str, top_k: int) -> str:
+    results = retriever.search(query, api_top_k=0, code_top_k=top_k, rewrite=False, rerank=False)
+    ctx = retriever.build_context(results)
+    return ctx.get("code_context") or f"No SDK examples found for {query!r}."
+
+
+# ── Tools ────────────────────────────────────────────────────────────────────
+
+@mcp.tool(annotations=_READ_ONLY)
+async def search_revit_api(query: str, top_k: int = 10) -> str:
+    """Search the Revit 2026 API reference (27,596 classes, methods, properties,
+    enums). Returns each match with its signature, parameters and remarks.
+    Query with an API name ("Wall.Create") or a short task ("rotate element
+    around axis"). top_k: 1-50, default 10."""
+    if not query or not query.strip():
+        return "Give a query: an API name such as 'Wall.Create' or a short task description."
+    msg = _state.message_if_not_ready()
+    if msg:
+        return msg
+    n = _clamp_top_k(top_k, 10)
+    return await asyncio.to_thread(search_api, _state.retriever, query.strip(), n)
+
+
+@mcp.tool(annotations=_READ_ONLY)
+async def get_code_examples(query: str, top_k: int = 3) -> str:
+    """Return C# examples from the official Revit SDK samples (153 projects)
+    that use the APIs matching the query, each with the project name and the
+    APIs it touches. top_k: 1-50, default 3."""
+    if not query or not query.strip():
+        return "Give a query: an API name or the task the sample should show."
+    msg = _state.message_if_not_ready()
+    if msg:
+        return msg
+    n = _clamp_top_k(top_k, 3)
+    return await asyncio.to_thread(search_examples, _state.retriever, query.strip(), n)
+
+
+# ── CLI ──────────────────────────────────────────────────────────────────────
+
+def _configure_logging(verbose: bool) -> None:
+    logging.basicConfig(
+        stream=sys.stderr,
+        level=logging.INFO if verbose else logging.WARNING,
+        format="%(name)s: %(message)s",
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="revit-api-docs",
+        description="MCP server for Revit API reference search (stdio).",
+    )
+    parser.add_argument("--version", action="version", version=f"revit-api-docs {__version__}")
+    parser.add_argument("-v", "--verbose", action="store_true", help="info-level logs on stderr")
+    sub = parser.add_subparsers(dest="command")
+    sub.add_parser("serve", help="run the MCP server on stdio (default)")
+    sub.add_parser("download", help="install the data set now instead of on first use")
+    p_search = sub.add_parser("search", help="query from the terminal (installs the data set if needed)")
+    p_search.add_argument("query")
+    p_search.add_argument("--examples", action="store_true", help="SDK code examples instead of API entries")
+    p_search.add_argument("--top-k", type=int, default=None)
+    args = parser.parse_args(argv)
+
+    _configure_logging(args.verbose or args.command in ("download", "search"))
+
+    if args.command == "download":
+        paths = data.ensure_data(progress=data.stderr_progress)
+        print(f"data ready in {paths.root}", file=sys.stderr)
+        return 0
+
+    if args.command == "search":
+        retriever = _state.prepare()
+        if args.examples:
+            text = search_examples(retriever, args.query, _clamp_top_k(args.top_k or 3, 3))
+        else:
+            text = search_api(retriever, args.query, _clamp_top_k(args.top_k or 10, 10))
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+        print(text)
+        return 0
+
+    _state.start_background()
+    mcp.run(transport="stdio")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

revit_api_docs-0.1.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: revit-api-docs
+Version: 0.1.0
+Summary: Revit API reference search for MCP hosts: local semantic + keyword lookup over the Revit 2026 API docs and SDK samples
+Project-URL: Homepage, https://github.com/revitbridge/revit-api-docs
+Project-URL: Issues, https://github.com/revitbridge/revit-api-docs/issues
+Project-URL: Changelog, https://github.com/revitbridge/revit-api-docs/blob/main/CHANGELOG.md
+Project-URL: Data, https://github.com/revitbridge/revit-api-docs/releases/tag/v1.0-data
+Author: revitbridge
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-docs,bim,mcp,rag,revit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: chromadb<2,>=1
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2
+Requires-Dist: openai<3,>=1
+Requires-Dist: pyyaml>=6
+Provides-Extra: pipeline
+Requires-Dist: beautifulsoup4>=4.12; extra == 'pipeline'
+Requires-Dist: google-genai>=1; extra == 'pipeline'
+Requires-Dist: tqdm>=4.66; extra == 'pipeline'
+Requires-Dist: tree-sitter-c-sharp>=0.20; extra == 'pipeline'
+Requires-Dist: tree-sitter>=0.20; extra == 'pipeline'
+Description-Content-Type: text/markdown
+
+# revit-api-docs
+
+Revit API reference search as an MCP server: two read-only tools over a local
+copy of the Revit 2026 API documentation (27,596 classes, methods, properties
+and enums) and the official SDK samples (153 projects).
+
+**Optional.** It exists for models that do not know the Revit API well. If
+your model already writes correct Revit code, you do not need it;
+[revit-bridge](https://github.com/revitbridge/revit-bridge) works without it.
+It never talks to Revit and it never calls a model itself.
+
+## Install
+
+Prerequisites: Python 3.11+ with [`uv`](https://docs.astral.sh/uv/) (for
+`uvx`), about 700 MB of disk for the data set, network for the first run.
+
+**Claude Desktop** — `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "revit-api-docs": {
+      "command": "uvx",
+      "args": ["revit-api-docs"]
+    }
+  }
+}
+```
+
+**Claude Code**:
+
+```bash
+claude mcp add revit-api-docs -- uvx revit-api-docs
+```
+
+**Any MCP client** — run `uvx revit-api-docs` as a stdio server.
+
+On the first start the server downloads the data set (335 MB, four files) from
+this repository's [`v1.0-data` release](https://github.com/revitbridge/revit-api-docs/releases/tag/v1.0-data)
+into `%LOCALAPPDATA%\revit-api-docs` (Windows) or `~/.local/share/revit-api-docs`
+(Linux; `~/Library/Application Support/revit-api-docs` on macOS), verifies each
+file's SHA-256 and unpacks the vector stores. Tool calls made while that runs
+return a short progress message instead of results. To do it ahead of time:
+
+```bash
+uvx revit-api-docs download
+```
+
+From a checkout: `uv sync` then `uv run revit-api-docs`.
+
+## Use
+
+Two tools, both read-only:
+
+- `search_revit_api(query, top_k=10)` — API entries with signature, parameters
+  and remarks. Query with an API name (`Wall.Create`,
+  `FilteredElementCollector OfCategory`) or a short task (`create floor from
+  boundary`).
+- `get_code_examples(query, top_k=3)` — C# from the SDK samples that use the
+  matching APIs, with the project name and the APIs each sample touches.
+
+Without any API key the server answers from keyword search over the SQLite
+reference (exact and partial name matches, which is what a model usually
+asks for once it knows roughly what it wants). With an embedding key it adds
+semantic search over the vector store, and with a Cohere key it reranks the
+merged candidates. See Configure.
+
+Try it from a terminal (installs the data set if needed):
+
+```bash
+uvx revit-api-docs search "Wall.Create"
+uvx revit-api-docs search "rotate element around axis" --examples
+```
+
+## Configure
+
+All settings are environment variables; there is no config file to edit.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `REVIT_API_DOCS_DATA_DIR` | `%LOCALAPPDATA%\revit-api-docs` (Windows), `~/.local/share/revit-api-docs` (Linux), `~/Library/Application Support/revit-api-docs` (macOS) | Where the data set lives. An existing tree with `sqlite/` and `chromadb/` from the old `revit-api-rag` checkout works as is |
+| `REVIT_API_DOCS_EMBEDDING_API_KEY` | *(unset)* | Key for the embedding endpoint; turns on semantic (vector) search. `OPENROUTER_API_KEY` is used when this is unset |
+| `REVIT_API_DOCS_EMBEDDING_BASE_URL` | `https://openrouter.ai/api/v1` | Any OpenAI-compatible `/embeddings` endpoint |
+| `REVIT_API_DOCS_EMBEDDING_MODEL` | `openai/text-embedding-3-large` | Must produce the same 3072-dimensional space the shipped vectors were built with (`text-embedding-3-large`); another model makes vector search return noise |
+| `COHERE_API_KEY` | *(unset)* | Enables reranking with Cohere `rerank-v3.5` (native REST API) |
+| `REVIT_API_DOCS_RELEASE_URL` | this repository's `v1.0-data` release | Mirror for the data files; the SHA-256 checks still apply |
+| `HTTPS_PROXY` / `HTTP_PROXY` | *(unset)* | Proxy for the embedding and rerank calls |
+
+Pass them through the `env` block of your MCP host's server entry.
+
+Data set: the SQLite databases and ChromaDB indexes were built from the Revit
+2026 API CHM and the Revit 2026 SDK samples with the pipeline in `pipeline/`
+(`uv sync --extra pipeline`; needs the CHM, the SDK and OpenRouter/Cohere keys
+in the environment). The server does not need any of that.
+
+Development:
+
+```bash
+uv sync
+uv run pytest
+uv build
+uvx --from . revit-api-docs search "Wall.Create"
+```
+
+License: MIT. Issues and discussion: <https://github.com/revitbridge/revit-api-docs/issues>.

revit_api_docs-0.1.0.dist-info/RECORD

@@ -0,0 +1,36 @@
+revit_api_docs/__init__.py,sha256=J8Oj82nU_jp1cA5r2On2L3f5De5ilGU29h96YjmQ-Lc,692
+revit_api_docs/__main__.py,sha256=UUDwvlo_KO7PHXswlG6hMan08oGrBjAdaY_TSbLw-so,136
+revit_api_docs/config.py,sha256=16w-Y6Cl3q2pCKWzjff2et8ow9qDwvPcY812KGGCa7g,4279
+revit_api_docs/data.py,sha256=6VwAQB-MtnE8LQ_KWS1gM7ccZ9Ts7bU3TnV7Xe3Pqq4,11913
+revit_api_docs/default_config.yaml,sha256=fawH_qwXbYkngV02RL-r_xDOVEUpgWlfq-4iJrlh7dc,2630
+revit_api_docs/llm_client.py,sha256=SJKjGYeCZmYqJ38hCnfPQEhvNyXT0yXYojJ99MbMYXk,10783
+revit_api_docs/reranker.py,sha256=_MHSrSM1BGBsZfE8ffu6_XCpre8kAAjgXKPQCkYPJ1E,5922
+revit_api_docs/retriever.py,sha256=N9UhO3YmNmYwH2zt5efby_gjLFMYa5lKWBb2hBYyWbU,38388
+revit_api_docs/server.py,sha256=9I4MaldKrQUFEF3lqEuIBaQxM-cV3VrGqs6188aXKgo,10276
+revit_api_docs/embedder/__init__.py,sha256=xzp42Ox_L0zJx6cCOn63rfEML6Nq_f8kGBLI7zagvsw,86
+revit_api_docs/embedder/providers/__init__.py,sha256=k-DxaLvQA1bzaK5DQVf1FiBwGcsjj2A78Z9TaQZ1u9E,889
+revit_api_docs/embedder/providers/base.py,sha256=gJQk0R1hgRH6eam2RXudlm7Vg412x9SvZg_kZsqets8,690
+revit_api_docs/embedder/providers/google.py,sha256=RGpRXmxmtwA7gOTzcgtXJJJJPxtF60OcZe5IPgr4WDk,1186
+revit_api_docs/embedder/providers/openai.py,sha256=vyxzrW88ytaC4joYPoVly3a_GSgUXvKydRsEfq1nWl0,1982
+revit_api_docs/prompts/__init__.py,sha256=LFP2WYzR1xFeT8LkL-gT2xdgHyVN9Z0w6iIO9lk0oHs,147
+revit_api_docs/prompts/loader.py,sha256=q-73PX83xHVSThH6g9HR2vO6wMKK5lw7ad9zIIMsSkA,609
+revit_api_docs/prompts/pipeline.api_quality_stage1_no_html.md,sha256=vYDToPvPmzughVgLy3s9Oa9oxBaPUJH4vlRixgh0lEg,1036
+revit_api_docs/prompts/pipeline.api_quality_stage1_system.md,sha256=lCvZcPaZAZHkYo1V5In8WROk6L5EzVtPL3R3RHpyn-Y,224
+revit_api_docs/prompts/pipeline.api_quality_stage1_with_html.md,sha256=RrsG5zucE4Ergfx_Z4yRsNdkDKKPGNvBDd1JZ47okBI,1491
+revit_api_docs/prompts/pipeline.api_quality_stage2.md,sha256=SlpFZvGoIXP7KBlPxRZlLiwxFBjlTGJBP6h00oiVUMM,1007
+revit_api_docs/prompts/pipeline.api_quality_stage2_system.md,sha256=X8-yLLUYIosnXs66Xc66zVzTADTN59gzJExOC7wdNSA,213
+revit_api_docs/prompts/pipeline.rewrite_query.md,sha256=UEJ-_D-SDNO4zwMzHJ72rI5_TH2_N3BnT2uUVucRSec,2177
+revit_api_docs/prompts/pipeline.rewrite_query_system.md,sha256=CRzQB-dFES_pz-UY2VwMVkqLcN8O-oay7kvOEgfeILQ,57
+revit_api_docs/prompts/pipeline.sdk_extract_readme_system.md,sha256=b3vD1EZlziKhSDrn_NeBmWO-OVCLDzYRvK2JrNTv1H8,119
+revit_api_docs/prompts/pipeline.sdk_extract_readme_user.md,sha256=IIvPc4TPDU6EzbPK8u8QTp1mdz3Yk_dYFP1e_2iSqUU,1067
+revit_api_docs/prompts/pipeline.sdk_golden_code.md,sha256=B6V6P1R4dI5kmrlNutjqrNLLY_SIlfOCHwaOCzsh4HM,1407
+revit_api_docs/prompts/pipeline.sdk_golden_code_system.md,sha256=5_oWAfd0PsehQEJgMStAgeGBL8NiJr0bPd0xOUn5quY,252
+revit_api_docs/prompts/pipeline.sdk_quality_file_batch.md,sha256=BFszmU58f345eVdETLuYgq9pXGugXmGK57nTHWhWpZA,497
+revit_api_docs/prompts/pipeline.sdk_quality_file_system.md,sha256=3L8RpxPt44uuy8zulqMCPmcGXCUzW2HzehnaWAVUbIs,142
+revit_api_docs/prompts/pipeline.sdk_quality_project.md,sha256=JHId6cNkNLeJ1c2Z0pKh9PLw_NQdegyyXCDv6ElkNEo,570
+revit_api_docs/prompts/pipeline.sdk_quality_project_system.md,sha256=Ba8sOPxXMxdVG5cakf9oTMt_ziddCKKTjLLCWVEfI4Y,167
+revit_api_docs-0.1.0.dist-info/METADATA,sha256=kdf7XXAJAr6nPajRzdnYNbTJkECIWiIfpbT_xg_hpNY,5855
+revit_api_docs-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+revit_api_docs-0.1.0.dist-info/entry_points.txt,sha256=YF_Lg7IY-5MdWayjEgtgE4yioMPPJ68gwPLdm1ZhgOE,62
+revit_api_docs-0.1.0.dist-info/licenses/LICENSE,sha256=gHSNJ_KoJMRDI0rhLKUQEGmyt7q1TRX6TpY9tDlqveE,1068
+revit_api_docs-0.1.0.dist-info/RECORD,,

revit_api_docs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

revit_api_docs-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+revit-api-docs = revit_api_docs.server:main

revit_api_docs-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 revitbridge
+
+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.