Tank Fight MCP — спецификация игры как сервис

MCP-сервер, который предоставляет каноническую спецификацию для Tank Fight: размер поля и окна, характеристики танков и пуль, правила появления, подсчёт очков, управление, поведение меню, стратегии ИИ, нарастание сложности и разрушаемый лабиринт для каждого уровня.

Он работает как локальный сервис на порту. Любой MCP-клиент может подключиться, узнать, какие инструменты он предлагает, и запросить спецификацию — при создании игры на Java, TypeScript или на чём угодно ещё.

Для чего это

Две задачи, и вторая важнее, чем кажется на первый взгляд.

1. Держать независимые реализации в согласии. Две сборки одной и той же игры, написанные отдельно, расходятся, как только им понадобится число, которое никто не записал. Обе спрашивают один и тот же сервис, насколько велик танк, — это устраняет догадки.

2. Остановить модель от выдумывания требований. Каждая деталь, которую спецификация не указывает, — это место, где ИИ-помощник по коду тихо выбирает что-то правдоподобное и идёт дальше — останавливаются ли пули у стен? могут ли союзники стрелять друг в друга? что происходит, когда игрок уничтожен в середине раунда? Он редко упоминает, что решил. Каждый из этих вопросов здесь отвечен, так что вопрос становится поиском, а не догадкой, а open_questions называет то, что действительно не решено, так что честный ответ — «спросите человека», а не уверенное изобретение.

Related MCP server: OWASP Pentest Guide Knowledge Base

Запуск

Требуется uv.

uv sync

uv run server.py

Это обслуживает спецификацию по адресу http://127.0.0.1:8082/mcp. Используйте --port, чтобы слушать другой порт, --host для привязки к другому интерфейсу и --stdio для клиентов, которые говорят только на stdio.

Подключение клиента

Любой MCP-клиент, сколько угодно одновременно. Для Claude Code:

claude mcp add --transport http tank-spec http://localhost:8082/mcp

Добавьте --scope project, чтобы записать его в репозиторий, в котором вы работаете, чтобы все, кто работает над этой сборкой, получили одну и ту же спецификацию. Затем /mcp для подтверждения подключения, и клиент может спросить у сервера, какие инструменты существуют и как их вызывать — здесь ничего не нужно настраивать для каждого клиента.

Инструменты

Что этот сервер намеренно не делает

Он понятия не имеет, кто подключён и что они строят, и это намеренно. Он знает о спецификации; клиенты знают о сервере. Ничто не указывает в другую сторону.

Поэтому проверка того, соответствует ли реализация спецификации, — задача клиента. Клиент может прочитать значения из своего собственного кода и сравнить их с тем, что возвращают эти инструменты, — он находится в этом репозитории, а сервер — нет. Серверу, который заглянул бы в рабочую копию для проверки, пришлось бы знать язык, структуру файлов и путь, и его нужно было бы обновлять каждый раз, когда появляется другая реализация.

По той же причине спецификация предоставляется через сервис, а не поставляется как файл:

• Она вне каждой реализации. Сессия, работающая в одном репозитории, не может читать файлы другого, но может вызвать сервис.

• Она запрашивается, а не выгружается. search_spec("friendly fire") возвращает одно правило. Загружать всю спецификацию в контекст модели, чтобы ответить на один вопрос, — именно та трата, которой это избегает.

• Некоторые ответы вычисляются, а не хранятся. Уровни генерируются по формуле нарастания — уровня 6 нет ни в одном файле. resolve_level — единственный правильный способ спросить, и его целочисленное усечение имеет значение: версия с плавающей точкой расходится на четырёх из восьми уровней.

Разрушаемый кирпич и лабиринты для каждого уровня

Всё внутри границы — кирпич, и кирпич можно расстрелять — с обеих сторон, поскольку стороны важны для танков и никогда для стен. Тайл имеет размер 20x20 и выдерживает 40 урона, так что две стандартные пули проделывают дыру, через которую затем проезжают танки. Сама граница неуязвима.

У каждого уровня свой лабиринт, так что номер уровня — единственная ручка сложности: он задаёт, сколько врагов прибывает, как быстро и на какую местность они прибывают. Уровень 1 почти открыт; уровень 8 настолько плотный, что пробить путь обычно быстрее, чем найти его.

get_maze(level) возвращает прямоугольники, развёрнутый список тайлов и картинку:

########################################
#EE................EE................EE#
#EE................EE................EE#
#......................................#
#......BBBBBBBBBBB....BBBBBBBBBBB......#
...
#.............AA...AA...AA.............#
########################################

Используйте развёрнутые тайлы, а не разворачивайте прямоугольники самостоятельно — этот шаг и правило, какой тайл повреждает пуля, когда она находится на границе двух, — это то, где две сборки легче всего начинают проделывать разные дыры из одних и тех же выстрелов.

Добавление лабиринта — это просто добавление прямоугольников в раздел mazes.levels в YAML. Затем тестовый набор проверяет его на соответствие инвариантам, которые делают уровень играбельным: выравнивание по тайлам, нахождение внутри области, отсутствие перекрытий, свободные зоны появления и союзников, а также доступность каждой точки входа пешком без разрушения чего-либо — пробивание — это сокращение, а не требование.

Редактирование спецификации

spec/game-spec.yaml — это весь документ, и он предназначен для редактирования вручную — в этом суть. Сервер перечитывает его при каждом вызове, так что изменение вступает в силу немедленно без перезапуска.

Спецификация была создана на основе рабочей реализации и с этого момента независима от неё. Она ведущая: сначала измените значение здесь, затем заставьте реализации следовать.

Тесты

uv run pytest

tests/test_spec.py фиксирует значения спецификации и проверяет каждый лабиринт на соответствие инвариантам играбельности. tests/test_server.py управляет сервером через MCP-клиент — обнаруживает инструменты, читает их описания, вызывает их. tests/test_http.py запускает реальный процесс на порту и подключается к нему по HTTP, как это делает клиент.

Структура

spec/game-spec.yaml   the specification — the actual source of truth
server.py             MCP server: tool definitions, their descriptions, and the transport
tank_spec/spec.py     loading, searching, level maths, maze expansion
tests/                spec and maze invariants, MCP integration, HTTP transport