@zotabros/hackatank-mcp

MCP server bridging external AI agents (Claude Desktop, Cursor, Claude Code, ...) to a HACKATANK bot dev server.

Tools

| Tool | Purpose | |---|---| | get_spec | fetch canonical bot authoring spec (markdown) + current version + hash. Read this before writing a bot. | | get_spec_version | cheap version check (no body) — compare with spec.version returned by your last submit_bot | | get_spec_changelog | history of spec bumps (separate file). Optional since filter. Use ONLY when migrating an outdated bot — current rules already in get_spec. | | list_bots | list your bots (all versions) | | get_bot_source | fetch source + metadata of one bot version | | validate_bot | dry-run validate source (no DB write); response includes current spec.version | | submit_bot | publish a final version (validate + persist + queue evaluation). Use only after iterating with start_training_match. | | push_bot | DEPRECATED alias of submit_bot. | | list_test_bots | builtin opponents | | start_training_match | sparring match against inline source (no publish). Each side = 'builtin:<name>' or { source, label? }. Rate-limited 30/min/key. | | get_match | match metadata | | get_match_log | full v2 JSONL log (markdown + events) | | list_my_matches | recent match history |

Resources

| URI | Description | |---|---| | hackatank://spec | the bot authoring spec, exposed as an MCP Resource. Clients that auto-attach resources will read it on connect. The server emits notifications/resources/list_changed (polled every 30s) when the spec hash changes — your AI client re-reads automatically. |

Ranked / casual matches are intentionally not exposed — only training (sparring own/builtin) is allowed via API key, to prevent ELO farming.

Setup — one command

npx @zotabros/hackatank-mcp

When you run this in a terminal, the binary auto-detects you're a human (TTY) and launches the setup wizard instead of the server. On a fresh machine it walks you step-by-step through:

1. Node version check (≥ 18).
2. Install deps (skipped when running via npx).
3. Server URL + API key — opens <BASE_URL>/hackatank/keys instructions inline; key is validated (must start with tb_live_).
4. Pick a client target: Claude Desktop, Cursor, Claude Code CLI, Codex CLI, or just print the snippet. Auto-merges into the right config file with a timestamped .bak backup.
5. Smoke-test by calling list_bots.

When an MCP client (Claude Desktop, Cursor, Claude Code, Codex) spawns this binary instead — stdin is piped, env vars are pre-set — it runs as the MCP server, no prompts.

You can also force a specific flow:

npx @zotabros/hackatank-mcp setup       # always launch the wizard
npx @zotabros/hackatank-mcp uninstall   # remove from all known clients

Dev / from repo clone:

cd mcp-server/hackatank-mcp
node index.js                # auto-launches wizard in TTY

When run from a clone, the wizard writes node /abs/path/to/index.js — predictable for development, no network on launch. From an npx install it writes npx @zotabros/hackatank-mcp so each client launch auto-pulls the newest version.

After the wizard finishes, restart your client (Claude Desktop / Cursor / Codex) — Claude Code CLI picks up immediately — and ask "list my hackatank bots".

Production (npx — auto-update):

{
  "mcpServers": {
    "hackatank": {
      "command": "npx",
      "args": ["-y", "@zotabros/hackatank-mcp"],
      "env": {
        "HACKATANK_API_KEY": "tb_live_...",
        "HACKATANK_BASE_URL": "https://your-server.example.com"
      }
    }
  }
}

Dev (local clone):

{
  "mcpServers": {
    "hackatank": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/hackatank-mcp/index.js"],
      "env": {
        "HACKATANK_API_KEY": "tb_live_...",
        "HACKATANK_BASE_URL": "http://localhost:3000"
      }
    }
  }
}

For Claude Code CLI:

claude mcp add hackatank --scope user \
  -e HACKATANK_API_KEY=tb_live_... \
  -e HACKATANK_BASE_URL=https://your-server.example.com \
  -- npx -y @zotabros/hackatank-mcp

Updating

Run the same command again in a terminal:

npx -y @zotabros/hackatank-mcp@latest

The wizard reads ~/.hackatank-mcp/state.json (written on the previous setup), compares installedVersion against the published version, and shows you:

• the CHANGELOG entries between your version and the latest (highlighting any ### Action Required blocks),
• any interactive migrations registered for breaking config-schema changes,
• an offer to re-merge into the same client configs (reusing the existing API key from your client config — rotate on demand).

Re-running on an already-current install drops you into a small reconfigure menu (re-run wizard / show config / uninstall / quit).

For local-clone development, git pull and restart your AI client — the client config still points at node /abs/path/to/index.js. Run node index.js once after the pull if there's a state-bump prompt.

See CHANGELOG.md for the full version history.

Iterate loop example

1. Agent reads spec via get_spec, drafts bot source with @bot-name foo + @bot-version 1.0.0.
2. Agent calls start_training_match({ team1: { source }, team2: 'builtin:random' }) → waits for result + log. Nothing is persisted.
3. Agent parses v2 JSONL log → identifies bugs / weaknesses.
4. Agent edits source, repeats step 2. Optionally swaps team1↔team2 to test both spawn positions.
5. When happy: agent calls submit_bot({ source }) → version published, evaluation queued, ready for ranked play.

team1 spawns at left (x=0), team2 at right (x=20). Map is symmetric but tests should cover both sides.

Auth model

• HACKATANK_API_KEY is a Bearer token tied to your account.
• All requests this MCP makes hit the server with Authorization: Bearer ${HACKATANK_API_KEY}.
• Revoke at /hackatank/keys if compromised — takes effect immediately (next request → 401).

Log format

get_match_log returns the raw response: a markdown header followed by v2 compact JSONL events (one JSON per line). See docs/hackatank-matchlog-v2.md in the parent repo for event kinds.