forbin-mcp 0.1.0__py3-none-any.whl

forbin/__init__.py

@@ -0,0 +1,36 @@
+from .cli import main as main, interactive_session as interactive_session
+from .client import (
+    connect_to_mcp_server as connect_to_mcp_server,
+    connect_and_list_tools as connect_and_list_tools,
+    wake_up_server as wake_up_server,
+    MCPSession as MCPSession,
+)
+from .tools import (
+    list_tools as list_tools,
+    call_tool as call_tool,
+    get_tool_parameters as get_tool_parameters,
+)
+from .display import (
+    display_tools as display_tools,
+    display_tool_header as display_tool_header,
+    display_tool_menu as display_tool_menu,
+    display_tool_schema as display_tool_schema,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "main",
+    "interactive_session",
+    "connect_to_mcp_server",
+    "connect_and_list_tools",
+    "wake_up_server",
+    "MCPSession",
+    "list_tools",
+    "call_tool",
+    "get_tool_parameters",
+    "display_tools",
+    "display_tool_header",
+    "display_tool_menu",
+    "display_tool_schema",
+]

forbin/__main__.py

@@ -0,0 +1,9 @@
+import sys
+from .cli import main
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        print("\n\nInterrupted by user. Exiting...")
+        sys.exit(0)

forbin/cli.py

