sia-vision-mcp-server

v1.4.1

Published

4 months ago

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

Downloads

0High
0Medium
0Low

sia.vision

mcp model-context-protocol storytelling ai claude chatgpt sia-vision

🤖 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.

🎯 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 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
API Key - Generate from your dashboard

Step 1: Get Your API Key

Visit SIA.Vision Dashboard
Navigate to "API Keys" in the sidebar
Click "Create New Key"
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

{
  "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

// 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

// 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

// 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:

# 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

# 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

// 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

# 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

# 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):

# 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

# 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

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

� Documentation

API Reference - Complete tool documentation
Integration Guide - Advanced usage patterns
Hierarchy Guide - Content structure patterns
Canvas Guide - Visual interface usage

🤝 Support

Documentation: docs.sia.vision
Community: Discord
Issues: GitHub Issues
Email: [email protected]

🧠 Enhanced LLM Integration Guide

🚀 Quick Start Workflow for AI Assistants

1. Initialize Storyworld Foundation

// 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

// 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

// 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

// 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

// 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

// 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

// 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

// 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

// SOLUTION: Always search first
const search = await useTool('search_content', {
  storyworldId: storyworldId,
  query: characterName,
  nodeTypes: ['CHARACTER']
});

Challenge: Incorrect Hierarchy Structure

// 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

// SOLUTION: Use get_scene_context for continuity
const context = await useTool('get_scene_context', {
  sceneId: sceneId,
  includeAdjacentScenes: true,
  includeCharacters: true
});

Challenge: Formatting Errors

// SOLUTION: Use validate_scene_content
const validation = await useTool('validate_scene_content', {
  sceneId: sceneId,
  content: sceneContent,
  checkFormatting: true
});

🚀 Advanced Workflows

Collaborative Writing Process

Use version control for concurrent edits
Validate changes against story continuity
Maintain character consistency across scenes

Iterative Development Approach

Create outline with placeholder scenes
Develop characters with detailed backstories
Write scenes with proper formatting
Validate continuity and formatting
Refine through targeted edits using patches

Quality Assurance Pipeline

Run continuity checks after major changes
Validate formatting before final output
Search for plot inconsistencies
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

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

📄 License

Proprietary - See LICENSE file for details.

Made with ❤️ by the SIA.Vision team