ai-task-board-mcp 0.1.0__tar.gz

ai_task_board_mcp-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# --- Secrets / credentials (NEVER commit) ---
+.secrets/
+*.secret
+*.secrets.md
+*credentials*.local.*
+.env
+.env.*
+!.env.example
+
+# --- Node ---
+node_modules/
+dist/
+build/
+*.log
+npm-debug.log*
+.pnpm-debug.log*
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.venv/
+venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# --- DB / local data ---
+*.sqlite
+*.sqlite3
+*.db
+data/
+
+# --- Build artifacts ---
+deploy/dist/
+
+# --- Editor / OS ---
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# nitro build output
+.output/

ai_task_board_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+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
+```

ai_task_board_mcp-0.1.0/README.md

@@ -0,0 +1,85 @@
+# 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
+```

ai_task_board_mcp-0.1.0/atb_mcp/__init__.py

@@ -0,0 +1 @@
+"""AI Task Board — MCP server package."""

ai_task_board_mcp-0.1.0/atb_mcp/client.py

@@ -0,0 +1,77 @@
+"""Thin HTTP client for the Board REST API."""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .config import Config
+
+
+class BoardAPIError(Exception):
+    """Raised for non-2xx responses; carries status and parsed body."""
+
+    def __init__(self, status: int, body: Any):
+        self.status = status
+        self.body = body
+        super().__init__(f"Board API error {status}: {body}")
+
+
+class BoardClient:
+    def __init__(self, config: Config):
+        self._config = config
+        self._client = httpx.Client(
+            base_url=f"{config.base_url}/api/v1",
+            headers={"Authorization": f"Bearer {config.api_key}"},
+            timeout=config.timeout,
+        )
+
+    def _request(self, method: str, path: str, **kwargs) -> Any:
+        if not self._config.api_key:
+            raise BoardAPIError(
+                401,
+                {"error": "no_api_key", "message": "Set ATB_API_KEY for the MCP server."},
+            )
+        resp = self._client.request(method, path, **kwargs)
+        try:
+            body = resp.json() if resp.content else None
+        except ValueError:
+            body = resp.text
+        if resp.status_code >= 400:
+            raise BoardAPIError(resp.status_code, body)
+        return body
+
+    # --- read ---
+    def list_projects(self) -> Any:
+        return self._request("GET", "/projects")
+
+    def get_board(self, project_id: str) -> Any:
+        return self._request("GET", f"/projects/{project_id}/board")
+
+    def list_tasks(self, project_id: str, params: dict) -> Any:
+        clean = {k: v for k, v in params.items() if v is not None}
+        return self._request("GET", f"/projects/{project_id}/tasks", params=clean)
+
+    def get_task(self, task_id: str) -> Any:
+        return self._request("GET", f"/tasks/{task_id}")
+
+    # --- write ---
+    def create_task(self, project_id: str, body: dict) -> Any:
+        clean = {k: v for k, v in body.items() if v is not None}
+        return self._request("POST", f"/projects/{project_id}/tasks", json=clean)
+
+    def update_task(self, task_id: str, body: dict) -> Any:
+        clean = {k: v for k, v in body.items() if v is not None}
+        return self._request("PATCH", f"/tasks/{task_id}", json=clean)
+
+    def claim_task(self, task_id: str, lease_seconds: int | None) -> Any:
+        body = {} if lease_seconds is None else {"leaseSeconds": lease_seconds}
+        return self._request("POST", f"/tasks/{task_id}/claim", json=body)
+
+    # --- report ---
+    def add_report(self, task_id: str, body: dict) -> Any:
+        clean = {k: v for k, v in body.items() if v is not None}
+        return self._request("POST", f"/tasks/{task_id}/reports", json=clean)
+
+    def close(self) -> None:
+        self._client.close()

ai_task_board_mcp-0.1.0/atb_mcp/config.py

