Mutagen MCP

mutagen-mcp

MCP-сервер (stdio) на .NET 9 + Mutagen для чтения Skyrim SE (и родственных релизов Mutagen с ToSkyrimRelease()): статус путей, список из plugins.txt (пагинация offset / maxPlugins, фильтр только отсутствующие на диске), заголовки, мастера, компактный режим mutagen_verify_masters без массива рёбер, а также ограниченный анализ записей (цепочка оверрайдов по FormKey, сравнение двух плагинов, кандидаты ITM / удалённые записи). Тяжёлые сценарии ограничены параметрами и настройками (maxPlugins, maxNodes, MaxConflictScanRecords, …).

Требования

• .NET SDK 9 (на машине с игрой обычно Windows; сборка кроссплатформенная; в Docker образ собирается сам).
• Путь к plugins.txt (список и порядок плагинов для игры или профиля MO2).
• DataFolder — первый корень поиска (обычно Skyrim Special Edition\Data с ванильными мастерами).
• PluginSearchRoots — дополнительные корни (плоские каталоги с .esp / .esm / .esl или корень mods Mod Organizer 2). Порядок важен: последний корень в списке выигрывает, если одно и то же имя файла встречается в нескольких корнях.
• Для MO2 (плагины в mods//…, а не в корне mods/): задайте ModlistTxtPath — путь к modlist.txt профиля. Резолвер ищет файл как modsRoot//(Data/)?/; приоритет как в MO2: ниже в modlist — выше приоритет при совпадении имён.

Если PluginSearchRoots пуст, используется только DataFolder. Без ModlistTxtPath дополнительные корни обрабатываются только плоско (корень/файл и при ProbeDataSubfolder — корень/Data/файл).

Заметка: это не дублирует Mod Organizer MCP: тот про управление профилем MO2; mutagen-mcp использует те же файлы, чтобы открыть бинарные плагины через Mutagen.

Сборка

dotnet build MutagenMcp.sln -c Release

Бинарь: src/MutagenMcp/bin/Release/net9.0/mutagen-mcp.dll.

Запуск в контейнере

MCP по stdio нуждается в интерактивном stdin у контейнера (-i). Смонтируйте Data, при MO2 — mods и modlist.txt, plugins.txt профиля; передайте внутренние пути в env.

Сборка образа (из корня репозитория):

docker build -t mutagen-mcp:local .

Минимальный пример (только игровой Data + plugins.txt):

docker run -i --rm \
  -v "/path/to/Skyrim Special Edition/Data:/data:ro" \
  -v "/path/to/profiles/MyProfile/plugins.txt:/config/plugins.txt:ro" \
  -e MutagenMcp__DataFolder=/data \
  -e MutagenMcp__PluginsTxtPath=/config/plugins.txt \
  mutagen-mcp:local

Mod Organizer 2 (игра + каталог mods + modlist.txt того же профиля, что и plugins.txt):

docker run -i --rm \
  -v "/path/to/Skyrim Special Edition/Data:/data:ro" \
  -v "/path/to/MO2/mods:/mods:ro" \
  -v "/path/to/MO2/profiles/MyProfile/plugins.txt:/config/plugins.txt:ro" \
  -v "/path/to/MO2/profiles/MyProfile/modlist.txt:/config/modlist.txt:ro" \
  -e MutagenMcp__DataFolder=/data \
  -e MutagenMcp__PluginsTxtPath=/config/plugins.txt \
  -e MutagenMcp__ModlistTxtPath=/config/modlist.txt \
  -e MutagenMcp__PluginSearchRoots__0=/mods \
  mutagen-mcp:local

Пример с плоским вторым корнем (без MO2-структуры папок):

docker run -i --rm \
  -v "/path/to/Skyrim Special Edition/Data:/data:ro" \
  -v "/path/to/mods/staging:/mods:ro" \
  -v "/path/to/profiles/MyProfile/plugins.txt:/config/plugins.txt:ro" \
  -e MutagenMcp__DataFolder=/data \
  -e MutagenMcp__PluginSearchRoots__0=/mods \
  -e MutagenMcp__PluginsTxtPath=/config/plugins.txt \
  mutagen-mcp:local

Фрагмент для Cursor (Linux / WSL; пути замените на свои; образ локально: mutagen-mcp:local):

{
  "mcpServers": {
    "mutagen-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/mnt/g/Games/steamapps/common/Skyrim Special Edition/Data:/data:ro",
        "-v", "/mnt/s/MO2_data/mods:/mods:ro",
        "-v", "/mnt/s/MO2_data/profiles/Default/plugins.txt:/config/plugins.txt:ro",
        "-v", "/mnt/s/MO2_data/profiles/Default/modlist.txt:/config/modlist.txt:ro",
        "-e", "MutagenMcp__DataFolder=/data",
        "-e", "MutagenMcp__PluginsTxtPath=/config/plugins.txt",
        "-e", "MutagenMcp__ModlistTxtPath=/config/modlist.txt",
        "-e", "MutagenMcp__PluginSearchRoots__0=/mods",
        "-e", "MutagenMcp__CacheGameEnvironment=true",
        "mutagen-mcp:local"
      ]
    }
  }
}

