Metadata-Version: 2.4
Name: ai-task-board-mcp
Version: 0.1.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
```bash
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`](../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=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`:
```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/`](../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
```