@@ -0,0 +1,27 @@
+"""MCP server configuration (from environment)."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Config:
+    base_url: str
+    api_key: str
+    default_project_id: str | None
+    timeout: float
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        base = os.environ.get("ATB_API_BASE_URL", "http://127.0.0.1:8077").rstrip("/")
+        key = os.environ.get("ATB_API_KEY", "")
+        if not key:
+            # Not fatal at import; tools return a clear error if it's missing.
+            pass
+        return cls(
+            base_url=base,
+            api_key=key,
+            default_project_id=os.environ.get("ATB_PROJECT_ID") or None,
+            timeout=float(os.environ.get("ATB_TIMEOUT", "15")),
+        )

ai_task_board_mcp-0.1.0/atb_mcp/server.py

@@ -0,0 +1,210 @@
+"""MCP server exposing the AI Task Board to Claude agents.
+
+Eight tools mapped 1:1 onto the Board REST API, grouped by scope
+(read / write / report). See docs/api/mcp-tools.md for the contract.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from .client import BoardAPIError, BoardClient
+from .config import Config
+
+config = Config.from_env()
+client = BoardClient(config)
+
+mcp = FastMCP("ai-task-board")
+
+
+def _project(project_id: str | None) -> str:
+    pid = project_id or config.default_project_id
+    if not pid:
+        raise ValueError(
+            "No project_id given and ATB_PROJECT_ID is not set. "
+            "Call list_projects first, then pass project_id."
+        )
+    return pid
+
+
+# ----------------------------- read scope -----------------------------
+@mcp.tool()
+def list_projects() -> Any:
+    """List the projects this API key can see. Start here to discover project ids."""
+    return client.list_projects()
+
+
+@mcp.tool()
+def get_board(project_id: str | None = None) -> Any:
+    """Get a full board snapshot: columns (by status) with their tasks, plus milestones."""
+    return client.get_board(_project(project_id))
+
+
+@mcp.tool()
+def list_tasks(
+    project_id: str | None = None,
+    status: str | None = None,
+    priority: str | None = None,
+    milestone_id: str | None = None,
+    assignee_id: str | None = None,
+    claimable: bool | None = None,
+) -> Any:
+    """List/filter tasks. Use claimable=true to get only unclaimed, unblocked work.
+
+    status: backlog|todo|in_progress|review|done|blocked. priority: low|medium|high|urgent.
+    """
+    return client.list_tasks(
+        _project(project_id),
+        {
+            "status": status,
+            "priority": priority,
+            "milestoneId": milestone_id,
+            "assigneeId": assignee_id,
+            "claimable": claimable,
+        },
+    )
+
+
+@mcp.tool()
+def get_task(task_id: str) -> Any:
+    """Get one task in full: description, acceptanceCriteria, dependencies, claim state, version."""
+    return client.get_task(task_id)
+
+
+# ----------------------------- write scope ----------------------------
+@mcp.tool()
+def claim_task(task_id: str, lease_seconds: int | None = None) -> Any:
+    """Claim/lease a task before working it, so other agents skip it.
+
+    If another actor already holds it, this does NOT take the task — it returns who
+    holds it and for how long, so you can tell the user instead of stealing it.
+    """
+    try:
+        task = client.claim_task(task_id, lease_seconds)
+        return {"claimed": True, "task": task}
+    except BoardAPIError as e:
+        if e.status == 409 and isinstance(e.body, dict):
+            b = e.body
+            holder = (b.get("claimedBy") or {}).get("displayName", "another actor")
+            return {
+                "claimed": False,
+                "reason": "already_claimed",
+                "message": b.get("message")
+                or f"Task is already being worked on by {holder}.",
+                "claimedBy": b.get("claimedBy"),
+                "heldForSeconds": b.get("heldForSeconds"),
+                "claimExpiresAt": b.get("claimExpiresAt"),
+                "advice": "Do not take this task. Tell the user who holds it and pick another.",
+            }
+        raise
+
+
+@mcp.tool()
+def create_task(
+    title: str,
+    project_id: str | None = None,
+    description: str | None = None,
+    status: str | None = None,
+    priority: str | None = None,
+    acceptance_criteria: str | None = None,
+    assignee_id: str | None = None,
+    milestone_id: str | None = None,
+    labels: list[str] | None = None,
+    blocked_by: list[str] | None = None,
+) -> Any:
+    """Create a task (defaults to the backlog). Search existing tasks first — do not duplicate."""
+    return client.create_task(
+        _project(project_id),
+        {
+            "title": title,
+            "description": description,
+            "status": status,
+            "priority": priority,
+            "acceptanceCriteria": acceptance_criteria,
+            "assigneeId": assignee_id,
+            "milestoneId": milestone_id,
+            "labels": labels,
+            "blockedBy": blocked_by,
+        },
+    )
+
+
+@mcp.tool()
+def update_task(
+    task_id: str,
+    expected_version: int,
+    title: str | None = None,
+    description: str | None = None,
+    status: str | None = None,
+    priority: str | None = None,
+    acceptance_criteria: str | None = None,
+    assignee_id: str | None = None,
+    milestone_id: str | None = None,
+    labels: list[str] | None = None,
+    blocked_by: list[str] | None = None,
+) -> Any:
+    """Update a task and/or move its status. Requires expected_version (optimistic lock).
+
+    On a version conflict the update is rejected — re-read with get_task and retry
+    with the new version, so you never overwrite a human's concurrent edit.
+    """
+    try:
+        return client.update_task(
+            task_id,
+            {
+                "expectedVersion": expected_version,
+                "title": title,
+                "description": description,
+                "status": status,
+                "priority": priority,
+                "acceptanceCriteria": acceptance_criteria,
+                "assigneeId": assignee_id,
+                "milestoneId": milestone_id,
+                "labels": labels,
+                "blockedBy": blocked_by,
+            },
+        )
+    except BoardAPIError as e:
+        if e.status == 409 and isinstance(e.body, dict):
+            return {
+                "updated": False,
+                "reason": "version_conflict",
+                "message": e.body.get("message"),
+                "currentVersion": e.body.get("currentVersion"),
+                "advice": "Re-read the task with get_task and retry with the current version.",
+            }
+        raise
+
+
+# ----------------------------- report scope ---------------------------
+@mcp.tool()
+def add_report(
+    task_id: str,
+    type: str,
+    body: str,
+    agent_session_id: str | None = None,
+    artifacts: list[dict] | None = None,
+) -> Any:
+    """Append a report to a task. type: progress|done|blocker.
+
+    For 'done' reports, link artifacts: [{"kind":"pr|commit|file|url","ref":"..."}].
+    Write one report per meaningful step — do not spam the timeline.
+    """
+    return client.add_report(
+        task_id,
+        {
+            "type": type,
+            "body": body,
+            "agentSessionId": agent_session_id,
+            "artifacts": artifacts,
+        },
+    )
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

