scitex 2.13.0__py3-none-any.whl → 2.15.1__py3-none-any.whl

scitex/capture/_mcp/tool_schemas.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-15
+# File: src/scitex/capture/_mcp/tool_schemas.py
+# ----------------------------------------
+
+"""Tool schemas for the scitex-capture MCP server."""
+
+from __future__ import annotations
+
+import mcp.types as types
+
+__all__ = ["get_tool_schemas"]
+
+
+def get_tool_schemas() -> list[types.Tool]:
+    """Return all tool schemas for the MCP server."""
+    return [
+        # Capture tools
+        types.Tool(
+            name="capture_screenshot",
+            description=(
+                "Capture screenshot - monitor, window, browser, or everything "
+                "including Windows screens from WSL"
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "message": {
+                        "type": "string",
+                        "description": "Optional message to include in filename",
+                    },
+                    "monitor_id": {
+                        "type": "integer",
+                        "description": "Monitor number (0-based, default: 0 for primary monitor)",
+                        "default": 0,
+                    },
+                    "all": {
+                        "type": "boolean",
+                        "description": "Capture all monitors (shorthand)",
+                        "default": False,
+                    },
+                    "app": {
+                        "type": "string",
+                        "description": "App name to capture (e.g., 'chrome', 'code')",
+                    },
+                    "url": {
+                        "type": "string",
+                        "description": "URL to capture (e.g., '127.0.0.1:8000' or 'http://localhost:3000')",
+                    },
+                    "quality": {
+                        "type": "integer",
+                        "description": "JPEG quality (1-100, default: 85)",
+                        "minimum": 1,
+                        "maximum": 100,
+                        "default": 85,
+                    },
+                    "return_base64": {
+                        "type": "boolean",
+                        "description": "Return screenshot as base64 string",
+                        "default": False,
+                    },
+                },
+            },
+        ),
+        types.Tool(
+            name="start_monitoring",
+            description="Start continuous screenshot monitoring at regular intervals",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "interval": {
+                        "type": "number",
+                        "description": "Seconds between captures (default: 1.0)",
+                        "minimum": 0.1,
+                        "default": 1,
+                    },
+                    "monitor_id": {
+                        "type": "integer",
+                        "description": "Monitor number (0-based, default: 0 for primary monitor)",
+                        "default": 0,
+                    },
+                    "capture_all": {
+                        "type": "boolean",
+                        "description": "Capture all monitors combined into single image (overrides monitor_id)",
+                        "default": False,
+                    },
+                    "output_dir": {
+                        "type": "string",
+                        "description": "Directory for screenshots (default: ~/.scitex/capture)",
+                    },
+                    "quality": {
+                        "type": "integer",
+                        "description": "JPEG quality (1-100, default: 60)",
+                        "minimum": 1,
+                        "maximum": 100,
+                        "default": 60,
+                    },
+                    "verbose": {
+                        "type": "boolean",
+                        "description": "Show capture messages",
+                        "default": True,
+                    },
+                },
+            },
+        ),
+        types.Tool(
+            name="stop_monitoring",
+            description="Stop continuous screenshot monitoring",
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        types.Tool(
+            name="get_monitoring_status",
+            description="Get current monitoring status and statistics",
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        types.Tool(
+            name="analyze_screenshot",
+            description="Analyze a screenshot for error indicators (stdout/stderr categorization)",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Path to screenshot to analyze",
+                    },
+                },
+                "required": ["path"],
+            },
+        ),
+        types.Tool(
+            name="list_recent_screenshots",
+            description="List recent screenshots from cache",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum number of screenshots to list",
+                        "minimum": 1,
+                        "maximum": 100,
+                        "default": 10,
+                    },
+                    "category": {
+                        "type": "string",
+                        "description": "Filter by category (stdout/stderr)",
+                        "enum": ["stdout", "stderr", "all"],
+                        "default": "all",
+                    },
+                },
+            },
+        ),
+        types.Tool(
+            name="clear_cache",
+            description="Clear screenshot cache or manage cache size",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "max_size_gb": {
+                        "type": "number",
+                        "description": "Keep cache under this size in GB (removes oldest files)",
+                        "minimum": 0.001,
+                        "default": 1,
+                    },
+                    "clear_all": {
+                        "type": "boolean",
+                        "description": "Remove all cached screenshots",
+                        "default": False,
+                    },
+                },
+            },
+        ),
+        types.Tool(
+            name="create_gif",
+            description="Create an animated GIF from screenshots to summarize sessions or workflows",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "session_id": {
+                        "type": "string",
+                        "description": "Session ID to create GIF from (e.g., '20250823_104523'). Use 'latest' for most recent session.",
+                    },
+                    "image_paths": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "List of image file paths to create GIF from (alternative to session_id)",
+                    },
+                    "pattern": {
+                        "type": "string",
+                        "description": "Glob pattern for images to include (alternative to session_id/image_paths)",
+                    },
+                    "output_path": {
+                        "type": "string",
+                        "description": "Output GIF file path (auto-generated if not specified)",
+                    },
+                    "duration": {
+                        "type": "number",
+                        "description": "Duration per frame in seconds (default: 0.5)",
+                        "minimum": 0.1,
+                        "maximum": 5,
+                        "default": 0.5,
+                    },
+                    "optimize": {
+                        "type": "boolean",
+                        "description": "Optimize GIF for smaller file size (default: true)",
+                        "default": True,
+                    },
+                    "max_frames": {
+                        "type": "integer",
+                        "description": "Maximum number of frames to include (default: no limit)",
+                        "minimum": 1,
+                        "maximum": 100,
+                    },
+                },
+            },
+        ),
+        types.Tool(
+            name="list_sessions",
+            description="List available monitoring sessions that can be converted to GIFs",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum number of sessions to list (default: 10)",
+                        "minimum": 1,
+                        "maximum": 50,
+                        "default": 10,
+                    },
+                },
+            },
+        ),
+        types.Tool(
+            name="get_info",
+            description="Enumerate all monitors, virtual desktops, and visible windows",
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        types.Tool(
+            name="list_windows",
+            description="List all visible windows with their handles and process names",
+            inputSchema={"type": "object", "properties": {}},
+        ),
+        types.Tool(
+            name="capture_window",
+            description="Capture a specific window by its handle",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "window_handle": {
+                        "type": "integer",
+                        "description": "Window handle from list_windows",
+                    },
+                    "output_path": {
+                        "type": "string",
+                        "description": "Optional output path for screenshot",
+                    },
+                    "quality": {
+                        "type": "integer",
+                        "description": "JPEG quality (1-100, default: 85)",
+                        "minimum": 1,
+                        "maximum": 100,
+                        "default": 85,
+                    },
+                },
+                "required": ["window_handle"],
+            },
+        ),
+    ]
+
+
+# EOF