@@ -0,0 +1,288 @@
+import asyncio
+import sys
+
+from rich.prompt import Prompt
+
+from . import config
+from .config import validate_config
+from .utils import setup_logging, listen_for_toggle
+from .client import connect_and_list_tools, wake_up_server
+from .tools import get_tool_parameters, call_tool
+from .display import (
+    display_tools,
+    display_tool_header,
+    display_tool_menu,
+    display_tool_schema,
+    display_logo,
+    display_config_panel,
+    display_step,
+    console,
+)
+
+
+async def test_connectivity():
+    """Test connectivity to the MCP server."""
+    # Start background listener for 'v' key toggle
+    listener_task = asyncio.create_task(listen_for_toggle())
+    mcp_session = None
+    try:
+        display_logo()
+        display_config_panel(config.MCP_SERVER_URL, config.MCP_HEALTH_URL)
+
+        # Determine total steps
+        total_steps = 2 if config.MCP_HEALTH_URL else 1
+        current_step = 1
+
+        # Step 1: Wake up server if health URL is configured
+        if config.MCP_HEALTH_URL:
+            display_step(current_step, total_steps, "WAKING UP SERVER", "in_progress")
+            is_awake = await wake_up_server(config.MCP_HEALTH_URL, max_attempts=6, wait_seconds=5)
+
+            if not is_awake:
+                console.print("[bold red]  Failed to wake up server[/bold red]\n")
+                return
+
+            display_step(current_step, total_steps, "WAKING UP SERVER", "success", update=True)
+
+            # Wait for MCP server to initialize (shorter wait like working example)
+            with console.status(
+                "  [dim]Waiting for server initialization (5s)...[/dim]", spinner="dots"
+            ):
+                await asyncio.sleep(5)
+
+            console.print()
+            current_step += 1
+
+        # Step 2: Connect to MCP server AND list tools in one operation
+        # (This avoids session expiry between connect and list_tools)
+        display_step(current_step, total_steps, "CONNECTING AND LISTING TOOLS", "in_progress")
+        mcp_session, tools = await connect_and_list_tools(max_attempts=3, wait_seconds=5)
+
+        if not mcp_session:
+            console.print("[bold red]  Failed to connect to MCP server[/bold red]\n")
+            console.print("[yellow]This may indicate:[/yellow]")
+            console.print("  - The MCP server is not properly configured")
+            console.print("  - The server endpoint URL is incorrect")
+            console.print("  - The server is returning errors for MCP requests")
+            return
+
+        display_step(
+            current_step, total_steps, "CONNECTING AND LISTING TOOLS", "success", update=True
+        )
+        console.print()
+        console.print(
+            f"[bold green]Test complete![/bold green] Server has [bold cyan]{len(tools)}[/bold cyan] tools available"
+        )
+        console.print()
+
+    finally:
+        # Cancel the listener task when exiting
+        listener_task.cancel()
+        try:
+            await listener_task
+        except asyncio.CancelledError:
+            pass
+        # Clean up MCP session
+        if mcp_session:
+            await mcp_session.cleanup()
+
+
+async def interactive_session():
+    """Run an interactive session to explore and test MCP tools."""
+    validate_config()
+    setup_logging()
+
+    # Start background listener for 'v' key toggle during setup
+    listener_task = asyncio.create_task(listen_for_toggle())
+    mcp_session = None
+
+    try:
+        # Display logo and configuration
+        display_logo()
+        display_config_panel(config.MCP_SERVER_URL, config.MCP_HEALTH_URL)
+
+        # Determine total steps
+        total_steps = 2 if config.MCP_HEALTH_URL else 1
+        current_step = 1
+
+        # Step 1: Wake up server if health URL is configured
+        if config.MCP_HEALTH_URL:
+            display_step(current_step, total_steps, "WAKING UP SERVER", "in_progress")
+            is_awake = await wake_up_server(config.MCP_HEALTH_URL, max_attempts=6, wait_seconds=5)
+
+            if not is_awake:
+                console.print(
+                    "[bold red]  Failed to wake up server after all attempts[/bold red]\n"
+                )
+                return
+
+            display_step(current_step, total_steps, "WAKING UP SERVER", "success", update=True)
+
+            # Wait for MCP server to initialize (shorter wait like working example)
+            with console.status(
+                "  [dim]Waiting for server initialization (5s)...[/dim]", spinner="dots"
+            ):
+                await asyncio.sleep(5)
+
+            console.print()
+            current_step += 1
+
+        # Step 2: Connect to MCP server AND list tools in one operation
+        # (This avoids session expiry between connect and list_tools)
+        display_step(current_step, total_steps, "CONNECTING AND LISTING TOOLS", "in_progress")
+        mcp_session, tools = await connect_and_list_tools(max_attempts=3, wait_seconds=5)
+
+        if not mcp_session:
+            console.print("[bold red]  Failed to connect to MCP server[/bold red]\n")
+            console.print("[yellow]This may indicate:[/yellow]")
+            console.print("  - The MCP server is not properly configured")
+            console.print("  - The server endpoint URL is incorrect")
+            console.print("  - The server is returning errors for MCP requests")
+            return
+
+        display_step(
+            current_step, total_steps, "CONNECTING AND LISTING TOOLS", "success", update=True
+        )
+        console.print()
+
+        if not tools:
+            console.print("[yellow]No tools available on this server.[/yellow]")
+            return
+
+        # Stop background listener before entering interactive loop
+        # The interactive loop handles 'v' key itself
+        listener_task.cancel()
+        try:
+            await listener_task
+        except asyncio.CancelledError:
+            pass
+
+        # Main interaction loop - Tool List View
+        running = True
+        while running:
+            display_tools(tools)
+
+            console.print("[bold underline]Commands:[/bold underline]")
+            console.print("  [bold cyan]number[/bold cyan] - Select a tool")
+            console.print(
+                "  [bold cyan]v[/bold cyan]      - Toggle verbose logging (current: {})".format(
+                    "[green]ON[/green]" if config.VERBOSE else "[red]OFF[/red]"
+                )
+            )
+            console.print("  [bold cyan]q[/bold cyan]      - Quit")
+            console.print()
+
+            choice = Prompt.ask("Select tool").strip().lower()
+
+            if choice in ("quit", "q", "exit"):
+                console.print("\n[bold yellow]Exiting...[/bold yellow]")
+                break
+
+            if choice == "v":
+                config.VERBOSE = not config.VERBOSE
+                status = (
+                    "[bold green]ON[/bold green]" if config.VERBOSE else "[bold red]OFF[/bold red]"
+                )
+                console.print(f"\n[bold cyan]Verbose logging toggled {status}[/bold cyan]\n")
+                continue
+
+            # Try to parse as tool number
+            try:
+                tool_num = int(choice)
+                if 1 <= tool_num <= len(tools):
+                    selected_tool = tools[tool_num - 1]
+
+                    # Enter Tool View loop
+                    while True:
+                        display_tool_header(selected_tool)
+                        display_tool_menu()
+
+                        tool_choice = Prompt.ask("Choose option").strip().lower()
+
+                        if tool_choice in ("d", "details", "1"):
+                            # View details
+                            display_tool_schema(selected_tool)
+
+                        elif tool_choice in ("r", "run", "2"):
+                            # Run tool
+                            params = get_tool_parameters(selected_tool)
+                            await call_tool(mcp_session, selected_tool, params)
+
+                        elif tool_choice in ("b", "back", "3"):
+                            # Back to tool list
+                            break
+
+                        elif tool_choice in ("q", "quit", "exit"):
+                            # Quit entirely
+                            console.print("\n[bold yellow]Exiting...[/bold yellow]")
+                            running = False
+                            break
+
+                        elif tool_choice == "v":
+                            config.VERBOSE = not config.VERBOSE
+                            status = (
+                                "[bold green]ON[/bold green]"
+                                if config.VERBOSE
+                                else "[bold red]OFF[/bold red]"
+                            )
+                            console.print(
+                                f"\n[bold cyan]Verbose logging toggled {status}[/bold cyan]\n"
+                            )
+
+                        else:
+                            console.print(
+                                "[red]Invalid option. Use 'd' for details, 'r' to run, 'b' to go back, or 'q' to quit.[/red]\n"
+                            )
+                else:
+                    console.print(
+                        f"[red]Invalid tool number. Choose between 1 and {len(tools)}[/red]\n"
+                    )
+            except ValueError:
+                console.print("[red]Invalid choice. Enter a tool number or 'q' to quit.[/red]\n")
+
+    finally:
+        # Ensure listener is cancelled if we exit early
+        if not listener_task.done():
+            listener_task.cancel()
+            try:
+                await listener_task
+            except asyncio.CancelledError:
+                pass
+
+        # Clean up MCP session
+        if mcp_session:
+            await mcp_session.cleanup()
+
+
+async def async_main():
+    """Async main entry point."""
+    setup_logging()
+
+    try:
+        # Check for command line arguments
+        if len(sys.argv) > 1:
+            if sys.argv[1] in ("--test", "-t"):
+                await test_connectivity()
+                return
+            elif sys.argv[1] in ("--help", "-h"):
+                display_logo()
+                console.print("\n[bold]Usage:[/bold]")
+                console.print("  forbin           Run interactive session")
+                console.print("  forbin --test    Test connectivity only")
+                console.print("  forbin --help    Show this help message")
+                console.print("\n[bold]Configuration:[/bold]")
+                console.print("  Set MCP_SERVER_URL, MCP_TOKEN, and optionally MCP_HEALTH_URL")
+                console.print("  in a .env file (see .env.example)")
+                console.print("\n[bold]Interactive Shortcuts:[/bold]")
+                console.print("  [bold cyan]'v'[/bold cyan] - Toggle verbose logging at any time")
+                return
+
+        # Run interactive session by default
+        await interactive_session()
+    except asyncio.CancelledError:
+        pass
+
+
+def main():
+    """Synchronous entry point for CLI."""
+    asyncio.run(async_main())

