Refactor as composition root (Layer 4)

- Add src/vtk_mcp/ package: config, composition, server, tools/, transport/
- VTKMCPContext wires vtk-knowledge + vtk-validate + vtk-index at startup
- Pydantic Settings with VTK_MCP_ env prefix
- 25 FastMCP tool registrations delegating to tools/ modules
- Dockerfile and docker-compose.yml for production deployment
- Remove chromadb, sys.path hack, live help() introspection, per-request model loading
- vtk-mcp-server package kept for C++ scraper backwards compatibility

Author: vicentebolea

Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.11-slim
+
+LABEL org.opencontainers.image.title="VTK MCP Gateway"
+LABEL org.opencontainers.image.description="Production MCP gateway for VTK LLM tooling"
+LABEL org.opencontainers.image.source="https://github.com/kitware/vtk-mcp"
+LABEL org.opencontainers.image.licenses="MIT"
+
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+# Install runtime dependencies — no VTK runtime, no LiteLLM
+RUN pip install vtk-knowledge vtk-validate vtk-mcp
+
+# Bundle the knowledge artifact (built separately and passed at build time)
+ARG VTK_VERSION=9.3.0
+ARG KNOWLEDGE_ARTIFACT_URL=""
+RUN if [ -n "$KNOWLEDGE_ARTIFACT_URL" ]; then \
+    curl -fSL "$KNOWLEDGE_ARTIFACT_URL" -o /app/data/vtk-knowledge.jsonl; \
+    fi
+
+COPY data/ /app/data/
+
+ENV VTK_MCP_KNOWLEDGE_ARTIFACT_PATH=/app/data/vtk-knowledge.jsonl
+ENV VTK_MCP_VTK_VERSION=${VTK_VERSION}
+ENV VTK_MCP_TRANSPORT=stdio
+
+ENTRYPOINT ["python", "-m", "vtk_mcp"]

TOOLS.md

@@ -0,0 +1,88 @@
+# vtk-mcp — MCP Tool Reference
+
+25 tools in 5 groups.  Each group lists the delegating library.
+
+---
+
+## Class discovery — `vtk-knowledge`
+
+Find classes by name, keyword, or module membership.
+
+| Tool | What it does |
+|---|---|
+| `vtk_is_a_class(class_name)` | Returns true if the name is a known VTK class |
+| `vtk_search_classes(query, limit)` | Substring search across all class names |
+| `vtk_get_class_module(class_name)` | Returns the `vtkmodules.*` import path |
+| `vtk_get_module_classes(module)` | Lists all classes in a given module |
+
+---
+
+## Class documentation — `vtk-knowledge`
+
+Retrieve metadata about a specific class.
+
+| Tool | What it does |
+|---|---|
+| `get_vtk_class_info_python(class_name)` | Full record: module, methods, role, datatypes, synopsis |
+| `vtk_get_class_doc(class_name)` | Raw class docstring |
+| `vtk_get_class_synopsis(class_name)` | One-sentence LLM-generated summary |
+| `vtk_get_class_action_phrase(class_name)` | Short noun-phrase for the class's primary action |
+| `vtk_get_class_role(class_name)` | Pipeline role: source, filter, mapper, output, utility, etc. |
+| `vtk_get_class_input_datatype(class_name)` | Expected input data type (e.g. `vtkPolyData`) |
+| `vtk_get_class_output_datatype(class_name)` | Produced output data type |
+| `vtk_get_class_visibility(class_name)` | Score 0.0–1.0 for how often this class is used directly |
+| `vtk_get_class_methods(class_name)` | All methods with signatures |
+| `vtk_get_class_semantic_methods(class_name)` | Non-boilerplate methods only |
+
+---
+
+## Method documentation — `vtk-knowledge`
+
+Drill into a specific method on a specific class.
+
+| Tool | What it does |
+|---|---|
+| `vtk_get_method_info(class_name, method_name)` | Full method record: signatures + docstring |
+| `vtk_get_method_doc(class_name, method_name)` | Docstring only |
+| `vtk_get_method_signature(class_name, method_name)` | Canonical signature string only |
+
+---
+
+## Validation — `vtk-validate`
+
+Check VTK Python code or imports for API mistakes.
+
+| Tool | What it does |
+|---|---|
+| `validate_vtk_code(source)` | Full AST check: imports, constructors, methods, ordering, security — returns a `ValidationReport` |
+| `vtk_validate_import(import_statement)` | Validates a single import line and suggests the correct module |
+
+---
+
+## Semantic search — `vtk-index` (Qdrant)
+
+Retrieve relevant documentation or code by meaning, not by exact name.
+
+| Tool | What it does |
+|---|---|
+| `vector_search_docs(query, k)` | Hybrid dense+BM25 search over documentation chunks |
+| `vector_search_examples(query, k)` | Hybrid dense+BM25 search over VTK code example chunks |
+
+---
+
+## C++ documentation — vtk.org scraper (self-contained)
+
+Live HTML scraping of the VTK C++ API docs.  No offline artifact required.
+
+| Tool | What it does |
+|---|---|
+| `get_vtk_class_info_cpp(class_name)` | Fetches class info from vtk.org C++ docs |
+| `search_vtk_classes_cpp(search_term)` | Searches class names in the C++ docs |
+
+---
+
+## Meta — `vtk-mcp` itself
+
+| Tool | What it does |
+|---|---|
+| `vtk_version_info()` | Returns the loaded VTK version, class count, and which capabilities are enabled |

