taut-mcp 0.7.0__tar.gz

taut_mcp-0.7.0/.gitignore

@@ -0,0 +1,25 @@
+.DS_Store
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+.venv/
+.taut.db
+.taut.db.lock
+.taut.lock
+.taut.db-wal
+.taut.db-shm
+.envrc
+.taut.toml
+.weft
+.broker*
+extensions/taut_pg/uv.lock

taut_mcp-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Van Lindberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

taut_mcp-0.7.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: taut-mcp
+Version: 0.7.0
+Summary: MCP extension for attaching agent sessions to Taut workspaces
+Author-email: Van Lindberg <van.lindberg@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1.28.1
+Requires-Dist: taut>=0.7.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.4.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: taut-pg>=0.7.0; extra == 'dev'
+Requires-Dist: types-jsonschema>=4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Taut MCP
+
+`taut-mcp` is the optional, connection-scoped MCP adapter for Taut. A client
+launches one protocol-clean stdio process and explicitly attaches up to eight
+existing Taut workspaces with their existing continuity tokens. The process is
+not a daemon and retains no attachment state after disconnect.
+
+The version-1 surface is specified in `docs/specs/05-taut-mcp.md`. It exposes
+15 explicit tools plus the read-only `taut://notifications/current` resource.
+The resource reports notification pointers, not every unread chat message, and
+does not claim notifications or advance read cursors.
+
+The repository has a GitHub-only release path for this package, but configuring
+that path does not publish a release. After the matching core tag and MCP wheel
+exist, install both into one environment:
+
+```bash
+pipx install "git+https://github.com/VanL/taut.git@v0.7.0"
+pipx inject --include-apps taut ./taut_mcp-0.7.0-py3-none-any.whl
+taut-mcp
+```
+
+From this checkout, use its package-local environment:
+
+```bash
+uv sync --directory extensions/taut_mcp --extra dev
+uv run --directory extensions/taut_mcp taut-mcp
+```
+
+Workspace attachment tokens are sensitive MCP tool inputs. Supply a token only
+to `attach_workspace`; do not repeat it in chat, logs, or ordinary tool calls.
+The opt-in `--claude-channel` flag advertises Claude's experimental channel
+capability and sends only a fixed cue to reread the notification resource when
+its content changes. Channel hints are best-effort and host-specific. Standard
+tools, manual resource reads, and resource update subscriptions remain the
+portable interface and the source of truth.

taut_mcp-0.7.0/README.md

@@ -0,0 +1,36 @@
+# Taut MCP
+
+`taut-mcp` is the optional, connection-scoped MCP adapter for Taut. A client
+launches one protocol-clean stdio process and explicitly attaches up to eight
+existing Taut workspaces with their existing continuity tokens. The process is
+not a daemon and retains no attachment state after disconnect.
+
+The version-1 surface is specified in `docs/specs/05-taut-mcp.md`. It exposes
+15 explicit tools plus the read-only `taut://notifications/current` resource.
+The resource reports notification pointers, not every unread chat message, and
+does not claim notifications or advance read cursors.
+
+The repository has a GitHub-only release path for this package, but configuring
+that path does not publish a release. After the matching core tag and MCP wheel
+exist, install both into one environment:
+
+```bash
+pipx install "git+https://github.com/VanL/taut.git@v0.7.0"
+pipx inject --include-apps taut ./taut_mcp-0.7.0-py3-none-any.whl
+taut-mcp
+```
+
+From this checkout, use its package-local environment:
+
+```bash
+uv sync --directory extensions/taut_mcp --extra dev
+uv run --directory extensions/taut_mcp taut-mcp
+```
+
+Workspace attachment tokens are sensitive MCP tool inputs. Supply a token only
+to `attach_workspace`; do not repeat it in chat, logs, or ordinary tool calls.
+The opt-in `--claude-channel` flag advertises Claude's experimental channel
+capability and sends only a fixed cue to reread the notification resource when
+its content changes. Channel hints are best-effort and host-specific. Standard
+tools, manual resource reads, and resource update subscriptions remain the
+portable interface and the source of truth.

