VTK MCP

A thin MCP gateway that exposes vtk-knowledge, vtk-index, and vtk-validate as Model Context Protocol tools. All domain logic lives in those libraries; this project only wires them together.

Installation

# With uv (recommended)
uv add vtk-mcp

# With pip
pip install \
  "git+https://github.com/vicentebolea/vtk-knowledge" \
  "git+https://github.com/vicentebolea/vtk-validate"
pip install -e .

# With retrieval support (vtk-index)
pip install \
  "git+https://github.com/vicentebolea/vtk-knowledge" \
  "git+https://github.com/vicentebolea/vtk-validate" \
  "git+https://github.com/vicentebolea/vtk-index"
pip install -e ".[retrieval]"

Usage

# stdio (default — for MCP clients)
vtk-mcp

# HTTP
vtk-mcp --transport http --port 8000

# Pin a specific VTK version (artifact auto-downloaded from ghcr.io)
vtk-mcp --vtk-version 9.6.1

Key environment variables:

Variable	Default	Description
VTK_MCP_VTK_VERSION	9.3.0	VTK version to fetch artifacts for
VTK_MCP_KNOWLEDGE_ARTIFACT_PATH	(auto)	Local JSONL path; skips auto-download
VTK_MCP_QDRANT_URL	(auto)	Qdrant server URL; if unset uses embedded storage from ghcr.io
VTK_MCP_ENABLE_VALIDATION	true	Enable vtk-validate code validation
VTK_MCP_TRANSPORT	stdio	stdio or http

MCP Tools

Knowledge lookup — via vtk-knowledge + vtk-validate

Data comes from the vtk-knowledge artifact; the query helpers are implemented in vtk-validate's tool layer.

Each field in VTKDocRecord has one of three origins:

• extraction — parsed directly from the VTK Python runtime (help(), introspection, MRO)
• LLM — generated by an LLM enrichment pass during artifact build
• metadata — versioning and integrity fields added at build time

Tool	Field(s)	Origin
vtk_get_class_info(class_name)	all fields	— (convenience: full record)
vtk_search_classes(query, limit)	class_name, module_name, synopsis	—
vtk_get_class_doc(class_name)	class_doc	extraction
vtk_get_class_methods(class_name)	methods (name, signatures, doc)	extraction
vtk_get_method_info(class_name, method_name)	single VTKMethod	extraction
vtk_get_method_doc(class_name, method_name)	method.doc	extraction
vtk_get_method_signature(class_name, method_name)	method.signatures[0]	extraction
vtk_get_class_inheritance(class_name)	inheritance (full MRO chain)	extraction
vtk_get_class_role(class_name)	role (source, filter, mapper, renderer, scene, …)	extraction
vtk_get_class_input_datatype(class_name)	input_datatype	extraction
vtk_get_class_output_datatype(class_name)	output_datatype	extraction
vtk_get_class_module(class_name)	module_name (vtkmodules.* path)	extraction
vtk_get_module_classes(module)	all class_names in a module	extraction
vtk_get_class_semantic_methods(class_name)	semantic_methods (non-inherited)	extraction
vtk_is_a_class(class_name)	membership check	—
vtk_get_class_synopsis(class_name)	synopsis (one sentence, ≤20 words)	LLM
vtk_get_class_action_phrase(class_name)	action_phrase (noun phrase, ≤5 words)	LLM
vtk_get_class_visibility(class_name)	visibility_score (0.0–1.0)	LLM
vtk_get_class_record_metadata(class_name)	vtk_version, schema_version, content_hash	metadata
vtk_version_info()	index-level vtk_version, class count, feature flags	metadata

Semantic search — via vtk-index

Requires VTK_MCP_ENABLE_RETRIEVAL=true. vtk-index owns all chunking, embedding, and Qdrant hybrid retrieval (dense + BM25 with RRF fusion); vtk-mcp simply delegates.

Tool	Description
vector_search_docs(query, k, role, class_name, min_visibility)	Hybrid search over VTK documentation chunks
vector_search_examples(query, k, role, class_name, min_visibility)	Hybrid search over VTK code example chunks

Both search tools accept optional Qdrant payload filters:

Parameter	Type	Description
k	int	Number of results (default 10)
role	str	Filter by pipeline role (source, filter, mapper, output)
class_name	str	Restrict to chunks mentioning a specific class
min_visibility	float	Minimum visibility score threshold (0.0–1.0)

When VTK_MCP_QDRANT_URL is unset, vtk-index downloads a pre-built embedded Qdrant storage from ghcr.io/vicentebolea/vtk-index on first use — no server required.

Validation — via vtk-validate

AST-based validation against the VTK API. Checks imports, constructors, method calls, argument ordering, and security issues.

Tool	Description
validate_vtk_code(source)	Validate a Python source string; returns {status, diagnostics, vtk_version, elapsed_ms}
vtk_validate_import(import_statement)	Validate a single import line and suggest corrections

Claude Code integration

With the pre-built container (recommended)

Start the container once; Claude Code connects over HTTP:

podman run -d --rm -p 8000:8000 --name vtk-mcp ghcr.io/kitware/vtk-mcp/vtk-mcp:latest

Then add to .claude/settings.json (project) or ~/.claude/settings.json (global):

{
  "mcpServers": {
    "vtk": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

With a local install

vtk-mcp --transport http --port 8000 --vtk-version 9.6.1 &

{
  "mcpServers": {
    "vtk": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

After adding the config, run /mcp in Claude Code to verify the server connects and tools are listed.

Docker

# Run pre-built image (artifacts pre-cached for VTK 9.6.1)
podman run ghcr.io/kitware/vtk-mcp:latest

# Build locally
podman build -f deploy.Dockerfile -t vtk-mcp .

# Build for a specific VTK version
podman build -f deploy.Dockerfile --build-arg VTK_VERSION=9.6.1 -t vtk-mcp .

Development

# Install sibling packages from local checkouts
uv sync --extra dev

# Or with pip
pip install \
  "git+https://github.com/vicentebolea/vtk-knowledge" \
  "git+https://github.com/vicentebolea/vtk-validate"
pip install -e ".[dev]"

# Lint and format
ruff check src/vtk_mcp/
ruff format src/vtk_mcp/

# Tests
pytest -m unit
pytest tests/test_client_no_server.py
pytest -m integration

Architecture

vtk-mcp  (this repo — composition root only)
├── vtk-knowledge   schema, VTKAPIIndex, artifact download
├── vtk-index       chunking, embedding, Qdrant retrieval
└── vtk-validate    AST-based code validation

src/vtk_mcp/composition.py constructs all dependencies once at startup; tool handlers in src/vtk_mcp/tools/ delegate to the libraries with no added logic.

Authors

• Patrick O'Leary @ Kitware
• Vicente Bolea @ Kitware