nova3d-mcp 0.1.0__tar.gz

nova3d_mcp-0.1.0/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pytest *)",
+      "Bash(python3 -m pytest tests/test_client.py::test_parse_auth_error_revoked tests/test_client.py::test_parse_auth_error_invalid_key -v)",
+      "Bash(.venv/bin/pytest *)"
+    ]
+  }
+}

nova3d_mcp-0.1.0/.env.example

@@ -0,0 +1,8 @@
+# Nova3D MCP Server — environment variables
+# Copy to .env and fill in your values
+
+# Required: API key from nova3d.xyz → Settings → API Keys
+NOVA3D_TOKEN=n3d_your-api-key-here
+
+# Optional: override the API base URL (advanced / self-hosted only)
+# NOVA3D_API_URL=https://nova3d.xyz/api

nova3d_mcp-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+*.egg-link
+*.pth
+.env

nova3d_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,62 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+An MCP server that wraps Nova3D's hosted 3D generation API as callable tools for Claude Code and other MCP-compatible agents. Users bring their own LLM provider key (Google, Anthropic, or OpenAI) and a Nova3D JWT token.
+
+## Commands
+
+```bash
+# First-time setup — create venv and install dev dependencies
+python3.10 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run tests (venv must be active)
+pytest
+
+# Run a single test
+pytest tests/test_client.py::test_generate_success
+
+# Run the server locally
+python -m nova3d_mcp.server
+# or after install:
+nova3d-mcp
+
+# Lint
+ruff check .
+```
+
+## Package layout note
+
+The source directory on disk is `nova3d_mcp/` (underscore), matching the Python import name. Always activate `.venv` before running tests.
+
+## Architecture
+
+**Three-file package:**
+
+- `nova3d_mcp/server.py` — FastMCP server. Registers 5 tools (`generate_3d`, `regenerate_part`, `add_part`, `articulate_model`, `get_generation_status`). Each tool creates a `Nova3DClient` context manager, calls the matching method, and maps the result to a flat dict. Auth (`NOVA3D_TOKEN`) and base URL (`NOVA3D_API_URL`) are read from env inside each tool call.
+
+- `nova3d_mcp/client.py` — Async HTTP client wrapping `httpx.AsyncClient`. Workflow pattern: readiness check → POST `/run/state/{workflow}` → poll `/status/{id}` every 3 s until terminal → GET `/result/{id}`. Transient 404/502/503/504 errors during polling are retried via `_is_recoverable()`. Auth and budget errors are never retried. Workflow IDs are microsecond timestamps (`state-{epoch_us}`).
+
+- `nova3d_mcp/models.py` — Pydantic models. `GenerationResult.from_api()` contains all response-parsing logic — the Nova3D API response structure is nested and has multiple fallback key paths (e.g. `model_url` vs `model_artifact.url`). `WorkflowState.parse()` normalizes state strings (`"succeeded"` → `COMPLETED`, etc.) and `is_terminal` drives the polling loop.
+
+**Data flow for a generation:**
+```
+tool call → _get_token() + _get_api_url()
+         → Nova3DClient.__aenter__()
+         → client.generate() → check_readiness() → _start_workflow() → _poll_and_collect()
+         → GenerationResult.from_api(raw_dict, workflow_id)
+         → tool returns flat dict to MCP caller
+```
+
+**Test setup:** `tests/test_client.py` uses `respx` to mock `httpx` at the transport level. `asyncio.sleep` is monkey-patched to `sleep(0)` inside tests to avoid real delays. The `mock_api` fixture scopes the mock to the test function with `assert_all_called=False`.
+
+## Environment variables
+
+| Variable | Required | Default |
+|---|---|---|
+| `NOVA3D_TOKEN` | Yes | — |
+| `NOVA3D_API_URL` | No | `https://nova3d.xyz/api` |

