# 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-05-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VTK MCP

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

A thin MCP gateway that exposes [vtk-knowledge](https://github.com/vicentebolea/vtk-knowledge), [vtk-index](https://github.com/vicentebolea/vtk-index), and [vtk-validate](https://github.com/vicentebolea/vtk-validate) as Model Context Protocol tools. All domain logic lives in those libraries; this project only wires them together.

## Installation

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

```bash
# 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](https://github.com/vicentebolea/vtk-knowledge) + [vtk-validate](https://github.com/vicentebolea/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_name`s 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](https://github.com/vicentebolea/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](https://github.com/vicentebolea/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:

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

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

### With a local install

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

```json
{
  "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

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

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