# vtk-mcp

**Repository Path**: mirrors_Kitware/vtk-mcp

## Basic Information

- **Project Name**: vtk-mcp
- **Description**: MCP server for VTK
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-02
- **Last Updated**: 2026-04-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VTK MCP Server

<img width="256" height="256" alt="vtk-mcp" src="https://github.com/user-attachments/assets/f1e8fc6d-2f51-4a15-8d02-12a05074dded" />

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](https://github.com/vicentebolea/vtk-data), a companion library that ships the pre-built VTK API index and a Qdrant-backed retriever.

## Installation

```bash
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):

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

## Usage

### Server

```bash
# 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

```bash
# 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](https://github.com/vicentebolea/vtk-data).

### Obtaining the database

The database is distributed as a container image on GHCR:

```bash
# 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):

```bash
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

```bash
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.

```bash
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):**

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

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

```bash
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:

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

## Development

```bash
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

```bash
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`.

```bash
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