mcp-huddle 0.3.0__py3-none-any.whl

mcp_huddle/__init__.py

@@ -0,0 +1,2 @@
+"""mcp-huddle — persistent multi-agent chat MCP server."""
+__version__ = "0.3.0"

mcp_huddle/__main__.py

@@ -0,0 +1,193 @@
+"""Entry point for `python -m mcp_huddle` and the `mcp-huddle` console script.
+
+Two modes:
+  default   stdio transport — for MCP clients (Claude Code, Codex, Antigravity,
+            Claude Desktop). Spawned per-client; storage in ~/.mcp-huddle/rooms/
+            is shared across processes via file locks.
+  --http    HTTP server + Liquid Glass dashboard on :8014. Run once manually
+            to watch rooms in a browser. Dashboard is the only difference —
+            the MCP tools are the same.
+"""
+import argparse
+import os
+import socket
+import sys
+
+DEFAULT_PORT = 8014
+
+
+def _version() -> str:
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+
+        try:
+            return version("mcp-huddle")
+        except PackageNotFoundError:
+            pass
+    except Exception:
+        pass
+    try:
+        from . import __version__
+
+        return __version__
+    except Exception:
+        return "unknown"
+
+
+def _resolve_port(cli_port: "int | None") -> int:
+    """Resolve the HTTP port from --port, then $PORT, then the default.
+
+    An invalid value never crashes: it prints a clear warning and falls back
+    to the default port.
+    """
+    if cli_port is not None:
+        # argparse already validated/typed this.
+        return cli_port
+
+    raw = os.environ.get("PORT")
+    if raw is None or raw == "":
+        return DEFAULT_PORT
+    try:
+        port = int(raw)
+    except (TypeError, ValueError):
+        print(
+            f"warning: invalid PORT={raw!r}, using default {DEFAULT_PORT}",
+            file=sys.stderr,
+            flush=True,
+        )
+        return DEFAULT_PORT
+    if not (1 <= port <= 65535):
+        print(
+            f"warning: PORT={port} out of range 1-65535, using default {DEFAULT_PORT}",
+            file=sys.stderr,
+            flush=True,
+        )
+        return DEFAULT_PORT
+    return port
+
+
+def _port_arg(value: str) -> int:
+    try:
+        port = int(value)
+    except (TypeError, ValueError):
+        raise argparse.ArgumentTypeError(f"invalid port {value!r}: must be an integer")
+    if not (1 <= port <= 65535):
+        raise argparse.ArgumentTypeError(f"port {port} out of range 1-65535")
+    return port
+
+
+def _install_hooks(dest: "str | None") -> None:
+    """Copy the bundled example hooks (Claude Code PostToolUse / Stop) to a
+    directory and print how to wire them in. pip can't run post-install code
+    safely, so this is the explicit opt-in step a user runs after installing.
+    """
+    import shutil
+    from pathlib import Path
+
+    src_dir = Path(__file__).parent / "hooks"
+    target = Path(dest).expanduser() if dest else (Path.home() / ".mcp-huddle" / "hooks")
+    target.mkdir(parents=True, exist_ok=True)
+    copied = []
+    for sh in sorted(src_dir.glob("*.sh")):
+        out = target / sh.name
+        shutil.copyfile(sh, out)
+        out.chmod(0o755)
+        copied.append(out)
+    print(f"Installed {len(copied)} hook(s) to {target}:")
+    for c in copied:
+        print(f"  {c}")
+    example = """
+Wire them into Claude Code (~/.claude/settings.json), e.g.:
+  "hooks": {
+    "PostToolUse": [{"hooks": [{"type":"command","command":"__T__/claude-check.sh"}]}],
+    "Stop":        [{"hooks": [{"type":"command","command":"__T__/session-end.sh"}]}]
+  }
+claude-check.sh surfaces pending huddle requests; session-end.sh closes this session's rooms on exit."""
+    print(example.replace("__T__", str(target)))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="mcp-huddle",
+        description=(
+            "Persistent multi-agent coordination rooms over MCP. "
+            "Default mode is stdio transport for MCP clients; --http serves a "
+            "browser dashboard."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"mcp-huddle {_version()}",
+    )
+    parser.add_argument(
+        "--http",
+        action="store_true",
+        help="run the HTTP server + dashboard instead of stdio transport",
+    )
+    parser.add_argument(
+        "--install-hooks",
+        nargs="?",
+        const="",
+        default=None,
+        metavar="DIR",
+        help="copy the bundled Claude Code hooks to DIR (default ~/.mcp-huddle/hooks) and exit",
+    )
+    parser.add_argument(
+        "--port",
+        type=_port_arg,
+        default=None,
+        help=f"HTTP port (default: $PORT or {DEFAULT_PORT}); only used with --http",
+    )
+    args = parser.parse_args()
+
+    if args.install_hooks is not None:
+        _install_hooks(args.install_hooks or None)
+        return
+
+    use_http = args.http or bool(os.environ.get("MCP_HUDDLE_HTTP"))
+
+    if use_http:
+        import uvicorn
+
+        from .server import build_app
+
+        host = "127.0.0.1"
+        port = _resolve_port(args.port)
+
+        # Bind first so the "ready" message only prints once we are actually
+        # listening — never advertise a URL the server failed to bind.
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            sock.bind((host, port))
+        except OSError as exc:
+            sock.close()
+            print(f"error: cannot bind {host}:{port}: {exc}", file=sys.stderr, flush=True)
+            sys.exit(1)
+        sock.listen()
+
+        print(f"mcp-huddle (HTTP + dashboard) on :{port}", flush=True)
+        print(f"Dashboard: http://{host}:{port}/dashboard", flush=True)
+
+        # One-line-per-agent discovery summary (which agents are enabled / why
+        # disabled) so the operator can see the roster at a glance.
+        try:
+            from . import spawn
+
+            spawn.log_discovery_summary()
+        except Exception:
+            pass
+
+        config = uvicorn.Config(build_app(), log_level="warning")
+        server = uvicorn.Server(config)
+        server.run(sockets=[sock])
+    else:
+        # stdio transport — JSON-RPC over stdin/stdout. Default for MCP clients.
+        from .server import mcp
+
+        mcp.run()
+
+
+if __name__ == "__main__":
+    main()

