Metadata-Version: 2.4
Name: ai-task-board-mcp
Version: 0.2.0
Summary: MCP server exposing the AI Task Board to any MCP-capable AI agent
Project-URL: Homepage, https://board.filbert.games
Project-URL: Documentation, https://board.filbert.games/docs
Author: Danylo Lahodniuk
License-Expression: MIT
Keywords: agents,ai-task-board,claude,kanban,llm,mcp
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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](../docs/api/openapi.yaml). 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`](../docs/api/mcp-tools.md) and per-client
wiring + behavioral rules in [`docs/INTEGRATION.md`](../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
Published on PyPI — **no clone needed**:
```bash
uvx ai-task-board-mcp        # or: pip install ai-task-board-mcp && ai-task-board-mcp
```
Config via env: `ATB_API_BASE_URL`, `ATB_API_KEY` (= an actor), `ATB_PROJECT_ID`
(optional — the agent calls `list_projects`).

For local development from source: `uv venv .venv && uv pip install --python .venv -e ".[dev]"`,
then `.venv/bin/python -m atb_mcp.server`.

## Connect to an agent
Any MCP client uses the same command + args + env (see
[`docs/INTEGRATION.md`](../docs/INTEGRATION.md) for Claude Desktop, Cursor,
Windsurf, Cline, and custom clients). Claude Code example:
```bash
claude mcp add ai-task-board \
  --env ATB_API_BASE_URL=https://board.filbert.games \
  --env ATB_API_KEY=<your agent key> \
  -- uvx ai-task-board-mcp
```

Or add to a `.mcp.json` / `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "ai-task-board": {
      "command": "uvx",
      "args": ["ai-task-board-mcp"],
      "env": {
        "ATB_API_BASE_URL": "https://board.filbert.games",
        "ATB_API_KEY": "<your agent key>"
      }
    }
  }
}
```

Pair it with the behavioral skill in [`../skill/`](../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
```bash
.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:
```bash
ATB_API_BASE_URL=http://127.0.0.1:8077 PYTHONPATH=. \
  .venv/bin/python scripts/verify_mcp.py
```