nova3d_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: nova3d-mcp
+Version: 0.1.0
+Summary: Nova3D MCP server — structured, part-aware 3D generation for AI agents
+Project-URL: Homepage, https://nova3d.xyz
+Project-URL: Repository, https://github.com/RareSense/nova3d-mcp
+Project-URL: Bug Tracker, https://github.com/RareSense/nova3d-mcp/issues
+Project-URL: Documentation, https://github.com/RareSense/nova3d-mcp#readme
+License: MIT
+Keywords: 3d-assets,3d-generation,ai,blender,generative-ai,mcp,model-context-protocol,nova3d
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.27.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nova3d-mcp
+
+**Structured, part-aware 3D generation for AI agents.**
+
+nova3d-mcp is an [MCP](https://modelcontextprotocol.io) server that exposes
+[Nova3D](https://nova3d.xyz)'s generation pipeline as a callable tool inside
+Claude Code, Cursor, and any MCP-compatible agent.
+
+One tool call. A washing machine comes back with named drum, door, control
+panel, and hose connectors — separately editable, not fused into a blob.
+
+---
+
+## Why Nova3D
+
+Every major AI 3D generator today produces **mesh blobs** — a single fused
+object that looks plausible in a render and collapses the moment you try to
+edit, rig, or pipeline it.
+
+Nova3D is different. Instead of diffusion → mesh, it runs:
+
+```
+prompt / image
+      ↓
+LLM writes Blender Python construction code
+      ↓
+headless Blender executes + validates + repairs
+      ↓
+structured GLB — named parts, intact hierarchy, real joints
+```
+
+The result is a 3D asset that **survives contact with real workflows**: game
+engines, configurators, robotics simulations, AR scenes. Parts have names.
+Hierarchy is intact. Joints are real. You can change one component without
+regenerating everything.
+
+---
+
+## Quickstart
+
+### 1. Install
+
+**Once on PyPI (coming soon):**
+```bash
+uvx nova3d-mcp
+```
+
+**From source (available now):**
+```bash
+git clone https://github.com/RareSense/nova3d-mcp.git
+cd nova3d-mcp
+python3.10 -m venv .venv && source .venv/bin/activate
+pip install .
+```
+
+### 2. Get an API key
+
+Sign in at [nova3d.xyz](https://nova3d.xyz), go to **Settings → API Keys**, and create a key.
+
+```bash
+export NOVA3D_TOKEN="n3d_your-api-key-here"
+```
+
+API keys never expire unless revoked. The MCP server validates your key on startup
+and prints a clear error if it's missing or invalid.
+
+### 3. Add to Claude Code
+
+**Once on PyPI:**
+```json
+{
+  "mcpServers": {
+    "nova3d": {
+      "command": "uvx",
+      "args": ["nova3d-mcp"],
+      "env": {
+        "NOVA3D_TOKEN": "n3d_your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+**From source (after `pip install .`):**
+```json
+{
+  "mcpServers": {
+    "nova3d": {
+      "command": "nova3d-mcp",
+      "env": {
+        "NOVA3D_TOKEN": "n3d_your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### 4. Generate
+
+```
+Generate a vending machine with separate door, glass panel, coin slot,
+button grid, frame, and interior shelving. Use Google Gemini with my
+API key AIza...
+```
+
+The agent calls `generate_3d`. You get back:
+
+```json
+{
+  "glb_url": "https://nova3d.xyz/assets/abc123.glb",
+  "preview_url": "https://nova3d.xyz/preview/state-...",
+  "parts": ["door", "glass_panel", "coin_slot", "button_grid", "frame", "shelf_1", "shelf_2"],
+  "joint_count": 1,
+  "code_artifact": { ... },
+  "workflow_id": "state-..."
+}
+```
+
+Open `preview_url` in your browser — interactive Three.js viewer, named parts,
+orbit controls, part explosion. No Blender required to preview.
+
+---
+
+## Tools
+
+### `generate_3d`
+
+Generate a structured 3D asset from text (and optional reference image).
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `prompt` | string | ✓ | Asset description. Be specific about parts. |
+| `provider` | string | ✓ | `"google"` · `"anthropic"` · `"openai"` |
+| `api_key` | string | ✓ | Your BYOK key for the provider |
+| `llm` | string | | Model ID. Defaults to recommended per provider. |
+| `image_base64` | string | | Reference image as plain base64 |
+| `image_mime` | string | | e.g. `"image/jpeg"` |
+
+**Recommended provider:** `google` with `gemini-2.0-flash` — best spatial
+reasoning for complex multi-part objects.
+
+---
+
+### `regenerate_part`
+
+Regenerate one named part without rebuilding the whole asset.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `code_artifact` | object | ✓ | From prior `generate_3d` result |
+| `part_type` | string | ✓ | Part name e.g. `"door"`, `"handle"` |
+| `description` | string | ✓ | What the new part should look like |
+| `provider` | string | ✓ | LLM provider |
+| `api_key` | string | ✓ | BYOK key |
+| `llm` | string | | Model ID |
+
+**Finding part names:** Open the `preview_url` from your generation — each
+mesh is labeled. Use that exact name as `part_type`.
+
+---
+
+### `add_part`
+
+Add a new component to an existing asset.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `code_artifact` | object | ✓ | From prior generation result |
+| `description` | string | ✓ | Description of the new part and where it goes |
+| `provider` | string | ✓ | LLM provider |
+| `api_key` | string | ✓ | BYOK key |
+| `llm` | string | | Model ID |
+
+---
+
+### `articulate_model`
+
+Add joints, hinges, or rotational articulation to an existing asset.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `code_artifact` | object | ✓ | From prior generation result |
+| `model_url` | string | ✓ | `glb_url` from prior generation |
+| `articulation_request` | string | ✓ | What should move and how |
+| `provider` | string | ✓ | LLM provider |
+| `api_key` | string | ✓ | BYOK key |
+| `llm` | string | | Model ID |
+| `selected_meshes` | list | | Specific mesh names to articulate |
+
+---
+
+### `get_generation_status`
+
+Check the status of a running workflow by ID.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `workflow_id` | string | ✓ | From any prior generation tool |
+
+---
+
+## Typical workflow
+
+```
+1. generate_3d("robot dog with four legs, head, torso, and tail")
+   → glb_url, preview_url, parts, code_artifact
+
+2. Open preview_url in browser
+   → see named parts, identify what needs changing
+
+3. regenerate_part(code_artifact, part_type="head", description="...")
+   → updated glb_url, new preview_url
+
+4. articulate_model(code_artifact, model_url, "make legs rotate at hip joints")
+   → glb_url with working joints
+```
+
+---
+
+## Provider reference
+
+| Provider | `provider` | Default `llm` | Notes |
+|---|---|---|---|
+| Google Gemini | `google` | `gemini-2.0-flash` | Recommended |
+| Anthropic | `anthropic` | `claude-sonnet-4-20250514` | Strong reasoning |
+| OpenAI | `openai` | `gpt-4o` | Widely available |
+
+---
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `NOVA3D_TOKEN` | ✓ | API key from nova3d.xyz → Settings → API Keys (recommended) or session JWT |
+| `NOVA3D_API_URL` | | Override API base URL (default: `https://nova3d.xyz/api`) |
+
+---
+
+## How it differs from blender-mcp
+
+[blender-mcp](https://github.com/ahujasid/blender-mcp) (21.9k ★) gives AI
+agents a remote control for a **locally running Blender instance**. It requires
+Blender installed, produces unstructured output, and inherits all the bpy
+hallucination problems of raw LLM → Blender code generation.
+
+nova3d-mcp is different in kind:
+
+| | blender-mcp | nova3d-mcp |
+|---|---|---|
+| Blender required | Yes | No |
+| Output | Unstructured scene | Named, hierarchical GLB |
+| Validation | None | Server-side repair loop |
+| Part awareness | No | Yes — named, addressable |
+| Joints | Manual scripting | First-class output |
+| Hosted backend | No | Yes |
+
+---
+
+## Contributing
+
+Issues, PRs, and workflow feedback welcome.
+[github.com/RareSense/nova3d-mcp](https://github.com/RareSense/nova3d-mcp)
+
+Community Discord: [discord.gg/QEH8mzcwdR](https://discord.gg/QEH8mzcwdR)
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)

nova3d_mcp-0.1.0/README.md

@@ -0,0 +1,270 @@
+# nova3d-mcp
+
+**Structured, part-aware 3D generation for AI agents.**
+
+nova3d-mcp is an [MCP](https://modelcontextprotocol.io) server that exposes
+[Nova3D](https://nova3d.xyz)'s generation pipeline as a callable tool inside
+Claude Code, Cursor, and any MCP-compatible agent.
+
+One tool call. A washing machine comes back with named drum, door, control
+panel, and hose connectors — separately editable, not fused into a blob.
+
+---
+
+## Why Nova3D
+
+Every major AI 3D generator today produces **mesh blobs** — a single fused
+object that looks plausible in a render and collapses the moment you try to
+edit, rig, or pipeline it.
+
+Nova3D is different. Instead of diffusion → mesh, it runs:
+
+```
+prompt / image
+      ↓
+LLM writes Blender Python construction code
+      ↓
+headless Blender executes + validates + repairs
+      ↓
+structured GLB — named parts, intact hierarchy, real joints
+```
+
+The result is a 3D asset that **survives contact with real workflows**: game
+engines, configurators, robotics simulations, AR scenes. Parts have names.
+Hierarchy is intact. Joints are real. You can change one component without
+regenerating everything.
+
+---
+
+## Quickstart
+
+### 1. Install
+
+**Once on PyPI (coming soon):**
+```bash
+uvx nova3d-mcp
+```
+
+**From source (available now):**
+```bash
+git clone https://github.com/RareSense/nova3d-mcp.git
+cd nova3d-mcp
+python3.10 -m venv .venv && source .venv/bin/activate
+pip install .
+```
+
+### 2. Get an API key
+
+Sign in at [nova3d.xyz](https://nova3d.xyz), go to **Settings → API Keys**, and create a key.
+
+```bash
+export NOVA3D_TOKEN="n3d_your-api-key-here"
+```
+
+API keys never expire unless revoked. The MCP server validates your key on startup
+and prints a clear error if it's missing or invalid.
+
+### 3. Add to Claude Code
+
+**Once on PyPI:**
+```json
+{
+  "mcpServers": {
+    "nova3d": {
+      "command": "uvx",
+      "args": ["nova3d-mcp"],
+      "env": {
+        "NOVA3D_TOKEN": "n3d_your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+**From source (after `pip install .`):**
+```json
+{
+  "mcpServers": {
+    "nova3d": {
+      "command": "nova3d-mcp",
+      "env": {
+        "NOVA3D_TOKEN": "n3d_your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### 4. Generate
+
+```
+Generate a vending machine with separate door, glass panel, coin slot,
+button grid, frame, and interior shelving. Use Google Gemini with my
+API key AIza...
+```
+
+The agent calls `generate_3d`. You get back:
+
+```json
+{
+  "glb_url": "https://nova3d.xyz/assets/abc123.glb",
+  "preview_url": "https://nova3d.xyz/preview/state-...",
+  "parts": ["door", "glass_panel", "coin_slot", "button_grid", "frame", "shelf_1", "shelf_2"],
+  "joint_count": 1,
+  "code_artifact": { ... },
+  "workflow_id": "state-..."
+}
+```
+
+Open `preview_url` in your browser — interactive Three.js viewer, named parts,
+orbit controls, part explosion. No Blender required to preview.
+
+---
+
+## Tools
+
+### `generate_3d`
+
+Generate a structured 3D asset from text (and optional reference image).
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `prompt` | string | ✓ | Asset description. Be specific about parts. |
+| `provider` | string | ✓ | `"google"` · `"anthropic"` · `"openai"` |
+| `api_key` | string | ✓ | Your BYOK key for the provider |
+| `llm` | string | | Model ID. Defaults to recommended per provider. |
+| `image_base64` | string | | Reference image as plain base64 |
+| `image_mime` | string | | e.g. `"image/jpeg"` |
+
+**Recommended provider:** `google` with `gemini-2.0-flash` — best spatial
+reasoning for complex multi-part objects.
+
+---
+
+### `regenerate_part`
+
+Regenerate one named part without rebuilding the whole asset.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `code_artifact` | object | ✓ | From prior `generate_3d` result |
+| `part_type` | string | ✓ | Part name e.g. `"door"`, `"handle"` |
+| `description` | string | ✓ | What the new part should look like |
+| `provider` | string | ✓ | LLM provider |
+| `api_key` | string | ✓ | BYOK key |
+| `llm` | string | | Model ID |
+
+**Finding part names:** Open the `preview_url` from your generation — each
+mesh is labeled. Use that exact name as `part_type`.
+
+---
+
+### `add_part`
+
+Add a new component to an existing asset.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `code_artifact` | object | ✓ | From prior generation result |
+| `description` | string | ✓ | Description of the new part and where it goes |
+| `provider` | string | ✓ | LLM provider |
+| `api_key` | string | ✓ | BYOK key |
+| `llm` | string | | Model ID |
+
+---
+
+### `articulate_model`
+
+Add joints, hinges, or rotational articulation to an existing asset.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `code_artifact` | object | ✓ | From prior generation result |
+| `model_url` | string | ✓ | `glb_url` from prior generation |
+| `articulation_request` | string | ✓ | What should move and how |
+| `provider` | string | ✓ | LLM provider |
+| `api_key` | string | ✓ | BYOK key |
+| `llm` | string | | Model ID |
+| `selected_meshes` | list | | Specific mesh names to articulate |
+
+---
+
+### `get_generation_status`
+
+Check the status of a running workflow by ID.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `workflow_id` | string | ✓ | From any prior generation tool |
+
+---
+
+## Typical workflow
+
+```
+1. generate_3d("robot dog with four legs, head, torso, and tail")
+   → glb_url, preview_url, parts, code_artifact
+
+2. Open preview_url in browser
+   → see named parts, identify what needs changing
+
+3. regenerate_part(code_artifact, part_type="head", description="...")
+   → updated glb_url, new preview_url
+
+4. articulate_model(code_artifact, model_url, "make legs rotate at hip joints")
+   → glb_url with working joints
+```
+
+---
+
+## Provider reference
+
+| Provider | `provider` | Default `llm` | Notes |
+|---|---|---|---|
+| Google Gemini | `google` | `gemini-2.0-flash` | Recommended |
+| Anthropic | `anthropic` | `claude-sonnet-4-20250514` | Strong reasoning |
+| OpenAI | `openai` | `gpt-4o` | Widely available |
+
+---
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `NOVA3D_TOKEN` | ✓ | API key from nova3d.xyz → Settings → API Keys (recommended) or session JWT |
+| `NOVA3D_API_URL` | | Override API base URL (default: `https://nova3d.xyz/api`) |
+
+---
+
+## How it differs from blender-mcp
+
+[blender-mcp](https://github.com/ahujasid/blender-mcp) (21.9k ★) gives AI
+agents a remote control for a **locally running Blender instance**. It requires
+Blender installed, produces unstructured output, and inherits all the bpy
+hallucination problems of raw LLM → Blender code generation.
+
+nova3d-mcp is different in kind:
+
+| | blender-mcp | nova3d-mcp |
+|---|---|---|
+| Blender required | Yes | No |
+| Output | Unstructured scene | Named, hierarchical GLB |
+| Validation | None | Server-side repair loop |
+| Part awareness | No | Yes — named, addressable |
+| Joints | Manual scripting | First-class output |
+| Hosted backend | No | Yes |
+
+---
+
+## Contributing
+
+Issues, PRs, and workflow feedback welcome.
+[github.com/RareSense/nova3d-mcp](https://github.com/RareSense/nova3d-mcp)
+
+Community Discord: [discord.gg/QEH8mzcwdR](https://discord.gg/QEH8mzcwdR)
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)