taut_mcp-0.7.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "taut-mcp"
+version = "0.7.0"
+description = "MCP extension for attaching agent sessions to Taut workspaces"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+license-files = ["LICENSE"]
+authors = [
+    {name = "Van Lindberg", email = "van.lindberg@gmail.com"},
+]
+dependencies = [
+    "mcp>=1.28.1,<2",
+    "taut>=0.7.0",
+]
+
+[project.scripts]
+taut-mcp = "taut_mcp.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2",
+    "mypy>=1.0",
+    "pytest>=7.0",
+    "pytest-timeout>=2.4.0",
+    "pytest-xdist>=3.0",
+    "ruff>=0.1.0",
+    "taut-pg>=0.7.0",
+    "types-jsonschema>=4.0",
+]
+
+[tool.uv.sources]
+taut = { path = "../..", editable = true }
+taut-pg = { path = "../taut_pg", editable = true }
+
+[tool.hatch.build]
+include = [
+    "/taut_mcp/**/*.py",
+    "/taut_mcp/py.typed",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+testpaths = ["tests"]
+addopts = "-ra -q --strict-markers -n auto --dist loadgroup"
+markers = [
+    "installed_wheel: tests that build and run isolated installed artifacts",
+    "pg_only: tests that validate the Postgres extension package",
+    "sqlite_only: tests that validate built-in SQLite/path behavior",
+]
+
+[tool.mypy]
+python_version = "3.11"
+no_namespace_packages = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP"]
+ignore = ["E501", "B008"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["taut", "taut_mcp"]

taut_mcp-0.7.0/taut_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Public Taut MCP extension package."""
+
+from __future__ import annotations
+
+__all__: list[str] = []

taut_mcp-0.7.0/taut_mcp/__main__.py

@@ -0,0 +1,7 @@
+"""Run ``python -m taut_mcp``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+main()

taut_mcp-0.7.0/taut_mcp/_claude_channel.py

@@ -0,0 +1,40 @@
+"""Isolated research-preview Claude channel notification adapter."""
+
+from __future__ import annotations
+
+from typing import Literal, cast
+
+from mcp import types
+from mcp.server.session import ServerSession
+
+CLAUDE_CHANNEL_METHOD: Literal["notifications/claude/channel"] = (
+    "notifications/claude/channel"
+)
+CLAUDE_CHANNEL_CUE = "Taut notifications changed; read taut://notifications/current."
+
+
+class ClaudeChannelParams(types.NotificationParams):
+    """The fixed, metadata-free channel payload."""
+
+    content: str
+
+
+class ClaudeChannelNotification(
+    types.Notification[
+        ClaudeChannelParams,
+        Literal["notifications/claude/channel"],
+    ]
+):
+    """Experimental notification shape understood by capable Claude hosts."""
+
+    method: Literal["notifications/claude/channel"] = CLAUDE_CHANNEL_METHOD
+    params: ClaudeChannelParams
+
+
+async def send_claude_channel(session: ServerSession) -> None:
+    """Send one fixed best-effort wake through the public SDK session API."""
+
+    notification = ClaudeChannelNotification(
+        params=ClaudeChannelParams(content=CLAUDE_CHANNEL_CUE)
+    )
+    await session.send_notification(cast(types.ServerNotification, notification))

taut_mcp-0.7.0/taut_mcp/_commands.py

@@ -0,0 +1,177 @@
+"""Explicit public-API dispatch for the twelve CLI-shaped MCP tools."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TypeAlias
+
+from taut import Member, Message, Notification, TautClient, Thread
+
+CommandScalar: TypeAlias = str | int | bool | None
+CommandArguments: TypeAlias = tuple[tuple[str, CommandScalar], ...]
+CommandRecord: TypeAlias = Message | Notification | Member | Thread
+
+RECORD_TYPE_BY_TOOL = {
+    "join": "message",
+    "leave": "message",
+    "set_name": "member",
+    "say": "message",
+    "reply": "message",
+    "read": "message",
+    "inbox": "notification",
+    "log": "message",
+    "list": "thread",
+    "rename": "thread",
+    "who": "member",
+    "whoami": "member",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class CommandRecords:
+    record_type: str
+    records: tuple[CommandRecord, ...]
+
+
+def _required_string(arguments: dict[str, CommandScalar], name: str) -> str:
+    value = arguments.get(name)
+    if not isinstance(value, str):
+        raise TypeError(f"{name} must be a string")
+    return value
+
+
+def _optional_string(arguments: dict[str, CommandScalar], name: str) -> str | None:
+    value = arguments.get(name)
+    if value is not None and not isinstance(value, str):
+        raise TypeError(f"{name} must be a string or null")
+    return value
+
+
+def _integer(arguments: dict[str, CommandScalar], name: str, default: int) -> int:
+    value = arguments.get(name, default)
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"{name} must be an integer")
+    return value
+
+
+def execute_command(
+    client: TautClient,
+    name: str,
+    frozen_arguments: CommandArguments,
+) -> CommandRecords:
+    """Run exactly one allowlisted public client operation."""
+
+    arguments = dict(frozen_arguments)
+    if name == "join":
+        record = client.join(
+            _required_string(arguments, "thread"),
+            persona=_optional_string(arguments, "persona"),
+            new=False,
+        )
+        records: tuple[CommandRecord, ...] = (record,)
+    elif name == "leave":
+        records = (client.leave(_required_string(arguments, "thread")),)
+    elif name == "set_name":
+        records = (client.set_name(_required_string(arguments, "name")),)
+    elif name == "say":
+        records = (
+            client.say(
+                _required_string(arguments, "target"),
+                _required_string(arguments, "text"),
+            ),
+        )
+    elif name == "reply":
+        records = (
+            client.reply(
+                _required_string(arguments, "thread"),
+                _required_string(arguments, "msg_id"),
+                _required_string(arguments, "text"),
+            ),
+        )
+    elif name == "read":
+        records = tuple(
+            client.read(
+                _optional_string(arguments, "thread"),
+                limit=_integer(arguments, "limit", 100),
+            )
+        )
+    elif name == "inbox":
+        records = tuple(client.inbox(limit=_integer(arguments, "limit", 1000)))
+    elif name == "log":
+        since = arguments.get("since")
+        if since is not None and (
+            isinstance(since, bool) or not isinstance(since, (str, int))
+        ):
+            raise TypeError("since must be a string, integer, or null")
+        records = tuple(
+            client.log(
+                _required_string(arguments, "thread"),
+                since=since,
+                limit=_integer(arguments, "limit", 100),
+            )
+        )
+    elif name == "list":
+        all_threads = arguments.get("all", False)
+        if not isinstance(all_threads, bool):
+            raise TypeError("all must be a boolean")
+        records = tuple(client.list_threads(all_threads=all_threads))
+    elif name == "rename":
+        records = (
+            client.rename_channel(
+                _required_string(arguments, "old_name"),
+                _required_string(arguments, "new_name"),
+            ),
+        )
+    elif name == "who":
+        records = tuple(client.who(_optional_string(arguments, "thread")))
+    elif name == "whoami":
+        records = (client.whoami(explain=False),)
+    else:
+        raise AssertionError(f"unregistered child command: {name}")
+    return CommandRecords(RECORD_TYPE_BY_TOOL[name], records)
+
+
+def record_object(record: CommandRecord) -> dict[str, object]:
+    """Encode one public value object without importing CLI rendering."""
+
+    if isinstance(record, Message):
+        return {
+            "from": record.from_name,
+            "from_id": record.from_id,
+            "kind": record.kind,
+            "text": record.text,
+            "thread": record.thread,
+            "ts": record.ts,
+        }
+    if isinstance(record, Notification):
+        notification: dict[str, object] = {
+            "actor_id": record.actor_id,
+            "actor_name": record.actor_name,
+            "message_ts": record.message_ts,
+            "thread": record.thread,
+            "to_id": record.to_id,
+            "type": record.type,
+        }
+        if record.matched is not None:
+            notification["matched"] = record.matched
+        return notification
+    if isinstance(record, Member):
+        return {
+            "aliases": list(record.aliases),
+            "kind": record.kind,
+            "last_active_ts": record.last_active_ts,
+            "member_id": record.member_id,
+            "name": record.name,
+            "persona": record.persona,
+            "presence": record.presence,
+        }
+    thread: dict[str, object] = {
+        "kind": record.kind,
+        "last_ts": record.last_ts,
+        "parent": record.parent,
+        "thread": record.name,
+        "unread": record.unread,
+    }
+    if record.kind == "dm":
+        thread["members"] = list(record.members)
+    return thread