Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
801 changes: 801 additions & 0 deletions .github/workflows/publish-upm.yml

Large diffs are not rendered by default.

1 change: 0 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@
.windsurf
.codeiumignore
.kiro
CLAUDE.md

# Code-copy related files
.clipignore
Expand Down
1 change: 1 addition & 0 deletions .serena/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
/cache
24 changes: 24 additions & 0 deletions .serena/memories/code_style_conventions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Code Style and Conventions

## C# (Unity Bridge)
- **Namespace**: `MCPForUnity.Editor` for editor code
- **Assembly Definition**: Uses `.asmdef` files for modularity
- **Naming**: PascalCase for classes/methods, camelCase for fields/parameters
- **Unity Conventions**: Follow Unity's coding standards
- **Error Handling**: Use try-catch with detailed logging via Debug.LogError
- **Serialization**: Use Newtonsoft.Json for JSON handling

## Python (MCP Server)
- **Style**: Follow PEP 8
- **Type Hints**: Use Python 3.10+ type annotations
- **Imports**: Standard library first, then third-party, then local
- **Error Handling**: Return structured error responses via MCP protocol
- **Async**: Use async/await for MCP tool handlers
- **Logging**: Log to stderr and rotating file, never to stdout

## General Principles
- No hardcoded paths - use config/environment variables
- Validate all inputs, especially file paths and Unity operations
- Handle platform differences (Windows/macOS/Linux) explicitly
- Clean up resources (sockets, file handles) properly
- Use defensive programming for Unity Editor state changes
22 changes: 22 additions & 0 deletions .serena/memories/project_overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# MCP for Unity Project Overview

## Purpose
MCP for Unity is a bridge that enables AI assistants (Claude, Cursor, etc.) to interact directly with Unity Editor via the Model Context Protocol (MCP). It allows LLMs to manage assets, control scenes, edit scripts, and automate tasks within Unity.

## Tech Stack
- **Unity Package**: C# (.NET/Unity 2021.3+ LTS)
- **MCP Server**: Python 3.10+ with MCP protocol implementation
- **Build System**: Unity Package Manager (UPM) for Unity side, uv for Python dependencies
- **Testing**: pytest for Python tests, Unity Test Framework for C# tests
- **CI/CD**: GitHub Actions for automated testing

## Architecture
1. **Unity Bridge** (`UnityMcpBridge/`): Unity package that runs inside the Editor
2. **Python Server** (`UnityMcpBridge/UnityMcpServer~/src/`): MCP server that communicates between Unity and MCP clients
3. **Communication**: TCP socket with custom framing protocol between Unity and Python server

## Key Components
- Editor tools for asset, scene, script, shader, and GameObject management
- Socket-based communication with strict framing for reliability
- Auto-configuration for popular MCP clients (Claude, Cursor, VSCode)
- Validation system with optional Roslyn support for advanced C# validation
53 changes: 53 additions & 0 deletions .serena/memories/suggested_commands.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Development Commands for MCP for Unity

## Testing
```bash
# Run Python tests
cd tests
pytest

# Run specific test file
pytest tests/test_script_tools.py

# Run Unity tests (requires Unity installation)
# Use Unity Test Framework in Unity Editor via Window > General > Test Runner
```

## Development Scripts
```bash
# Deploy development code to test installation
./deploy-dev.bat # Windows only - deploys to Unity package cache and MCP server location

# Restore from backup
./restore-dev.bat # Windows only - restores original files

# Switch package sources
python mcp_source.py # Switch between upstream, remote branch, or local workspace

# Run stress test
python tools/stress_mcp.py --duration 60 --clients 8
```

## Python Environment
```bash
# Install dependencies (using uv)
cd UnityMcpBridge/UnityMcpServer~/src
uv sync

# Run the MCP server manually
uv run server.py
```

