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 18 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.0**
- ⚡ **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

### 📚 **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 document
const scene = await mcp.node_create({
  storyworldId: storyworld.nodeId,
  nodeType: "SCENE",
  title: "INT. NEON-LIT APARTMENT - NIGHT",
  parentId: episode.nodeId,
  content: "Maya stares at the holographic display..."
});

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

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

## 📄 License

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

---

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