unreal-engine-mcp-server 0.4.7 → 0.5.0

package/docs/GraphQL-API.md

@@ -0,0 +1,888 @@
+# GraphQL API Documentation
+
+## Overview
+
+The Unreal Engine MCP Server now includes a GraphQL API that provides a flexible, efficient alternative to the standard MCP tools for complex queries. The GraphQL API allows you to:
+
+- Query multiple related objects in a single request
+- Specify exactly what data you need (no over-fetching)
+- Use nested queries to traverse object relationships
+- Perform mutations (create, update, delete) through mutations
+- Leverage GraphQL's strong typing and introspection
+
+## GraphQL Server Configuration
+
+### Environment Variables
+
+```bash
+# Enable/disable GraphQL server
+GRAPHQL_ENABLED=true
+
+# Server host and port
+GRAPHQL_HOST=127.0.0.1
+GRAPHQL_PORT=4000
+
+# GraphQL endpoint path
+GRAPHQL_PATH=/graphql
+
+# CORS settings
+GRAPHQL_CORS_ORIGIN=*
+GRAPHQL_CORS_CREDENTIALS=false
+```
+
+### Accessing the GraphQL API
+
+The GraphQL server runs on a separate port from the MCP server:
+
+- **URL**: `http://127.0.0.1:4000/graphql`
+- **Default Port**: 4000 (configurable via `GRAPHQL_PORT`)
+- **Default Host**: 127.0.0.1 (configurable via `GRAPHQL_HOST`)
+
+## GraphQL Schema
+
+### Custom Scalars
+
+- **Vector**: 3D vector with `x`, `y`, `z` fields (Float)
+- **Rotator**: Rotation with `pitch`, `yaw`, `roll` fields (Float, degrees)
+- **Transform**: Combined transform with `location`, `rotation`, `scale` (Vector/Rotator/Vector)
+- **JSON**: Arbitrary JSON data
+
+### Core Types
+
+#### Asset
+```graphql
+type Asset {
+  name: String!
+  path: String!
+  class: String!
+  packagePath: String!
+  size: Float
+  dependencies: [Asset!]!
+  dependents: [Asset!]!
+  metadata: JSON
+  tags: [String!]!
+}
+```
+
+#### Actor
+```graphql
+type Actor {
+  name: String!
+  class: String!
+  location: Vector
+  rotation: Rotator
+  scale: Vector
+  components: [Component!]!
+  tags: [String!]!
+  properties: JSON
+}
+```
+
+#### Blueprint
+```graphql
+type Blueprint {
+  name: String!
+  path: String!
+  parentClass: String
+  variables: [Variable!]!
+  functions: [Function!]!
+  events: [Event!]!
+  components: [Component!]!
+  scsHierarchy: JSON
+}
+```
+
+## Query Examples
+
+### 1. List All Assets
+
+```graphql
+query {
+  assets {
+    edges {
+      node {
+        name
+        path
+        class
+        packagePath
+      }
+      cursor
+    }
+    pageInfo {
+      hasNextPage
+      hasPreviousPage
+    }
+    totalCount
+  }
+}
+```
+
+### 2. Filter Assets by Class
+
+```graphql
+query {
+  assets(filter: { class: "Material" }) {
+    edges {
+      node {
+        name
+        path
+        class
+        tags
+      }
+    }
+    totalCount
+  }
+}
+```
+
+### 3. Get Asset with Dependencies
+
+```graphql
+query {
+  asset(path: "/Game/Materials/M_Master") {
+    name
+    path
+    class
+    dependencies {
+      name
+      path
+    }
+    dependents {
+      name
+      path
+    }
+    metadata
+    tags
+  }
+}
+```
+
+### 4. Paginated Asset Query
+
+```graphql
+query {
+  assets(pagination: { offset: 0, limit: 10 }) {
+    edges {
+      node {
+        name
+        path
+        class
+      }
+      cursor
+    }
+    pageInfo {
+      hasNextPage
+      hasPreviousPage
+      startCursor
+      endCursor
+    }
+    totalCount
+  }
+}
+```
+
+### 5. List All Actors
+
+```graphql
+query {
+  actors {
+    edges {
+      node {
+        name
+        class
+        location {
+          x
+          y
+          z
+        }
+        rotation {
+          pitch
+          yaw
+          roll
+        }
+        tags
+      }
+    }
+    totalCount
+  }
+}
+```
+
+### 6. Get Actor with Properties and Components
+
+```graphql
+query {
+  actor(name: "SpotLight_Main") {
+    name
+    class
+    location {
+      x
+      y
+      z
+    }
+    rotation {
+      pitch
+      yaw
+      roll
+    }
+    tags
+    properties
+    components {
+      name
+      type
+      properties
+    }
+  }
+}
+```
+
+### 7. Filter Actors by Tag
+
+```graphql
+query {
+  actors(filter: { tag: "Enemy" }) {
+    edges {
+      node {
+        name
+        class
+        tags
+      }
+    }
+    totalCount
+  }
+}
+```
+
+### 8. Get Blueprint Details
+
+```graphql
+query {
+  blueprint(path: "/Game/Blueprints/BP_PlayerCharacter") {
+    name
+    path
+    parentClass
+    variables {
+      name
+      type
+      defaultValue
+      metadata
+    }
+    functions {
+      name
+      inputs {
+        name
+        type
+      }
+      outputs {
+        name
+        type
+      }
+    }
+    events {
+      name
+      type
+    }
+    components {
+      name
+      type
+    }
+    scsHierarchy
+  }
+}
+```
+
+### 9. List All Blueprints
+
+```graphql
+query {
+  blueprints {
+    edges {
+      node {
+        name
+        path
+        parentClass
+        variables {
+          name
+          type
+        }
+        functions {
+          name
+        }
+      }
+    }
+    totalCount
+  }
+}
+```
+
+### 10. Filter Blueprints by Parent Class
+
+```graphql
+query {
+  blueprints(filter: { parentClass: "Actor" }) {
+    edges {
+      node {
+        name
+        path
+        parentClass
+      }
+    }
+    totalCount
+  }
+}
+```
+
+### 11. Get Current Level Information
+
+```graphql
+query {
+  currentLevel {
+    name
+    path
+    loaded
+    lightingQuality
+    actors {
+      name
+      class
+    }
+    streamingLevels
+  }
+}
+```
+
+### 12. List All Levels
+
+```graphql
+query {
+  levels {
+    name
+    path
+    loaded
+    actorCount
+  }
+}
+```
+
+### 13. Search Across All Types
+
+```graphql
+query {
+  search(query: "Player", type: ALL) {
+    ... on Asset {
+      name
+      path
+      __typename
+    }
+    ... on Actor {
+      name
+      class
+      __typename
+    }
+    ... on Blueprint {
+      name
+      path
+      __typename
+    }
+  }
+}
+```
+
+### 14. Search for Assets Only
+
+```graphql
+query {
+  search(query: "Material", type: ASSETS) {
+    ... on Asset {
+      name
+      path
+      class
+    }
+  }
+}
+```
+
+## Mutation Examples
+
+### 1. Duplicate an Asset
+
+```graphql
+mutation {
+  duplicateAsset(path: "/Game/Materials/M_Master", newName: "M_Master_Copy") {
+    name
+    path
+    class
+  }
+}
+```
+
+### 2. Move an Asset
+
+```graphql
+mutation {
+  moveAsset(path: "/Game/Materials/M_Master", newPath: "/Game/Archived/Materials/M_Master") {
+    name
+    path
+  }
+}
+```
+
+### 3. Delete an Asset
+
+```graphql
+mutation {
+  deleteAsset(path: "/Game/Materials/M_Old")
+}
+```
+
+### 4. Spawn an Actor
+
+```graphql
+mutation {
+  spawnActor(input: {
+    classPath: "StaticMeshActor"
+    name: "Cube_001"
+    transform: {
+      location: { x: 0, y: 0, z: 100 }
+      rotation: { pitch: 0, yaw: 0, roll: 0 }
+      scale: { x: 1, y: 1, z: 1 }
+    }
+    tags: ["Spawned"]
+  }) {
+    name
+    class
+    location {
+      x
+      y
+      z
+    }
+    tags
+  }
+}
+```
+
+### 5. Delete an Actor
+
+```graphql
+mutation {
+  deleteActor(name: "Cube_001")
+}
+```
+
+### 6. Set Actor Transform
+
+```graphql
+mutation {
+  setActorTransform(
+    name: "SpotLight_Main"
+    transform: {
+      location: { x: 500, y: 300, z: 200 }
+      rotation: { pitch: 45, yaw: 90, roll: 0 }
+      scale: { x: 1, y: 1, z: 1 }
+    }
+  ) {
+    name
+    location {
+      x
+      y
+      z
+    }
+    rotation {
+      pitch
+      yaw
+      roll
+    }
+  }
+}
+```
+
+### 7. Create a Blueprint
+
+```graphql
+mutation {
+  createBlueprint(input: {
+    name: "BP_NewCharacter"
+    blueprintType: "Actor"
+    savePath: "/Game/Blueprints"
+  }) {
+    name
+    path
+    parentClass
+  }
+}
+```
+
+### 8. Add Variable to Blueprint
+
+```graphql
+mutation {
+  addVariableToBlueprint(
+    path: "/Game/Blueprints/BP_NewCharacter"
+    input: {
+      variableName: "Health"
+      variableType: "Float"
+      defaultValue: 100
+    }
+  ) {
+    name
+    variables {
+      name
+      type
+      defaultValue
+    }
+  }
+}
+```
+
+### 9. Add Function to Blueprint
+
+```graphql
+mutation {
+  addFunctionToBlueprint(
+    path: "/Game/Blueprints/BP_NewCharacter"
+    input: {
+      functionName: "TakeDamage"
+      inputs: [
+        { name: "Damage", type: "Float" }
+        { name: "Source", type: "String" }
+      ]
+    }
+  ) {
+    name
+    functions {
+      name
+      inputs {
+        name
+        type
+      }
+    }
+  }
+}
+```
+
+### 10. Load a Level
+
+```graphql
+mutation {
+  loadLevel(path: "/Game/Maps/Level_01") {
+    name
+    path
+    loaded
+    actorCount
+  }
+}
+```
+
+### 11. Save Current Level
+
+```graphql
+mutation {
+  saveLevel(path: "/Game/Maps/Level_01")
+}
+```
+
+### 12. Create Material Instance
+
+```graphql
+mutation {
+  createMaterialInstance(
+    parentPath: "/Game/Materials/M_Master"
+    name: "MI_Player"
+    parameters: {
+      BaseColor: { x: 1, y: 0, z: 0 }
+      Metallic: 0.5
+    }
+  ) {
+    name
+    path
+    class
+  }
+}
+```
+
+## Fragment Examples
+
+Fragments allow you to reuse field selections:
+
+```graphql
+fragment AssetInfo on Asset {
+  name
+  path
+  class
+  packagePath
+}
+
+query {
+  assets(filter: { class: "Material" }) {
+    edges {
+      node {
+        ...AssetInfo
+        dependencies {
+          ...AssetInfo
+        }
+      }
+    }
+  }
+}
+```
+
+## Variable Examples
+
+Use variables for dynamic queries:
+
+```graphql
+query GetAsset($path: String!, $withDependencies: Boolean!) {
+  asset(path: $path) {
+    ...AssetInfo
+    dependencies @include(if: $withDependencies) {
+      ...AssetInfo
+    }
+  }
+}
+
+fragment AssetInfo on Asset {
+  name
+  path
+  class
+}
+```
+
+With these variables:
+```json
+{
+  "path": "/Game/Materials/M_Master",
+  "withDependencies": true
+}
+```
+
+## Alias Examples
+
+Use aliases to rename fields in results:
+
+```graphql
+query {
+  materials: assets(filter: { class: "Material" }) {
+    edges {
+      node {
+        materialName: name
+        materialPath: path
+        class
+      }
+    }
+  }
+}
+```
+
+## Introspection Query
+
+Get the complete schema:
+
+```graphql
+query {
+  __schema {
+    types {
+      name
+      kind
+      fields {
+        name
+        type {
+          name
+          kind
+        }
+      }
+    }
+  }
+}
+```
+
+## Best Practices
+
+### 1. Use Specific Field Selection
+Always specify only the fields you need:
+
+```graphql
+# Good
+query {
+  assets {
+    edges {
+      node {
+        name
+        path
+      }
+    }
+  }
+}
+
+# Bad (over-fetching)
+query {
+  assets {
+    edges {
+      node {
+        _ # Get everything
+      }
+    }
+  }
+}
+```
+
+### 2. Use Fragments for Reuse
+Create fragments for commonly used field sets:
+
+```graphql
+fragment ActorBasicInfo on Actor {
+  name
+  class
+  location {
+    x
+    y
+    z
+  }
+}
+```
+
+### 3. Use Pagination for Large Datasets
+Always use pagination for queries that might return many results:
+
+```graphql
+query {
+  assets(pagination: { offset: 0, limit: 50 }) {
+    edges {
+      node {
+        name
+        path
+      }
+    }
+    pageInfo {
+      hasNextPage
+      hasPreviousPage
+    }
+  }
+}
+```
+
+### 4. Use Filtering
+Filter results on the server side to reduce data transfer:
+
+```graphql
+query {
+  actors(filter: { class: "StaticMeshActor", tag: "Static" }) {
+    edges {
+      node {
+        name
+        class
+      }
+    }
+  }
+}
+```
+
+### 5. Use Mutations for Modifications
+Use mutations instead of queries for operations that modify data:
+
+```graphql
+mutation {
+  spawnActor(input: { ... }) {
+    name
+    location {
+      x
+      y
+      z
+    }
+  }
+}
+```
+
+## Limitations
+
+1. **Unreal Connection Required**: GraphQL resolvers require an active connection to Unreal Editor
+2. **Plugin Support**: Some queries require specific Unreal plugins to be enabled
+3. **Performance**: Complex nested queries may be slower than focused MCP tool calls
+4. **Not a Replacement**: GraphQL complements but doesn't replace the MCP tool system
+
+## Troubleshooting
+
+### GraphQL Server Not Starting
+
+Check logs for errors:
+```bash
+# Check if port is already in use
+netstat -an | grep 4000
+
+# Verify environment variables
+echo $GRAPHQL_ENABLED
+echo $GRAPHQL_PORT
+```
+
+### Queries Timing Out
+
+Increase timeout in your GraphQL client, or break complex queries into smaller parts.
+
+### Authentication
+
+Currently, GraphQL API has no authentication. Access is restricted to localhost by default. For production, consider:
+- Running behind a reverse proxy with authentication
+- Implementing API keys
+- Using VPN or firewall rules
+
+## Migration from MCP Tools
+
+### MCP Tool → GraphQL Equivalent
+
+| MCP Tool | GraphQL Query | Notes |
+|----------|---------------|-------|
+| `manage_asset` (list) | `assets` query | Use filter and pagination |
+| `manage_asset` (create) | `createMaterialInstance` mutation | Asset creation varies |
+| `control_actor` (spawn) | `spawnActor` mutation | Transform input format |
+| `control_actor` (delete) | `deleteActor` mutation | Simpler API |
+| `manage_blueprint` (get) | `blueprint` query | More detailed response |
+| `manage_level` (load) | `loadLevel` mutation | Direct mapping |
+
+### Example Migration
+
+**Before (MCP Tool):**
+```json
+{
+  "tool": "manage_asset",
+  "arguments": {
+    "action": "list",
+    "directory": "/Game"
+  }
+}
+```
+
+**After (GraphQL):**
+```graphql
+query {
+  assets(filter: { pathStartsWith: "/Game" }, pagination: { limit: 100 }) {
+    edges {
+      node {
+        name
+        path
+        class
+      }
+    }
+    totalCount
+  }
+}
+```
+
+## Additional Resources
+
+### GraphQL Clients
+- [GraphiQL](https://github.com/graphql/graphiql) - In-browser GraphQL IDE
+- [Apollo Studio](https://studio.apollographql.com) - Powerful visual editor
+- [Insomnia](https://insomnia.rest/) - REST client with GraphQL support
+- [Postman](https://www.postman.com/) - API platform with GraphQL support
+
+### Learning Resources
+- [Introduction to GraphQL](https://graphql.org/learn/)
+- [Queries and Mutations](https://graphql.org/learn/queries/)
+- [Apollo Client React](https://www.apollographql.com/docs/react/)
+- [GraphQL Best Practices](https://graphql.org/learn/best-practices/)
+
+## Next Steps
+
+1. Start the MCP server with `GRAPHQL_ENABLED=true`
+2. Use a GraphQL client (GraphiQL, Apollo Studio, Insomnia, or Postman) to explore the schema
+3. Try the query examples above
+4. Build your own queries tailored to your needs
+5. Consider using fragments and variables for complex workflows