Metadata-Version: 2.4
Name: spline-mcp
Version: 0.1.1
Summary: MCP server for Spline.design 3D scene orchestration
Project-URL: Homepage, https://github.com/lesleslie/spline-mcp
Project-URL: Repository, https://github.com/lesleslie/spline-mcp.git
Author-email: Les Leslie <les@wedgwood.us>
License: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.13
Requires-Dist: fastmcp>=2.12.3
Requires-Dist: httpx>=0.28.0
Requires-Dist: mcp-common>=0.4.8
Requires-Dist: oneiric>=0.3.6
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: rich>=13.0.0
Requires-Dist: structlog>=25.0.0
Requires-Dist: typer>=0.15.0
Requires-Dist: uvicorn>=0.30.0
Description-Content-Type: text/markdown

# spline-mcp

MCP server for [Spline.design](https://spline.design) 3D scene orchestration.

## Installation

```bash
uv pip install -e .
```

## Configuration

Set your Spline API key as an environment variable:

```bash
export SPLINE_API_KEY="your-api-key-here"
```

Or create a `.env` file:

```
SPLINE_API_KEY=your-api-key-here
```

## Usage

### Stdio Mode (default)

```bash
spline-mcp serve
```

### HTTP Mode

```bash
spline-mcp serve --http --port 3048
```

### Health Check

```bash
spline-mcp health
```

## Available Tools

### Scene Management

| Tool | Description |
|------|-------------|
| `list_scenes` | List all accessible scenes |
| `get_scene` | Get scene details by ID |
| `create_scene` | Create a new scene |
| `delete_scene` | Delete a scene |

### Object Management

| Tool | Description |
|------|-------------|
| `list_objects` | List all objects in a scene |
| `get_object` | Get object details |
| `create_object` | Create a new 3D object |
| `update_object` | Update object properties |
| `delete_object` | Delete an object |

### Material System

| Tool | Description |
|------|-------------|
| `list_materials` | List all materials in a scene |
| `create_material` | Create a new material |
| `apply_material` | Apply material to an object |

### Events & Actions

| Tool | Description |
|------|-------------|
| `list_events` | List all events in a scene |
| `create_event` | Create a new event |
| `trigger_event` | Manually trigger an event |

### Runtime API

| Tool | Description |
|------|-------------|
| `get_runtime_state` | Get current runtime state |
| `set_variable` | Set a runtime variable |
| `export_scene` | Export scene to file format |

## Configuration Options

Set via environment variables with `SPLINE_` prefix:

| Variable | Default | Description |
|----------|---------|-------------|
| `SPLINE_API_KEY` | - | Spline API authentication key |
| `SPLINE_API_BASE_URL` | `https://api.spline.design/v1` | API base URL |
| `SPLINE_API_TIMEOUT` | `30.0` | Request timeout in seconds |
| `SPLINE_DEFAULT_SCENE_ID` | - | Default scene for operations |
| `SPLINE_AUTO_SAVE` | `true` | Auto-save after modifications |
| `SPLINE_HTTP_HOST` | `127.0.0.1` | HTTP server host |
| `SPLINE_HTTP_PORT` | `3048` | HTTP server port |
| `SPLINE_LOG_LEVEL` | `INFO` | Logging level |
| `SPLINE_LOG_JSON` | `true` | Use JSON logging format |

## Architecture

Built with the Bodai ecosystem stack:

- **FastMCP**: MCP protocol implementation
- **Oneiric**: Configuration management
- **mcp-common**: Shared utilities
- **Pydantic**: Data validation
- **httpx**: Async HTTP client

## License

BSD-3-Clause