На Windows с Docker Desktop пути в -v часто задают как D:/Games/.../Data:/data:ro. Флаг :ro необязателен, но удобен для чтения.

При MutagenMcp__CacheGameEnvironment=true в Docker имеет смысл задать лимит памяти контейнера (например --memory=8g в args перед образом), если лоад большой.

Ограничения: контейнер должен видеть те же файлы, что и ваша установка. В Linux-контейнере на смонтированном NTFS возможны проблемы с регистром имён файлов относительно plugins.txt.

Процесс MCP, Docker и кэши

• Нет отдельного «вечного» контейнера под MCP: при типичном конфиге docker run -i --rm … Cursor запускает контейнер на время одной сессии MCP (stdio к процессу dotnet …/mutagen-mcp.dll внутри контейнера). Выключили MCP или перезагрузили окно — процесс завершился, с --rm контейнер удаляется. Следующий старт — снова новый контейнер и пустая память процесса.
• Кэш резолва путей (класс PluginPathResolver, RAM процесса, на диск не пишется): накопительный словарь «имя файла плагина → абсолютный путь» (или пометка, что файла нет). Общий для пакетного ResolvePluginPaths и одиночного TryResolve. Сбрасывается при смене списка корней (DataFolder + PluginSearchRoots), пути или mtime modlist.txt, флага ProbeDataSubfolder. Порядок plugins.txt на физическое расположение файлов на диске не влияет — в ключ инвалидации он не входит. Для MO2 резолв по папкам модов делается пакетно (перечисление .esp / .esm / .esl в каталоге мода), без комбинаторного числа отдельных проверок «мод × плагин».
• mutagen_plugin_master_closure перед обходом мастеров один раз вызывает пакетный резолв для всех включённых плагинов из plugins.txt, чтобы заполнить этот словарь; дальнейшие обращения к тем же именам идут из кэша.
• CacheGameEnvironment — отдельный кэш: полный GameEnvironment Mutagen в памяти до смены лоада/сигнатуры; см. таблицу ниже. С кэшем путей к файлам он не смешивается.

Конфигурация

src/MutagenMcp/appsettings.json, секция MutagenMcp:

Переменные окружения (перекрывают JSON): MutagenMcp__DataFolder, MutagenMcp__PluginsTxtPath, MutagenMcp__ModlistTxtPath, MutagenMcp__GameRelease, MutagenMcp__PrependImplicitStandardMasters, MutagenMcp__MaxPluginsPerRequest, MutagenMcp__MaxConflictScanRecords, MutagenMcp__MaxCompareResults, MutagenMcp__MaxOverrideChainLength, MutagenMcp__OverrideChainUseBinaryOverlay, MutagenMcp__OverrideChainOverlayMaxDegreeOfParallelism, MutagenMcp__CacheGameEnvironment, MutagenMcp__EnvironmentCacheMaxAgeSeconds, MutagenMcp__ExposeToolTimingsInJson, MutagenMcp__ToolDiagnosticsLogPath, MutagenMcp__ToolDiagnosticsProgressPluginInterval, MutagenMcp__ProbeDataSubfolder, MutagenMcp__PluginSearchRoots__0, MutagenMcp__PluginSearchRoots__1, …

Cursor / MCP (без Docker)

Пример (путь к проекту и пути к Data / MO2 подставьте свои):

{
  "mcpServers": {
    "mutagen-mcp": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "C:/path/to/mutagen-mcp/src/MutagenMcp/MutagenMcp.csproj",
        "-c",
        "Release",
        "--no-build"
      ],
      "env": {
        "MutagenMcp__DataFolder": "D:/Steam/steamapps/common/Skyrim Special Edition/Data",
        "MutagenMcp__PluginsTxtPath": "C:/ModOrganizer/profiles/Default/plugins.txt",
        "MutagenMcp__ModlistTxtPath": "C:/ModOrganizer/profiles/Default/modlist.txt",
        "MutagenMcp__PluginSearchRoots__0": "C:/ModOrganizer/mods",
        "MutagenMcp__CacheGameEnvironment": "true"
      }
    }
  }
}

После первой сборки можно вызывать dotnet exec .../mutagen-mcp.dll вместо dotnet run, если удобнее.

Готовый фрагмент для вставки в конфиг MCP Cursor (с кэшем окружения): docs/cursor-mcp.example.json — скопируйте содержимое в свой mcp.json / настройки MCP и поправьте пути. Новые аргументы tools (offset, onlyFileMissing, includeDirectEdges, …) не требуют правок mcp.json: схема приходит от сервера при подключении; достаточно пересобрать образ или обновить бинарь и перезапустить MCP.

Длинные ответы: пагинация и «только проблемы»

Полный проход mutagen_verify_masters по всем включённым плагинам по-прежнему ограничен maxPlugins и серверным MaxPluginsPerRequest.

