ai-task-board-mcp 0.1.0

MCP server exposing the AI Task Board to any MCP-capable AI agent

AI Task Board — MCP Server

Exposes the board to any MCP-capable AI agent (Claude Code/Desktop, Cursor, Cline, Windsurf, or a custom client — MCP is model-agnostic) as 8 typed tools mapped 1:1 onto the Board REST API. It is a thin client: it holds one scoped API key (one actor) and forwards calls. See the tool contract in docs/api/mcp-tools.md and per-client wiring + behavioral rules in docs/INTEGRATION.md.

Tools

list_projects · get_board · list_tasks · get_task (read) · claim_task · create_task · update_task (write) · add_report (report)

Conflict handling baked in:

• claim_task on a contested task returns who holds it and for how long (never steals it).
• update_task on a stale expected_version returns a version_conflict with advice to re-read and retry (never overwrites a human's edit).

Install & run

cd mcp-server
uv venv --python 3.14 .venv
uv pip install --python .venv -e ".[dev]"

export ATB_API_BASE_URL="http://127.0.0.1:8077"   # the backend
export ATB_API_KEY="datb_danylo_full"             # this agent's scoped key (= an actor)
export ATB_PROJECT_ID="<project-id>"              # optional default project
.venv/bin/python -m atb_mcp.server                # speaks MCP over stdio

Connect to an agent

Any MCP client uses the same command + args + env (see docs/INTEGRATION.md for Claude Desktop, Cursor, Windsurf, Cline, and custom clients). Claude Code example:

claude mcp add ai-task-board \
  --env ATB_API_BASE_URL=http://127.0.0.1:8077 \
  --env ATB_API_KEY=datb_danylo_full \
  --env ATB_PROJECT_ID=<project-id> \
  -- /media/work/GitHub/ai-task-board/mcp-server/.venv/bin/python -m atb_mcp.server

Or add to a .mcp.json / claude_desktop_config.json:

{
  "mcpServers": {
    "ai-task-board": {
      "command": "/media/work/GitHub/ai-task-board/mcp-server/.venv/bin/python",
      "args": ["-m", "atb_mcp.server"],
      "env": {
        "ATB_API_BASE_URL": "http://127.0.0.1:8077",
        "ATB_API_KEY": "datb_danylo_full",
        "ATB_PROJECT_ID": "<project-id>"
      }
    }
  }
}

Pair it with the behavioral skill in ../skill/ so the agent knows how to run the board (claim before working, one report per step, respect priorities and other actors' claims).

Config (env)

Var	Default	Meaning
ATB_API_BASE_URL	http://127.0.0.1:8077	backend base URL
ATB_API_KEY	—	scoped key = the agent's actor identity
ATB_PROJECT_ID	—	default project when a tool omits project_id
ATB_TIMEOUT	15	HTTP timeout (s)

Tests

.venv/bin/python -m pytest

Spins up the real backend (via backend/.venv) as a subprocess and exercises all 8 tools end-to-end, including the claim-conflict and version-conflict paths.

Verify end-to-end (manual script)

With a seeded backend already running:

ATB_API_BASE_URL=http://127.0.0.1:8077 PYTHONPATH=. \
  .venv/bin/python scripts/verify_mcp.py