## Unity Package Management
```bash
# Install via Git URL in Unity Package Manager
# URL: https://github.com/The1Studio/unity-mcp.git?path=/UnityMcpBridge
# Original: https://github.com/CoplayDev/unity-mcp.git?path=/UnityMcpBridge

# Or via OpenUPM (Studio fork)
openupm add com.theonegamestudio.unity-mcp
```

## Version Management
- Version is stored in `UnityMcpBridge/package.json` and `UnityMcpBridge/UnityMcpServer~/src/pyproject.toml`
- Keep both versions in sync when updating
28 changes: 28 additions & 0 deletions .serena/memories/task_completion_checklist.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Task Completion Checklist

When completing a task in the MCP for Unity codebase:

## For Python Changes
1. Run pytest to ensure tests pass: `pytest tests/`
2. Check for any print statements (should use logging instead)
3. Verify error handling returns proper MCP protocol responses
4. Test with actual Unity connection if modifying protocol/tools

## For C# Unity Changes
1. Ensure no compilation errors in Unity Editor
2. Test the modified functionality in Unity Editor
3. Check Unity console for any errors or warnings
4. Verify compatibility with Unity 2021.3 LTS minimum version

## For Both
1. Update version in both `package.json` and `pyproject.toml` if needed
2. Ensure no sensitive information in code or commits
3. Test auto-configuration with target MCP clients if modifying setup
4. Run stress test if modifying connection/protocol code
5. Update README.md if adding new features or changing setup

## Before Committing
1. No hardcoded paths or credentials
2. Platform-specific code handles Windows/macOS/Linux
3. Error messages are helpful and actionable
4. Code follows established patterns in the codebase
68 changes: 68 additions & 0 deletions .serena/project.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# language of the project (csharp, python, rust, java, typescript, go, cpp, or ruby)
# * For C, use cpp
# * For JavaScript, use typescript
# Special requirements:
# * csharp: Requires the presence of a .sln file in the project folder.
language: csharp

# whether to use the project's gitignore file to ignore files
# Added on 2025-04-07
ignore_all_files_in_gitignore: true
# list of additional paths to ignore
# same syntax as gitignore, so you can use * and **
# Was previously called `ignored_dirs`, please update your config if you are using that.
# Added (renamed) on 2025-04-07
ignored_paths: []

# whether the project is in read-only mode
# If set to true, all editing tools will be disabled and attempts to use them will result in an error
# Added on 2025-04-18
read_only: false


# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
# Below is the complete list of tools for convenience.
# To make sure you have the latest list of tools, and to view their descriptions,
# execute `uv run scripts/print_tool_overview.py`.
#
# * `activate_project`: Activates a project by name.
# * `check_onboarding_performed`: Checks whether project onboarding was already performed.
# * `create_text_file`: Creates/overwrites a file in the project directory.
# * `delete_lines`: Deletes a range of lines within a file.
# * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
# * `execute_shell_command`: Executes a shell command.
# * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
# * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
# * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
# * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
# * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
# * `initial_instructions`: Gets the initial instructions for the current project.
# Should only be used in settings where the system prompt cannot be set,
# e.g. in clients you have no control over, like Claude Desktop.
# * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
# * `insert_at_line`: Inserts content at a given line in a file.
# * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
# * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
# * `list_memories`: Lists memories in Serena's project-specific memory store.
# * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
# * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
# * `read_file`: Reads a file within the project directory.
# * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
# * `remove_project`: Removes a project from the Serena configuration.
# * `replace_lines`: Replaces a range of lines within a file with new content.
# * `replace_symbol_body`: Replaces the full definition of a symbol.
# * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
# * `search_for_pattern`: Performs a search for a pattern in the project.
# * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
# * `switch_modes`: Activates modes by providing a list of their names
# * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
# * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
# * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
# * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
excluded_tools: []

# initial prompt for the project. It will always be given to the LLM upon activating the project
# (contrary to the memories, which are loaded on demand).
initial_prompt: ""

project_name: "unity-mcp"
Loading