GraphQL-API.md

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

# 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

type Asset {
  name: String!
  path: String!
  class: String!
  packagePath: String!
  size: Float
  dependencies: [Asset!]!
  dependents: [Asset!]!
  metadata: JSON
  tags: [String!]!
}

Actor

type Actor {
  name: String!
  class: String!
  location: Vector
  rotation: Rotator
  scale: Vector
  components: [Component!]!
  tags: [String!]!
  properties: JSON
}

Blueprint

type Blueprint {
  name: String!
  path: String!
  parentClass: String
  variables: [Variable!]!
  functions: [Function!]!
  events: [Event!]!
  components: [Component!]!
  scsHierarchy: JSON
}

Query Examples

1. List All Assets

query {
  assets {
    edges {
      node {
        name
        path
        class
        packagePath
      }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
    }
    totalCount
  }
}

2. Filter Assets by Class

query {
  assets(filter: { class: "Material" }) {
    edges {
      node {
        name
        path
        class
        tags
      }
    }
    totalCount
  }
}

3. Get Asset with Dependencies

query {
  asset(path: "/Game/Materials/M_Master") {
    name
    path
    class
    dependencies {
      name
      path
    }
    dependents {
      name
      path
    }
    metadata
    tags
  }
}

4. Paginated Asset Query

query {
  assets(pagination: { offset: 0, limit: 10 }) {
    edges {
      node {
        name
        path
        class
      }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

5. List All Actors

query {
  actors {
    edges {
      node {
        name
        class
        location {
          x
          y
          z
        }
        rotation {
          pitch
          yaw
          roll
        }
        tags
      }
    }
    totalCount
  }
}

6. Get Actor with Properties and Components

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

query {
  actors(filter: { tag: "Enemy" }) {
    edges {
      node {
        name
        class
        tags
      }
    }
    totalCount
  }
}

8. Get Blueprint Details

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

query {
  blueprints {
    edges {
      node {
        name
        path
        parentClass
        variables {
          name
          type
        }
        functions {
          name
        }
      }
    }
    totalCount
  }
}

10. Filter Blueprints by Parent Class

query {
  blueprints(filter: { parentClass: "Actor" }) {
    edges {
      node {
        name
        path
        parentClass
      }
    }
    totalCount
  }
}

11. Get Current Level Information

query {
  currentLevel {
    name
    path
    loaded
    lightingQuality
    actors {
      name
      class
    }
    streamingLevels
  }
}

12. List All Levels

query {
  levels {
    name
    path
    loaded
    actorCount
  }
}

13. Search Across All Types

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

query {
  search(query: "Material", type: ASSETS) {
    ... on Asset {
      name
      path
      class
    }
  }
}

Mutation Examples

1. Duplicate an Asset

mutation {
  duplicateAsset(path: "/Game/Materials/M_Master", newName: "M_Master_Copy") {
    name
    path
    class
  }
}

2. Move an Asset

mutation {
  moveAsset(path: "/Game/Materials/M_Master", newPath: "/Game/Archived/Materials/M_Master") {
    name
    path
  }
}

3. Delete an Asset

mutation {
  deleteAsset(path: "/Game/Materials/M_Old")
}

4. Spawn an Actor

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

mutation {
  deleteActor(name: "Cube_001")
}

6. Set Actor Transform

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

mutation {
  createBlueprint(input: {
    name: "BP_NewCharacter"
    blueprintType: "Actor"
    savePath: "/Game/Blueprints"
  }) {
    name
    path
    parentClass
  }
}

8. Add Variable to Blueprint

mutation {
  addVariableToBlueprint(
    path: "/Game/Blueprints/BP_NewCharacter"
    input: {
      variableName: "Health"
      variableType: "Float"
      defaultValue: 100
    }
  ) {
    name
    variables {
      name
      type
      defaultValue
    }
  }
}

9. Add Function to Blueprint

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

mutation {
  loadLevel(path: "/Game/Maps/Level_01") {
    name
    path
    loaded
    actorCount
  }
}

11. Save Current Level

mutation {
  saveLevel(path: "/Game/Maps/Level_01")
}

12. Create Material Instance

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:

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:

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:

{
  "path": "/Game/Materials/M_Master",
  "withDependencies": true
}

Alias Examples

Use aliases to rename fields in results:

query {
  materials: assets(filter: { class: "Material" }) {
    edges {
      node {
        materialName: name
        materialPath: path
        class
      }
    }
  }
}

Introspection Query

Get the complete schema:

query {
  __schema {
    types {
      name
      kind
      fields {
        name
        type {
          name
          kind
        }
      }
    }
  }
}

Best Practices

1. Use Specific Field Selection

Always specify only the fields you need:

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

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:

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:

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:

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:

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

{
  "tool": "manage_asset",
  "arguments": {
    "action": "list",
    "directory": "/Game"
  }
}

After (GraphQL):

query {
  assets(filter: { pathStartsWith: "/Game" }, pagination: { limit: 100 }) {
    edges {
      node {
        name
        path
        class
      }
    }
    totalCount
  }
}

Additional Resources

GraphQL Clients

• GraphiQL - In-browser GraphQL IDE
• Apollo Studio - Powerful visual editor
• Insomnia - REST client with GraphQL support
• Postman - API platform with GraphQL support

Learning Resources

• Introduction to GraphQL
• Queries and Mutations
• Apollo Client React
• GraphQL 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