scitex/cli/__init__.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
 """
 SciTeX CLI - Command-line interface for SciTeX platform
 
@@ -12,6 +11,49 @@ Provides unified interface for:
 - Project operations (integrated workflows)
 """
 
+import click
+
 from .main import cli
 
-__all__ = ["cli"]
+
+def print_help_recursive(ctx, group: click.Group) -> None:
+    """Print help for a group and all its subcommands.
+
+    Args:
+        ctx: The click context
+        group: The click group to print help for
+    """
+    # Create a fake parent context to show correct command path in Usage
+    fake_parent = click.Context(click.Group(), info_name="scitex")
+    parent_ctx = click.Context(group, info_name=group.name, parent=fake_parent)
+
+    click.secho(f"━━━ scitex {group.name} ━━━", fg="cyan", bold=True)
+    click.echo(group.get_help(parent_ctx))
+
+    for name in sorted(group.list_commands(ctx) or []):
+        cmd = group.get_command(ctx, name)
+        if cmd is None:
+            continue
+        click.echo()
+        click.secho(f"━━━ scitex {group.name} {name} ━━━", fg="cyan", bold=True)
+        with click.Context(cmd, info_name=name, parent=parent_ctx) as sub_ctx:
+            click.echo(cmd.get_help(sub_ctx))
+            # Handle nested subgroups
+            if isinstance(cmd, click.Group):
+                for sub_name in sorted(cmd.list_commands(sub_ctx) or []):
+                    sub_cmd = cmd.get_command(sub_ctx, sub_name)
+                    if sub_cmd is None:
+                        continue
+                    click.echo()
+                    click.secho(
+                        f"━━━ scitex {group.name} {name} {sub_name} ━━━",
+                        fg="cyan",
+                        bold=True,
+                    )
+                    with click.Context(
+                        sub_cmd, info_name=sub_name, parent=sub_ctx
+                    ) as sub_sub_ctx:
+                        click.echo(sub_cmd.get_help(sub_sub_ctx))
+
+
+__all__ = ["cli", "print_help_recursive"]

scitex/cli/audio.py

@@ -10,8 +10,13 @@ import sys
 import click
 
 
