forbin-mcp 0.1.0__tar.gz

forbin_mcp-0.1.0/.env.example

@@ -0,0 +1,40 @@
+# MCP Remote Tool Tester Configuration
+# Copy this file to .env and configure with your MCP server details
+
+# Required: MCP Server URL
+# This is the endpoint where your MCP server is hosted
+MCP_SERVER_URL=https://your-mcp-server.example.com/mcp
+
+# Required: Authentication Token
+# Bearer token for authenticating with the MCP server
+MCP_TOKEN=your-secret-token-here
+
+# Optional: Health Check URL
+# Used to wake up suspended services (e.g., Fly.io apps)
+# If your server doesn't suspend, you can omit this
+MCP_HEALTH_URL=https://your-mcp-server.example.com/health
+
+
+# ============================================================================
+# Example Configurations
+# ============================================================================
+
+# Local Development Server:
+# MCP_SERVER_URL=http://localhost:8000/mcp
+# MCP_TOKEN=test-token-123
+# MCP_HEALTH_URL=http://localhost:8000/health
+
+# Fly.io Production Server:
+# MCP_SERVER_URL=https://my-app.fly.dev/mcp
+# MCP_HEALTH_URL=https://my-app.fly.dev/health
+# MCP_TOKEN=prod-token-xyz
+
+# Fly.io Preview/Staging Server:
+# MCP_SERVER_URL=https://my-app-staging.fly.dev/mcp
+# MCP_HEALTH_URL=https://my-app-staging.fly.dev/health
+# MCP_TOKEN=staging-token-abc
+
+# Remote Server (No Health Check):
+# MCP_SERVER_URL=https://api.example.com/mcp
+# MCP_TOKEN=api-key-here
+# # MCP_HEALTH_URL is omitted - server doesn't suspend

forbin_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.13"
+    - name: Install uv
+      run: curl -LsSf https://astral.sh/uv/install.sh | sh
+    - name: Install dependencies
+      run: uv sync
+    - name: Run tests
+      run: uv run pytest

