tackboard-mcp 0.8.0__tar.gz

tackboard_mcp-0.8.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.3
+Name: tackboard-mcp
+Version: 0.8.0
+Summary: Optional MCP adapter for the tackboard CLI — exposes board tools to MCP clients
+License: MIT
+Requires-Dist: tackboard>=0.8.0,<0.9
+Requires-Dist: mcp>=2.3,<3
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# tackboard-mcp — an optional MCP adapter
+
+A small [Model Context Protocol](https://modelcontextprotocol.io) server that
+exposes one `tack` project board to an MCP client (an IDE assistant, a chat
+client, another agent runtime).
+
+**This package is optional and outside the core.** The `tackboard` package —
+the CLI, the database, the JSON contracts — stays dependency-free and does not
+import anything here. If you only want the board, install `tackboard`; if your
+agent runtime speaks MCP and you would rather it called tools than assembled
+shell commands, install this beside it.
+
+## What it is, precisely
+
+The adapter contains **no domain logic**. Every tool shells out to the `tack`
+CLI with `--json` and returns that document unchanged, so a client can never
+see a claim, a transition or a validation rule that differs from the board. A
+non-zero exit is raised as an error whose payload is the CLI's own error
+document (`{"schema_version":1,"error":{...}}`).
+
+What it adds is discovery and a typed surface: seven named tools with described
+arguments, instead of a CLI string to compose.
+
+## Install
+
+```bash
+uv tool install tackboard-mcp      # or: pip install tackboard-mcp
+```
+
+This installs the adapter and pulls `tackboard` with it, so the `tack` CLI
+comes along in the same environment. The MCP framework and the core are this
+package's dependencies, and they are declared here — never in the core.
+
+`TACK_CMD` remains available for unusual environments where the adapter and the
+CLI live in separate environments; set it to the command that invokes `tack`
+(for example `TACK_CMD="uv run tack"`).
+
+## Configure
+
+The server reads three environment variables:
+
+| Variable | Meaning |
+|---|---|
+| `TACKBOARD_DB` | the board file to operate on (same variable the CLI reads) |
+| `TACKBOARD_AGENT` | the actor every mutation is attributed to |
+| `TACK_CMD` | overrides the CLI command prefix; defaults to the installed core module, or `tack` when the core is not importable |
+
+```bash
+TACKBOARD_DB=~/.local/state/board.sqlite3 TACKBOARD_AGENT=assistant tackboard-mcp
+```
+
+The process speaks MCP over stdio. Register it with your client the way that
+client documents stdio servers:
+
+```json
+{
+  "mcpServers": {
+    "tackboard": {
+      "command": "tackboard-mcp",
+      "env": {
+        "TACKBOARD_DB": "/path/to/board.sqlite3",
+        "TACKBOARD_AGENT": "assistant"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Arguments | Returns |
+|---|---|---|
+| `next_claim` | `stage?` (`work`/`review`) | the `next --claim` document; `task` is `null` when nothing is eligible |
+| `show` | `task_id` | the `show` document: the task and its notes |
+| `note` | `task_id`, `text`, `refs?` (`KIND:VALUE`) | the `note` document with the appended event |
+| `complete` | `task_id` | the mutation document; completing unblocks dependents |
+| `release` | `task_id`, `reason?` | the mutation document; a reason is the audited force path |
+| `create` | `title`, `description?`, `priority?`, `assignee?`, `labels?`, `depends_on?`, `status?` | the created task document |
+| `board_brief` | — | the counts-only board document |
+
+Every tool declares all four MCP annotation hints as explicit booleans. The two
+read tools (`board_brief`, `show`) are read-only and repeatable; every mutating
+tool writes only the one local board and touches no external system
+(`openWorldHint` false); nothing on this surface deletes data
+(`destructiveHint` false); and `complete` is idempotent while `next_claim`,
+`note`, `release` and `create` are not.
+
+Each tool returns the CLI's JSON document unchanged. Exit codes are not
+translated into a second vocabulary: a failed call raises with the CLI's
+`error.code`, `exit_code` and `details` intact.
+
+## Tests
+
+```bash
+uv run pytest packages/tackboard-mcp/tests
+```
+
+The tool layer is tested without the framework: argument mapping against a fake
+transport, plus a scratch board driven through the real CLI. The binding tests
+(`test_server.py`) run only when `mcp` is installed — including a real client
+handshake over stdio — and skip otherwise, so the core suite never needs the
+framework.
+
+## Limits
+
+- One board per process: the database is fixed at start-up.
+- The web view and the schema commands are not exposed; they are not tool-shaped.
+- `--force` is reachable only through `release`'s `reason`, deliberately: the
+  other force cases are operator decisions, not assistant ones.

tackboard_mcp-0.8.0/README.md

@@ -0,0 +1,109 @@
+# tackboard-mcp — an optional MCP adapter
+
+A small [Model Context Protocol](https://modelcontextprotocol.io) server that
+exposes one `tack` project board to an MCP client (an IDE assistant, a chat
+client, another agent runtime).
+
+**This package is optional and outside the core.** The `tackboard` package —
+the CLI, the database, the JSON contracts — stays dependency-free and does not
+import anything here. If you only want the board, install `tackboard`; if your
+agent runtime speaks MCP and you would rather it called tools than assembled
+shell commands, install this beside it.
+
+## What it is, precisely
+
+The adapter contains **no domain logic**. Every tool shells out to the `tack`
+CLI with `--json` and returns that document unchanged, so a client can never
+see a claim, a transition or a validation rule that differs from the board. A
+non-zero exit is raised as an error whose payload is the CLI's own error
+document (`{"schema_version":1,"error":{...}}`).
+
+What it adds is discovery and a typed surface: seven named tools with described
+arguments, instead of a CLI string to compose.
+
+## Install
+
+```bash
+uv tool install tackboard-mcp      # or: pip install tackboard-mcp
+```
+
+This installs the adapter and pulls `tackboard` with it, so the `tack` CLI
+comes along in the same environment. The MCP framework and the core are this
+package's dependencies, and they are declared here — never in the core.
+
+`TACK_CMD` remains available for unusual environments where the adapter and the
+CLI live in separate environments; set it to the command that invokes `tack`
+(for example `TACK_CMD="uv run tack"`).
+
+## Configure
+
+The server reads three environment variables:
+
+| Variable | Meaning |
+|---|---|
+| `TACKBOARD_DB` | the board file to operate on (same variable the CLI reads) |
+| `TACKBOARD_AGENT` | the actor every mutation is attributed to |
+| `TACK_CMD` | overrides the CLI command prefix; defaults to the installed core module, or `tack` when the core is not importable |
+
+```bash
+TACKBOARD_DB=~/.local/state/board.sqlite3 TACKBOARD_AGENT=assistant tackboard-mcp
+```
+
+The process speaks MCP over stdio. Register it with your client the way that
+client documents stdio servers:
+
+```json
+{
+  "mcpServers": {
+    "tackboard": {
+      "command": "tackboard-mcp",
+      "env": {
+        "TACKBOARD_DB": "/path/to/board.sqlite3",
+        "TACKBOARD_AGENT": "assistant"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Arguments | Returns |
+|---|---|---|
+| `next_claim` | `stage?` (`work`/`review`) | the `next --claim` document; `task` is `null` when nothing is eligible |
+| `show` | `task_id` | the `show` document: the task and its notes |
+| `note` | `task_id`, `text`, `refs?` (`KIND:VALUE`) | the `note` document with the appended event |
+| `complete` | `task_id` | the mutation document; completing unblocks dependents |
+| `release` | `task_id`, `reason?` | the mutation document; a reason is the audited force path |
+| `create` | `title`, `description?`, `priority?`, `assignee?`, `labels?`, `depends_on?`, `status?` | the created task document |
+| `board_brief` | — | the counts-only board document |
+
+Every tool declares all four MCP annotation hints as explicit booleans. The two
+read tools (`board_brief`, `show`) are read-only and repeatable; every mutating
+tool writes only the one local board and touches no external system
+(`openWorldHint` false); nothing on this surface deletes data
+(`destructiveHint` false); and `complete` is idempotent while `next_claim`,
+`note`, `release` and `create` are not.
+
+Each tool returns the CLI's JSON document unchanged. Exit codes are not
+translated into a second vocabulary: a failed call raises with the CLI's
+`error.code`, `exit_code` and `details` intact.
+
+## Tests
+
+```bash
+uv run pytest packages/tackboard-mcp/tests
+```
+
+The tool layer is tested without the framework: argument mapping against a fake
+transport, plus a scratch board driven through the real CLI. The binding tests
+(`test_server.py`) run only when `mcp` is installed — including a real client
+handshake over stdio — and skip otherwise, so the core suite never needs the
+framework.
+
+## Limits
+
+- One board per process: the database is fixed at start-up.
+- The web view and the schema commands are not exposed; they are not tool-shaped.
+- `--force` is reachable only through `release`'s `reason`, deliberately: the
+  other force cases are operator decisions, not assistant ones.

tackboard_mcp-0.8.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "tackboard-mcp"
+version = "0.8.0"
+description = "Optional MCP adapter for the tackboard CLI — exposes board tools to MCP clients"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "tackboard>=0.8.0,<0.9",
+    "mcp>=2.3,<3",
+]
+
+[project.license]
+text = "MIT"
+
+[project.scripts]
+tackboard-mcp = "tackboard_mcp.server:main"
+
+[tool.uv.sources.tackboard]
+workspace = true
+
+[tool.uv.build-backend]
+module-name = "tackboard_mcp"
+
+[build-system]
+requires = ["uv_build>=0.7,<0.13"]
+build-backend = "uv_build"

tackboard_mcp-0.8.0/pyproject.toml.orig

@@ -0,0 +1,21 @@
+[project]
+name = "tackboard-mcp"
+version = "0.8.0"
+description = "Optional MCP adapter for the tackboard CLI — exposes board tools to MCP clients"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+dependencies = ["tackboard>=0.8.0,<0.9", "mcp>=2.3,<3"]
+
+[tool.uv.sources]
+tackboard = { workspace = true }
+
+[project.scripts]
+tackboard-mcp = "tackboard_mcp.server:main"
+
+[build-system]
+requires = ["uv_build>=0.7,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "tackboard_mcp"

tackboard_mcp-0.8.0/src/tackboard_mcp/__init__.py

@@ -0,0 +1,14 @@
+"""Optional MCP adapter for the ``tack`` board CLI.
+
+The tool layer (:mod:`tackboard_mcp.tools`) has no MCP dependency and can be
+used directly; :mod:`tackboard_mcp.server` is the thin MCP binding and imports
+the framework only when it is asked to build a server.
+"""
+
+from __future__ import annotations
+
+from .tools import Document, TackCli, TackCommandError
+
+__version__ = "0.1.0"
+
+__all__ = ["Document", "TackCli", "TackCommandError", "__version__"]

tackboard_mcp-0.8.0/src/tackboard_mcp/server.py

@@ -0,0 +1,166 @@
+"""The MCP binding: one tool per board operation, over the CLI.
+
+This module is the only place the MCP framework is imported, and only inside
+:func:`build_server` — so importing :mod:`tackboard_mcp` or its tool layer never
+requires the framework, and the core ``tackboard`` package never depends on it.
+
+Every tool returns the CLI's JSON document unchanged. A failed call raises, and
+the framework turns that into a tool error whose text is the CLI's own message.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .tools import TackCli
+
+if TYPE_CHECKING:  # pragma: no cover - typing only, the framework is optional
+    from mcp.server.mcpserver import MCPServer
+
+INSTRUCTIONS = """\
+This server exposes one project's tackboard through the `tack` CLI.
+
+Read the board before acting: board_brief for counts, then next_claim to take
+work atomically. A claim is a promise to every other agent — complete the task
+when the work is done, and leave a note with evidence (commit ids, paths, urls)
+at every handoff. `show` returns the full task including notes. `release`
+without a reason gives up a claim you hold; with a reason it is the audited
+force path, so use it only to recover a dead agent's claim.
+"""
+
+
+def _server_class() -> type[MCPServer]:
+    """The framework's server class, under either release line's name.
+
+    MCP 2.x renamed ``mcp.server.fastmcp.FastMCP`` to
+    ``mcp.server.mcpserver.MCPServer``; the decorator surface this adapter uses
+    is the same, so it supports both rather than pinning a client's toolchain.
+    """
+    try:
+        from mcp.server.mcpserver import MCPServer as _MCPServer
+    except ImportError:  # pragma: no cover - 1.x
+        from mcp.server.fastmcp import FastMCP as _MCPServer  # type: ignore[attr-defined,no-redef]
+    return _MCPServer
+
+
+def build_server(cli: TackCli) -> MCPServer:
+    """Build the MCP server for ``cli``'s board.
+
+    Imported lazily: the MCP framework lives only in this package's metadata,
+    so a checkout without it can still use the tool layer and its tests.
+    """
+    from mcp.types import ToolAnnotations
+
+    server = _server_class()("tackboard", instructions=INSTRUCTIONS)
+
+    @server.tool(
+        annotations=ToolAnnotations(
+            read_only_hint=False,
+            destructive_hint=False,
+            idempotent_hint=False,
+            open_world_hint=False,
+        )
+    )
+    def next_claim(stage: str | None = None) -> dict[str, Any]:
+        """Claim and return the next eligible task. `stage` may be "review"."""
+        return cli.next_claim(stage)
+
+    @server.tool(
+        annotations=ToolAnnotations(
+            read_only_hint=True,
+            destructive_hint=False,
+            idempotent_hint=True,
+            open_world_hint=False,
+        )
+    )
+    def show(task_id: str) -> dict[str, Any]:
+        """Read one task in full, including its notes."""
+        return cli.show(task_id)
+
+    @server.tool(
+        annotations=ToolAnnotations(
+            read_only_hint=False,
+            destructive_hint=False,
+            idempotent_hint=False,
+            open_world_hint=False,
+        )
+    )
+    def note(task_id: str, text: str, refs: list[str] | None = None) -> dict[str, Any]:
+        """Append a handoff note; refs are KIND:VALUE strings (commit/url/path/task)."""
+        return cli.note(task_id, text, tuple(refs or ()))
+
+    @server.tool(
+        annotations=ToolAnnotations(
+            read_only_hint=False,
+            destructive_hint=False,
+            idempotent_hint=True,
+            open_world_hint=False,
+        )
+    )
+    def complete(task_id: str) -> dict[str, Any]:
+        """Finish a task, unblocking its dependents."""
+        return cli.complete(task_id)
+
+    @server.tool(
+        annotations=ToolAnnotations(
+            read_only_hint=False,
+            destructive_hint=False,
+            idempotent_hint=False,
+            open_world_hint=False,
+        )
+    )
+    def release(task_id: str, reason: str | None = None) -> dict[str, Any]:
+        """Release a claim; a reason makes it the audited force path."""
+        return cli.release(task_id, reason)
+
+    @server.tool(
+        annotations=ToolAnnotations(
+            read_only_hint=False,
+            destructive_hint=False,
+            idempotent_hint=False,
+            open_world_hint=False,
+        )
+    )
+    def create(
+        title: str,
+        description: str | None = None,
+        priority: str | None = None,
+        assignee: str | None = None,
+        labels: list[str] | None = None,
+        depends_on: list[str] | None = None,
+        status: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a task, optionally with labels, assignment and prerequisite ids."""
+        return cli.create(
+            title,
+            description=description,
+            priority=priority,
+            assignee=assignee,
+            labels=tuple(labels or ()),
+            depends_on=tuple(depends_on or ()),
+            status=status,
+        )
+
+    @server.tool(
+        annotations=ToolAnnotations(
+            read_only_hint=True,
+            destructive_hint=False,
+            idempotent_hint=True,
+            open_world_hint=False,
+        )
+    )
+    def board_brief() -> dict[str, Any]:
+        """The board's counts only: the cheapest look at what is on the board."""
+        return cli.board_brief()
+
+    return server
+
+
+def main() -> int:
+    """Start the server over stdio, configured from the environment."""
+    build_server(TackCli.from_environment()).run()
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover - entry point
+    raise SystemExit(main())

tackboard_mcp-0.8.0/src/tackboard_mcp/tools.py

@@ -0,0 +1,220 @@
+"""The tool layer: one function per board operation, each a ``tack`` call.
+
+There is deliberately no domain logic here. Every tool shells out to the CLI
+with ``--json`` and returns that JSON document unchanged, so the adapter can
+never disagree with the board: the CLI is the only implementation of claims,
+transitions, validation and exit codes. A non-zero exit becomes a
+``TackCommandError`` carrying the CLI's own error document, so an MCP client
+sees exactly what an agent at a terminal would see.
+
+The runner is injectable (``runner=``) so tests can exercise argument building
+without a board; production always spawns the real executable.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from collections.abc import Callable, Iterator, Mapping, Sequence
+from contextlib import contextmanager
+from dataclasses import dataclass
+from importlib.util import find_spec
+from pathlib import Path
+from typing import Any
+
+#: A runner takes the full argv and stdin text and returns
+#: ``(returncode, stdout, stderr)``. The default spawns a process.
+Runner = Callable[[Sequence[str], str | None], tuple[int, str, str]]
+
+#: A ``tack --json`` document.
+Document = dict[str, Any]
+
+
+class TackCommandError(RuntimeError):
+    """A ``tack`` call failed; carries the CLI's error document when it sent one."""
+
+    def __init__(
+        self,
+        argv: Sequence[str],
+        returncode: int,
+        message: str,
+        document: Document | None = None,
+    ) -> None:
+        super().__init__(f"tack exited {returncode}: {' '.join(argv)}")
+        self.argv = tuple(argv)
+        self.returncode = returncode
+        self.stderr = message
+        self.document = document
+
+
+def _subprocess_runner(argv: Sequence[str], stdin: str | None) -> tuple[int, str, str]:
+    completed = subprocess.run(
+        list(argv), input=stdin, capture_output=True, text=True, check=False
+    )
+    return completed.returncode, completed.stdout, completed.stderr
+
+
+def _parse(argv: Sequence[str], returncode: int, text: str) -> Document:
+    try:
+        document = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise TackCommandError(argv, returncode, f"stdout is not JSON: {text[:200]!r}") from exc
+    if not isinstance(document, dict):
+        raise TackCommandError(
+            argv, returncode, f"stdout is not a JSON object: {text[:200]!r}"
+        )
+    return document
+
+
+@contextmanager
+def _environment(actor: str | None) -> Iterator[None]:
+    """Set ``TACKBOARD_AGENT`` for one call and restore the process state after."""
+    saved = os.environ.get("TACKBOARD_AGENT")
+    if actor is None:
+        os.environ.pop("TACKBOARD_AGENT", None)
+    else:
+        os.environ["TACKBOARD_AGENT"] = actor
+    try:
+        yield
+    finally:
+        if saved is None:
+            os.environ.pop("TACKBOARD_AGENT", None)
+        else:
+            os.environ["TACKBOARD_AGENT"] = saved
+
+
+def _default_command() -> tuple[str, ...]:
+    """Prefer the installed core module, falling back to the console script.
+
+    The adapter depends on ``tackboard``, so the core is importable from the
+    same environment in the normal case: running ``sys.executable -m tackboard``
+    avoids depending on ``tack`` being on ``PATH``. When the adapter lives in a
+    different environment from the CLI, ``tackboard`` is not importable and the
+    historical ``tack`` lookup remains the fallback. ``TACK_CMD`` still takes
+    first precedence in ``from_environment``.
+    """
+    if find_spec("tackboard") is not None:
+        return (sys.executable, "-m", "tackboard")
+    return ("tack",)
+
+
+@dataclass(frozen=True, slots=True)
+class TackCli:
+    """A configured ``tack`` invocation: command prefix, board and actor.
+
+    ``command`` is the executable plus any fixed prefix, e.g. ``("tack",)`` or
+    ``(sys.executable, "-m", "tackboard")``. ``db`` and ``actor`` become
+    ``--db`` and ``TACKBOARD_AGENT`` on every call.
+    """
+
+    command: tuple[str, ...] = ("tack",)
+    db: Path | None = None
+    actor: str | None = None
+    runner: Runner = _subprocess_runner
+
+    @classmethod
+    def from_environment(
+        cls, environ: Mapping[str, str] | None = None, runner: Runner | None = None
+    ) -> TackCli:
+        """Build from ``TACK_CMD``, ``TACKBOARD_DB`` and ``TACKBOARD_AGENT``."""
+        env = os.environ if environ is None else environ
+        command = tuple(env.get("TACK_CMD", "").split()) or _default_command()
+        db_text = env.get("TACKBOARD_DB")
+        return cls(
+            command=command,
+            db=Path(db_text) if db_text else None,
+            actor=env.get("TACKBOARD_AGENT"),
+            runner=runner or _subprocess_runner,
+        )
+
+    def _argv(self, *argv: str) -> list[str]:
+        taken = [*self.command, *argv, "--json"]
+        if self.db is not None:
+            taken.extend(["--db", str(self.db)])
+        return taken
+
+    def run(self, *argv: str, stdin: str | None = None) -> Document:
+        """Run one ``tack`` command and return its JSON document unchanged."""
+        full = self._argv(*argv)
+        with _environment(self.actor):
+            returncode, stdout, stderr = self.runner(full, stdin)
+        text = stdout.strip()
+        if returncode != 0:
+            document = None
+            if text:
+                try:
+                    parsed = json.loads(text)
+                except json.JSONDecodeError:
+                    parsed = None
+                document = parsed if isinstance(parsed, dict) else None
+            raise TackCommandError(full, returncode, stderr.strip() or text, document)
+        if not text:
+            raise TackCommandError(full, returncode, "tack printed no JSON document")
+        return _parse(full, returncode, text)
+
+    # -- the board operations ------------------------------------------------
+
+    def next_claim(self, stage: str | None = None) -> Document:
+        """Claim and return the next eligible task (``task`` may be ``null``)."""
+        argv: list[str] = ["next", "--claim"]
+        if stage is not None:
+            argv.extend(["--stage", stage])
+        return self.run(*argv)
+
+    def show(self, task_id: str) -> Document:
+        """One task in full, with its notes."""
+        return self.run("show", task_id)
+
+    def note(self, task_id: str, text: str, refs: Sequence[str] = ()) -> Document:
+        """Append a handoff note; ``refs`` are ``KIND:VALUE`` strings."""
+        argv = ["note", task_id, text]
+        for ref in refs:
+            argv.extend(["--ref", ref])
+        return self.run(*argv)
+
+    def complete(self, task_id: str) -> Document:
+        """Finish a task; its dependents become eligible."""
+        return self.run("complete", task_id)
+
+    def release(self, task_id: str, reason: str | None = None) -> Document:
+        """Release a claim; a reason forces (audited) rather than plain release."""
+        argv = ["release", task_id]
+        if reason is not None:
+            argv.extend(["--force", "--reason", reason])
+        return self.run(*argv)
+
+    def create(
+        self,
+        title: str,
+        *,
+        description: str | None = None,
+        priority: str | None = None,
+        assignee: str | None = None,
+        labels: Sequence[str] = (),
+        depends_on: Sequence[str] = (),
+        status: str | None = None,
+    ) -> Document:
+        """Create a task, optionally with its dependency edges."""
+        argv = ["create", title]
+        if description is not None:
+            argv.extend(["--description", description])
+        if priority is not None:
+            argv.extend(["--priority", priority])
+        if assignee is not None:
+            argv.extend(["--assignee", assignee])
+        if status is not None:
+            argv.extend(["--status", status])
+        for label in labels:
+            argv.extend(["--label", label])
+        for prerequisite in depends_on:
+            argv.extend(["--depends-on", prerequisite])
+        return self.run(*argv)
+
+    def board_brief(self) -> Document:
+        """The counts-only board document: the cheapest look at a board."""
+        return self.run("board", "--brief")
+
+
+__all__ = ["Document", "Runner", "TackCli", "TackCommandError"]