-@click.group(context_settings={"help_option_names": ["-h", "--help"]})
-def audio():
+@click.group(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    invoke_without_command=True,
+)
+@click.option("--help-recursive", is_flag=True, help="Show help for all subcommands")
+@click.pass_context
+def audio(ctx, help_recursive):
     """
     Text-to-speech utilities
 
@@ -28,7 +33,13 @@ def audio():
       scitex audio backends              # List available backends
       scitex audio check                 # Check audio status (WSL)
     """
-    pass
+    if help_recursive:
+        from . import print_help_recursive
+
+        print_help_recursive(ctx, audio)
+        ctx.exit(0)
+    elif ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
 
 
 @audio.command()
@@ -229,5 +240,141 @@ def stop():
         sys.exit(1)
 
 
+@audio.command()
+@click.option(
+    "-t",
+    "--transport",
+    type=click.Choice(["stdio", "sse", "http"]),
+    default="stdio",
+    help="Transport protocol (default: stdio)",
+)
+@click.option(
+    "--host",
+    default="0.0.0.0",
+    help="Host for HTTP/SSE transport (default: 0.0.0.0)",
+)
+@click.option(
+    "--port",
+    default=31293,
+    type=int,
+    help="Port for HTTP/SSE transport (default: 31293)",
+)
+def serve(transport, host, port):
+    """
+    Run MCP server for remote audio playback
+
+    Enables remote agents (via SSH) to play audio on local speakers.
+
+    \b
+    Transports:
+      stdio  - Standard I/O (Claude Desktop, default)
+      sse    - Server-Sent Events
+      http   - HTTP Streamable
+
+    \b
+    Examples:
+      # Local stdio (Claude Desktop)
+      scitex audio serve
+
+      # HTTP server for remote agents
+      scitex audio serve -t http --port 31293
+
+      # SSE server
+      scitex audio serve -t sse --port 31293
+
+    \b
+    Remote Setup:
+      1. Local:  scitex audio serve -t http --port 31293
+      2. SSH:    Add to ~/.ssh/config:
+                   LocalForward 31293 127.0.0.1:31293
+      3. Remote MCP config:
+                   {"type": "sse", "url": "http://localhost:31293/sse"}
+    """
+    try:
+        from scitex.audio.mcp_server import FASTMCP_AVAILABLE, run_server
+
+        if not FASTMCP_AVAILABLE:
+            click.secho("Error: fastmcp not installed", fg="red", err=True)
+            click.echo("\nInstall with:")
+            click.echo("  pip install fastmcp")
+            sys.exit(1)
+
+        if transport != "stdio":
+            click.secho(f"Starting scitex-audio MCP server ({transport})", fg="cyan")
+            click.echo(f"  Host: {host}")
+            click.echo(f"  Port: {port}")
+            click.echo()
+            click.echo("Remote agents can connect via SSH tunnel:")
+            click.echo(f"  ssh -L {port}:localhost:{port} <this-host>")
+            click.echo()
+
+        run_server(transport=transport, host=host, port=port)
+
+    except ImportError as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        click.echo("\nInstall dependencies:")
+        click.echo("  pip install fastmcp")
+        sys.exit(1)
+    except Exception as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+
+
+@audio.command()
+@click.option(
+    "--host",
+    default="0.0.0.0",
+    help="Host to bind (default: 0.0.0.0)",
+)
+@click.option(
+    "--port",
+    default=31293,
+    type=int,
+    help="Port to bind (default: 31293)",
+)
+def relay(host, port):
+    """
+    Run simple HTTP relay server for remote audio playback
+
+    Unlike 'serve' (MCP server), this exposes simple REST endpoints
+    that remote agents can POST to for audio playback.
+
+    \b
+    Endpoints:
+      POST /speak        - Play text-to-speech
+      GET  /health       - Health check
+      GET  /list_backends - List available backends
+
+    \b
+    Example:
+      # On your local machine (where you want audio)
+      scitex audio relay --port 31293
+
+      # On remote server, set env var
+      export SCITEX_AUDIO_RELAY_URL=http://YOUR_LOCAL_IP:31293
+
+      # Or use SSH reverse tunnel
+      ssh -R 31293:localhost:31293 remote-server
+    """
+    try:
+        from scitex.audio.mcp_server import run_relay_server
+
+        click.secho(f"Starting audio relay server", fg="cyan")
+        click.echo(f"  Host: {host}")
+        click.echo(f"  Port: {port}")
+        click.echo()
+        click.echo("Endpoints:")
+        click.echo("  POST /speak       - Play text-to-speech")
+        click.echo("  GET  /health      - Health check")
+        click.echo("  GET  /list_backends - List backends")
+        click.echo()
+
+        run_relay_server(host=host, port=port)
+
+    except Exception as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+
+
 if __name__ == "__main__":
     audio()