forbin_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+    - name: Install uv
+      run: curl -LsSf https://astral.sh/uv/install.sh | sh
+    - name: Install dependencies
+      run: uv sync
+    - name: Run tests
+      run: uv run pytest
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+    - name: Install build tools
+      run: pip install build
+    - name: Build package
+      run: python -m build
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+    - name: Download artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v4
+    - name: Download artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@v1
+      with:
+        files: dist/*
+        generate_release_notes: true

forbin_mcp-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.DS_Store
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment variables (contains secrets)
+.env

forbin_mcp-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+# Pre-commit hooks for Zorac
+# Install: pre-commit install
+# Run manually: pre-commit run --all-files
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-json
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: mixed-line-ending
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.8
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - types-requests
+        args: [--ignore-missing-imports]

forbin_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

forbin_mcp-0.1.0/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "makefile.configureOnOpen": false
+}

forbin_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# 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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-02-05
+
+### Added
+
+- **Interactive CLI** - Two-level tool browser for exploring and testing MCP tools
+- **Automatic server wake-up** - Health check polling for suspended services (Fly.io, etc.)
+- **Cold-start resilient connections** - Retry logic with extended timeouts for slow-starting servers
+- **Tool schema inspection** - View detailed tool schemas with syntax-highlighted JSON
+- **Interactive parameter input** - Type-safe parsing for strings, booleans, numbers, and JSON objects
+- **Connectivity test mode** - `forbin --test` for verifying server connectivity
+- **Verbose logging toggle** - Press `v` at any time to toggle debug output
+- **Modular package structure** - Organized into cli, client, tools, display, and utils modules
+- **Comprehensive documentation** - README, CLAUDE.md, DOCS.md, USAGE.md, DEVELOPMENT.md, CONTRIBUTING.md
+- **CI/CD pipeline** - GitHub Actions workflow for testing and linting
+- **Pre-commit hooks** - Automated code quality checks
+- **Makefile automation** - Common development tasks (`make test`, `make check`, etc.)
+
+### Technical Details
+
+- Python 3.13+ required
+- Built with fastmcp, httpx, python-dotenv, and tenacity
+- MIT licensed
+
+[1.0.0]: https://github.com/chris-colinsky/Forbin/releases/tag/v1.0.0

forbin_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,223 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**Forbin** is an interactive CLI tool for testing remote MCP (Model Context Protocol) servers and their tools. Named after Dr. Charles Forbin from "Colossus: The Forbin Project" (1970), where two computers learn to communicate - a perfect parallel to MCP enabling systems to communicate.
+
+It's designed for developers building agentic workflows and testing FastAPI/FastMCP-based remote tools. The tool specializes in handling suspended services (like Fly.io) with automatic wake-up functionality.
+
+## Key Features
+
+- Interactive tool browser with parameter input
+- Automatic server wake-up for suspended services
+- Cold-start resilient connection logic
+- Type-safe parameter parsing
+- Connectivity testing mode
+
+## Running the Tool
+
+### Interactive Mode
+
+```bash
+python forbin.py
+```
+
+This launches the interactive tool browser that:
+1. Wakes up suspended servers (if health URL configured)
+2. Connects to the MCP server
+3. Lists all available tools
+4. Allows interactive tool selection and calling
+
+### Connectivity Test Mode
+
+```bash
+python forbin.py --test
+```
+
+Tests server connectivity without running tools.
+
+### Help
+
+```bash
+python forbin.py --help
+```
+
+## Configuration
+
+Configuration is via `.env` file:
+
+- `MCP_SERVER_URL` (required) - MCP server endpoint
+- `MCP_TOKEN` (required) - Bearer token for authentication
+- `MCP_HEALTH_URL` (optional) - Health endpoint for wake-up
+
+Create from template:
+```bash
+cp .env.example .env
+```
+
+## Architecture
+
+### Main Components
+
+**`forbin.py`** - Single-file CLI application with these key functions:
+
+1. **wake_up_server()** (lines 72-111)
+   - Polls health endpoint until server responds
+   - 6 attempts with 5-second waits
+   - Returns True if server is awake
+
+2. **connect_to_mcp_server()** (lines 114-161)
+   - Establishes MCP connection with retry logic
+   - Uses `init_timeout=30.0` for cold starts
+   - 3 attempts with 5-second waits
+   - Returns connected Client or None
+
+3. **list_tools()** (lines 164-177)
+   - Retrieves tool manifest from server
+   - 15-second timeout for the list operation
+
+4. **interactive_session()** (lines 394-476)
+   - Main interactive loop
+   - Handles tool selection and parameter input
+   - Displays results
+
+5. **test_connectivity()** (lines 348-391)
+   - Connectivity-only testing mode
+   - Useful for CI/CD health checks
+
+### Wake-Up Process
+
+Three-step approach for suspended services:
+
+1. **Health Check Wake-Up** - Polls `/health` endpoint until 200 response
+2. **Initialization Wait** - Waits 20 seconds for MCP server to fully initialize
+3. **Connection with Retry** - Connects with extended timeout and retry logic
+
+This is critical for Fly.io and similar platforms that suspend inactive services.
+
+### Error Handling
+
+**FilteredStderr class** (lines 18-51):
+- Suppresses harmless MCP session termination errors
+- Filters stderr output for cleaner user experience
+- Specifically suppresses "Session termination failed: 400" warnings
+
+**Connection retry logic**:
+- Handles `BrokenResourceError`, `ClosedResourceError`, `TimeoutError`
+- Creates fresh client on each retry attempt
+- Provides clear feedback on connection status
+
+### Parameter Handling
+
+**parse_parameter_value()** (lines 236-250):
+- Converts string input to appropriate types
+- Supports: boolean, integer, number, string, object, array
+- Handles JSON parsing for complex types
+
+**get_tool_parameters()** (lines 253-310):
+- Interactive parameter collection
+- Validates required vs optional parameters
+- Shows enum values when available
+- Retry loop for invalid inputs
+
+## Development Notes
+
+### Dependencies
+
+- **fastmcp** - MCP client library (requires >=2.0.0)
+- **httpx** - Async HTTP for health checks
+- **python-dotenv** - Environment variable management
+- **tenacity** - Retry logic utilities (currently imported but not actively used)
+
+### Package Management
+
+Uses `uv` for dependency management:
+```bash
+uv sync
+```
+
+Python 3.11+ required.
+
+### CLI Entry Point
+
+Configured in `pyproject.toml`:
+```toml
+[project.scripts]
+mcp-test = "main:main"
+```
+
+After installation, users can run `mcp-test` directly.
+
+### Making Changes
+
+When modifying the tool:
+
+1. **Connection logic** - Edit `connect_to_mcp_server()` and adjust timeouts/retries
+2. **Wake-up behavior** - Edit `wake_up_server()` and the 20-second sleep in `interactive_session()`
+3. **Display formatting** - Edit `display_tools()` and `display_tool_schema()`
+4. **Parameter parsing** - Edit `parse_parameter_value()` for new type support
+5. **Error suppression** - Edit `FilteredStderr` class patterns
+
+### Important Constants
+
+- **Health check**: 6 attempts x 5 seconds = 30 seconds max
+- **Initialization wait**: 20 seconds after health check
+- **Connection retry**: 3 attempts with 30-second init timeout each
+- **Tool listing timeout**: 15 seconds
+
+These are tuned for Fly.io cold starts but can be adjusted for other platforms.
+
+## Testing
+
+The tool itself is used for testing MCP servers. To test the tester:
+
+1. Set up a local MCP server or use a remote one
+2. Configure `.env` with server details
+3. Run `python forbin.py --test` to verify connectivity
+4. Run `python forbin.py` to test interactive mode
+
+## FastAPI/FastMCP Server Compatibility
+
+This tool expects servers to:
+- Expose an MCP endpoint (e.g., `/mcp`)
+- Implement bearer token authentication
+- Optionally provide `/health` endpoint for wake-up detection
+- Follow MCP protocol specification
+
+Example compatible server:
+```python
+from fastapi import FastAPI
+from fastmcp import FastMCP
+
+app = FastAPI()
+mcp = FastMCP("My Tools")
+
+@mcp.tool()
+def my_tool(param: str) -> str:
+    return f"Result: {param}"
+
+app.include_router(mcp.get_router(), prefix="/mcp")
+
+@app.get("/health")
+def health():
+    return {"status": "ok"}
+```
+
+## Common Issues
+
+### "Failed to wake up server"
+- Check `MCP_HEALTH_URL` is correct and accessible
+- Try increasing retry attempts in `wake_up_server()`
+- Remove `MCP_HEALTH_URL` if server doesn't suspend
+
+### "Connection error (server not ready)"
+- Increase initialization wait time (line 410: `await asyncio.sleep(20)`)
+- Verify `MCP_SERVER_URL` and `MCP_TOKEN` are correct
+- Check server logs for initialization issues
+
+### "Session termination failed: 400"
+- This is harmless and automatically suppressed
+- Occurs during FastMCP library cleanup
+- No action needed

forbin_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,168 @@
+# Contributing to Forbin
+
+Thank you for your interest in contributing to Forbin! This document provides guidelines and information for contributors.
+
+## Getting Started
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/yourusername/forbin.git
+   cd forbin
+   ```
+3. **Install dependencies**:
+   ```bash
+   uv sync
+   # or
+   pip install -r requirements.txt
+   ```
+4. **Set up your environment**:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your test MCP server details
+   ```
+
+## Development Workflow
+
+1. **Create a branch** for your feature or bugfix:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** following the code style guidelines below
+
+3. **Test your changes**:
+   ```bash
+   # Test connectivity
+   python forbin.py --test
+
+   # Test interactive mode
+   python forbin.py
+   ```
+
+4. **Commit your changes**:
+   ```bash
+   git add .
+   git commit -m "Add feature: description of your changes"
+   ```
+
+5. **Push to your fork**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+6. **Open a Pull Request** on GitHub
+
+## Code Style Guidelines
+
+- **Python version**: Target Python 3.11+
+- **Line length**: 100 characters (configured in `pyproject.toml`)
+- **Formatting**: We use Black for code formatting
+  ```bash
+  black forbin.py
+  ```
+- **Linting**: We use Ruff for linting
+  ```bash
+  ruff check forbin.py
+  ```
+- **Type hints**: Use type hints where appropriate
+- **Docstrings**: Use docstrings for functions, following Google style
+
+## What to Contribute
+
+### Good First Issues
+
+- Improve error messages
+- Add support for new parameter types
+- Enhance display formatting
+- Update documentation
+
+### Feature Ideas
+
+- Support for environment variable expansion in parameters
+- Save/load parameter presets for frequent tool calls
+- Export tool call results to file
+- Batch tool calling
+- Non-interactive mode for scripting
+
+### Bug Reports
+
+When reporting bugs, please include:
+- Your Python version (`python --version`)
+- Your operating system
+- Steps to reproduce the issue
+- Expected vs actual behavior
+- Relevant error messages
+
+## Testing
+
+We have comprehensive automated testing with pytest:
+
+**Run all tests:**
+```bash
+make test
+```
+
+**Run specific test types:**
+```bash
+make test-unit          # Unit tests only
+make test-integration   # Integration tests only
+make test-coverage      # With coverage report
+```
+
+**Writing tests:**
+- Add unit tests to `tests/test_main.py`
+- Add integration tests to `tests/test_integration.py`
+- Use fixtures from `tests/conftest.py`
+- Mark async tests with `@pytest.mark.asyncio`
+
+**Example test:**
+```python
+import pytest
+from unittest.mock import AsyncMock
+
+@pytest.mark.asyncio
+async def test_new_feature(mock_mcp_client):
+    """Test description."""
+    result = await your_function()
+    assert result == expected
+```
+
+**Manual testing:**
+1. Set up a test MCP server (local or remote)
+2. Test connectivity with `make run-test`
+3. Test interactive mode with `make run`
+4. Verify new features work as expected
+
+**Coverage requirements:**
+- New code should maintain or improve coverage
+- Check coverage with `make test-coverage`
+- View HTML report: `open htmlcov/index.html`
+
+## Documentation
+
+When adding features:
+- Update `README.md` with usage examples
+- Update `CLAUDE.md` with implementation details
+- Add comments for complex logic
+- Update `--help` text if adding CLI arguments
+
+## Pull Request Guidelines
+
+- **Keep PRs focused**: One feature or bugfix per PR
+- **Write clear commit messages**: Explain what and why, not just how
+- **Update documentation**: Keep docs in sync with code changes
+- **Test thoroughly**: Verify your changes don't break existing functionality
+- **Respond to feedback**: Be open to suggestions and iteration
+
+## Questions or Need Help?
+
+- Open an issue on GitHub
+- Check existing issues and PRs for similar topics
+- Review the `CLAUDE.md` file for implementation guidance
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+Thank you for contributing to Forbin!

forbin_mcp-0.1.0/DOCS.md

@@ -0,0 +1,64 @@
+# Forbin Technical Documentation
+
+This document provides a detailed look at how Forbin works under the hood, its connection logic, and its user interface components.
+
+## How It Works
+
+### Wake-Up Process
+
+For suspended services (like Fly.io apps), Forbin uses a orchestrated three-step approach to ensure the server is ready before attempting an MCP connection:
+
+1. **Health Check Wake-Up**
+   - Polls the configured `MCP_HEALTH_URL` until it returns a successful (200 OK) response.
+   - **Limit:** 6 attempts with 5-second intervals (30 seconds total).
+   - This triggers the cloud provider to wake up the suspended instance.
+
+2. **Initialization Wait**
+   - Once the health endpoint responds, Forbin waits for an additional **20 seconds**.
+   - This gives the MCP server time to fully initialize its inner services after the container has started.
+
+3. **Connection with Retry**
+   - Connects to the MCP server with an extended `init_timeout` of **30 seconds**.
+   - **Retry logic:** 3 attempts with 5-second waits between them if the connection fails or times out.
+
+This process ensures reliable connections even to cold-started servers that might take significant time to become "fully" ready for MCP traffic.
+
+---
+
+## User Interface
+
+### Step Indicators
+
+Throughout the connection and execution process, Forbin displays step indicators to show progress.
+
+| Color | Icon | Meaning |
+|-------|------|---------|
+| **Yellow** | > | **In Progress** - The current action is being performed. |
+| **Green** | + | **Success** - The step completed successfully. |
+| **Dim/Grey** | - | **Skip** - This step was skipped (e.g., wake-up skipped if no health URL). |
+
+### Anytime Logging Toggle
+
+Forbin includes a background listener that monitors for the **`v`** keypress.
+
+- **Non-blocking:** You can toggle logging even while Forbin is waiting for a health check or establishing a connection.
+- **Real-time unsuppression:** When logging is toggled **ON**, Forbin's `FilteredStderr` immediately stops suppressing typical MCP library warnings and errors, showing you full tracebacks and connection details.
+- **Visual Feedback:** A notification will appear in the CLI whenever the logging state changes.
+
+### Interactive Tool Browser
+
+1. **Discovery:** Forbin lists all tools provided by the MCP server.
+2. **Inspection:** Selecting a tool shows its description and parameter requirements.
+3. **Execution:** Forbin prompts for each parameter, performing basic type validation:
+   - **Strings:** Direct input.
+   - **Booleans:** Accepts `true`, `false`, `y`, `n`, `1`, `0`.
+   - **Numbers:** Parses integers and floats.
+   - **Objects/Arrays:** Parses local JSON strings.
+
+---
+
+## Error Handling Details
+
+- **Session termination errors:** FastMCP sometimes returns a 400 error when a session is closed. Forbin automatically suppresses these harmless warnings.
+- **Connection retries:** Uses exponential backoff and fresh client instantiation for each retry to recover from transient network issues.
+- **Timeout management:** Specifically tuned timeouts for discovery (15s) and tool execution (30s+).