Инструменты

Ответы — JSON-текст. Для conflict-tools при ExposeToolTimingsInJson: true в том же JSON есть timings (мс) — удобно для агента и UI без stderr. У mutagen_formid_override_chain в overlay-режиме в timings есть resolvedListingsPrepMs (суммарно: чтение листингов + резолв путей до скана). Разбивка readListingsMs / resolvePathsMs выводится только в NDJSON-событии OverrideChainResolvedListings (см. ToolDiagnosticsLogPath), а не в поле timings JSON-ответа. Дополнительно логи в stderr: сборка GameEnvironment, RentFullEnvironment: CACHE HIT|MISS|…, те же цифры дублируются текстом. Если задан ToolDiagnosticsLogPath, события и тайминги пишутся в файл построчно (NDJSON) — удобно, когда stderr клиента MCP не сохраняется или нужен последующий разбор (jq, Grafana Loki и т.п.). В Docker смонтируйте каталог для файла, например -v "/path/to/mcp-logs:/logs" и -e MutagenMcp__ToolDiagnosticsLogPath=/logs/mutagen-mcp-diagnostics.ndjson.

Производительность тяжёлых инструментов

• mutagen_formid_override_chain: winnerOnly: true — один победитель (макс. индекс лоадордера); overlay параллелит открытия как полный скан. winnerOnly: false — полная цепочка. accurateRecordLookup: true — перебор всех major-записей в каждом плагине лоада вместо быстрого top-level поиска: на сотнях модов и «левом» FormKey время может исчисляться минутами; по умолчанию false. В timings JSON (и NDJSON ConflictToolOk) для overlay есть resolvedListingsPrepMs. Детальная разбивка чтения лоада vs резолва путей — в NDJSON OverrideChainResolvedListings (readListingsMs, resolvePathsMs). maxChainLength только обрезка JSON.
• mutagen_verify_masters с includeDirectEdges: false сильно уменьшает размер ответа при том же объёме работы на диске (чтение заголовков плагинов для графа).
• mutagen_list_plugins: для обзора лоада без гигантского JSON используйте offset и умеренный maxPlugins; для поиска «дыр» в установке — onlyFileMissing.
• Кэш резолва путей (см. выше) переиспользуется между вызовами в одном процессе: повторный mutagen_list_plugins, mutagen_verify_masters, mutagen_formid_override_chain и т.д. после первого полного прохода по именам дают гораздо меньше обращений к диску, пока не сменились корни или modlist.txt.
• Включите CacheGameEnvironment (и при необходимости EnvironmentCacheMaxAgeSeconds), если клиент MCP часто вызывает тяжёлые инструменты с полным лоадом подряд: повторно не поднимается полный GameEnvironment (кроме сценария ITM — там по-прежнему строится второй лоад без целевого мода).
• Для Docker задайте достаточный лимит памяти контейнера: кэш окружения держит один полный граф модов в RAM; словарь путей к плагинам обычно скромнее, но тоже живёт в процессе.
• Не запускайте несколько долгих вызовов параллельно на одном stdio-процессе без необходимости.

Ограничения v1

• mutagen_formid_override_chain не видит плагины, включённые в plugins.txt, но без найденного файла под DataFolder / PluginSearchRoots / MO2 — они выпадают из скана. Стандартные мастера (Skyrim.esm, …) при PrependImplicitStandardMasters: true добавляются к лоаду даже без строк в plugins.txt (см. конфиг). Пустая цепочка при корректном лоаде часто означает неверную строку FormKey относительно Mutagen, а не только «нет оверрайдов».
• Инструменты по FormKey и сравнению плагинов используют резолв путей к файлам плагинов (внутрипроцессный кэш имён до смены корней / modlist.txt / ProbeDataSubfolder). Полный GameEnvironment поднимается в зависимости от режима (overlay vs полный лоад) и CacheGameEnvironment; держите лимиты (maxRecords, maxResults, настройки Max*) разумными.
• Семантика ITM / сравнение записей опирается на Loqui/Mutagen Equals, а не на побайтовое совпадение с xEdit; удалённые записи определяются через MajorRecordFlags рефлексией — возможны расхождения с UI.
• includeHeaders в mutagen_list_plugins открывает каждый плагин через Mutagen — держите maxPlugins умеренным; для длинного лоада используйте offset и при необходимости onlyFileMissing; большие JSON-ответы клиент MCP может обрывать по таймауту.
• mutagen_plugin_master_closure строит только мастер → мастер мастера из заголовков; патчи без записи в мастерах и «кто зависит от плагина X» сюда не входят.
• mutagen_verify_masters по умолчанию обрабатывает только первые maxPlugins включённых записей в порядке файла — не весь список целиком; увеличьте maxPlugins или MaxPluginsPerRequest для полного прохода.
• Разрешение по modlist.txt опирается на строки +ИмяПапкиМода; при несовпадении имени папки на диске плагин может не находиться.

Лицензия

Укажите лицензию по желанию владельца репозитория (файл не добавлялся автоматически).