unreal-engine-mcp-server 0.5.4 → 0.5.6

package/docs/Migration-Guide-v0.5.0.md

@@ -1,684 +0,0 @@
-# Migration Guide: v0.5.0 - GraphQL API & WebAssembly Integration
-
-## Overview
-
-Version 0.5.0 introduces two major new features to the Unreal Engine MCP Server:
-
-1. **GraphQL API** - A flexible query interface for complex data retrieval
-2. **WebAssembly Integration** - High-performance operations for critical tasks
-
-This guide explains what's new, how to upgrade, and how to take advantage of these features.
-
-## What's New in v0.5.0
-
-### GraphQL API
-
-The GraphQL API provides a modern alternative to MCP tools for complex queries:
-
-- **Flexible Queries**: Request exactly the data you need
-- **Nested Queries**: Fetch related data in a single request
-- **Real-time Schema**: Introspection and strongly-typed API
-- **Multiple Endpoints**: Run alongside existing MCP tools
-- **Better Performance**: Reduce over-fetching and under-fetching
-
-**Endpoint**: `http://127.0.0.1:4000/graphql` (configurable)
-
-### WebAssembly Integration
-
-WebAssembly provides 3-8x performance improvements for computational tasks:
-
-- **Property Parsing**: 5-8x faster JSON parsing
-- **Transform Math**: 5-10x faster vector/matrix operations
-- **Dependency Resolution**: 3-5x faster asset dependency traversal
-- **Graceful Fallbacks**: Automatic TypeScript fallback if WASM unavailable
-
-## Breaking Changes
-
-### None! ✅
-
-All changes are **backward compatible**. Existing MCP tools continue to work exactly as before.
-
-## New Dependencies
-
-The following npm dependencies have been added:
-
-```json
-{
-  "@graphql-tools/schema": "^10.0.0",
-  "@graphql-tools/utils": "^10.0.0",
-  "graphql": "^16.8.1",
-  "graphql-yoga": "^5.1.0"
-}
-```
-
-**Installation**: These are automatically installed when you run `npm install`.
-
-## Configuration
-
-### Environment Variables
-
-#### GraphQL Configuration
-
-```bash
-# Enable/disable GraphQL server
-GRAPHQL_ENABLED=true
-
-# Server host and port (default: 127.0.0.1:4000)
-GRAPHQL_HOST=127.0.0.1
-GRAPHQL_PORT=4000
-
-# GraphQL endpoint path (default: /graphql)
-GRAPHQL_PATH=/graphql
-
-# CORS configuration
-GRAPHQL_CORS_ORIGIN=*
-GRAPHQL_CORS_CREDENTIALS=false
-```
-
-#### WebAssembly Configuration
-
-```bash
-# Enable/disable WebAssembly
-WASM_ENABLED=true
-
-# Path to WASM module (default: ./pkg/unreal_mcp_wasm.js)
-WASM_PATH=./pkg/unreal_mcp_wasm.js
-
-# Enable/disable TypeScript fallbacks (default: true)
-WASM_FALLBACK_ENABLED=true
-
-# Enable/disable performance monitoring (default: true)
-WASM_MONITORING_ENABLED=true
-```
-
-### Configuration File Example
-
-Create a `.env` file in your project root:
-
-```bash
-# GraphQL Settings
-GRAPHQL_ENABLED=true
-GRAPHQL_PORT=4000
-GRAPHQL_HOST=127.0.0.1
-
-# WebAssembly Settings
-WASM_ENABLED=true
-WASM_MONITORING_ENABLED=true
-
-# Existing MCP settings
-MCP_AUTOMATION_HOST=127.0.0.1
-MCP_AUTOMATION_PORT=8091
-```
-
-## Migration Steps
-
-### Step 1: Update Dependencies
-
-```bash
-npm install
-```
-
-This installs the new GraphQL dependencies.
-
-### Step 2: Build the Project
-
-```bash
-npm run build
-```
-
-### Step 3: (Optional) Build WebAssembly Module
-
-To enable WebAssembly features:
-
-```bash
-# Install wasm-pack (one-time setup)
-curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
-
-# Build the WebAssembly module
-npm run build:wasm
-```
-
-This creates the WebAssembly binary in `src/wasm/pkg/`.
-
-**Note**: WebAssembly is optional. The server works with TypeScript fallbacks if WASM is not built.
-
-### Step 4: Update Client Code (Optional)
-
-If you want to use the new GraphQL API from your client:
-
-```typescript
-// Old approach (MCP Tool)
-const result = await callTool('manage_asset', {
-  action: 'list',
-  directory: '/Game'
-});
-
-// New approach (GraphQL)
-const query = `
-  {
-    assets(filter: { pathStartsWith: "/Game" }) {
-      edges {
-        node {
-          name
-          path
-          class
-        }
-      }
-      totalCount
-    }
-  }
-`;
-
-const result = await fetch('http://127.0.0.1:4000/graphql', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ query })
-});
-```
-
-### Step 5: Update Docker Configuration (Optional)
-
-If you're using Docker:
-
-```dockerfile
-# Dockerfile
-FROM node:18
-
-# Install Rust and wasm-pack for WASM builds
-RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
-ENV PATH="/root/.cargo/bin:${PATH}"
-RUN curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
-
-WORKDIR /app
-COPY package*.json ./
-RUN npm install
-
-# Build TypeScript
-RUN npm run build
-
-# Build WebAssembly (optional)
-RUN npm run build:wasm
-
-EXPOSE 8090
-EXPOSE 4000
-
-CMD ["npm", "start"]
-```
-
-## Using the New Features
-
-### GraphQL API
-
-#### 1. Access the GraphQL Endpoint
-
-The GraphQL server runs on a separate port from the MCP server:
-
-- **URL**: `http://127.0.0.1:4000/graphql`
-- **Default Port**: 4000
-- **Default Host**: 127.0.0.1
-
-#### 2. Use a GraphQL Client
-
-You can use any GraphQL client:
-
-**GraphiQL (In-browser IDE)**
-```bash
-# Start the server
-npm start
-
-# Open in browser:
-# http://127.0.0.1:4000/graphql
-```
-
-**Apollo Studio**
-```typescript
-import { ApolloClient, InMemoryCache, gql } from '@apollo/client/core';
-
-const client = new ApolloClient({
-  uri: 'http://127.0.0.1:4000/graphql',
-  cache: new InMemoryCache(),
-});
-
-const GET_ASSETS = gql`
-  query GetAssets {
-    assets {
-      edges {
-        node {
-          name
-          path
-          class
-        }
-      }
-    }
-  }
-`;
-
-const result = await client.query({ query: GET_ASSETS });
-```
-
-**Postman/REST Client**
-```bash
-curl -X POST http://127.0.0.1:4000/graphql \
-  -H "Content-Type: application/json" \
-  -d '{"query": "{ assets { edges { node { name path } } } }"}'
-```
-
-#### 3. Example Queries
-
-**List All Assets**
-```graphql
-{
-  assets {
-    edges {
-      node {
-        name
-        path
-        class
-        packagePath
-      }
-    }
-    totalCount
-  }
-}
-```
-
-**Get Actor with Properties**
-```graphql
-{
-  actor(name: "Cube_001") {
-    name
-    class
-    location {
-      x
-      y
-      z
-    }
-    properties
-  }
-}
-```
-
-**Nested Query (Assets + Dependencies)**
-```graphql
-{
-  asset(path: "/Game/Materials/M_Master") {
-    name
-    class
-    dependencies {
-      name
-      path
-    }
-    dependents {
-      name
-      path
-    }
-  }
-}
-```
-
-**Search Across Types**
-```graphql
-{
-  search(query: "Player", type: ALL) {
-    ... on Asset {
-      name
-      path
-      __typename
-    }
-    ... on Actor {
-      name
-      class
-      __typename
-    }
-    ... on Blueprint {
-      name
-      path
-      __typename
-    }
-  }
-}
-```
-
-### WebAssembly Features
-
-WebAssembly features are enabled automatically if the module is built. No client changes needed!
-
-#### Performance Monitoring
-
-Check WASM performance from your code:
-
-```typescript
-import { wasmIntegration } from 'unreal-mcp-server/src/wasm/index.js';
-
-// Initialize WASM
-await wasmIntegration.initialize();
-
-// Get performance metrics
-const metrics = wasmIntegration.getMetrics();
-console.log(`WASM operations: ${metrics.wasmOperations}`);
-console.log(`TypeScript operations: ${metrics.tsOperations}`);
-console.log(`Average time: ${metrics.averageTime.toFixed(2)}ms`);
-
-// Print full report
-console.log(wasmIntegration.reportPerformance());
-```
-
-#### Using WASM in Your Code
-
-The WASM integration is used automatically in:
-
-1. **Property Parsing**: Automatic in GraphQL resolvers and MCP tools
-2. **Transform Calculations**: Automatic in actor operations
-3. **Dependency Resolution**: Automatic in asset management
-
-You can also use WASM directly:
-
-```typescript
-import { wasmIntegration } from 'unreal-mcp-server/src/wasm/index.js';
-
-await wasmIntegration.initialize();
-
-// Parse properties with WASM
-const properties = await wasmIntegration.parseProperties(jsonString);
-
-// Compose transforms with WASM
-const matrix = wasmIntegration.composeTransform(
-  [100, 200, 300],  // location
-  [0, 90, 0],       // rotation
-  [1, 1, 1]         // scale
-);
-
-// Vector operations with WASM
-const sum = wasmIntegration.vectorAdd([1, 2, 3], [4, 5, 6]);
-```
-
-## Migration Examples
-
-### Example 1: Migrate from MCP Tools to GraphQL
-
-**Before (MCP Tool)**
-
-```typescript
-// List assets
-const assetsResult = await callTool('manage_asset', {
-  action: 'list',
-  directory: '/Game/Materials'
-});
-
-// List actors
-const actorsResult = await callTool('control_actor', {
-  action: 'list'
-});
-
-// Requires 2 separate calls
-```
-
-**After (GraphQL)**
-
-```typescript
-// Single GraphQL query
-const query = `
-  {
-    assets(filter: { pathStartsWith: "/Game/Materials" }) {
-      edges {
-        node { name path class }
-      }
-    }
-    actors {
-      edges {
-        node { name class location { x y z } }
-      }
-    }
-  }
-`;
-
-const result = await fetch('http://127.0.0.1:4000/graphql', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ query })
-});
-
-// Single call retrieves everything!
-```
-
-### Example 2: Using WebAssembly for Performance
-
-**Before (Pure TypeScript)**
-
-```typescript
-// Parse properties
-function parseProperties(jsonStr) {
-  return JSON.parse(jsonStr); // Slow for large objects
-}
-
-// Calculate transform
-function composeTransform(location, rotation, scale) {
-  // Complex matrix math in JavaScript
-  // Can be slow for many operations
-}
-```
-
-**After (With WASM)**
-
-```typescript
-import { wasmIntegration } from 'unreal-mcp-server/src/wasm/index.js';
-
-// WASM automatically used if available
-const properties = await wasmIntegration.parseProperties(jsonStr);
-const matrix = wasmIntegration.composeTransform(location, rotation, scale);
-
-// 3-8x faster! No code changes needed.
-```
-
-### Example 3: Client Migration Pattern
-
-**Step 1: Detect GraphQL Support**
-
-```typescript
-async function queryUnreal(query: string) {
-  // Try GraphQL first
-  try {
-    const response = await fetch('http://127.0.0.1:4000/graphql', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ query })
-    });
-
-    if (response.ok) {
-      return await response.json();
-    }
-  } catch (error) {
-    console.warn('GraphQL unavailable, falling back to MCP tools');
-  }
-
-  // Fallback to MCP tools
-  // ... implement fallback logic
-}
-```
-
-**Step 2: Use Optimized Queries**
-
-```typescript
-// Optimize for minimal data transfer
-const query = `
-  {
-    assets(pagination: { limit: 50 }) {
-      edges {
-        node {
-          name      # Only request what you need
-          path
-          class
-        }
-      }
-    }
-  }
-`;
-```
-
-## Testing
-
-### Run Tests
-
-```bash
-# Test GraphQL server
-npm run test:graphql
-
-# Test WebAssembly integration
-npm run test:wasm
-
-# Test WASM with full build
-npm run test:wasm:all
-
-# Run all existing tests
-npm test
-```
-
-### Manual Testing
-
-1. **Start the server**:
-   ```bash
-   npm start
-   ```
-
-2. **Test GraphQL**:
-   ```bash
-   # In another terminal
-   curl -X POST http://127.0.0.1:4000/graphql \
-     -H "Content-Type: application/json" \
-     -d '{"query": "{ assets { edges { node { name } } } }"}'
-   ```
-
-3. **Check WASM Status**:
-   ```bash
-   # Check logs for WASM initialization
-   # Look for: "✅ WebAssembly module initialized successfully"
-   ```
-
-## Troubleshooting
-
-### GraphQL Server Won't Start
-
-**Problem**: Port 4000 already in use
-
-**Solution**:
-```bash
-# Use a different port
-GRAPHQL_PORT=4001 npm start
-
-# Or kill the process using port 4000
-lsof -ti:4000 | xargs kill
-```
-
-### WebAssembly Module Not Loading
-
-**Problem**: `Failed to initialize WebAssembly module`
-
-**Solution**:
-```bash
-# Build the WASM module
-npm run build:wasm
-
-# Check if file exists
-ls -la src/wasm/pkg/unreal_mcp_wasm.js
-
-# Verify WASM is enabled
-echo $WASM_ENABLED  # Should be "true"
-```
-
-### Performance Not Improved
-
-**Problem**: Still using TypeScript fallbacks
-
-**Solution**:
-1. Build WASM: `npm run build:wasm`
-2. Enable WASM: `WASM_ENABLED=true npm start`
-3. Check logs for: "WebAssembly module initialized successfully"
-4. Check metrics: `wasmIntegration.getMetrics()`
-
-### Queries Timing Out
-
-**Problem**: Complex GraphQL queries taking too long
-
-**Solution**:
-1. Use pagination: Add `pagination: { limit: 50 }`
-2. Simplify queries: Request only needed fields
-3. Use filtering: Add `filter` to reduce result set
-
-## Best Practices
-
-### GraphQL
-
-1. **Use Specific Field Selection**: Only request fields you need
-2. **Use Pagination**: For large datasets
-3. **Use Filtering**: Reduce server-side processing
-4. **Use Fragments**: Reuse common field selections
-5. **Use Variables**: For dynamic queries
-
-### WebAssembly
-
-1. **Monitor Performance**: Use `getMetrics()` to track improvements
-2. **Measure Before Optimizing**: Don't assume WASM is always faster
-3. **Handle Fallbacks**: Ensure TypeScript fallback works correctly
-4. **Test Both Paths**: Verify both WASM and fallback work
-
-## Performance Comparison
-
-### GraphQL vs MCP Tools
-
-| Use Case | GraphQL Advantage | When to Use |
-|----------|-------------------|-------------|
-| Complex nested queries | Fetch all data in one request | Multi-object relationships |
-| Custom data shapes | Request exactly what you need | Flexible UI requirements |
-| Multiple resources | Combine queries | Dashboard/data aggregation |
-| Client-side optimization | Reduce over-fetching | Mobile/limited bandwidth |
-| Strong typing | Introspection & IDE support | Better DX |
-
-**When to stick with MCP tools**:
-- Simple, single-resource operations
-- Existing code that works well
-- When GraphQL overhead isn't worth it
-
-### WebAssembly Performance
-
-| Operation | TypeScript | WASM | Improvement |
-|-----------|------------|------|-------------|
-| Parse 1000 properties | 150-300ms | 20-40ms | **5-8x** |
-| Vector math (1000 ops) | 5-10ms | 1-2ms | **5x** |
-| Transform composition | 5ms | 0.5ms | **10x** |
-| Dependency analysis | 50-100ms | 10-20ms | **5x** |
-
-## Resources
-
-### Documentation
-- [GraphQL API Documentation](GraphQL-API.md)
-- [WebAssembly Integration Guide](WebAssembly-Integration.md)
-
-### Tools
-- [GraphiQL](https://github.com/graphql/graphiql) - In-browser GraphQL IDE
-- [Apollo Studio](https://studio.apollographql.com) - GraphQL platform
-- [Postman](https://www.postman.com/) - API testing
-
-### Learning
-- [GraphQL.org](https://graphql.org/) - Official GraphQL documentation
-- [WebAssembly.org](https://webassembly.org/) - WebAssembly specification
-
-## Support
-
-If you encounter issues:
-
-1. Check this migration guide
-2. Review the documentation files
-3. Check the troubleshooting sections
-4. Open an issue on GitHub
-
-## Summary
-
-Upgrading to v0.5.0 is straightforward:
-
-1. **No breaking changes** - Everything works as before
-2. **Optional features** - Enable GraphQL and WASM via environment variables
-3. **Gradual migration** - Adopt new features at your own pace
-4. **Better performance** - Get 3-8x improvements automatically with WASM
-5. **Flexible querying** - Use GraphQL for complex data needs
-
-**Start using the new features today!**