Skip to content

README.md

Latest commit

 

History

History
226 lines (156 loc) · 6.84 KB

README.md

File metadata and controls

226 lines (156 loc) · 6.84 KB

VTK MCP Server

vtk-mcp

Access VTK class documentation through a Model Context Protocol server. The server exposes 22 tools covering C++ online documentation, Python API introspection, import validation, and semantic vector search over VTK examples.

The Python API tools and vector search depend on vtk-data, a companion library that ships the pre-built VTK API index and a Qdrant-backed retriever.

Installation

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

pip install git+https://github.com/vicentebolea/vtk-data.git
pip install .

To enable vector search (requires a running Qdrant instance):

pip install "vtk-data[rag] @ git+https://github.com/vicentebolea/vtk-data.git"

Usage

Server

# Stdio transport (default, for MCP clients)
vtk-mcp-server

# HTTP transport
vtk-mcp-server --transport http --host localhost --port 8000

# With Python API tools enabled (requires vtk-python-docs.jsonl)
vtk-mcp-server --data-path /path/to/vtk-python-docs.jsonl

# With vector search enabled (requires Qdrant)
vtk-mcp-server --data-path /path/to/vtk-python-docs.jsonl \
               --qdrant-url http://localhost:6333

Client

# Get C++ class documentation
vtk-mcp-client info-cpp vtkActor

# Get Python API documentation
vtk-mcp-client info-python vtkSphereSource

# Search for classes
vtk-mcp-client search Camera

# List all available tools
vtk-mcp-client list-tools

# Connect to a specific server
vtk-mcp-client --host localhost --port 8000 info-cpp vtkActor

MCP Tools

C++ documentation (no setup required)

  • get_vtk_class_info_cpp(class_name) - Fetch C++ class documentation from online VTK docs
  • search_vtk_classes(search_term) - Search VTK class names

Python API (requires --data-path)

These tools use the pre-built vtk-python-docs.jsonl index generated by vtk-data.

  • get_vtk_class_info_python(class_name) - Full Python API docs: synopsis, role, module, methods
  • vtk_get_class_info(class_name) - Complete class record as JSON
  • vtk_search_classes(query, limit) - Search classes by name or keyword
  • vtk_get_class_module(class_name) - Return the vtkmodules.* import path
  • vtk_get_class_methods(class_name, method_name) - List methods, optionally look up one
  • vtk_get_module_classes(module) - List all classes in a VTK module
  • vtk_get_method_info(class_name, method_name) - Full method documentation
  • vtk_get_method_doc(class_name, method_name) - Method docstring only
  • vtk_get_method_signature(class_name, method_name) - Canonical method signature
  • vtk_get_class_doc(class_name) - Class docstring
  • vtk_get_class_synopsis(class_name) - One-line class summary
  • vtk_get_class_action_phrase(class_name) - Short action phrase (e.g. "mesh filtering")
  • vtk_get_class_role(class_name) - Pipeline role (input, filter, renderer, output, ...)
  • vtk_get_class_visibility(class_name) - Visibility score (0.0-1.0)
  • vtk_get_class_input_datatype(class_name) - Expected input data type
  • vtk_get_class_output_datatype(class_name) - Produced output data type
  • vtk_get_class_semantic_methods(class_name) - Non-boilerplate callable methods
  • vtk_is_a_class(class_name) - Check whether a name is a valid VTK class

Import validation (requires --data-path)

  • vtk_validate_import(import_statement) - Validate a VTK import and suggest the correct module path

Vector search (requires --data-path and --qdrant-url)

  • vector_search_vtk_examples(query, collection, top_k) - Hybrid semantic + BM25 search over VTK code examples indexed in Qdrant

vtk-data and the API database

The Python API tools and vector search depend on vtk-python-docs.jsonl, a pre-built index of 2,943 VTK classes with LLM-enriched documentation generated by vtk-data.

Obtaining the database

The database is distributed as a container image on GHCR:

# Extract with Docker
docker create --name vtk-db ghcr.io/vicentebolea/vtk-data-database:latest
docker cp vtk-db:/vtk-python-docs.jsonl .
docker rm vtk-db

# Extract with Podman
podman create --name vtk-db ghcr.io/vicentebolea/vtk-data-database:latest
podman cp vtk-db:/vtk-python-docs.jsonl .
podman rm vtk-db

Alternatively, generate it from scratch (requires VTK installed and an LLM API key, takes approximately one hour):

pip install "vtk-data[extract] @ git+https://github.com/vicentebolea/vtk-data.git"
vtk-data extract --output ./data
# produces ./data/docs/vtk-python-docs.jsonl

Starting the server with the database

vtk-mcp-server --transport http \
               --host 0.0.0.0 \
               --port 8000 \
               --data-path ./vtk-python-docs.jsonl

Docker

Using the pre-built image

The image is built with the pre-built database embedded and serves over HTTP on port 8000.

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

# Access the MCP endpoint at http://localhost:8000/mcp

Building locally

The deploy.Dockerfile supports two modes controlled by the SKIP_EXTRACT build argument.

Use the pre-built database (recommended):

podman build --build-arg SKIP_EXTRACT=true -f deploy.Dockerfile -t vtk-mcp .

Run full extraction during build (requires an LLM API key):

podman build --secret id=llm_api_key,src=~/.llm_api_key -f deploy.Dockerfile -t vtk-mcp .

A test.Dockerfile is also provided for local development. It expects vtk-python-docs.jsonl in the repository root:

podman build -f test.Dockerfile -t vtk-mcp-test .

Development

python -m venv venv
source venv/bin/activate

pip install git+https://github.com/vicentebolea/vtk-data.git
pip install -e .

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

# Run the server
vtk-mcp-server --transport http &
vtk-mcp-client info-cpp vtkActor

Testing

pip install -e ".[test]"

# All tests
pytest

# By category
pytest -m unit
pytest -m integration
pytest -m http
pytest -m stdio

Test structure

  • tests/test_server_functions.py - Unit tests for MCP tool functions
  • tests/test_client_no_server.py - Client error handling when server is unavailable
  • tests/test_http_integration.py - Full integration tests over HTTP transport
  • tests/test_stdio_integration.py - Full integration tests over stdio transport
  • tests/test_vector_search_integration.py - Vector search integration tests (requires Qdrant)

Release

The package version is determined automatically from git tags using setuptools-scm.

git tag -a v0.3.0 -m "Release v0.3.0"
git push origin v0.3.0

CI will build and push the deployment image to ghcr.io/kitware/vtk-mcp on every push to master.

Authors

  • Vicente Bolea @ Kitware