mcp-spatial-asset-profile — Python SDK

Reference Python SDK for the MCP Spatial Asset Profile v2 — a JSON envelope format for 3D / spatial assets in Model Context Protocol (MCP) tool ecosystems.

• Distribution name (PyPI): mcp-spatial-asset-profile
• Import package: spatial_asset_v2
• TypeScript counterpart: @furuse-kazufumi/mcp-spatial-asset-profile
• Spec & repository: https://github.com/furuse-kazufumi/mcp-spatial-asset-profile
• Release tag: v0.1.0-poc

Status — Proof of Concept. The format is usable for prototyping and interoperability experiments. The wire format is not yet frozen; feedback via GitHub Discussions is explicitly welcome before v2.1.

Installation

Once published to PyPI:

pip install mcp-spatial-asset-profile
# Optional: enable JSON Schema validation
pip install "mcp-spatial-asset-profile[validate]"

From source (this repository):

cd sdk/python
pip install -e ".[dev]"

Quick Start

from spatial_asset_v2.models import SpatialAsset, Representation, Spatial
from spatial_asset_v2.codec import encode_asset, decode_asset
from spatial_asset_v2.validators import validate_asset
from spatial_asset_v2.workflow import WorkflowMockRunner

# Create a v2 asset
asset = SpatialAsset(
    asset_id="urn:uuid:550e8400-e29b-41d4-a716-446655440001",
    kind="point-cloud",
    representations=[
        Representation(format="ply", uri="samples/bunny.ply", point_count=35947)
    ],
    spatial=Spatial(unit="m", up_axis="+Y"),
    name="Stanford Bunny",
)

# Encode to dict / JSON
d = encode_asset(asset)

# Decode from dict
asset2 = decode_asset(d)

# Validate against JSON schema (requires jsonschema)
errors = validate_asset(d)
print("Valid:", len(errors) == 0)

# Run mock segmentation workflow
runner = WorkflowMockRunner(base_dir="samples/inspection")
pipeline = runner.run_full_pipeline(
    source_asset_id="urn:uuid:...",
    source_ply_path="bunny_full.ply"
)

Modules

CLI

# Validate a JSON asset file
spatial-asset-v2 validate spec/examples/pointcloud-asset.json

# Generate sample assets
spatial-asset-v2 generate --output /tmp/samples

# Run mock segmentation pipeline
spatial-asset-v2 workflow --source spec/examples/pointcloud-asset.json

# Migrate v1 asset to v2
spatial-asset-v2 migrate old-asset-v1.json new-asset-v2.json

Running Tests

cd sdk/python
pip install -e ".[dev]"
pytest tests/ -v

License

MIT — see the LICENSE file at the repository root.