cmux-mcp 0.2.0__tar.gz

cmux_mcp-0.2.0/.gitignore

@@ -0,0 +1,105 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# uv
+uv.lock.bak
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.json
+.tox/
+.nox/
+
+# Type checkers
+.mypy_cache/
+.pyright_cache/
+
+# Linters / formatters
+.ruff_cache/
+.black/
+
+# Crackerjack
+.crackerjack/
+# Crackerjack tool output caches
+.cache/
+# lychee link checker persistent cache (single file at repo root)
+.lycheecache
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Logs
+*.log
+logs/
+
+# Worktrees (no-op; designed for repos that use clones)
+.claude/worktrees/
+
+# Oneiric runtime cache (mcp-common BaseOneiricServerMixin writes snapshots here)
+.oneiric_cache/
+
+# direnv auto-generated files
+.envrc
+
+# >>> bodai-shared-gitignore >>>
+# Source of truth: crackerjack/templates/GITIGNORE_BODAI.md
+# Enforced by: crackerjack check `gitignore-conformance`
+# Fleet list: /Users/les/Projects/mahavishnu/BODAI_REPO_REGISTRY.md
+# Do NOT remove the marker line above — `crackerjack gitignore sync` uses it
+# to detect already-applied state.
+
+# Editor / pre-edit backups (foo.py.backup, foo.py.backup.json)
+*.backup
+*.backup.*
+*.bak
+*.tmpl
+# XDG mistake dirs (env var expansion failed; literal names)
+# Note: both `{` and `}` are escaped (`{` -> `[{]`, `}` -> `[}]`)
+# because gitignore parsers interpret `${...}` as a brace-expansion
+# alternate group; escaping only the open brace leaves a stray `}`.
+~
+[{]HOME[}]
+[{]XDG_DATA_HOME:-$HOME[}]
+# pytest-benchmark autosave cache (sibling of the tracked `benchmarks/` test suite)
+.benchmarks/
+# Vitest config timestamp cache
+vitest.config.js.timestamp-*.mjs
+# Playwright output cruft
+playwright-junit.xml
+playwright-report/
+playwright-results.json
+test-results/
+# <<< bodai-shared-gitignore <<<

cmux_mcp-0.2.0/.gitignore.bak.20260921T082924Z

@@ -0,0 +1,75 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# uv
+uv.lock.bak
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.json
+.tox/
+.nox/
+
+# Type checkers
+.mypy_cache/
+.pyright_cache/
+
+# Linters / formatters
+.ruff_cache/
+.black/
+
+# Crackerjack
+.crackerjack/
+# Crackerjack tool output caches
+.cache/
+# lychee link checker persistent cache (single file at repo root)
+.lycheecache
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Logs
+*.log
+logs/
+
+# Worktrees (no-op; designed for repos that use clones)
+.claude/worktrees/
+
+# Oneiric runtime cache (mcp-common BaseOneiricServerMixin writes snapshots here)
+.oneiric_cache/
+
+# direnv auto-generated files
+.envrc

cmux_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-09-21
+
+### Fixed
+
+- browser: Handle CmuxMockTransport missing _config in truncate path
+- client+server: H7/H9/H10 — counter, JSONDecodeError, PID PermissionError
+- client: H8 — surface-lock refcount + eviction (no more lock leak)
+- client: Subprocess lifecycle on cancellation + real aclose() (C2+C3)
+- errors+README: H5 — missing exception classes + honest README (H6)
+- gitignore: Exclude crackerjack tool-output caches (.cache/ + .lycheecache)
+- logging: Use Oneiric's structlog-based logger (C7 — CLAUDE.md violation)
+- quality: All fast hooks now pass — lint + tc-refs scope fix
+- server: Custom /health route returns 503 on degraded (C4)
+- tools: Cmux_browser_type returns BrowserTypeOutput (H3)
+- tools: Cmux_list_workspaces iterates correct field + adds surface.list (H4)
+- tools: H1/H2 — wire max_response_bytes + notify rate limit
+- tools: Record_success() reachable in cmux_browser_navigate (C5)
+- tools: Tool errors raise ToolError (C6 — was returning plain dict)
+- Wire register_tools into startup (C1 — server exposed zero tools)
+
+### Documentation
+
+- plans: Mark cmux-mcp plan + spec shipped (v0.1.0)
+
+### Internal
+
+- deps: Add crackerjack to PEP 735 dependency-groups
+- Migrate cmux-mcp from src-layout to flat layout

