# GMS2 MCP Server
MCP сервер для работы с проектами GameMaker Studio 2 в Cursor IDE.
## Что это такое?
Этот MCP сервер парсит и извлекает информацию из проектов GameMaker Studio 2, предоставляя разработчикам и AI-агентам быстрый доступ к структуре проекта, коду GML и метаданным ассетов.
**Основные возможности:**
- 📊 **Для разработчиков**: экспорт всех данных проекта в читаемом формате для изучения и анализа
- 🤖 **Для AI-агентов**: быстрое понимание структуры проекта, что значительно ускоряет vibe-кодинг
- 🔍 **Глубокий анализ**: автоматическое сканирование объектов, скриптов, комнат, спрайтов и их взаимосвязей
- ⚡ **Мгновенный доступ**: получение информации о любом ассете без открытия GameMaker Studio 2
Это решение делает работу с GMS2 проектами более эффективной, особенно при совместной работе с нейронными сетями.
## Структура проекта
```
gms2-mcp-server/
├── mcp-serv/
│ ├── mcp_server.py # MCP сервер с 7 инструментами
│ └── gms2_parser.py # Парсер проектов GameMaker Studio 2
├── docs/
│ ├── README.md # Документация проекта на английском
│ └── README_RU.md # Документация проекта на русском
├── requirements.txt # Зависимости (mcp==1.11.0, python-dotenv==1.1.1)
└── venv/ # Виртуальное окружение Python (создается пользователем)
Дополнительно пользователь создает:
└── .cursor/mcp.json # Конфигурация Cursor IDE (включает путь к проекту)
```
## Установка
### 1. Клонирование репозитория
```bash
git clone https://github.com/Atennebris/gms2-mcp-server
cd gms2-mcp-server
```
### 2. Создание виртуального окружения
```bash
# Создание venv
python -m venv venv
# Активация (Windows)
venv\Scripts\activate
# Активация (Linux/Mac)
source venv/bin/activate
```
### 3. Установка зависимостей
```bash
pip install -r requirements.txt
```
**Текущие зависимости:**
- `mcp==1.11.0` - официальный Python SDK для Model Context Protocol
- `python-dotenv==1.1.1` - загрузка конфигурации из .env файлов
### 4. Конфигурация Cursor IDE
Создайте файл `.cursor/mcp.json` в корне вашего проекта со следующим содержимым:
#### Полная конфигурация с путем к проекту (рекомендуется):
```json
{
"mcpServers": {
"gms2-mcp": {
"command": "python",
"args": ["C:/Users/YourName/Desktop/gms2-mcp-server/mcp-serv/mcp_server.py"],
"env": {
"GMS2_PROJECT_PATH": "C:/Users/YourName/Downloads/Your GMS2 Project"
}
}
}
}
```
**⚠️ Важно:**
- Замените путь в `args` на абсолютный путь к папке вашего MCP сервера!
- Замените путь в `env.GMS2_PROJECT_PATH` на абсолютный путь к папке вашего проекта GMS2 (содержащей .yyp файл)!
- Используйте прямые слеши `/` даже в Windows
#### Вариант 2: Глобальная конфигурация (для всех проектов)
1. В Cursor IDE откройте настройки
2. Перейдите в раздел **Tools & Integrations**
3. Внизу нажмите кнопку **New MCP Server**
4. Откроется глобальный mcp.json файл
5. Добавьте туда такую же конфигурацию
**Архитектура запуска:**
1. Cursor IDE напрямую запускает `python mcp-serv/mcp_server.py`
2. `mcp_server.py` загружает путь к проекту из переменной окружения `GMS2_PROJECT_PATH` (задается в mcp.json)
3. Парсер `gms2_parser.py` предоставляет функциональность для работы с GMS2 проектами
### 5. Перезапуск Cursor IDE
После настройки конфигурации перезапустите Cursor IDE.
**В Cursor IDE:** Откройте командную палитру и проверьте статус MCP серверов.
## Возможности
После успешной установки в Cursor IDE будут доступны **7 инструментов**:
- 🔍 **scan_gms2_project** - сканирование структуры проекта GMS2 (подсчет ассетов, поиск GML файлов)
- 📄 **get_gml_file_content** - чтение содержимого конкретного GML файла
- 🏠 **get_room_info** - получение детальной информации о комнатах из .yy файлов
- 🎯 **get_object_info** - анализ объектов и их событий из .yy файлов
- 🖼️ **get_sprite_info** - информация о спрайтах (размеры, кадры, настройки)
- 📊 **export_project_data** - экспорт всех данных проекта в текстовый формат
- 📋 **list_project_assets** - список всех ассетов по категориям (Objects, Scripts, Rooms, Sprites, etc.)
**Особенности:**
- Поддержка проектов с пробелами в путях (через переменные окружения)
- Автоматическое определение структуры проекта
- Экспорт в человекочитаемый формат
- Полная совместимость с форматами .yyp и .yy файлов
- Упрощенная конфигурация только через mcp.json
## Пример использования
В Cursor IDE (AI-агента) вы можете спросить:
```
"Покажи структуру моего GMS2 проекта"
"Прочитай код объекта obj_player"
"Какие комнаты есть в проекте?"
"Экспортируй все данные проекта"
```
## Системные требования
- **Python:** 3.8+ (рекомендуется 3.10+) - тесты были на 3.12
- **GameMaker Studio 2:** Любая версия с .yyp проектами
- **Cursor IDE:** С поддержкой MCP
- **ОС:** Windows 10/11 (протестировано)
## Решение проблем
### MCP сервер показывает красный статус
1. Проверьте абсолютный путь в `.cursor/mcp.json` (в разделах `args` и `env.GMS2_PROJECT_PATH`)
2. Убедитесь что venv создан и зависимости установлены
3. Проверьте путь к проекту в разделе `env.GMS2_PROJECT_PATH` файла mcp.json
### Сервер не находит проект
1. Убедитесь что путь в `env.GMS2_PROJECT_PATH` правильный
2. Путь должен указывать на папку с .yyp файлом
3. Используйте прямые слеши `/` даже в Windows
### Инструменты не отображаются (0 tools)
1. Перезапустите Cursor IDE
2. Проверьте что Python интерпретатор доступен
3. Протестируйте сервер вручную: `python mcp-serv/mcp_server.py`
### Ошибки импорта или проблемы с путями
Все проблемы с импортами и путями исправлены в текущей версии:
- `gms2_parser.py` теперь находится в той же папке что и `mcp_server.py`
- Путь к проекту настраивается напрямую в `.cursor/mcp.json` через переменные окружения
- Файлы конфигурации и wrapper скрипты больше не нужны
## Техническая информация
### Зависимости
- `mcp==1.11.0` - официальный Python SDK для Model Context Protocol
- `python-dotenv==1.1.1` - загрузка конфигурации из .env файлов
### Архитектура
Проект состоит из двух основных компонентов:
- **mcp-serv/gms2_parser.py** - парсер проектов GameMaker Studio 2
- **mcp-serv/mcp_server.py** - MCP сервер с 7 инструментами для анализа
### Что изменилось
**Улучшения версии 2.1:**
- ✅ Упрощенная структура проекта (без wrapper скриптов)
- ✅ Исправлены все проблемы с импортами и путями
- ✅ Убрана зависимость от config.env - вся конфигурация теперь в mcp.json
- ✅ Весь серверный код объединен в mcp-serv/
- ✅ Путь к проекту настраивается через переменные окружения в mcp.json
- ✅ Улучшена обработка ошибок и отладка
## История проекта
Этот MCP сервер был создан на основе идеи и функционала проекта [vibe2gml](https://github.com/zsturg/vibe2gml), который также был разработан для упрощения и ускорения vibe-кодинга в игровом движке GameMaker Studio 2.
**vibe2gml** - это инструмент для экспорта проектов GMS2 в текстовый формат для работы с AI-агентами. Наш MCP сервер развивает эту идею, предоставляя:
- Прямую интеграцию с Cursor IDE через протокол MCP
- Более богатый набор инструментов для анализа проектов
- Возможность получения данных в реальном времени без экспорта файлов
- Упрощенную конфигурацию и установку
## Дополнительные ресурсы
### Документация
- **docs/README.md** - основная документация на английском языке
- **docs/README_RU.md** - основная документация на русском языке
### Полезные ссылки
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - официальный SDK
- [MCP Documentation](https://modelcontextprotocol.io/introduction) - документация протокола
- [GameMaker Studio 2](https://gamemaker.io/) - официальный сайт GameMaker
- [vibe2gml](https://github.com/zsturg/vibe2gml) - оригинальный проект, вдохновивший создание этого MCP сервера