mcp_huddle/acp.py

@@ -0,0 +1,57 @@
+"""Phase 2.5 stub: Gemini ACP (Agent Client Protocol) daemon integration.
+
+ACP is JSON-RPC 2.0 over stdio. Spec: https://geminicli.com/docs/cli/acp-mode/
+
+INTENT (when implemented):
+  * Spawn `gemini --acp` once as a long-running daemon (one process per Gemini
+    identity, multiplexed across many rooms)
+  * Manage a session per room via `newSession` / `loadSession`
+  * On respond_via_agent for Gemini: send `prompt` JSON-RPC to existing daemon
+    instead of forking a new `gemini -p` process
+  * Stream events from daemon stdout back to per-room agent log files (the
+    existing SSE endpoint will pick them up unchanged)
+
+EXPECTED BENEFITS:
+  * 0ms cold start vs ~3-5s for fresh `gemini -p`
+  * Persistent per-room context without prepending huge digests
+  * Native streaming events (typing indicators, tool calls, partial responses)
+
+WHY THIS IS A STUB:
+  * ACP requires async lifecycle (start daemon, monitor health, restart on
+    crash, correlate JSON-RPC ids ↔ pending awaits)
+  * Spec details (auth flow, capabilities negotiation, session mode/model
+    overrides) need careful implementation + integration testing
+  * Risk of half-broken implementation is high; Phase 1 + Phase 2 (Codex
+    resume) already deliver the main value.
+
+NEXT STEPS for whoever picks this up:
+  1. Implement `class AcpClient` with async send/recv JSON-RPC over stdio
+  2. Add `initialize`, `newSession`, `prompt`, `cancel` method wrappers
+  3. Module-level singleton: `get_gemini_daemon()` that lazy-spawns the daemon
+  4. In server.respond_via_agent for Gemini: route to AcpClient.prompt()
+  5. Wire daemon stdout into agent log file (so SSE picks it up)
+  6. Lifecycle: tear down daemon on huddle server shutdown (lifespan context)
+  7. Tests: mock `gemini --acp` with a fake JSON-RPC responder
+
+Reference implementations:
+  * Zed: https://zed.dev/acp/agent/gemini-cli
+  * IntelliJ: https://glaforge.dev/posts/2026/02/01/...
+  * Spec: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/acp-mode.md
+"""
+
+class AcpNotImplemented(NotImplementedError):
+    """Raised when Phase 2.5 ACP integration is not yet wired up."""
+    pass
+
+
+def gemini_acp_prompt(session_id: str | None, prompt: str) -> str:
+    """Stub for Phase 2.5: send a prompt to Gemini --acp daemon.
+
+    Currently raises AcpNotImplemented. Use respond_via_agent for Codex
+    (Phase 2 Codex resume works) or a fresh `gemini -p` spawn.
+    """
+    raise AcpNotImplemented(
+        "Gemini --acp daemon integration is Phase 2.5 (not yet implemented). "
+        "Use respond_via_agent with agent_name='Codex' for resume support, "
+        "or auto_spawn={'Gemini': '<fresh brief>'} for a new process."
+    )