VTK API Validation via MCP

Post-generation validation of VTK Python code using Model Context Protocol (MCP).

Overview

This module provides automatic validation of generated VTK code to catch API hallucinations:

• ✅ Direct API lookups - No vector search overhead, exact class/method verification
• ✅ Method existence validation - Detects when LLM invents non-existent methods
• ✅ Import validation - Verifies VTK classes are imported from correct modules
• ✅ Fast in-memory index - Loads ~2,900 VTK classes at startup
• ✅ Structured error reporting - Clear error messages with suggestions

---

Quick Start

1. Install Dependencies

./setup.sh          # Production only (MCP library)
./setup.sh --dev    # Include testing tools (pytest, ruff)

This creates a virtual environment and installs dependencies.

2. Test MCP Integration (Optional)

source .venv/bin/activate
python demo_mcp_integration.py

This runs a complete demo showing how to use vtkapi-mcp as an MCP server (not as standalone Python library). It demonstrates all 5 MCP tools and error detection.

3. Configure MCP Client

Add to your MCP settings (e.g., Claude Desktop config):

{
  "mcpServers": {
    "vtk-api": {
      "command": "python",
      "args": [
        "-m",
        "vtkapi_mcp",
        "--api-docs",
        "/absolute/path/to/vtkapi-mcp/data/vtk-python-docs.jsonl"
      ]
    }
  }
}

4. Use VTK Tools

The MCP server provides 5 tools for VTK API validation and lookup. See MCP Tools below.

---

Project Structure

Package Organization

vtkapi_mcp/
├── core/              # API indexing and data loading
│   └── api_index.py
├── validation/        # Code validation logic
│   ├── models.py
│   ├── validator.py
│   ├── import_validator.py
│   ├── class_validator.py
│   └── method_validator.py
├── server/           # MCP server implementation
│   ├── mcp_server.py
│   └── tools.py
└── utils/            # Utilities for parsing and search
    ├── extraction.py
    └── search.py

Supporting Files

File	Purpose
demo_mcp_integration.py	Demo showing proper MCP integration (not standalone)
requirements.txt	Python dependencies
README.md	This file

Data

File	Purpose	Size
data/vtk-python-docs.jsonl	VTK API documentation (~2,900 classes)	~64 MB

---

Architecture

VTKAPIIndex (vtkapi_mcp/core/api_index.py)

Fast in-memory index of all VTK classes and methods:

VTKAPIIndex
├── Classes Dict: {class_name → {module, methods, docs}}
├── Modules Dict: {module_name → [class_names]}
└── Load Time: <1 second for ~2,900 classes

Key Methods:

• get_class_info(class_name) - Get module and documentation
• search_classes(query) - Search by name or keyword
• get_module_classes(module) - List classes in module
• class_exists(class_name) - Check if class exists

VTKCodeValidator (vtkapi_mcp/validation/validator.py)

AST-based validation of generated Python code:

VTKCodeValidator
├── Parse Code: Uses Python's ast module
├── Extract VTK Usage:
│   ├── Import statements
│   ├── Class instantiations
│   └── Method calls
├── Validate Against Index:
│   ├── Check classes exist
│   ├── Check imports correct
│   └── Check methods exist
└── Generate Error Report

Validation Types:

1. Import Validation - Verifies module paths
2. Class Validation - Checks class existence
3. Method Validation - Detects hallucinated methods

---

MCP Tools Provided

When running as MCP server, provides these tools:

1. vtk_get_class_info

Get complete information about a VTK class.

Input:

{
  "class_name": "vtkPolyDataMapper"
}

Output:

{
  "class_name": "vtkPolyDataMapper",
  "module": "vtkmodules.vtkRenderingCore",
  "content_preview": "vtkPolyDataMapper - map vtkPolyData to graphics primitives..."
}

2. vtk_search_classes

Search for VTK classes by name or keyword.

Input:

{
  "query": "reader",
  "limit": 5
}

Output:

[
  {
    "class_name": "vtkSTLReader",
    "module": "vtkmodules.vtkIOGeometry",
    "description": "Read ASCII or binary stereo lithography files."
  }
]

3. vtk_validate_import

Validate and correct VTK import statements.

Input:

{
  "import_statement": "from vtkmodules.vtkCommonDataModel import vtkPolyDataMapper"
}

Output:

{
  "valid": false,
  "message": "Incorrect module. 'vtkPolyDataMapper' is in 'vtkmodules.vtkRenderingCore'",
  "suggested": "from vtkmodules.vtkRenderingCore import vtkPolyDataMapper"
}

4. vtk_get_method_info

Get documentation for a specific method.

Input:

{
  "class_name": "vtkPolyDataMapper",
  "method_name": "SetInputData"
}

Output:

{
  "class_name": "vtkPolyDataMapper",
  "method_name": "SetInputData",
  "documentation": "SetInputData(vtkDataObject) - Set the input data..."
}

---

Benefits Over RAG Retrieval

Aspect	RAG Retrieval	MCP Validation
Speed	Vector search + reranking	Direct hash lookup (instant)
Accuracy	Semantic similarity (can drift)	Exact API match (100%)
Coverage	Top-K only (~10 results)	All ~2,900 classes available
Tokens	Consumes prompt tokens	Tool calls (minimal cost)
Errors	Silent hallucinations	Explicit error messages

---

Validation Examples

Example 1: Method Hallucination (CAUGHT ✅)

Generated Code:

stencil = vtkImageStencilToImage()
stencil.SetOutputWholeExtent([0, 10, 0, 10, 0, 10])  # ❌ Doesn't exist!

Validation Error:

UNKNOWN_METHOD: Method 'SetOutputWholeExtent' not found on class 'vtkImageStencilToImage'
Suggestion: Did you mean SetOutputOrigin or SetOutputSpacing?

Example 2: Wrong Import Module (CAUGHT ✅)

Generated Code:

from vtkmodules.vtkCommonDataModel import vtkPolyDataMapper  # ❌ Wrong module!

Validation Error:

IMPORT_ERROR: 'vtkPolyDataMapper' is not in module 'vtkmodules.vtkCommonDataModel'
Correct import: from vtkmodules.vtkRenderingCore import vtkPolyDataMapper

Example 3: Non-existent Class (CAUGHT ✅)

Generated Code:

converter = vtkImageDataToPolyDataConverter()  # ❌ Class doesn't exist!

Validation Error:

UNKNOWN_CLASS: Class 'vtkImageDataToPolyDataConverter' not found in VTK
Suggestion: Did you mean vtkImageDataGeometryFilter?

---

Data Source

Input: data/vtk-python-docs.jsonl

Each line is a VTK class documentation in JSON format:

{
  "class": "vtkPolyDataMapper",
  "module": "vtkmodules.vtkRenderingCore",
  "methods": ["SetInputData", "GetInput", "Update", ...],
  "documentation": "Full class documentation..."
}

Coverage: ~2,900 VTK classes from VTK Python API

---

Future Enhancements

• Method signature validation - Check parameter types and counts
• Deprecation warnings - Flag deprecated VTK methods
• Pipeline validation - Verify data flow compatibility
• Auto-fix suggestions - Generate corrected code automatically
• Performance profiling - Track validation overhead
• Cache layer - Cache frequent lookups for speed

---

License

This is a standalone MCP server for VTK API validation. Extracted from the vtk-rag project.

---

Status: Production ready MCP server for VTK API validation.