一个 MCP 服务器，提供 Tank Fight 的权威规范：场地和窗口大小、坦克和子弹属性、生成规则、计分、控制、菜单行为、AI 策略、难度曲线，以及每个关卡的可破坏迷宫。
它作为本地服务运行在一个端口上。任何 MCP 客户端都可以连接，询问它提供哪些工具，并查询规范 — 无论你是用 Java、TypeScript 还是其他任何语言构建游戏。
两项工作，第二项比乍看起来更重要。
1. 让独立的实现保持一致。 同一款游戏的两个独立构建，一旦需要一个没人记录下来的数字，就会开始分叉。让两者都向同一个服务询问坦克有多大，就消除了猜测。
2. 阻止模型凭空发明需求。 规范中遗漏的每个细节，都是 AI 编码助手悄悄挑一个看似合理的选项然后继续的地方 — 子弹会停在墙边吗？友军能互相射击吗？玩家在回合中途被摧毁会发生什么？ 它很少提及自己做了决定。这些问题在这里都有答案，于是问题变成了查表而不是猜测，而 open_questions 会指出真正尚未决定的内容，因此诚实的答案是“问人类”，而不是自信的编造。
Related MCP server: 17-0 MCP Server
需要 uv。
uv syncuv 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 确认连接，客户端就可以询问服务器存在哪些工具以及如何调用它们 — 这里不需要为每个客户端进行任何配置。
工具 | 回答 |
| 规范里有什么，每项一行 — 从这里开始 |
| 一个章节，或一个点分路径，如 |
| “X 会发生吗？” — 找到决定它的规则 |
| 第 N 关意味着什么：敌人总数、最大同时出现数、生成间隔、哪个迷宫 |
| 该关卡的砖块布局，展开为瓦片，并附 ASCII 图片 |
| 规范刻意尚未决定的内容 |
它不知道谁连接了它，也不知道他们在构建什么，这是有意为之。它了解规范；客户端了解服务器。没有任何反向的指向。
因此，检查实现是否仍然符合规范是客户端的工作。客户端可以从自己的代码中读取这些值，并将它们与这些工具返回的内容进行比较 — 客户端就在那个仓库中，而服务器不在。一个服务器如果要深入检出目录去检查实现，就必须知道语言、文件布局和路径，并且每次出现另一个实现时都需要更新。
同样的理由也解释了为什么规范是以服务形式提供，而不是作为文件分发：
它在每个实现之外。 在一个仓库中工作的会话无法读取另一个仓库的文件，但它可以调用服务。
它是被查询的，而不是被倾倒的。 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.............#
########################################使用展开后的瓦片，而不是自己展开矩形 — 这一步，以及子弹横跨两个瓦片时伤害哪个瓦片的规则，正是两个构建最容易从同样的射击中挖出不同洞的地方。
添加一个迷宫只需在 YAML 的 mazes.levels 下添加矩形。测试套件随后会使其满足让关卡可玩的各项不变量：与瓦片对齐、在区域内、不重叠、出生点和友军框畅通，并且每个入口点都可以在不摧毁任何东西的情况下步行到达 — 挖掘是捷径，绝不是必需。
spec/game-spec.yaml 就是全部内容，而且它本意就是手工编辑 — 这正是重点。服务器在每次调用时都会重新读取它，因此更改会立即生效，无需重启任何东西。
该规范最初来自一个可工作的实现，并从此独立于该实现。它起引领作用：先在这里更改一个值，然后让各个实现跟随。
uv run pytesttests/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 transportGet a level's brick layout: the rectangles, and those rectangles expanded into the exact 20x20 tiles the level starts with.
Every level has its own maze, and all of the brick in it is destructible — bullets from either side chew through it, so the terrain changes as a round is played. Border walls are separate and indestructible.
Use the expanded tile list rather than expanding the rectangles yourself: that expansion is the step two implementations most easily get subtly different, and a one-tile disagreement changes which shots open a route.
Args: level: The level number. Out-of-range values are clamped. ascii_map: Include a picture of the layout — '#' border, 'B' brick, 'E' enemy entry point, 'A' ally start. Useful for checking a build renders the level you think it does; set false to save context.
| Name | Required | Description | Default |
|---|---|---|---|
| level | Yes | ||
| ascii_map | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that all bricks are destructible and terrain changes during play, and that border walls are indestructible. It also notes that out-of-range level values are clamped, which is a behavioral trait. However, it doesn't mention the return format or any potential side effects, but given the tool is a read operation, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, a rationale for using the expanded tiles, and a concise Args section. Every sentence adds value, and it's appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (not shown but mentioned), the description doesn't need to explain return values. It covers the key aspects: what the tool returns, why to use it, parameter semantics, and behavioral notes. The description is complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the 'level' parameter (level number, out-of-range clamped) and 'ascii_map' (include a picture, useful for checking build, set false to save context). This adds meaning beyond the schema's basic types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to get a level's brick layout as rectangles and expanded 20x20 tiles. It specifies the resource (level maze) and the action (get), and distinguishes it from siblings by focusing on the brick layout, while siblings like list_sections and get_spec handle other aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using the expanded tile list rather than expanding rectangles manually, explaining the risk of subtle differences. It also provides guidance on when to set ascii_map to false to save context, and mentions that border walls are separate and indestructible, which helps the agent understand the tool's output.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return one section of the Tank Fight specification as JSON.
Use this to get the authoritative numbers and rules before implementing a feature — screen size, tank and bullet stats, wall layout, controls, AI parameters, and so on. Do not infer these values from an existing implementation and do not invent them; this file is what the implementations are supposed to agree with.
Args: section: A section name from list_sections, or a dotted path to go straight to a value, e.g. "entities.bullet" or "ai.enemy.turn_chance_per_tick".
| Name | Required | Description | Default |
|---|---|---|---|
| section | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It adds crucial context: the spec is authoritative, and it explicitly warns against inferring values from existing implementations. However, it does not mention error handling or behavior for invalid section names, so it's not fully transparent on edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with a clear one-sentence summary followed by usage guidance and a well-formatted Args section. Every sentence adds value, and the formatting makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with an output schema, the description is complete: it explains the purpose, parameter format, and authoritative nature of the data. It appropriately references list_sections for valid section names and provides examples of dotted paths. No additional return-value details are needed given the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only declares 'section' as a string with no description, so the description provides all parameter semantics. It explains that the value can be a section name from list_sections or a dotted path, with concrete examples like 'entities.bullet'. This is essential information not available from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Return one section of the Tank Fight specification as JSON,' which is a specific verb+resource statement. It also explains the use case ('before implementing a feature') and distinguishes itself from sibling tools by focusing on retrieving a named section of the specification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states when to use the tool ('before implementing a feature') and warns against inferring or inventing values, which provides strong context. However, it does not explicitly name alternative tools or exclusions beyond referencing list_sections for section names, so it stops short of the explicit alternative guidance found in a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the sections of the Tank Fight specification, with a one-line summary of each, so you can fetch only the part you need.
Start here when you don't yet know where a rule lives. Fetching the whole spec is rarely necessary and wastes context.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It clearly discloses that the tool returns a section list with summaries rather than full content, and frames itself as a navigation helper. For a simple read-only listing tool, this is sufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and every phrase earns its place. It avoids filler while adding practical usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter listing tool with an output schema, the description is complete: it says what the tool returns, why to use it, and when to start with it. It sufficiently covers the low-complexity context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is effectively 100%, so no parameter explanation is needed. The baseline of 4 applies because there is no param information to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('List the sections'), the resource ('Tank Fight specification'), and the output form ('with a one-line summary of each'). It also differentiates from siblings by positioning this as the starting point for locating rules before fetching a specific part.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit guidance: 'Start here when you don't yet know where a rule lives' and warns that 'Fetching the whole spec is rarely necessary and wastes context.' It lacks an explicit contrast with search_spec, which is a sibling that may be a better alternative when users know search terms.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the design decisions the specification deliberately has NOT made.
Check this before inventing an answer to something the spec is silent on. If your question is here, the honest answer is "not decided yet" — say so and ask, rather than picking something and moving on. Anything on this list is a place where two implementations will otherwise diverge.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context: the tool returns a list of open items and hints that these are places where implementations diverge. However, no annotations are provided, so the description carries the burden. It does not state whether the list is static or generated, or any caching/rate limits, but for this kind of read-only tool, it is adequate. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short paragraphs, each earning its place: purpose, timing, action on hit, consequence. No fluff, front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter tool, the description fully explains when and how to use it and what it returns. It doesn't describe output format, but an output schema exists, so that's not needed. It is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so the description has little to add. The description explains what the output represents (open design decisions), adding semantic meaning beyond the empty schema. Baseline for 0 params is 4, and it meets that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists design decisions left open by the specification. It uses specific verb 'List' and resource 'design decisions', and distinguishes it from sibling tools like list_sections or get_spec by focusing on unresolved questions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: check this tool before inventing an answer, and what to do if a question is here (say 'not decided yet' and ask). It implies when not to use (when question is not listed, it may be intentionally handled elsewhere).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve what a level number actually means: how many enemy tanks the round fields in total, how many may be alive at once, and how often they arrive.
Levels are GENERATED from a ramp formula, not stored anywhere, so this cannot be answered by reading a file — call this tool instead of computing it yourself, because the formula truncates with integer division and a floating-point version disagrees at several levels.
The result also names the level's maze; call get_maze for its actual layout.
Args: level: The level number. Out-of-range values are clamped to the supported range rather than rejected.
| Name | Required | Description | Default |
|---|---|---|---|
| level | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals important traits: integer division with truncation, potential disagreement with floating-point calculations, and clamping behavior for out-of-range values. It also states what the result includes without exposing unnecessary details. This goes beyond a generic description and provides genuinely useful edge-case information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise, with a clear lead sentence, a paragraph explaining rationale, and a compact Args section. Every sentence earns its place—no filler or redundancy. The structure (purpose, why, related tool, parameter details) is logical and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter) and the presence of an output schema, the description covers all necessary aspects: what it computes, why it's needed, how parameters behave, and what the output references (maze). It does not omit critical context and does not need to detail return types because an output schema is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no description for the 'level' parameter (0% coverage), so the description must compensate. The Args section does this effectively by explaining the parameter's meaning and its clamping behavior, which is not present in the schema. This fully addresses potential confusion and guides correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Resolve') and a detailed resource ('what a level number actually means: how many enemy tanks the round fields in total, how many may be alive at once, and how often they arrive'). It distinguishes itself from siblings by mentioning get_maze for maze layout and contrasting with reading a file. This is more than just a restatement of the name—it provides concrete capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool instead of alternatives: 'Levels are GENERATED from a ramp formula, not stored anywhere, so this cannot be answered by reading a file — call this tool instead of computing it yourself'. It also directs to a sibling ('call get_maze for its actual layout'). This gives clear decision guidance, exceeding basic when-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the specification for the rule or value that answers a question.
Use this whenever you are about to assume how the game behaves — "do bullets stop at walls?", "can allies shoot each other?", "how fast is a bullet?", "what happens when a player is destroyed?". Searching costs far less context than loading whole sections, and the answer is authoritative.
If the search comes back empty, the spec may genuinely not cover it: check open_questions() before deciding anything yourself.
Args: query: Plain words describing what you need, e.g. "friendly fire" or "spawn interval" or "health bar colour".
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It explains the tool is a read-only search ('costs far less context than loading whole sections') and the behavior on empty results (spec may not cover it, check open_questions). This adds transparency about the search's scope and fallback, though it doesn't detail return format or limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise, using a short intro, a usage guideline paragraph, and a parameter explanation. Every sentence adds value, and it is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter) and the description covers purpose, usage, fallback behavior, and parameter semantics. The output schema exists, so return values don't need explanation. It is complete for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the 'query' parameter with examples: 'Plain words describing what you need, e.g. "friendly fire" or "spawn interval" or "health bar colour".' This adds meaningful guidance beyond the schema's bare string type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search the specification for the rule or value that answers a question.' It uses a specific verb ('search') and resource ('the specification'), and provides concrete examples of questions it answers, distinguishing it from sibling tools like list_sections or get_spec.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly guides when to use this tool: 'Use this whenever you are about to assume how the game behaves'. It contrasts with alternatives by noting that searching costs less context than loading whole sections. It also provides a clear fallback: if the search comes back empty, check open_questions() before deciding anything yourself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_mazeget_speclist_sectionsopen_questionsresolve_levelsearch_specScored across 6 tools
Each tool has a distinct purpose: listing sections, getting a section, searching the spec, resolving level semantics, retrieving maze layouts, and listing open questions. No overlaps or ambiguity.
All tool names follow a consistent verb_noun pattern (list_, get_, search_, resolve_, open_), making the API predictable and easy to navigate.
Six tools is well-scoped for a specification server, covering all necessary access patterns without unnecessary redundancy or bloat.
The tool set fully covers the domain: discovering, retrieving, searching, interpreting, and visualizing spec details, plus handling open questions. No obvious gaps.
Read-only MCP server for the OPERANT AI operating-agent calibration benchmark.
Read-only MCP server for the WebAssembly spec: instructions, types, sections, search, proposals.
Public, read-only MCP server for FarmNeural company facts, packages, and capabilities.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.