cmux_mcp-0.2.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Les Leslie, Wedgwood Web Works LLC
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

cmux_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.5
+Name: cmux-mcp
+Version: 0.2.0
+Summary: MCP server for cmux terminal automation (macOS only)
+Author-email: Les Leslie <les@wedgwoodwebworks.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: fastmcp<4,>=3.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp-common<0.27,>=0.26
+Requires-Dist: oneiric>=0.21.0
+Requires-Dist: psutil>=7.2.2
+Requires-Dist: pydantic-settings>=2
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: crackerjack>=0.20; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'

cmux_mcp-0.2.0/README.md

@@ -0,0 +1,103 @@
+# cmux-mcp
+
+[![Code style: crackerjack](https://img.shields.io/badge/code%20style-crackerjack-000042)](https://github.com/lesleslie/crackerjack)
+[![Runtime: oneiric](https://img.shields.io/badge/runtime-oneiric-6e5494)](https://github.com/lesleslie/oneiric)
+[![Framework: FastMCP](https://img.shields.io/badge/framework-FastMCP-0ea5e9)](https://github.com/jlowin/fastmcp)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Python: 3.14+](https://www.python.org/downloads/)](https://www.python.org/downloads/)
+
+Catalog and operating map for cmux-mcp.
+
+**Status:** v0.1.0 (initial release — 12 tools, BSD-3-Clause)
+
+## Quick Links
+
+- [Overview](#overview)
+- [Tool Reference](#tool-reference)
+- [Quick Start](#quick-start)
+- [MCP Client Configuration](#mcp-client-configuration)
+- [Configuration](#configuration)
+- [Security Notes](#security-notes)
+
+## Overview
+
+cmux-mcp exposes programmatic control of a running [cmux](https://github.com/manaflow-ai/cmux) instance (macOS-only, Ghostty-based terminal for AI coding agents) as 12 MCP tools over Streamable HTTP. The server speaks cmux's Unix-socket JSON-RPC protocol directly for orchestration and notifications, and shells out to the cmux CLI for browser automation.
+
+## Quick Start
+
+```bash
+# Install
+cd /Users/les/Projects/cmux-mcp && uv sync --extra dev
+
+# Run (mock mode, for testing)
+CMUX_MCP_MOCK=1 uv run cmux-mcp start
+
+# Run (real, on macOS with cmux running)
+uv run cmux-mcp start
+
+# Lifecycle
+uv run cmux-mcp start --bg
+uv run cmux-mcp status
+uv run cmux-mcp health
+uv run cmux-mcp stop
+```
+
+## MCP Client Configuration
+
+```json
+{
+  "mcpServers": {
+    "cmux": {
+      "command": "uv",
+      "args": ["run", "--project", "/Users/les/Projects/cmux-mcp", "cmux-mcp", "start"]
+    }
+  }
+}
+```
+
+## Tool Reference
+
+| Tool | Mode | Description |
+|---|---|---|
+| `cmux_list_workspaces` | Read-only | List all workspaces with panes and surfaces |
+| `cmux_list_notifications` | Read-only | List pending cmux notifications |
+| `cmux_identify` | Read-only | Return focused window/workspace/pane/surface |
+| `cmux_send_keys` | Destructive | Send text or special key to terminal surface (fire-and-forget) |
+| `cmux_notify` | Mutation | Dispatch OS notification that rings pane and lights sidebar |
+| `cmux_browser_navigate` | Destructive | Navigate browser surface to URL |
+| `cmux_browser_snapshot` | Read-only | A11y tree with Playwright-style refs |
+| `cmux_browser_evaluate` | Destructive | Execute JS in browser (arbitrary; trust model documented) |
+| `cmux_browser_click` | Destructive | Click element by CSS selector |
+| `cmux_browser_type` | Destructive | Type into input (uses fill semantics) |
+| `cmux_browser_tabs` | Read-only | List open tabs |
+| `cmux_browser_console` | Read-only | Read console + JS errors (aggregates 2 sub-calls) |
+
+## Configuration
+
+All settings via `CMUX_MCP_*` env vars. See `settings/cmux-mcp.yaml` for committed defaults.
+
+| Setting | Default | Description |
+|---|---|---|
+| `CMUX_MCP_HOST` | `127.0.0.1` | HTTP bind address |
+| `CMUX_MCP_PORT` | `3061` | HTTP port |
+| `CMUX_MCP_SOCKET_PATH` | `/tmp/cmux.sock` | cmux Unix socket |
+| `CMUX_MCP_CLI_PATH` | auto-discover | cmux CLI binary path |
+| `CMUX_MCP_MOCK` | unset | `1`/`true` enables mock mode |
+| `CMUX_MCP_AUTH_ENABLED` | `false` | Enable JWT auth for non-loopback deployments |
+
+## Security Notes
+
+- macOS-only; non-macOS hosts must use `CMUX_MCP_MOCK=1` (auto-flipped with WARN banner)
+- cmux's `cmuxOnly` access mode restricts socket connections to processes spawned inside cmux terminals
+- PII redaction helpers (`redact_url_query_string`, `redact_expression`) exist in `logging_setup.py` for future log-site use; v0.1.x ships with no PII-logging call sites by default (deferred)
+- Subprocess env filtered to `SUBPROCESS_ENV_ALLOWLIST` to prevent leaking API keys
+- Default loopback bind; non-loopback requires `CMUX_MCP_AUTH_ENABLED=true`
+
+## Development Commands
+
+```bash
+uv run pytest                 # Run all tests
+uv run pytest -m unit         # Unit tests only
+uv run pytest -m integration  # Integration tests (require live cmux)
+uv run crackerjack run        # Full quality gate
+```

cmux_mcp-0.2.0/cmux_mcp/__init__.py

@@ -0,0 +1,11 @@
+"""cmux-mcp: MCP server for cmux terminal automation (macOS only)."""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+__version__ = importlib.metadata.version("cmux-mcp")
+
+DEFAULT_PORT: int = 3061  # per spec decision log row 2 + 8
+
+__all__ = ["DEFAULT_PORT", "__version__"]

cmux_mcp-0.2.0/cmux_mcp/__main__.py

@@ -0,0 +1,24 @@
+"""cmux-mcp entry point."""
+
+from __future__ import annotations
+
+from mcp_common.cli import MCPServerCLIFactory
+
+from cmux_mcp.config import CmuxMCPConfig
+from cmux_mcp.server import CmuxMCPServer
+
+
+def main() -> None:
+    """Entry point for `cmux-mcp` console script."""
+    factory = MCPServerCLIFactory.create_server_cli(
+        server_class=CmuxMCPServer,
+        config_class=CmuxMCPConfig,
+        name="cmux-mcp",
+        _description="MCP server for cmux terminal automation (macOS only).",
+    )
+    app = factory.create_app()
+    app()
+
+
+if __name__ == "__main__":
+    main()

cmux_mcp-0.2.0/cmux_mcp/_tools.py

@@ -0,0 +1,49 @@
+"""cmux_mcp._tools — programmatic tool registration.
+
+Per spec §"_tools.py — registration pattern":
+  Per-instance FastMCP (in CmuxMCPServer.__init__) means @mcp.tool() decorators
+  can't bind at module-load time. Instead, register_tools() registers all 12
+  tools programmatically in CmuxMCPServer.startup().
+
+  Each tool body follows the try/except/else/return pattern per spec §"/health
+  envelope wiring → Tool feed placement".
+
+FastMCP 3.4+ API used: `FunctionTool.from_function(fn, name=..., description=...,
+annotations=ToolAnnotations(...), output_schema=...)` → `mcp.add_tool(tool)`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cmux_mcp.health import TOOL_NAMES
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+    from cmux_mcp.client import CmuxCliTransportProtocol, CmuxSocketTransportProtocol
+    from cmux_mcp.health import ToolFeedComponent
+
+
+def build_tool_feed_components() -> list[ToolFeedComponent]:
+    """Delegate to health.build_tool_feed_components (single source of truth)."""
+    from cmux_mcp.health import build_tool_feed_components as _impl
+
+    return _impl()
+
+
+def register_tools(
+    mcp: FastMCP,
+    socket_transport: CmuxSocketTransportProtocol,
+    cli_transport: CmuxCliTransportProtocol,
+    tool_feeds: dict[str, ToolFeedComponent],
+) -> None:
+    """Register all 12 tools on the FastMCP instance. Idempotent."""
+    from cmux_mcp.tools.browser_tools import register_browser_tools
+    from cmux_mcp.tools.socket_tools import register_socket_tools
+
+    register_socket_tools(mcp, socket_transport, tool_feeds)
+    register_browser_tools(mcp, cli_transport, tool_feeds)
+
+
+__all__ = ["TOOL_NAMES", "build_tool_feed_components", "register_tools"]

cmux_mcp-0.2.0/cmux_mcp/cli.py

@@ -0,0 +1,3 @@
+"""cli.py — placeholder; lifecycle CLI is wired via __main__.py + mcp-common."""
+
+from __future__ import annotations

cmux_mcp-0.2.0/cmux_mcp/cli_discovery.py

@@ -0,0 +1,98 @@
+"""cmux_mcp.cli_discovery — locate the cmux CLI binary.
+
+Per spec §"cmux CLI binary discovery":
+  1. CMUX_MCP_CLI_PATH env var (operator override)
+  2. which cmux from $PATH
+  3. /Applications/cmux.app/Contents/Resources/bin/cmux
+  4. /opt/homebrew/Caskroom/cmux/*/cmux.app/.../bin/cmux (latest version)
+  5. /usr/local/Caskroom/cmux/*/cmux.app/.../bin/cmux (Intel macs)
+  6. ~/Library/Developer/Xcode/DerivedData/cmux-*/Build/Products/{Debug,Release}/cmux.app/.../bin/cmux
+  7. fail with CmuxBinaryNotFoundError listing probed paths
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+from cmux_mcp.errors import CmuxBinaryNotFoundError
+
+# Module-level so tests can monkeypatch (see test_cli_discovery.py).
+_DEFAULT_APP_BUNDLE = Path("/Applications/cmux.app")
+_CASKROOM_PATHS: list[Path] = [
+    Path("/opt/homebrew/Caskroom/cmux"),
+    Path("/usr/local/Caskroom/cmux"),
+]
+
+
+def _candidate_paths() -> list[Path]:
+    candidates: list[Path] = []
+    if "PATH" in os.environ:
+        which_result = shutil.which("cmux")
+        if which_result:
+            candidates.append(Path(which_result))
+    candidates.append(_DEFAULT_APP_BUNDLE / "Contents" / "Resources" / "bin" / "cmux")
+    for caskroom in _CASKROOM_PATHS:
+        if caskroom.exists() and caskroom.is_dir():
+            # Numeric tuple sort so "10.0.0" sorts after "2.0.0".
+            versions = sorted(
+                (p for p in caskroom.iterdir() if p.is_dir()),
+                key=lambda p: tuple(
+                    int(x) if x.isdigit() else 0 for x in p.name.split(".")
+                ),
+                reverse=True,
+            )
+            for v in versions:
+                candidates.append(
+                    v / "cmux.app" / "Contents" / "Resources" / "bin" / "cmux"
+                )
+    derived = Path.home() / "Library" / "Developer" / "Xcode" / "DerivedData"
+    if derived.exists():
+        # PERF402: candidates.extend(glob(...)) beats `for d in glob: append`
+        # — single C-level call instead of N Python appends.
+        candidates.extend(
+            derived.glob(
+                "cmux-*/Build/Products/Debug/cmux.app/Contents/Resources/bin/cmux"
+            ),
+        )
+        candidates.extend(
+            derived.glob(
+                "cmux-*/Build/Products/Release/cmux.app/Contents/Resources/bin/cmux"
+            ),
+        )
+    return candidates
+
+
+def discover_cmux_cli(explicit_path: Path | None = None) -> Path:
+    """Resolve the cmux CLI binary path.
+
+    Args:
+        explicit_path: if set (e.g., via CMUX_MCP_CLI_PATH env), use directly.
+
+    Returns:
+        Path to a verified cmux binary.
+
+    Raises:
+        CmuxBinaryNotFoundError: when no candidate is found.
+    """
+    env_override = os.environ.get("CMUX_MCP_CLI_PATH")
+    candidates: list[Path] = []
+    if explicit_path is not None:
+        candidates.append(explicit_path)
+    elif env_override:
+        candidates.append(Path(env_override))
+    candidates.extend(_candidate_paths())
+
+    for path in candidates:
+        if path.exists() and path.is_file() and os.access(path, os.X_OK):
+            return path
+
+    probed = "\n  ".join(str(p) for p in candidates)
+    raise CmuxBinaryNotFoundError(
+        f"cmux CLI binary not found. Probed paths:\n  {probed}\n"
+        "Set CMUX_MCP_CLI_PATH or install cmux from https://cmux.com/"
+    )
+
+
+__all__ = ["discover_cmux_cli"]