foundry-mcp 0.3.3__py3-none-any.whl

foundry_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""Foundry MCP - MCP server for SDD toolkit spec management."""
+
+__version__ = "0.1.0"
+
+from foundry_mcp.server import create_server, main
+
+__all__ = ["__version__", "create_server", "main"]

foundry_mcp/cli/__init__.py

@@ -0,0 +1,80 @@
+"""SDD CLI - Native command-line interface for Spec-Driven Development.
+
+This CLI provides JSON-only output designed for AI coding assistants.
+All commands emit structured JSON to stdout for reliable parsing.
+"""
+
+from foundry_mcp.cli.config import CLIContext, create_context
+from foundry_mcp.cli.flags import (
+    CLIFlagRegistry,
+    apply_cli_flag_overrides,
+    flags_for_discovery,
+    get_cli_flags,
+    with_flag_options,
+)
+from foundry_mcp.cli.logging import (
+    CLILogContext,
+    cli_command,
+    get_cli_logger,
+    get_request_id,
+    set_request_id,
+)
+from foundry_mcp.cli.main import cli
+from foundry_mcp.cli.output import emit, emit_error, emit_success
+from foundry_mcp.cli.registry import get_context, set_context
+from foundry_mcp.cli.resilience import (
+    FAST_TIMEOUT,
+    MEDIUM_TIMEOUT,
+    SLOW_TIMEOUT,
+    with_sync_timeout,
+    cli_retryable,
+    handle_keyboard_interrupt,
+)
+from foundry_mcp.cli.context import (
+    ContextSession,
+    ContextTracker,
+    get_context_tracker,
+    get_session_status,
+    record_consultation,
+    start_cli_session,
+)
+
+__all__ = [
+    # Entry point
+    "cli",
+    # Context
+    "CLIContext",
+    "create_context",
+    "get_context",
+    "set_context",
+    # Output
+    "emit",
+    "emit_error",
+    "emit_success",
+    # Feature flags
+    "CLIFlagRegistry",
+    "apply_cli_flag_overrides",
+    "flags_for_discovery",
+    "get_cli_flags",
+    "with_flag_options",
+    # Logging
+    "CLILogContext",
+    "cli_command",
+    "get_cli_logger",
+    "get_request_id",
+    "set_request_id",
+    # Resilience
+    "FAST_TIMEOUT",
+    "MEDIUM_TIMEOUT",
+    "SLOW_TIMEOUT",
+    "with_sync_timeout",
+    "cli_retryable",
+    "handle_keyboard_interrupt",
+    # Session/Context tracking
+    "ContextSession",
+    "ContextTracker",
+    "get_context_tracker",
+    "get_session_status",
+    "record_consultation",
+    "start_cli_session",
+]

foundry_mcp/cli/__main__.py

@@ -0,0 +1,9 @@
+"""SDD CLI module entry point.
+
+Enables running the CLI via: python -m foundry_mcp.cli
+"""
+
+from foundry_mcp.cli.main import cli
+
+if __name__ == "__main__":
+    cli()

foundry_mcp/cli/agent.py

@@ -0,0 +1,96 @@
+"""Agent detection and feature gating for CLI commands.
+
+Provides mechanisms to detect which AI coding assistant is running the CLI
+and gate features that are only available for specific agents.
+
+Agent types:
+- claude-code: Anthropic's Claude Code (has transcript access)
+- cursor: Cursor IDE
+- generic: Unknown/default agent
+
+Configuration:
+- Set FOUNDRY_MCP_AGENT_TYPE in MCP server config (env section)
+- The CLI inherits this from the MCP server environment
+"""
+
+import os
+from functools import wraps
+from typing import Callable, TypeVar
+
+from foundry_mcp.cli.output import emit_success
+
+# Valid agent types
+AGENT_TYPES = frozenset({"claude-code", "cursor", "generic"})
+DEFAULT_AGENT_TYPE = "generic"
+
+F = TypeVar("F", bound=Callable)
+
+
+def get_agent_type() -> str:
+    """Get the configured agent type from environment.
+
+    Set via MCP server config:
+        "env": {"FOUNDRY_MCP_AGENT_TYPE": "claude-code"}
+
+    Returns:
+        Agent type string (claude-code, cursor, generic).
+    """
+    env_agent = os.environ.get("FOUNDRY_MCP_AGENT_TYPE", "")
+    agent = env_agent.lower().strip()
+    return agent if agent in AGENT_TYPES else DEFAULT_AGENT_TYPE
+
+
+def agent_gated(required_agent: str) -> Callable[[F], F]:
+    """Decorator for agent-specific commands.
+
+    When the current agent type doesn't match the required agent,
+    returns a success response with a warning indicating the feature
+    is unavailable, rather than failing.
+
+    Args:
+        required_agent: The agent type required for this command (e.g., "claude-code").
+
+    Returns:
+        Decorated function that gates execution by agent type.
+
+    Example:
+        @session.command("token-usage")
+        @agent_gated("claude-code")
+        def token_usage_cmd():
+            # Only runs when agent_type == "claude-code"
+            ...
+    """
+
+    def decorator(f: F) -> F:
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            current_agent = get_agent_type()
+
+            if current_agent != required_agent:
+                emit_success(
+                    {
+                        "available": False,
+                        "reason": f"This feature requires agent_type='{required_agent}'",
+                        "current_agent": current_agent,
+                        "hint": f"Set FOUNDRY_MCP_AGENT_TYPE={required_agent} or configure in foundry-mcp.toml",
+                    },
+                    meta={
+                        "warning": f"Feature unavailable for agent_type='{current_agent}'"
+                    },
+                )
+                return
+
+            return f(*args, **kwargs)
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+def is_claude_code() -> bool:
+    """Check if the current agent is Claude Code.
+
+    Returns:
+        True if agent_type is "claude-code".
+    """
+    return get_agent_type() == "claude-code"

foundry_mcp/cli/commands/__init__.py

@@ -0,0 +1,37 @@
+"""CLI command groups.
+
+The CLI is organized into domain groups (e.g. `specs`, `tasks`, `test`).
+Legacy top-level aliases are intentionally not exported.
+"""
+
+from foundry_mcp.cli.commands.cache import cache
+from foundry_mcp.cli.commands.dashboard import dashboard_group
+from foundry_mcp.cli.commands.dev import dev_group
+from foundry_mcp.cli.commands.journal import journal
+from foundry_mcp.cli.commands.lifecycle import lifecycle
+from foundry_mcp.cli.commands.modify import modify_group
+from foundry_mcp.cli.commands.plan import plan_group
+from foundry_mcp.cli.commands.pr import pr_group
+from foundry_mcp.cli.commands.review import review_group
+from foundry_mcp.cli.commands.session import session
+from foundry_mcp.cli.commands.specs import specs
+from foundry_mcp.cli.commands.tasks import tasks
+from foundry_mcp.cli.commands.testing import test_group
+from foundry_mcp.cli.commands.validate import validate_group
+
+__all__ = [
+    "cache",
+    "dashboard_group",
+    "dev_group",
+    "journal",
+    "lifecycle",
+    "modify_group",
+    "plan_group",
+    "pr_group",
+    "review_group",
+    "session",
+    "specs",
+    "tasks",
+    "test_group",
+    "validate_group",
+]

foundry_mcp/cli/commands/cache.py

@@ -0,0 +1,137 @@
+"""Cache management commands for SDD CLI.
+
+Provides commands for inspecting and managing the AI consultation cache.
+"""
+
+from typing import Optional
+
+import click
+
+from foundry_mcp.cli.logging import cli_command, get_cli_logger
+from foundry_mcp.cli.output import emit_success
+from foundry_mcp.cli.resilience import (
+    FAST_TIMEOUT,
+    handle_keyboard_interrupt,
+    with_sync_timeout,
+)
+from foundry_mcp.core.cache import CacheManager, is_cache_enabled
+
+logger = get_cli_logger()
+
+
+@click.group("cache")
+def cache() -> None:
+    """AI consultation cache management."""
+    pass
+
+
+@cache.command("info")
+@click.pass_context
+@cli_command("info")
+@handle_keyboard_interrupt()
+@with_sync_timeout(FAST_TIMEOUT, "Cache info lookup timed out")
+def cache_info_cmd(ctx: click.Context) -> None:
+    """Show cache information and statistics.
+
+    Displays cache location, size, and entry counts.
+    """
+    if not is_cache_enabled():
+        emit_success(
+            {
+                "enabled": False,
+                "message": "Cache is disabled",
+                "hint": "Unset FOUNDRY_MCP_CACHE_DISABLED to enable caching",
+            }
+        )
+        return
+
+    manager = CacheManager()
+    stats = manager.get_stats()
+
+    emit_success(
+        {
+            "enabled": True,
+            **stats,
+        }
+    )
+
+
+@cache.command("clear")
+@click.option("--spec-id", help="Only clear entries for this spec ID.")
+@click.option(
+    "--review-type",
+    type=click.Choice(["fidelity", "plan"]),
+    help="Only clear entries of this review type.",
+)
+@click.pass_context
+@cli_command("clear")
+@handle_keyboard_interrupt()
+@with_sync_timeout(FAST_TIMEOUT, "Cache clear timed out")
+def cache_clear_cmd(
+    ctx: click.Context,
+    spec_id: Optional[str],
+    review_type: Optional[str],
+) -> None:
+    """Clear cache entries with optional filters.
+
+    Without filters, clears all cache entries.
+    Use --spec-id and/or --review-type to filter.
+    """
+    if not is_cache_enabled():
+        emit_success(
+            {
+                "enabled": False,
+                "entries_deleted": 0,
+                "message": "Cache is disabled",
+            }
+        )
+        return
+
+    manager = CacheManager()
+    deleted = manager.clear(spec_id=spec_id, review_type=review_type)
+
+    filters = {}
+    if spec_id:
+        filters["spec_id"] = spec_id
+    if review_type:
+        filters["review_type"] = review_type
+
+    emit_success(
+        {
+            "entries_deleted": deleted,
+            "filters": filters if filters else None,
+        }
+    )
+
+
+@cache.command("cleanup")
+@click.pass_context
+@cli_command("cleanup")
+@handle_keyboard_interrupt()
+@with_sync_timeout(FAST_TIMEOUT, "Cache cleanup timed out")
+def cache_cleanup_cmd(ctx: click.Context) -> None:
+    """Remove expired cache entries.
+
+    Cleans up entries that have exceeded their TTL.
+    """
+    if not is_cache_enabled():
+        emit_success(
+            {
+                "enabled": False,
+                "entries_removed": 0,
+                "message": "Cache is disabled",
+            }
+        )
+        return
+
+    manager = CacheManager()
+    removed = manager.cleanup_expired()
+
+    emit_success(
+        {
+            "entries_removed": removed,
+            "message": f"Removed {removed} expired entries"
+            if removed
+            else "No expired entries found",
+        }
+    )

foundry_mcp/cli/commands/dashboard.py

@@ -0,0 +1,148 @@
+"""Dashboard CLI commands.
+
+Provides commands for starting, stopping, and managing the Streamlit dashboard.
+"""
+
+import click
+
+from foundry_mcp.cli.output import emit, emit_error
+
+
+@click.group("dashboard")
+def dashboard_group() -> None:
+    """Dashboard server management commands.
+
+    Start, stop, and manage the Streamlit-based observability dashboard.
+    """
+    pass
+
+
+@dashboard_group.command("start")
+@click.option(
+    "--port",
+    "-p",
+    default=8501,
+    type=int,
+    help="Port to run dashboard on (default: 8501)",
+)
+@click.option(
+    "--host",
+    "-H",
+    default="127.0.0.1",
+    help="Host to bind to (default: 127.0.0.1 for localhost only)",
+)
+@click.option(
+    "--no-browser",
+    is_flag=True,
+    default=False,
+    help="Don't automatically open browser",
+)
+@click.pass_context
+def dashboard_start_cmd(
+    ctx: click.Context,
+    port: int,
+    host: str,
+    no_browser: bool,
+) -> None:
+    """Start the Streamlit dashboard server.
+
+    Launches the dashboard in a background process and optionally opens
+    your browser to view it.
+
+    Examples:
+        # Start with defaults (localhost:8501, opens browser)
+        foundry-cli dashboard start
+
+        # Start on custom port without browser
+        foundry-cli dashboard start --port 8080 --no-browser
+
+        # Expose to network (be careful with security)
+        foundry-cli dashboard start --host 0.0.0.0
+    """
+    try:
+        from foundry_mcp.dashboard import launch_dashboard
+
+        result = launch_dashboard(
+            host=host,
+            port=port,
+            open_browser=not no_browser,
+        )
+
+        if result.get("success"):
+            emit(
+                {
+                    "success": True,
+                    "message": result.get("message", "Dashboard started"),
+                    "url": result.get("url"),
+                    "pid": result.get("pid"),
+                }
+            )
+        else:
+            emit_error(result.get("message", "Failed to start dashboard"))
+
+    except ImportError:
+        emit_error(
+            "Dashboard dependencies not installed. "
+            "Install with: pip install foundry-mcp[dashboard]"
+        )
+    except Exception as e:
+        emit_error(f"Failed to start dashboard: {e}")
+
+
+@dashboard_group.command("stop")
+@click.pass_context
+def dashboard_stop_cmd(ctx: click.Context) -> None:
+    """Stop the running dashboard server.
+
+    Terminates the dashboard process if one is running.
+    """
+    try:
+        from foundry_mcp.dashboard import stop_dashboard
+
+        result = stop_dashboard()
+
+        if result.get("success"):
+            emit(
+                {
+                    "success": True,
+                    "message": result.get("message", "Dashboard stopped"),
+                }
+            )
+        else:
+            emit(
+                {
+                    "success": False,
+                    "message": result.get("message", "No dashboard to stop"),
+                }
+            )
+
+    except ImportError:
+        emit_error("Dashboard module not available")
+    except Exception as e:
+        emit_error(f"Failed to stop dashboard: {e}")
+
+
+@dashboard_group.command("status")
+@click.pass_context
+def dashboard_status_cmd(ctx: click.Context) -> None:
+    """Check if dashboard is running.
+
+    Shows the current status of the dashboard server process.
+    """
+    try:
+        from foundry_mcp.dashboard import get_dashboard_status
+
+        status = get_dashboard_status()
+
+        emit(
+            {
+                "running": status.get("running", False),
+                "pid": status.get("pid"),
+                "exit_code": status.get("exit_code"),
+            }
+        )
+
+    except ImportError:
+        emit({"running": False, "message": "Dashboard module not available"})
+    except Exception as e:
+        emit_error(f"Failed to get dashboard status: {e}")