sia-vision-mcp-server/README.md

Enhanced v2 MCP server with improved error handling, validation, and comprehensive tool schemas for SIA.Vision storytelling platform

# 🤖 SIA.Vision MCP Server

> **Official MCP server for the SIA.Vision storytelling platform**

Connect AI assistants like Claude Desktop directly to your creative projects for seamless story development, character creation, and narrative collaboration.

[![npm version](https://badge.fury.io/js/sia-vision-mcp-server.svg)](https://www.npmjs.com/package/sia-vision-mcp-server)
[![License: Proprietary](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE)
[![Test Status](https://img.shields.io/badge/Tests-Passing-brightgreen.svg)](MCP_TOOLS_TEST_REPORT.md)

## 🎯 Overview

The **SIA.Vision MCP Server** enables AI assistants to interact with your storytelling projects through the Model Context Protocol (MCP). This release features enhanced v2 tools with comprehensive validation, improved error handling, and MongoDB-backed storage with 60% faster queries.

### ✅ **Fully Tested & Verified**
All 19 v2 tools have been comprehensively tested with:
- ✅ **MongoDB Storage Verification** - All data properly persisted
- ✅ **Firebase Asset Integration** - Image uploads and storage confirmed  
- ✅ **Document Patching** - TipTap JSON content editing validated
- ✅ **Relationship Management** - Cross-content linking operational
- ✅ **Performance Benchmarks** - Sub-second response times

*See [Test Report](MCP_TOOLS_TEST_REPORT.md) for detailed validation results.*

### 🛠️ **Enhanced v2 Tool Categories**
- 🔧 **Core Node Management** (5): node_create, node_update, node_delete, nodes_get, document_ensure
- 🏗️ **Hierarchy** (3): get_content_hierarchy, reorder_nodes, move_node  
- 📝 **Documents** (3): get_document_view, apply_document_patch, update_document
- 🔗 **Relationships** (5): create_relationship, get_relationships, update_relationship, delete_relationship, get_related_nodes
- 🎨 **Assets** (2): asset_create, asset_upload_and_create

### 🚀 **New in v1.4.1**
- 🧹 **Simplified Node Types** - Removed SERIES, EPISODE, CLIP types (scenes handle this with visuals)
- ⚡ **Enhanced Error Handling** - Comprehensive validation with specific error codes
- 🔄 **Automatic Retry Logic** - Network resilience with exponential backoff
- 📝 **Improved Tool Schemas** - Better descriptions and validation rules
- 🎯 **Performance Optimizations** - Faster response times and connection pooling
- 🔍 **Debug Mode** - Detailed logging for development and troubleshooting

### 🔄 **Breaking Changes in v1.4.1**
- **Removed node types**: `SERIES`, `EPISODE`, `CLIP` - Use `SCENE` with visuals instead
- **Updated tool schemas**: All node type enums now reflect simplified hierarchy
- **Improved descriptions**: Updated tool documentation to reflect new node structure

### 📚 **Resources & Templates**
- **Story Structure Templates** - Three-act structure, Hero's Journey, Save the Cat, TikTok, Instagram Reel templates
- **Character Archetype Templates** - Protagonist, Antagonist, Sidekick, Mentor templates
- **World-Building Frameworks** - Setting, Culture, Magic System, Technology templates
- **Scene Templates** - Dialogue-driven, Action, Exposition, Climax templates
- **Genre Conventions** - Fantasy, Sci-Fi, Mystery, Romance, Horror templates

### 💡 **Guided Prompts**
- **Story Development** - Concept generation, structure development, plot hole identification
- **Character Development** - Backstory creation, personality profiling, relationship mapping
- **World-Building** - Setting design, cultural development, magic system creation
- **Scene Creation** - Dialogue writing, action choreography, emotional beats
- **Creative Workflows** - Writer's block solutions, genre blending, adaptation strategies

### 🔄 **Polymorphic Content Hierarchy**
Supports both **long-form** and **short-form** content structures:

**Long-form Content** (TV/Film/Books):
```
Storyworld → Series → Episodes → Scenes
```

**Short-form Content** (Social Media/Digital):
```
Storyworld → Collections → Content Items → Scenes
```

## ⚡ Quick Start

### Prerequisites
- **Node.js 18+** and **npm**
- **SIA.Vision Account** - [Sign up free](https://sia.vision)
- **API Key** - Generate from your [dashboard](https://sia.vision/dashboard)

### Step 1: Get Your API Key
1. Visit [SIA.Vision Dashboard](https://sia.vision/dashboard)
2. Navigate to **"API Keys"** in the sidebar
3. Click **"Create New Key"**
4. Copy your API key (starts with `sia_`)

### Step 2: Configure Claude Desktop

Add to your Claude Desktop configuration:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "sia-vision": {
      "command": "npx",
      "args": ["-y", "sia-vision-mcp-server"],
      "env": {
        "SIA_API_KEY": "your-api-key-here",
        "SIA_MCP_BASE_URL": "https://us-central1-sia-vision.cloudfunctions.net"
      }
    }
  }
}
```

### Step 3: Restart Claude Desktop

Close and reopen Claude Desktop. You should see the 🔌 MCP connection indicator.

## 🎨 **Usage Examples**

### Creating a Complete Story Structure

```javascript
// 1. Create a storyworld
const storyworld = await mcp.node_create({
  nodeType: "STORYWORLD",
  title: "Cyberpunk Chronicles",
  content: "A dystopian future where AI and humanity collide",
  metadata: {
    genre: "cyberpunk",
    target_audience: "young_adult",
    themes: ["technology", "identity", "resistance"]
  }
});
// Returns: { nodeId: "64f...", storyworldId: "64f...", created: true }

// 2. Create a series
const series = await mcp.node_create({
  storyworldId: storyworld.nodeId,
  nodeType: "SERIES", 
  title: "Season 1: The Awakening",
  parentId: storyworld.nodeId,
  metadata: { season_number: 1, episode_count: 8 }
});

// 3. Create an episode
const episode = await mcp.node_create({
  storyworldId: storyworld.nodeId,
  nodeType: "EPISODE",
  title: "Pilot: Ghost in the Shell",
  parentId: series.nodeId,
  metadata: { episode_number: 1, runtime: "45 minutes" }
});

// 4. Create a scene with slugline metadata (editor-aligned)
const scene = await mcp.node_create({
  storyworldId: storyworld.nodeId,
  nodeType: "SCENE",
  title: "First Encounter",
  parentId: episode.nodeId,
  metadata: {
    slugline: { intExt: 'INT.', location: 'NEON-LIT APARTMENT', timeOfDay: 'NIGHT' }
  }
});

// 5. Ensure the scene has a document for editing
const document = await mcp.document_ensure({
  nodeId: scene.nodeId
});
```

## 🔁 UI ↔ API Mapping and Best Practices

To keep assistants in sync with the web canvas UI:

- scene → `SCENE`
- character → `CHARACTER`
- location → `LOCATION`
- visual → `VISUAL`
- prompt → `PROMPT`
- notes → `NOTE`
- song → `ASSET` with `metadata.assetSubtype = "song"`
- section (folder frame) → `BOARD` with `metadata.boardKind = "section"`
- collection → `BOARD` with `metadata.boardKind = "collection"`

Scene slugline:
- Set `metadata.slugline = { intExt, location, timeOfDay }`
- Also add a `heading2` block like `INT. LOCATION - TIME OF DAY` to the document so the editor displays it.


### Adding Images to Scenes

```javascript
// 1. Upload an AI-generated image
const asset = await mcp.asset_upload_and_create({
  storyworldId: storyworld.nodeId,
  title: "Maya's Apartment - Wide Shot",
  fileBase64: "data:image/png;base64,iVBORw0KGgoAAAA...", // Your base64 image
  mimeType: "image/png",
  parentId: scene.nodeId,
  metadata: {
    ai_generated: true,
    prompt: "Cyberpunk apartment, neon lights, holographic displays",
    style: "cinematic_realism"
  }
});
// Returns: { assetId: "64f...", storagePath: "gs://...", created: true }

// 2. Link asset to scene via relationship
const relationship = await mcp.create_relationship({
  storyworldId: storyworld.nodeId,
  sourceId: scene.nodeId,
  targetId: asset.assetId,
  relType: "uses_asset",
  metadata: {
    usage_type: "scene_illustration",
    placement: "header_image"
  }
});

// 3. Add image to scene document via patch
const docView = await mcp.get_document_view({
  document_id: document.documentId
});

const patch = await mcp.apply_document_patch({
  document_id: document.documentId,
  version: docView.version,
  ops: [
    { op: "test", path: "/version", value: docView.version },
    { 
      op: "add", 
      path: "/content/-", 
      value: {
        type: "image",
        attrs: {
          src: `https://storage.googleapis.com/sia-bucket/assets/${asset.assetId}.png`,
          alt: "Maya's Apartment Wide Shot",
          assetId: asset.assetId,
          width: 800,
          height: 450,
          caption: "The neon-soaked apartment where Maya lives"
        }
      }
    }
  ]
});
```

### Querying and Navigation

```javascript
// Get complete story hierarchy
const hierarchy = await mcp.get_content_hierarchy({
  storyworld_id: storyworld.nodeId,
  include_counts: true,
  max_depth: 4
});

// Find all scenes in the episode
const scenes = await mcp.nodes_get({
  storyworldId: storyworld.nodeId,
  parentId: episode.nodeId,
  nodeTypes: ["SCENE"],
  orderBy: "orderKey",
  limit: 20
});

// Get all assets used by a scene
const relatedAssets = await mcp.get_related_nodes({
  nodeId: scene.nodeId,
  relType: "uses_asset",
  direction: "target",
  includeContent: true
});
```

## 🧪 Testing & Verification

### ✅ **Automated Test Results**

All MCP tools have been comprehensively tested:

```bash
# Test Results Summary (Latest: 2025-08-21)
✅ Node Creation & Management: PASSED
✅ Asset Upload & Storage: PASSED  
✅ Document Patching: PASSED
✅ Relationship Management: PASSED
✅ MongoDB Data Persistence: VERIFIED
✅ Firebase Storage Integration: VERIFIED
✅ Error Handling: VALIDATED
✅ Performance Benchmarks: SUB-SECOND RESPONSE
```

### Quick Tool Verification
```bash
# Clone and test locally
git clone https://github.com/sia-vision/sia-modern.git
cd sia-modern/apps/mcp-server

# Install and build
npm install && npm run build

# Export your API key
export SIA_API_KEY="your-api-key-here"

# Test tool listing
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js

# Test node creation
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"node_create","arguments":{"nodeType":"STORYWORLD","title":"Test World"}}}' | node dist/index.js
```

### Performance Metrics
- **Tool Response Time:** 200-500ms average
- **Asset Upload:** 1-3s (network dependent) 
- **Document Patches:** <100ms
- **Relationship Queries:** <200ms
- **MongoDB Queries:** 60% faster than v1

### Error Handling Examples
```javascript
// Enhanced error messages with specific codes
try {
  await mcp.node_create({ nodeType: "INVALID" });
} catch (error) {
  console.log(error.code);    // "VALIDATION_ERROR"
  console.log(error.message); // "Invalid nodeType: INVALID"
  console.log(error.details); // { field: "nodeType", received: "INVALID" }
}

// Automatic retry on network issues
try {
  await mcp.nodes_get({ storyworldId: "abc123" });
} catch (error) {
  // Automatically retried 3 times with exponential backoff
  console.log(error.code); // "TIMEOUT" or "NETWORK_ERROR"
}
```

## 🔌 Available Tools (v2)

The MCP server surfaces the following v2 Mongo-backed tools via Firebase Functions:

- Core: `node_create`, `node_update`, `node_delete`, `nodes_get`, `document_ensure`
- Hierarchy: `get_content_hierarchy`, `reorder_nodes`, `move_node`
- Documents: `get_document_view`, `apply_document_patch`, `update_document`
- Relationships: `create_relationship`, `get_relationships`, `update_relationship`, `delete_relationship`, `get_related_nodes`
- Assets: `asset_create`, `asset_upload_and_create`

Resources & prompts are available via `resources/list`, `resources/read`, `prompts/list`, and `prompts/get`.

### Legacy v1 tools (deprecated)

Legacy v1 tool definitions still exist in the repo for reference but are hidden from discovery and scheduled for removal in the next major version. Prefer the v2 tools listed above. Files in `src/tools/*` are annotated with `@deprecated` to reflect this status.

## � Development

### Local Development
```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Start HTTP server (for testing)
npm run dev:http

# Build for production
npm run build

# Type checking
npm run type-check
```

### Environment Variables
```bash
# Required
SIA_API_KEY=your-api-key-here

# Optional
SIA_MCP_BASE_URL=https://us-central1-sia-vision.cloudfunctions.net
DEBUG=1  # Enable debug logging

# MCP protocol negotiation
# The client sends MCP-Protocol-Version: 2024-11-05 to HTTP bridges for forward compatibility
# (not strictly required for Firebase Functions today)
```

## 🚀 Deployment

### Firebase Functions (1st Gen)
The MCP server integrates with Firebase Functions (1st Gen HTTPS endpoints for MCP):

```bash
# Deploy Firebase Functions
cd ../functions
npm run deploy

# Test MCP endpoints
curl -X GET https://us-central1-sia-vision.cloudfunctions.net/mcpTools
curl -X POST https://us-central1-sia-vision.cloudfunctions.net/mcpExecute \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $SIA_API_KEY" \
  -d '{"tool":"node_create","arguments":{"nodeType":"STORYWORLD","title":"API World"}}'
```

### NPM Package
```bash
# Build and publish
npm run build
npm publish

# Install globally
npm install -g sia-vision-mcp-server
```

## 🎨 Visual Canvas Integration

The MCP server works seamlessly with the SIA.Vision visual canvas:

- **React Flow Interface** - Drag-and-drop content creation
- **Hierarchy Visualization** - See story structure visually  
- **MCP Actions** - Canvas actions trigger MCP tools
- **Real-time Updates** - Changes sync across all interfaces

## 🔍 Troubleshooting

### Common Issues

**"Unknown tool" errors:**
- Verify API key is set correctly
- Ensure MCP server is built: `npm run build`
- Check tool registration: `npm run test:list`

**Connection issues:**
- Restart Claude Desktop after configuration changes
- Verify JSON syntax in claude_desktop_config.json
- Check network connectivity to Firebase Functions

**Tool execution failures:**
- Validate input parameters match schema
- Check storyworld_id exists and is accessible
- Review error messages for specific validation issues

### Debug Mode
```bash
# Enable detailed logging
export DEBUG=1
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
```

## � Documentation

- **[API Reference](https://docs.sia.vision/mcp-api)** - Complete tool documentation
- **[Integration Guide](https://docs.sia.vision/mcp-integration)** - Advanced usage patterns
- **[Hierarchy Guide](https://docs.sia.vision/content-hierarchy)** - Content structure patterns
- **[Canvas Guide](https://docs.sia.vision/visual-canvas)** - Visual interface usage

## 🤝 Support

- **Documentation**: [docs.sia.vision](https://docs.sia.vision)
- **Community**: [Discord](https://discord.gg/sia-vision)
- **Issues**: [GitHub Issues](https://github.com/sia-vision/mcp-server/issues)
- **Email**: support@sia.vision

## 🧠 Enhanced LLM Integration Guide

### 🚀 Quick Start Workflow for AI Assistants

#### 1. Initialize Storyworld Foundation
```javascript
// First, create your storyworld foundation
const storyworld = await useTool('node_create', {
  nodeType: 'STORYWORLD',
  title: 'My Epic Story',
  content: 'A compelling story about [theme]',
  metadata: { genre: 'Science Fiction', targetAudience: 'YA' }
});
```

#### 2. Build Hierarchical Structure
```javascript
// Create series/season structure
const series = await useTool('node_create', {
  storyworldId: storyworld.storyworldId,
  nodeType: 'SERIES',
  title: 'Season 1',
  parentId: storyworld.nodeId
});

// Create episodes within series
const episode = await useTool('node_create', {
  storyworldId: storyworld.storyworldId,
  nodeType: 'EPISODE',
  title: 'Episode 1: The Beginning',
  parentId: series.nodeId
});
```

#### 3. Develop Characters with Depth
```javascript
// Create main characters with comprehensive details
const protagonist = await useTool('node_create', {
  storyworldId: storyworld.storyworldId,
  nodeType: 'CHARACTER',
  title: 'Alex Chen',
  content: 'A brilliant scientist who discovers [secret]',
  metadata: {
    age: 28,
    role: 'Protagonist',
    traits: ['Intelligent', 'Curious', 'Determined'],
    goals: ['Uncover the truth', 'Save the world']
  }
});
```

#### 4. Write Scenes with Professional Formatting
```javascript
// Create scenes with proper screenplay structure
const scene = await useTool('create_scene_with_slugline', {
  storyworldId: storyworld.storyworldId,
  parentId: episode.nodeId,
  title: 'The Discovery',
  slugline: {
    intExt: 'INT.',
    location: 'RESEARCH LAB',
    time: 'NIGHT'
  },
  initialContent: [
    {
      id: 'heading1',
      type: 'heading2',
      content: 'INT. RESEARCH LAB - NIGHT'
    },
    {
      id: 'action1',
      type: 'paragraph',
      content: 'ALEX CHEN, 28, brilliant but disheveled, hunches over a microscope. His eyes widen as he sees something impossible.'
    },
    {
      id: 'character1',
      type: 'character',
      content: 'ALEX'
    },
    {
      id: 'dialogue1',
      type: 'dialogue',
      content: 'This... this changes everything.'
    }
  ],
  metadata: {
    characters: ['Alex Chen'],
    duration: '2:30',
    genre: 'Suspense'
  }
});
```

### 🛠️ Enhanced Tools Overview

#### Core Creation Tools
- **`node_create`** - Foundation for all content creation with detailed examples
- **`create_scene_with_slugline`** - Professional scene creation with screenplay formatting
- **`node_update`** - Modify existing content with version control
- **`node_delete`** - Clean removal with relationship cleanup

#### Content Management & Discovery
- **`get_content_hierarchy`** - Understand project structure before making changes
- **`search_content`** - Find existing characters, locations, themes to maintain consistency
- **`get_document_view`** - Access scene content for editing with version info
- **`apply_document_patch`** - Precise content modifications with conflict prevention

#### Quality Assurance & Continuity
- **`get_scene_context`** - Comprehensive context for writing/editing scenes
- **`validate_scene_content`** - Formatting and consistency validation
- **`get_relationships`** - Character and plot connections

### 📋 Best Practices for LLMs

#### 1. Always Check Existing Content First
```javascript
// Before creating new characters/locations
const existing = await useTool('search_content', {
  storyworldId: storyworldId,
  query: 'detective',
  nodeTypes: ['CHARACTER']
});

if (existing.results.length > 0) {
  // Use existing character instead of creating duplicate
  console.log('Found existing character:', existing.results[0]);
}
```

#### 2. Use Proper Hierarchy Structure
- **STORYWORLD** → Top-level project container
- **SERIES** → Seasons or story arcs
- **EPISODE** → Chapters or episodes
- **SCENE** → Individual scenes (must have EPISODE parent)
- **CHARACTER/LOCATION** → Can be at storyworld level or episode level

#### 3. Professional Scene Formatting Standards
```javascript
// Always use proper screenplay format
const sceneContent = [
  {
    id: 'slugline',
    type: 'heading2',
    content: 'INT. COFFEE SHOP - DAY'  // Proper slugline format
  },
  {
    id: 'action',
    type: 'paragraph',
    content: 'SARAH enters, looking nervous. She scans the room.'
  },
  {
    id: 'character',
    type: 'character',
    content: 'SARAH'
  },
  {
    id: 'dialogue',
    type: 'dialogue',
    content: 'I need to talk to you about something important.'
  }
];
```

#### 4. Version Control for Collaborative Editing
```javascript
// Always get current version before editing
const document = await useTool('get_document_view', {
  document_id: scene.documentId
});

// Use version in patch operations to prevent conflicts
await useTool('apply_document_patch', {
  document_id: scene.documentId,
  version: document.version,
  ops: [
    { op: 'test', path: '/version', value: document.version },
    { op: 'add', path: '/content/-', value: newBlock }
  ]
});
```

#### 5. Maintain Character Consistency
```javascript
// Check character details before writing scenes
const characters = await useTool('nodes_get', {
  storyworldId: storyworldId,
  nodeTypes: ['CHARACTER']
});

// Use consistent character descriptions
const character = characters.nodes.find(c => c.title === 'Sarah Chen');
// Reference: character.content or character.metadata
```

### 🎭 Scene Writing Guidelines

#### Slugline Format Standards
```
INT. LOCATION - TIME     (Interior scenes)
EXT. LOCATION - TIME     (Exterior scenes)
INT/EXT. LOCATION - TIME (Scenes that move between inside/outside)
```

#### Character Name Formatting
- **First appearance**: Full introduction with description
- **Subsequent appearances**: Just character name
- **Format**: ALL CAPS, centered above dialogue

#### Action Line Best Practices
- Present tense descriptions
- Visual and specific details
- Follow the 3-5 second rule (what would be seen in a shot)

#### Dialogue Formatting
- Natural but purposeful conversations
- Reveals character and advances plot
- Parentheticals only when essential: (wryly), (pause), (excited)

### 🔍 Common LLM Challenges & Solutions

#### Challenge: Creating Duplicate Characters/Locations
```javascript
// SOLUTION: Always search first
const search = await useTool('search_content', {
  storyworldId: storyworldId,
  query: characterName,
  nodeTypes: ['CHARACTER']
});
```

#### Challenge: Incorrect Hierarchy Structure
```javascript
// SOLUTION: Use get_content_hierarchy to understand structure
const hierarchy = await useTool('get_content_hierarchy', {
  storyworld_id: storyworldId
});
// Then create nodes with correct parentId relationships
```

#### Challenge: Scene Continuity Issues
```javascript
// SOLUTION: Use get_scene_context for continuity
const context = await useTool('get_scene_context', {
  sceneId: sceneId,
  includeAdjacentScenes: true,
  includeCharacters: true
});
```

#### Challenge: Formatting Errors
```javascript
// SOLUTION: Use validate_scene_content
const validation = await useTool('validate_scene_content', {
  sceneId: sceneId,
  content: sceneContent,
  checkFormatting: true
});
```

### 🚀 Advanced Workflows

#### Collaborative Writing Process
1. Use version control for concurrent edits
2. Validate changes against story continuity
3. Maintain character consistency across scenes

#### Iterative Development Approach
1. Create outline with placeholder scenes
2. Develop characters with detailed backstories
3. Write scenes with proper formatting
4. Validate continuity and formatting
5. Refine through targeted edits using patches

#### Quality Assurance Pipeline
1. Run continuity checks after major changes
2. Validate formatting before final output
3. Search for plot inconsistencies
4. Ensure character arcs are coherent

### 📚 Available Resources for LLMs

- **Screenplay Formatting Guide** - Professional script formatting standards
- **Scene Structure Template** - Effective scene construction patterns
- **Character Development Framework** - Deep character creation methodology
- **Story Structure Templates** - Various narrative frameworks (Three-act, Hero's Journey, etc.)

### 🎯 Pro Tips for AI Assistants

1. **Ask clarifying questions** when requirements are ambiguous
2. **Use idempotency keys** to prevent accidental duplicates during regeneration
3. **Maintain version awareness** for all document edits to prevent conflicts
4. **Leverage search tools** before creating new content to maintain consistency
5. **Validate relationships** between characters and scenes regularly
6. **Follow screenplay conventions** for professional-quality results
7. **Use get_scene_context** before writing to understand existing continuity

## 📄 License

Proprietary - See [LICENSE](LICENSE) file for details.

---

**Made with ❤️ by the SIA.Vision team**