ai_task_board_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ai-task-board-mcp"
+version = "0.1.0"
+description = "MCP server exposing the AI Task Board to any MCP-capable AI agent"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Danylo Lahodniuk" }]
+keywords = ["mcp", "ai-task-board", "kanban", "agents", "claude", "llm"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.2",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://board.filbert.games"
+Documentation = "https://board.filbert.games/docs"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.scripts]
+ai-task-board-mcp = "atb_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["atb_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["atb_mcp", "README.md", "scripts"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

ai_task_board_mcp-0.1.0/scripts/verify_mcp.py

@@ -0,0 +1,97 @@
+"""End-to-end check: drive the MCP tools against a running Board backend.
+
+Usage: ATB_API_BASE_URL + ATB_API_KEY must point at a seeded backend.
+Exercises the read/write/report tools and the two conflict paths.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+
+import httpx
+
+BASE = os.environ.setdefault("ATB_API_BASE_URL", "http://127.0.0.1:8077")
+os.environ.setdefault("ATB_API_KEY", "datb_danylo_full")  # acts as Claude (Danylo)
+
+# Import AFTER env is set (config is read at import time).
+from atb_mcp import server  # noqa: E402
+
+
+def ok(label: str, cond: bool, extra: str = "") -> None:
+    mark = "✓" if cond else "✗"
+    print(f"  {mark} {label} {extra}")
+    if not cond:
+        raise SystemExit(f"FAILED: {label}")
+
+
+def main() -> None:
+    print("MCP end-to-end verification")
+
+    # tool registration
+    tools = asyncio.run(server.mcp.list_tools())
+    names = {t.name for t in tools}
+    expected = {
+        "list_projects", "get_board", "list_tasks", "get_task",
+        "claim_task", "create_task", "update_task", "add_report",
+    }
+    ok("8 tools registered", expected <= names, extra=str(sorted(names)))
+
+    # read
+    projects = server.list_projects()
+    ok("list_projects", len(projects) >= 1)
+    pid = projects[0]["id"]
+
+    board = server.get_board(pid)
+    ok("get_board", "columns" in board)
+
+    claimable = server.list_tasks(project_id=pid, claimable=True)
+    ok("list_tasks(claimable)", isinstance(claimable, list) and len(claimable) >= 1)
+
+    # write: create
+    created = server.create_task(
+        title="MCP smoke task", project_id=pid, priority="high",
+        acceptance_criteria="verified by script",
+    )
+    ok("create_task", created["version"] == 1 and created["createdBy"]["id"] == "claude/danylo")
+    tid = created["id"]
+
+    # write: claim success
+    claim = server.claim_task(tid)
+    ok("claim_task (success)", claim["claimed"] is True)
+
+    # write: update with wrong version -> conflict dict
+    bad = server.update_task(tid, expected_version=999, status="review")
+    ok("update_task version conflict", bad.get("reason") == "version_conflict")
+
+    # write: update correct version
+    good = server.update_task(tid, expected_version=created["version"], status="in_progress")
+    ok("update_task success", good["version"] == created["version"] + 1)
+
+    # report
+    rep = server.add_report(
+        tid, type="progress", body="working on it",
+        artifacts=[{"kind": "url", "ref": "https://example.com"}],
+    )
+    ok("add_report", rep["type"] == "progress" and rep["author"]["id"] == "claude/danylo")
+
+    # claim conflict: have Bob claim a fresh task, then MCP (Danylo) must be told who/how long
+    with httpx.Client(base_url=f"{BASE}/api/v1",
+                      headers={"Authorization": "Bearer datb_bob_full"}) as bob:
+        t = bob.post(f"/projects/{pid}/tasks", json={"title": "Contended (MCP)"}).json()
+        c = bob.post(f"/tasks/{t['id']}/claim")
+        assert c.status_code == 200, c.text
+    conflict = server.claim_task(t["id"])
+    ok(
+        "claim_task conflict reports holder + duration",
+        conflict["claimed"] is False
+        and conflict["claimedBy"]["displayName"] == "Claude (Bob)"
+        and conflict["heldForSeconds"] >= 0,
+        extra=f'-> "{conflict["message"]}"',
+    )
+
+    print("\nALL MCP CHECKS PASSED")
+
+
+if __name__ == "__main__":
+    sys.exit(main())