forbin/client.py

@@ -0,0 +1,232 @@
+import asyncio
+from typing import Optional
+import httpx
+from fastmcp.client import Client
+from fastmcp.client.auth import BearerAuth
+
+from . import config
+from .display import console
+
+
+class MCPSession:
+    """Wrapper to hold both the client and session for proper lifecycle management."""
+
+    def __init__(self, client: Client, session):
+        self.client = client
+        self.session = session
+
+    async def list_tools(self):
+        """List available tools from the MCP server."""
+        return await self.session.list_tools()
+
+    async def call_tool(self, name: str, arguments: dict):
+        """Call a tool with the given arguments."""
+        return await self.session.call_tool(name, arguments)
+
+    async def cleanup(self):
+        """Close the MCP session."""
+        if self.client:
+            try:
+                await self.client.__aexit__(None, None, None)
+            except Exception:
+                # Suppress session termination errors (these are harmless cleanup warnings)
+                pass
+
+
+async def wake_up_server(health_url: str, max_attempts: int = 6, wait_seconds: float = 5) -> bool:
+    """
+    Wake up a suspended server by calling the health endpoint.
+    Useful for Fly.io and other platforms that suspend inactive services.
+
+    Args:
+        health_url: The health endpoint URL
+        max_attempts: Maximum number of health check attempts
+        wait_seconds: Seconds to wait between attempts
+
+    Returns:
+        True if server is awake, False otherwise
+    """
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        with console.status("  [dim]Polling health endpoint...[/dim]", spinner="dots") as status:
+            for attempt in range(1, max_attempts + 1):
+                try:
+                    status.update(f"  [dim]Attempt {attempt}/{max_attempts}...[/dim]")
+                    response = await client.get(health_url)
+
+                    if response.status_code == 200:
+                        return True
+                    else:
+                        if attempt == max_attempts:
+                            console.print(
+                                f"  [yellow]Server responded with status {response.status_code}[/yellow]"
+                            )
+
+                except (httpx.ConnectError, httpx.TimeoutException) as e:
+                    if config.VERBOSE or attempt == max_attempts:
+                        error_msg = f"  [yellow]Connection failed: {type(e).__name__}[/yellow]"
+                        if config.VERBOSE:
+                            error_msg += f" [dim]({str(e)})[/dim]"
+                        console.print(error_msg)
+                except Exception as e:
+                    if config.VERBOSE or attempt == max_attempts:
+                        console.print(f"  [red]Unexpected error: {e}[/red]")
+
+                if attempt < max_attempts:
+                    await asyncio.sleep(wait_seconds)
+
+    return False
+
+
+async def connect_to_mcp_server(
+    max_attempts: int = 3, wait_seconds: float = 5
+) -> Optional[MCPSession]:
+    """
+    Connect to the MCP server with retry logic.
+
+    Args:
+        max_attempts: Maximum connection attempts
+        wait_seconds: Seconds to wait between attempts
+
+    Returns:
+        MCPSession instance or None if failed
+    """
+    server_url = config.MCP_SERVER_URL or ""
+    token = config.MCP_TOKEN or ""
+
+    with console.status("  [dim]Establishing connection...[/dim]", spinner="dots") as status:
+        for attempt in range(1, max_attempts + 1):
+            client = None
+            try:
+                status.update(f"  [dim]Attempt {attempt}/{max_attempts}...[/dim]")
+
+                client = Client(
+                    server_url,
+                    auth=BearerAuth(token=token),
+                    init_timeout=30.0,  # Extended timeout for cold starts
+                    timeout=600.0,  # Wait up to 10 minutes for tool operations
+                )
+
+                # Enter the client context and capture the session
+                session = await client.__aenter__()
+                return MCPSession(client, session)
+
+            except asyncio.TimeoutError:
+                if config.VERBOSE or attempt == max_attempts:
+                    console.print("  [red]Timeout (server not responding)[/red]")
+                # Clean up partial connection
+                if client:
+                    try:
+                        await client.__aexit__(None, None, None)
+                    except Exception:
+                        pass
+                if attempt < max_attempts:
+                    await asyncio.sleep(wait_seconds)
+            except Exception as e:
+                error_name = type(e).__name__
+                if config.VERBOSE or attempt == max_attempts:
+                    if "BrokenResourceError" in error_name or "ClosedResourceError" in error_name:
+                        console.print("  [yellow]Connection error (server not ready)[/yellow]")
+                    else:
+                        console.print(f"  [red]{error_name}: {e}[/red]")
+
+                    if config.VERBOSE and not (
+                        "BrokenResourceError" in error_name or "ClosedResourceError" in error_name
+                    ):
+                        import traceback
+
+                        console.print(f"[dim]{traceback.format_exc()}[/dim]")
+
+                # Clean up partial connection
+                if client:
+                    try:
+                        await client.__aexit__(None, None, None)
+                    except Exception:
+                        pass
+
+                if attempt < max_attempts:
+                    await asyncio.sleep(wait_seconds)
+
+    return None
+
+
+async def connect_and_list_tools(
+    max_attempts: int = 3, wait_seconds: float = 5
+) -> tuple[Optional[MCPSession], list]:
+    """
+    Connect to MCP server AND list tools in a single retry loop.
+
+    This combines connection and tool listing to avoid session expiry
+    between the two operations.
+
+    Args:
+        max_attempts: Maximum connection attempts
+        wait_seconds: Seconds to wait between attempts
+
+    Returns:
+        Tuple of (MCPSession instance or None, list of tools)
+    """
+    server_url = config.MCP_SERVER_URL or ""
+    token = config.MCP_TOKEN or ""
+
+    with console.status("  [dim]Establishing connection...[/dim]", spinner="dots") as status:
+        for attempt in range(1, max_attempts + 1):
+            client = None
+            try:
+                status.update(f"  [dim]Attempt {attempt}/{max_attempts}...[/dim]")
+
+                client = Client(
+                    server_url,
+                    auth=BearerAuth(token=token),
+                    init_timeout=30.0,  # Extended timeout for cold starts
+                    timeout=600.0,  # Wait up to 10 minutes for tool operations
+                )
+
+                # Enter the client context and capture the session
+                session = await client.__aenter__()
+                mcp_session = MCPSession(client, session)
+
+                # Immediately list tools while session is fresh
+                status.update(
+                    f"  [dim]Retrieving tools (attempt {attempt}/{max_attempts})...[/dim]"
+                )
+                tools = await asyncio.wait_for(mcp_session.list_tools(), timeout=15.0)
+
+                return mcp_session, tools
+
+            except asyncio.TimeoutError:
+                if config.VERBOSE or attempt == max_attempts:
+                    console.print("  [red]Timeout (server not responding)[/red]")
+                # Clean up partial connection
+                if client:
+                    try:
+                        await client.__aexit__(None, None, None)
+                    except Exception:
+                        pass
+                if attempt < max_attempts:
+                    await asyncio.sleep(wait_seconds)
+            except Exception as e:
+                error_name = type(e).__name__
+                if config.VERBOSE or attempt == max_attempts:
+                    if "BrokenResourceError" in error_name or "ClosedResourceError" in error_name:
+                        console.print("  [yellow]Connection error (server not ready)[/yellow]")
+                    else:
+                        console.print(f"  [red]{error_name}: {e}[/red]")
+
+                    if config.VERBOSE and not (
+                        "BrokenResourceError" in error_name or "ClosedResourceError" in error_name
+                    ):
+                        import traceback
+
+                        console.print(f"[dim]{traceback.format_exc()}[/dim]")
+
+                # Clean up partial connection
+                if client:
+                    try:
+                        await client.__aexit__(None, None, None)
+                    except Exception:
+                        pass
+
+                if attempt < max_attempts:
+                    await asyncio.sleep(wait_seconds)
+
+    return None, []

forbin/config.py

@@ -0,0 +1,28 @@
+import os
+import sys
+from dotenv import load_dotenv
+
+from typing import Optional
+
+# Load environment variables from .env file
+load_dotenv()
+
+# Get configuration from environment variables
+MCP_SERVER_URL: Optional[str] = os.getenv("MCP_SERVER_URL")
+MCP_HEALTH_URL: Optional[str] = os.getenv("MCP_HEALTH_URL")
+MCP_TOKEN: Optional[str] = os.getenv("MCP_TOKEN")
+
+# Runtime flags
+VERBOSE: bool = False
+
+
+def validate_config():
+    """Validate required environment variables."""
+    if not MCP_SERVER_URL:
+        print("Error: MCP_SERVER_URL environment variable is required")
+        print("Please create a .env file (see .env.example for template)")
+        sys.exit(1)
+    if not MCP_TOKEN:
+        print("Error: MCP_TOKEN environment variable is required")
+        print("Please create a .env file (see .env.example for template)")
+        sys.exit(1)