Tank Fight MCP — 게임 스펙을 서비스로 제공

Tank Fight의 표준 사양(canonical specification) 을 제공하는 MCP 서버: 필드 및 창 크기, 탱크와 총알 스탯, 생성 규칙, 점수, 조작, 메뉴 동작, AI 전략, 난이도 상승 곡선, 레벨별 파괴 가능한 미로.

로컬 서비스로 포트에서 실행된다. 모든 MCP 클라이언트는 연결하여 제공되는 도구를 확인하고 스펙을 조회할 수 있다 — Java로 게임을 만들든, TypeScript로 만들든, 다른 무엇으로 만들든 상관없다.

용도

두 가지 역할이 있으며, 두 번째는 처음 보기보다 더 중요하다.

1. 독립적인 구현들 간의 일치 유지. 같은 게임을 별도로 작성한 두 빌드는, 아무도 기록하지 않은 숫자가 필요해지는 순간 어긋나기 시작한다. 둘 다 같은 서비스에 탱크 크기가 얼마인지 묻는다면 추측이 사라진다.

2. 모델이 요구사항을 지어내는 것을 막는다. 스펙이 빠뜨린 모든 세부 사항은 AI 코딩 어시스턴트가 조용히 그럴듯한 값을 골라 넘어가는 지점이다 — 총알은 벽에서 멈추는가? 아군끼리 쏠 수 있는가? 플레이어가 라운드 중간에 파괴되면 어떻게 되는가? 모델은 자신이 결정했다는 사실을 거의 언급하지 않는다. 이러한 각 질문은 여기서 답이 제공되므로, 추측 대신 조회가 되며, 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이 물어보는 유일한 올바른 방법이며, 그 정수 절삭(integer truncation)은 중요한 역할을 한다: 부동소수점 버전은 8개 레벨 중 4개에서 불일치한다.

파괴 가능한 벽돌과 레벨별 미로

경계선 안의 모든 것은 벽돌이며, 벽돌은 쏘아 없앨 수 있다 — 양쪽 모두 가능하다. 진영은 탱크에게는 중요하지만 벽에는 결코 중요하지 않기 때문이다. 타일은 20x20이고 40의 피해를 받으므로, 표준 총알 두 발이 구멍을 내면 탱크가 그곳을 통과한다. 경계선 자체는 면역이다.

각 레벨에는 고유한 미로가 있으므로, 레벨 번호가 유일한 난이도 조절 장치다: 적이 몇 명 도착하는지, 얼마나 빠르게 도착하는지, 그리고 도착하는 지형까지 설정한다. 레벨 1은 거의 열려 있고, 레벨 8은 길을 찾는 것보다 길을 쏘아 뚫는 것이 보통 더 빠를 정도로 빽빽하다.

get_maze(level)은 사각형, 확장된 타일 목록, 그림을 반환한다:

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

사각형을 직접 확장하지 말고 확장된 타일을 사용하라 — 그 단계와, 총알이 두 타일에 걸쳐 있을 때 어느 타일에 피해를 입히는지에 대한 규칙이, 두 빌드가 같은 사격에서 서로 다른 구멍을 파게 되기 가장 쉬운 지점이다.

미로를 추가하는 것은 YAML의 mazes.levels 아래에 사각형을 추가하는 것뿐이다. 그러면 테스트 스위트가 레벨을 플레이 가능하게 만드는 불변 조건을 검증한다: 타일에 정렬되고, 영역 안에 있으며, 겹치지 않고, 생성 지점과 아군 상자가 비어 있으며, 모든 진입점이 아무것도 파괴하지 않고 도보로 도달 가능해야 한다 — 파내는 것은 지름길이지 요구사항이 아니다.

스펙 편집

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