Unity Context Slicer

Unity Context Slicer is a graph-based context extraction engine and Model Context Protocol (MCP) server designed for Unity projects. It parses C# scripts, Unity scenes (.unity), prefabs (.prefab), and .meta asset GUIDs into an in-memory knowledge graph. By slicing targeted $N$-hop neighborhoods around relevant components and compressing raw YAML/AST structures, it delivers 5–10× token reduction, producing compact context bundles optimized for local and cloud LLMs.

⚡ Quick Start (Zero Install)

Run the server directly without installing Python dependencies using uvx:

uvx unity-context-slicer --project-dir "path/to/YourUnityProject"

Or install via pip:

pip install unity-context-slicer
unity-context-slicer --project-dir "path/to/YourUnityProject"

🔑 Key Features

• 🕸️ Graph-Based Project Indexing: Maps C# classes, methods, events, Unity GameObjects, MonoBehaviours, scenes, and prefabs into a unified directed graph.

• ⚡ 5–10× Context Compression: Converts verbose scene YAML and code structures into dense, high-information text representations suited for restricted LLM context windows (e.g., 7B local models).

• 🎯 Focused Slicing: Extracts $N$-hop relational neighborhoods (unity_slice) or comprehensive class context cards (unity_class) including method callers, attached scene objects, and inheritance hierarchies.

• 🔄 Auto-Reloading Resident Session: Monitors file modification times (mtime) across .cs, .unity, and .prefab files to update the resident graph in milliseconds upon code changes.

• 🔌 Built-in MCP Server: Exposes stdio-based MCP tools for direct integration with MCP clients such as Cursor, Windsurf, Claude Desktop, VS Code (Cline / Roo Code), and custom AI agents.

• 🆔 Unity GUID Resolution: Resolves .meta file GUIDs to bridge C# MonoBehaviours with serialized scene/prefab component references.

🛠️ Architecture & Pipeline

graph TD
    A["Unity Project Directory"] --> B["C# Roslyn Scanner / YAML Parser"]
    A --> C["Meta GUID Resolver"]
    B --> D["Loader & In-Memory Graph"]
    C --> D
    D --> E["Session Manager"]
    E --> F["Graph Slicer"]
    F --> G["Compressor & Task Bundler"]
    G --> H["MCP Server & Prompt Bundles"]

Pipeline Steps

1. Parsing & Resolution: C# AST analysis via Roslyn (ScannerCore.cs) combined with Python-native Unity scene/prefab parsing (unity_parser.py) and GUID resolution (meta_resolver.py).

2. Graph Construction: Builds a unified node/edge model in ProjectGraph indexed for bidirectional lookup.

3. Neighborhood Slicing: SubGraph algorithms isolate relevant subgraphs based on class, method, or GameObject seeds.

4. Dense Compression: Renders subgraphs into task-ready prompt context via compressor.py.

🔌 MCP Tools Provided

🤖 Integration Guide for Popular Coding Agents

1. Cursor

Navigate to Cursor Settings $\rightarrow$ Features $\rightarrow$ MCP Servers and click + Add New MCP Server:

• Name: unity-context-slicer

• Type: command

• Command: uvx unity-context-slicer --project-dir "${workspaceFolder}"

2. Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "unity-context-slicer": {
      "command": "uvx",
      "args": [
        "unity-context-slicer",
        "--project-dir",
        "C:/Path/To/Your/UnityProject"
      ]
    }
  }
}

3. Windsurf (Codeium)

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "unity-context-slicer": {
      "command": "uvx",
      "args": [
        "unity-context-slicer",
        "--project-dir",
        "${workspaceFolder}"
      ]
    }
  }
}

4. VS Code Extensions (Cline / Roo Code / Continue.dev)

Add to your extension's MCP server configuration JSON:

{
  "mcpServers": {
    "unity-context-slicer": {
      "command": "uvx",
      "args": [
        "unity-context-slicer",
        "--project-dir",
        "${workspaceFolder}"
      ]
    }
  }
}

💡 Recommended Agent Rules (.cursorrules / .windsurfrules)

To help AI coding agents use Unity Context Slicer effectively, add this instruction to your project's rule file:

When answering questions or writing C#/Unity code:
1. Use `unity_search` to discover relevant classes, methods, or scene GameObjects.
2. Use `unity_class` to inspect MonoBehaviour callers, attached scene objects, and class inheritance.
3. Use `unity_bundle` before initiating large refactors to receive a compressed graph context bundle.

📁 Repository Structure

• unity_context_slicer/

  • mcp_server.py — FastMCP stdio server implementation and tool definitions.

  • loader.py — Data primitives (GraphNode, GraphEdge) and graph indexing.

  • slicer.py — Neighborhood traversal and class context extraction.

  • compressor.py — Dense text formatting and LLM context reduction.

  • session.py — Resident GraphSession manager with stale file detection.

  • unity_parser.py — Scene and prefab document structure extractor.

  • meta_resolver.py — Mapping between .meta GUIDs and C# source files.

  • annotations.py — Annotation cache for node purpose metadata.

  • task_log.py — Task history parser and context embedder.

  • csharp_scanner/ — C# Roslyn scanner project (CSharpScanner.csproj).

📜 License

This project is licensed under the MIT License.