AI Integration

Nightshade provides two features for AI integration: mcp for exposing the engine as a Model Context Protocol server, and claude for embedding Claude Code CLI as a subprocess. Both are native-only (not available on WASM).

MCP Server

The mcp feature starts an HTTP-based MCP server on http://127.0.0.1:3333/mcp when the application launches. Any MCP-compatible client can connect and manipulate the running scene through structured tool calls.

Setup

Enable the feature in Cargo.toml:

nightshade = { git = "...", features = ["mcp"] }

The server starts automatically during engine initialization. No code changes are needed beyond enabling the feature.

Connecting Claude Code

Register the running engine as an MCP server:

claude mcp add --transport http nightshade http://127.0.0.1:3333/mcp

Claude Code can then call any of the engine's MCP tools directly during a conversation.

Available Tools

The MCP server exposes 50+ tools organized by category:

Entity Management

Transforms

Materials

Lighting

Camera

Assets

Environment

Effects

Text

Physics (requires physics feature)

Animation

Scripting (requires scripting feature)

Debug

Batch Operations

Intercepting MCP Commands

Applications can intercept MCP commands before the engine processes them by implementing handle_mcp_command on the State trait:

#![allow(unused)]
fn main() {
#[cfg(all(feature = "mcp", not(target_arch = "wasm32")))]
fn handle_mcp_command(
    &mut self,
    world: &mut World,
    command: &McpCommand,
) -> Option<McpResponse> {
    match command {
        McpCommand::SpawnEntity { name, .. } => {
            // Update editor scene tree after engine handles the spawn
            self.pending_scene_refresh = true;
            None // let engine handle it
        }
        McpCommand::DespawnEntity { name } => {
            self.scene_tree.remove(name);
            None // let engine handle it
        }
        McpCommand::ClearScene => {
            self.scene_tree.clear();
            None
        }
        _ => None,
    }
}
}

Return Some(McpResponse) to fully handle a command yourself (the engine skips its default handler), or None to let the engine process it normally. This is useful for blocking certain commands or implementing custom command handling.

Reacting to MCP Results

after_mcp_command is called after a command has been processed (by the engine or your pre-hook). It receives both the command and the response, making it the right place to record undo entries, refresh scene trees, or trigger other side effects based on whether the command succeeded:

#![allow(unused)]
fn main() {
#[cfg(all(feature = "mcp", not(target_arch = "wasm32")))]
fn after_mcp_command(
    &mut self,
    world: &mut World,
    command: &McpCommand,
    response: &McpResponse,
) {
    let is_success = matches!(response, McpResponse::Success(_));

    match command {
        McpCommand::SpawnEntity { name, .. } => {
            if is_success {
                if let Some(&entity) = world.resources.entity_names.get(name) {
                    let hierarchy = capture_hierarchy(world, entity);
                    self.undo_history.push(
                        UndoableOperation::EntityCreated {
                            hierarchy: Box::new(hierarchy),
                            current_entity: entity,
                        },
                        format!("MCP: Spawn {}", name),
                    );
                }
            }
            self.scene_tree_dirty = true;
        }
        McpCommand::DespawnEntity { .. } | McpCommand::ClearScene => {
            self.scene_tree_dirty = true;
        }
        _ => {}
    }
}
}

The pre-hook/post-hook pattern works together: use handle_mcp_command to capture before-state (e.g. an entity's transform before it changes), then use after_mcp_command to create undo entries by comparing the before-state with the result.

Architecture

The MCP server runs on a background thread using tokio and axum. Communication with the main engine thread happens through synchronized queues:

1. MCP client sends a tool call via HTTP
2. The server deserializes the request into an McpCommand and pushes it to the command queue
3. On the next frame, the engine drains the queue and processes each command
4. Responses are written to the response queue
5. The server reads the response and returns it to the MCP client

Commands are processed once per frame, after run_systems() and before the FrameSchedule dispatch. This means MCP-driven changes are visible to the same frame's transform, physics, and rendering systems.

Claude Code CLI

The claude feature provides a background worker for spawning Claude Code as a subprocess and streaming its JSON output. This lets applications embed an AI chat interface.

Setup

nightshade = { git = "...", features = ["claude"] }

Requires the claude CLI to be installed and available on PATH.

Usage

Create channels and spawn the worker:

#![allow(unused)]
fn main() {
let (command_sender, command_receiver, event_sender, event_receiver) =
    nightshade::claude::create_cli_channels();

nightshade::claude::spawn_cli_worker(
    command_receiver,
    event_sender,
    ClaudeConfig {
        system_prompt: Some("You are a scene designer.".to_string()),
        mcp_config: McpConfig::Auto,
        ..Default::default()
    },
);
}

Send a query:

#![allow(unused)]
fn main() {
command_sender.send(CliCommand::StartQuery {
    prompt: "Create a forest scene with 10 trees".to_string(),
    session_id: None,
    model: None,
}).ok();
}

Poll for events each frame:

#![allow(unused)]
fn main() {
while let Ok(event) = event_receiver.try_recv() {
    match event {
        CliEvent::TextDelta { text } => self.chat_buffer.push_str(&text),
        CliEvent::ThinkingDelta { text } => self.thinking_buffer.push_str(&text),
        CliEvent::ToolUseStarted { tool_name, .. } => {
            self.status = format!("Using tool: {}", tool_name);
        }
        CliEvent::Complete { total_cost_usd, num_turns, .. } => {
            self.status = format!("Done ({} turns)", num_turns);
        }
        CliEvent::Error { message } => {
            self.status = format!("Error: {}", message);
        }
        _ => {}
    }
}
}

ClaudeConfig

Auto MCP Configuration

When both claude and mcp features are enabled and mcp_config is set to McpConfig::Auto (the default), the worker automatically passes --mcp-config with a JSON payload pointing at http://127.0.0.1:3333/mcp. This means Claude Code can call engine tools without any manual mcp add step.

CliEvent Types