data/.gitkeep

@@ -0,0 +1,25 @@
+services:
+  qdrant:
+    image: qdrant/qdrant:latest
+    ports:
+      - "6333:6333"
+    volumes:
+      - qdrant_data:/qdrant/storage
+
+  vtk-mcp:
+    build: .
+    environment:
+      VTK_MCP_TRANSPORT: http
+      VTK_MCP_HTTP_PORT: "8000"
+      VTK_MCP_ENABLE_RETRIEVAL: "true"
+      VTK_MCP_QDRANT_URL: http://qdrant:6333
+      VTK_MCP_KNOWLEDGE_ARTIFACT_PATH: /app/data/vtk-knowledge.jsonl
+    ports:
+      - "8000:8000"
+    depends_on:
+      - qdrant
+    volumes:
+      - ./data:/app/data:ro
+
+volumes:
+  qdrant_data:

docker-compose.yml

@@ -1,8 +1,8 @@
 [project]
-name = "vtk-mcp-server"
-dynamic = ["version"]
-description = "MCP server for VTK class documentation"
-authors = [{name = "Vicente Adolfo Bolea Sanchez", email = "vicente.bolea@kitware.com"}]
+name = "vtk-mcp"
+version = "1.0.0"
+description = "Production MCP gateway composing vtk-knowledge, vtk-index, and vtk-validate"
+authors = [{name = "Patrick O'Leary"}, {name = "Vicente Adolfo Bolea Sanchez", email = "vicente.bolea@kitware.com"}]
 license = {text = "MIT"}
 readme = "README.md"
 requires-python = ">=3.10"
@@ -20,21 +20,23 @@ classifiers = [
 ]
 dependencies = [
     "fastmcp>=2.0.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
     "beautifulsoup4>=4.12.0",
-    "importlib_resources>=5.0.0",
     "requests>=2.31.0",
     "lxml>=4.9.0",
     "click>=8.0.0",
-    "chromadb==0.6.3",
-    "sentence-transformers==3.4.1",
-    "vtk",
+    "vtk-knowledge>=1.0.0",
+    "vtk-validate>=1.0.0",
 ]
 
 [project.scripts]
-vtk-mcp-server = "vtk_mcp_server.server:main"
-vtk-mcp-client = "vtk_mcp_server.simple_client:main"
+vtk-mcp = "vtk_mcp.__main__:main"
 
 [project.optional-dependencies]
+retrieval = [
+    "vtk-index>=1.0.0",
+]
 test = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
