x3d-mcp

This project has been adopted by the Web3D Consortium. Development continues at Web3DConsortium/x3d_mcp, the official MCP server for X3D under the AI with X3D Special Interest Group. This repository is preserved as the origin implementation and for publication credit.

An MCP server that gives AI models the ability to validate, look up, generate, analyze, and render X3D content.

X3D (Extensible 3D Graphics) is the ISO standard (ISO/IEC 19775) for representing 3D scenes and objects in XML. The Model Context Protocol (MCP) is a standard that lets AI models call external tools. This server bridges the two: it exposes 24 tools and 4 workflow prompts that let an AI work with X3D using authoritative spec data rather than training-data guesses, produce schema-valid output, animate it, and render it in a browser.

Features

• Validation -- Validate X3D content against the official X3D 4.0 XML Schema (26,000+ line XSD), catching invalid nodes, wrong attribute types, and hierarchy violations
• Semantic Checks -- Catch real-world authoring bugs that XSD can't: missing geometry on shapes, empty grouping nodes, broken DEF/USE references, duplicate DEF names, ROUTEs with invalid fields or mismatched types, and missing viewpoints
• Spec Lookup -- Query the full X3D Unified Object Model: 200+ concrete nodes, field types with constraints, inheritance chains, component/profile browsing, and parent-child hierarchy checking. Node and field descriptions are enriched at startup with human-readable authoring guidance — Hints and Warnings — sourced from the official X3D-Edit tooltip profile (x3d-4.0.profile.xml)
• Scene Generation -- Programmatically create X3D content via the official x3d.py library (X3DPSAIL), manipulate scenes with targeted node insertion, and convert to standalone X3DOM HTML pages for browser rendering
• Scene Manipulation -- Complete CRUD on existing scenes: modify field values on DEF'd nodes, remove nodes by DEF or type+index, and reparent nodes with cycle detection
• Animation & Interaction -- Auto-generate full TimeSensor + Interpolator + ROUTE chains from a target DEF and field name (the correct interpolator is selected based on the field's type), validate and insert individual ROUTEs with full type/access-type checking, and look up animation reference docs
• File Operations -- Parse existing X3D scenes into readable tree views, get node statistics by type and component, list all named (DEF'd) nodes, and extract specific node subtrees
• Guided Workflows -- MCP prompts for common multi-step tasks: building a scene from scratch, auditing an existing file, animating a scene, and converting to X3DOM

Quickstart

Prerequisites: Python 3.12+, uv

git clone <repo-url>
cd x3d-mcp
uv sync

The server uses stdio transport and is designed to be launched by an MCP client (see configuration below), not run standalone. To verify it starts correctly:

uv run python server.py

MCP Inspector

You can test the server interactively using the MCP Inspector, which is bundled with the mcp[cli] dependency:

uv run mcp dev server.py

This opens a web UI where you can call each tool, see input schemas, and inspect responses.

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "x3d": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/absolute/path/to/x3d-mcp"
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root. Use uv run --directory to point at the x3d-mcp project (this is more reliable than cwd, especially with paths containing spaces):

{
  "mcpServers": {
    "x3d": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/x3d-mcp", "python", "server.py"]
    }
  }
}

Replace /absolute/path/to/x3d-mcp with the actual path to this repository. If Cursor can't find uv, use the full path (e.g., /opt/homebrew/bin/uv on macOS).

Tools

Validation

Tool	Parameters	Description
validate_x3d	x3d_xml (string)	Validate an X3D XML string against the X3D 4.0 schema
validate_x3d_file_tool	filepath (string)	Validate a .x3d file on disk

Spec Lookup

Tool	Parameters	Description
x3d_node_info	node_name (string)	Get full spec info for a node: fields, types, defaults, constraints, inheritance
x3d_search_nodes	query (string)	Search nodes by name or description
x3d_list_components	component_name (string, optional)	List all components, or all nodes in a specific component
x3d_list_profiles	--	List all X3D profiles with descriptions
x3d_field_type_info	field_type (string)	Explain a field type (e.g. SFVec3f) or enumeration type
x3d_check_hierarchy	parent_node, child_node (strings)	Check if a parent-child node relationship is valid

Scene Generation

Tool	Parameters	Description
x3d_scene_template	profile, title, include_viewpoint, include_light	Generate a complete, valid X3D scene template
x3d_generate_node	node_name, fields (JSON string)	Generate a single X3D node XML fragment
x3d_add_node	scene_xml, node_xml, parent_def	Insert a node into an existing scene
x3dom_page	x3d_content, title, width, height, show_stats, show_log	Wrap X3D content in a standalone X3DOM HTML page
x3dom_starter	--	Generate a ready-to-open X3DOM page with an example scene

File Operations

Tool	Parameters	Description
x3d_parse_scene	x3d_source (file path or XML string)	Parse and display the scene graph as an indented tree
x3d_scene_stats	x3d_source	Get statistics: node counts by type and X3D component
x3d_list_defs	x3d_source	List all DEF'd (named) nodes with parent/children context
x3d_extract_node	x3d_source, def_name, node_type, index	Extract a specific node subtree as XML

Scene Manipulation

Tool	Parameters	Description
x3d_modify_node	x3d_source, def_name, field_changes (JSON string)	Update attribute values on a DEF'd node
x3d_remove_node	x3d_source, def_name, node_type, index	Remove a node (and its children) by DEF or by type+index
x3d_move_node	x3d_source, def_name, new_parent_def	Reparent a node to a new parent (or to <Scene> root); detects cycles

Semantic Validation

Tool	Parameters	Description
x3d_semantic_check	x3d_source	Run authoring checks beyond XSD: shape completeness, empty groups, duplicate DEFs, broken USE refs, ROUTE validity (DEF refs + field names + access types + type matching), missing viewpoint

Animation & Interaction

Tool	Parameters	Description
x3d_animate	x3d_source, target_def, field_name, from_value, to_value, duration, loop	Generate a complete animation chain (TimeSensor + correct Interpolator + 2 ROUTEs) for a target field and insert it into the scene
x3d_route	x3d_source, from_node, from_field, to_node, to_field	Validate (DEF existence, field existence, accessType compatibility, type matching) and insert a ROUTE statement
x3d_animation_info	topic (optional: interpolators, timesensor, routes, examples)	Reference documentation for X3D's event-driven animation system

Prompts

Prompt	Parameters	Description
build_scene	description (optional)	Step-by-step guide to build an X3D scene from scratch
audit_scene	filepath (optional)	Guide to analyze and audit an existing X3D file (now includes semantic check step)
convert_to_x3dom	--	Guide to convert X3D content into a browser-viewable HTML page
animate_scene	target_description (optional)	Step-by-step guide to add animation to an X3D scene

Common Workflows

Build a 3D scene

1. x3d_scene_template(profile="Interchange", title="My Scene")
2. x3d_node_info("Sphere")                          -- check available fields
3. x3d_generate_node("Sphere", '{"radius": 2.5}')   -- create geometry
4. x3d_add_node(scene_xml, node_xml)                 -- insert into scene
5. validate_x3d(scene_xml)                           -- verify against schema
6. x3dom_page(scene_xml, title="My Scene")           -- render in browser

Audit an existing X3D file

1. x3d_parse_scene("/path/to/model.x3d")          -- see the scene graph tree
2. x3d_scene_stats("/path/to/model.x3d")          -- get node counts by type/component
3. x3d_list_defs("/path/to/model.x3d")            -- list all named nodes
4. validate_x3d_file_tool("/path/to/model.x3d")   -- check schema compliance
5. x3d_semantic_check("/path/to/model.x3d")       -- catch authoring bugs (broken ROUTEs, etc.)
6. x3d_extract_node("/path/to/model.x3d", def_name="SomeNode")  -- inspect specific nodes

Modify and animate an existing scene

1. x3d_list_defs(scene_xml)                       -- find DEF names to target
2. x3d_modify_node(scene_xml, "RedMat",
                   '{"diffuseColor": "0 1 0"}')   -- recolor a material
3. x3d_animation_info("interpolators")            -- reference: which interp matches the field
4. x3d_animate(scene_xml, target_def="MyTransform",
               field_name="rotation",
               from_value="0 1 0 0",
               to_value="0 1 0 6.283",
               duration=4.0, loop=True)           -- spin a transform around Y
5. x3d_semantic_check(scene_xml)                  -- verify ROUTEs are correctly wired
6. x3dom_page(scene_xml, title="Animated")        -- render in browser

Example: X3D input/output

A minimal X3D scene with a red sphere:

<?xml version="1.0" encoding="UTF-8"?>
<X3D profile="Interchange" version="4.0">
  <Scene>
    <Viewpoint description="Front" position="0 0 10"/>
    <Shape>
      <Appearance>
        <Material diffuseColor="1 0 0"/>
      </Appearance>
      <Sphere radius="2"/>
    </Shape>
  </Scene>
</X3D>

Key X3D patterns:

• Shape = Appearance (Material + optional Texture) + Geometry (Box, Sphere, Cylinder, etc.)
• Transform wraps children with translation, rotation, and scale
• DEF/USE names let you define a node once and reuse it
• SFColor is 3 floats in [0,1] range (e.g., 1 0 0 = red)
• SFRotation is axis-angle: x y z angle_in_radians

Architecture

flowchart TD
    Server["server.py\n24 MCP tools + 4 prompts"] --> Validation["src/validation.py\nxmlschema"]
    Server --> SpecLookup["src/spec_lookup.py\nquery functions"]
    Server --> Generation["src/generation.py\nx3d.py + lxml"]
    Server --> FileOps["src/file_ops.py\nparse + analyze"]
    Server --> SceneOps["src/scene_manipulation.py\nmodify / remove / move"]
    Server --> Semantic["src/semantic_check.py\nauthoring checks"]
    Server --> Animation["src/animation.py\nTimeSensor + Interp + ROUTE"]

    SpecLookup --> X3DUOM["src/x3duom_loader.py\nin-memory index"]
    FileOps --> X3DUOM
    Semantic --> X3DUOM
    Animation --> X3DUOM

    SceneOps --> FileOps
    Semantic --> FileOps
    Animation --> FileOps

    Validation --> XSD["spec/x3d-4.0.xsd"]
    X3DUOM --> UOM["spec/X3dUnifiedObjectModel-4.0.xml"]
    X3DUOM --> Tooltips["src/tooltip_loader.py\ntooltip enrichment"]
    Tooltips --> Profile["wiki/x3d-4.0.profile.xml\nX3D-Edit authoring profile"]

    Generation --> Validation

File	Role
server.py	MCP entry point. Registers all 24 tools and 4 prompts with FastMCP and runs the stdio transport.
src/validation.py	Loads the X3D 4.0 XSD via xmlschema, strips namespace/DOCTYPE processing instructions, and validates XML strings or files.
src/x3duom_loader.py	Parses the 43,000-line X3DUOM XML into in-memory dictionaries. Resolves full inheritance chains to collect all fields for any node. At load time calls tooltip_loader to overlay richer descriptions. Singleton via lru_cache.
src/tooltip_loader.py	Parses wiki/x3d-4.0.profile.xml (the X3D-Edit authoring profile) and indexes per-node and per-field tooltip text — including human-readable descriptions, authoring Hints, and Warnings from the Web3D Consortium. Merged into the X3DUOM index at startup.
src/spec_lookup.py	Query layer over the X3DUOM index: node info, search, component/profile listing, field type documentation, hierarchy checking with inheritance-aware type matching.
src/generation.py	Constructs X3D nodes via the official x3d.py (X3DPSAIL) library, manipulates scene trees with lxml, and converts X3D XML to X3DOM-compatible HTML (lowercase tags, explicit closing tags, namespace stripping).
src/file_ops.py	Reads and analyzes existing X3D content: scene graph tree view, statistics by type/component, DEF node listing, and node extraction. Exposes parse_x3d_source and find_scene as the shared parsing foundation used by the manipulation, semantic, and animation modules.
src/scene_manipulation.py	Completes the CRUD cycle for X3D scenes: modify field values on DEF'd nodes, remove nodes by DEF or type+index, and reparent nodes with cycle detection.
src/semantic_check.py	Authoring-level checks beyond XSD: shape completeness, empty grouping nodes, duplicate DEFs, DEF/USE consistency, ROUTE validity (DEF refs + field names + access types + type matching), and missing viewpoints.
src/animation.py	Auto-generates TimeSensor + Interpolator + ROUTE chains for animations (the correct interpolator is selected from the target field's type via X3DUOM lookup), validates and inserts individual ROUTEs, and provides reference documentation for X3D's event-driven animation system.
spec/	Bundled official spec files: X3D 4.0 XSD (with Web3D extension schemas) and the X3D Unified Object Model XML.
wiki/x3d-4.0.profile.xml	X3D-Edit authoring profile from the Web3D Consortium (Don Brutzman). Contains rich tooltip text for every X3D 4.0 node and attribute — used by tooltip_loader.py to enrich spec lookup output.

Development

Install all dependencies including dev tools:

uv sync --group dev

Run the test suite:

uv run pytest

There are currently 171 tests across seven test files:

Test file	Count	Covers
tests/test_validation.py	8	Schema validation of valid/invalid documents, XSI attribute stripping, file handling, edge cases
tests/test_spec_lookup.py	31	X3DUOM loading, node info, search, components, profiles, field types, hierarchy checking
tests/test_generation.py	26	Scene templates, node generation, scene composition, X3DOM page output, HTML escaping
tests/test_file_ops.py	36	Scene parsing, statistics, DEF listing, node extraction, file path handling
tests/test_scene_manipulation.py	26	Modify, remove, and move nodes; cycle detection; round-trip schema validation
tests/test_semantic_check.py	19	Shape completeness, empty groups, duplicate DEFs, DEF/USE consistency, ROUTE validity, missing viewpoint
tests/test_animation.py	25	Animation chain generation for rotation/translation/color/scalar fields, ROUTE validation, animation reference docs

Adding a New Tool

1. Implement the function in the appropriate src/ module
2. Register it in server.py with the @mcp.tool() decorator
3. Write a detailed docstring -- the AI model sees this as the tool description
4. Add tests in the corresponding tests/test_*.py file