@@ -45,16 +47,15 @@ test = [
 
 [project.urls]
 Homepage = "https://github.com/kitware/vtk-mcp"
-Documentation = "https://github.com/kitware/vtk-mcp/blob/master/README.md"
 Repository = "https://github.com/kitware/vtk-mcp"
 Issues = "https://github.com/kitware/vtk-mcp/issues"
 
 [build-system]
-requires = ["setuptools>=61.0", "setuptools-scm>=8.0"]
+requires = ["setuptools>=61.0"]
 build-backend = "setuptools.build_meta"
 
-[tool.setuptools_scm]
-fallback_version = "0.1.0"
+[tool.setuptools.packages.find]
+where = ["src"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

pyproject.toml

@@ -0,0 +1,8 @@
+"""vtk-mcp — production MCP gateway composing vtk-knowledge, vtk-index, and vtk-validate."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("vtk-mcp")
+except PackageNotFoundError:
+    __version__ = "unknown"

src/vtk_mcp/__init__.py

@@ -0,0 +1,44 @@
+"""vtk-mcp entry point: ``python -m vtk_mcp``."""
+
+import click
+
+
+@click.command()
+@click.option(
+    "--transport",
+    type=click.Choice(["stdio", "http"]),
+    default="stdio",
+    show_default=True,
+    help="Transport protocol.",
+)
+@click.option("--host", default="0.0.0.0", show_default=True, help="HTTP host.")
+@click.option("--port", default=8000, show_default=True, help="HTTP port.")
+@click.option(
+    "--knowledge-artifact",
+    envvar="VTK_MCP_KNOWLEDGE_ARTIFACT_PATH",
+    type=click.Path(exists=True),
+    help="Path to the vtk-knowledge JSONL artifact.",
+)
+def main(transport: str, host: str, port: int, knowledge_artifact: str | None) -> None:
+    """Run the VTK MCP gateway server."""
+    import os
+    from .config import Settings
+    from .composition import init_context
+
+    if knowledge_artifact:
+        os.environ["VTK_MCP_KNOWLEDGE_ARTIFACT_PATH"] = knowledge_artifact
+
+    settings = Settings()
+    init_context(settings)
+
+    if transport == "http":
+        click.echo(f"Starting vtk-mcp on http://{host}:{port}")
+        from .transport.http import run
+        run(host=host, port=port)
+    else:
+        from .transport.stdio import run
+        run()
+
+
+if __name__ == "__main__":
+    main()

src/vtk_mcp/__main__.py

@@ -0,0 +1,86 @@
+"""Composition root — wires layers 1–3 at startup.
+
+All layer dependencies are constructed exactly once here and held as
+singletons on VTKMCPContext.  Tool handlers receive a context instance
+rather than constructing their own dependencies.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from vtk_knowledge import VTKAPIIndex
+
+from .config import Settings
+
+logger = logging.getLogger(__name__)
+
+
+class VTKMCPContext:
+    """Holds all layer-1/2/3 dependencies as singletons.
+
+    Constructed once at gateway startup; injected into every tool handler.
+    """
+
+    api_index: VTKAPIIndex
+    retriever: object  # vtk_index.Retriever | None
+    validate: object   # callable(source: str) -> ValidationReport | None
+    settings: Settings
+
+    def __init__(self, settings: Settings) -> None:
+        self.settings = settings
+        # Layer 1: knowledge index
+        logger.info("Loading knowledge artifact from %s", settings.knowledge_artifact_path)
+        self.api_index = VTKAPIIndex.from_jsonl(settings.knowledge_artifact_path)
+        logger.info(
+            "Loaded %d classes (vtk_version=%s)",
+            len(self.api_index.classes),
+            self.api_index.vtk_version,
+        )
+
+        # Layer 2: retrieval (optional)
+        self.retriever = None
+        if settings.enable_retrieval:
+            try:
+                from vtk_index import Retriever
+
+                self.retriever = Retriever(
+                    qdrant_url=settings.qdrant_url,
+                    vtk_version=self.api_index.vtk_version,
+                )
+                logger.info("Retriever connected to %s", settings.qdrant_url)
+            except Exception as exc:
+                logger.warning("Retrieval disabled: %s", exc)
+
+        # Layer 3: validation (optional — library call, no subprocess)
+        self.validate = None
+        if settings.enable_validation:
+            try:
+                from vtk_validate import validate as _validate
+
+                _index = self.api_index
+
+                def _validate_bound(source: str):
+                    return _validate(source, _index)
+
+                self.validate = _validate_bound
+                logger.info("Validation enabled")
+            except Exception as exc:
+                logger.warning("Validation disabled: %s", exc)
+
+
+_context: VTKMCPContext | None = None
+
+
+def get_context() -> VTKMCPContext:
+    if _context is None:
+        raise RuntimeError("VTKMCPContext not initialised. Call init_context() first.")
+    return _context
+
+
+def init_context(settings: Settings | None = None) -> VTKMCPContext:
+    global _context
+    if settings is None:
+        settings = Settings()
+    _context = VTKMCPContext(settings)
+    return _context

src/vtk_mcp/composition.py

@@ -0,0 +1,33 @@
+"""Pydantic Settings for the vtk-mcp gateway.
+
+All parameters are configured via environment variables prefixed with
+``VTK_MCP_``.  For example: ``VTK_MCP_TRANSPORT=http``.
+"""
+
+from pathlib import Path
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    # Layer 1 — knowledge artifact
+    knowledge_artifact_path: Path = Path("/app/data/vtk-knowledge.jsonl")
+    vtk_version: str = "9.3.0"
+
+    # Layer 2 — retrieval
+    enable_retrieval: bool = True
+    qdrant_url: str = "http://qdrant:6333"
+
+    # Layer 3 — validation
+    enable_validation: bool = True
+
+    # Transport
+    transport: str = "stdio"
+    http_host: str = "0.0.0.0"
+    http_port: int = 8000
+
+    # C++ docs scraping
+    enable_cpp_scraping: bool = True
+    vtk_docs_base_url: str = "https://vtk.org/doc/nightly/html/"
+
+    class Config:
+        env_prefix = "VTK_MCP_"