ferrum-mcp 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9053a5693d5260b569d476ac94b970edcb7557637f1191961eb3037f3b4834de
-  data.tar.gz: ca905498d67b1b8ee5834e532fb0478968c411dc2751d7cb4c0423a079215bda
+  metadata.gz: 2eb5504afb33d3f509798c6a98d9103c8da74c995e971a684503a5f5ca711228
+  data.tar.gz: 71e4317848e0ee839ae286d0b41d738572bd168a9a0e120ec6a139e98ab3124c
 SHA512:
-  metadata.gz: cc2b19c3c127d7d1efe72d35eea10743cb224e18c66ee1e0fcd4fa56f84a878ded6b9da11a10a57c3fd513e78b36484a8c2a1e2fbe70865c131aa67eb6251c66
-  data.tar.gz: f60da3eb3ac99efc0b65d6a1ef4b5fa58306c816cfcc3b6784fd20ca50deb06f55573f9fd2b11ced4e6ffede2037a7815bc722826d45d25398e5b978d0b5e3f4
+  metadata.gz: 2ed7eb1616f05fd46e21c4f451834b28753b1f76c2858b54080e61c64e3c539580ba93092bfd281e7bfb0864a3a78a6f357d854bd52d7bd96b26a89e28a22cf1
+  data.tar.gz: c4595fc9ac25047a3c2c38a2d6bd9402fb7f375bca44253c025894aacfc16d39153b0b4d42af8697080faac4c496888674a1a1fd5e707f031dd82fbde58caf14

data/.env.example

@@ -18,8 +18,45 @@ RATE_LIMIT_ENABLED=true
 RATE_LIMIT_MAX_REQUESTS=100
 RATE_LIMIT_WINDOW=60
 
+# =============================================================================
+# API KEY AUTHENTICATION (HTTP Transport only)
+# Protects /mcp endpoint with Bearer token authentication
+# Generate a key with: rake generate_api_key
+# =============================================================================
+
+# Enable/disable API key authentication (default: false)
+API_KEY_ENABLED=false
+
+# Single API key
+# API_KEY=your_secret_api_key_here
+
+# Multiple API keys (comma-separated) - useful for key rotation or multiple clients
+# API_KEYS=key1,key2,key3
+
+# Note: /health and / endpoints remain accessible without authentication
+# Clients must include header: Authorization: Bearer <api_key>
+
 # Logging
+# Levels: debug, info, warn, error (default: info)
 LOG_LEVEL=info
+# Destination: a file path, or "stderr". Never STDOUT (used by the stdio transport).
+# Default: ./logs/ferrum_mcp.log under the current working directory.
+# LOG_FILE=/var/log/ferrum-mcp/ferrum_mcp.log
+
+# Reverse proxy (HTTP Transport only)
+# Set to true ONLY when the server sits behind a trusted proxy (nginx, Traefik, ...),
+# so X-Forwarded-For is used for rate limiting and audit logs.
+TRUST_PROXY=false
+
+# Navigation policy (optional, comma-separated). Entries: exact host, *.suffix, or CIDR.
+# When ALLOWED_HOSTS is set only those hosts can be visited; BLOCKED_HOSTS always wins.
+# Recommended for exposed HTTP deployments:
+# BLOCKED_HOSTS=localhost,127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,169.254.0.0/16,*.internal
+# ALLOWED_HOSTS=*.example.com
+
+# Directories the upload_file tool may read from (comma-separated).
+# Default: current working directory and the system temp dir.
+# UPLOAD_ALLOWED_DIRS=/data/uploads
 
 # =============================================================================
 # MULTI-BROWSER CONFIGURATION

data/CHANGELOG.md

@@ -7,6 +7,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-09-28
+
+### Added
+- **Snapshot tool** (`snapshot`): compact, LLM-friendly list of interactive elements and headings with stable
+  refs (`e12`). Every element-based tool accepts `ref:e12` as a selector.
+- **Waiting tools**: `wait_for_selector` (visible/hidden/attached/detached), `wait_for_text`,
+  `wait_for_network_idle`.
+- **Page tools**: `scroll`, `select_option`, `upload_file`, `set_viewport`.
+- **Tab tools**: `list_tabs`, `new_tab`, `switch_tab`, `close_tab`. Tools act on the session's current tab.
+- XPath (`xpath:` prefix or `//`) accepted by every element-based tool, not only `click`/`get_text`.
+- `LOG_FILE` (path or `stderr`) to choose the log destination.
+- `TRUST_PROXY` to opt in to `X-Forwarded-For` for rate limiting and audit logs.
+- `ALLOWED_HOSTS` / `BLOCKED_HOSTS` navigation policy (exact hosts, `*.suffix`, CIDR).
+- `UPLOAD_ALLOWED_DIRS` restricting where `upload_file` may read from.
+- `fill_form` field option `clear`, `get_html` option `max_length`, `get_text` option `wait`,
+  `navigate` options `wait_for_idle` / `timeout`, `set_cookie` option `expires`.
+- `rake test:unit` (no Chrome) and `rake test:integration`.
+- Unit specs for `BrowserManager`, `SessionManager` concurrency, the CLI runner, logging and the rate limiter.
+
+### Changed
+- **Tool DSL**: tools declare `tool_name`, `description` and `param`s; the JSON schema is generated,
+  `session_id` is injected automatically and params reach `#perform` with symbol keys and defaults applied.
+- `BrowserManager` detects a dead Chrome process and the session restarts it on the next call.
+- Cookies are read through Ferrum's cookie accessors (structured `domain`, `path`, `expires`, flags).
+- Screenshot resizing is optional: without libvips the image is returned untouched.
+- `LOG_LEVEL` defaults to `info` everywhere (Configuration used to default to `debug`).
+- Ruby: Gemfile requires `>= 3.2`, Docker images build on Ruby 3.3.
+- `test/` debug scripts removed, `scripts/` moved to `examples/`.
+- RuboCop metric exclusions narrowed to the two heuristic tools (`accept_cookies`, `solve_captcha`).
+
+### Fixed
+- Session `browser_options` never reached Ferrum (private method behind a `respond_to?` check) and keys
+  written with a leading `--` produced `----flag`. Keys are now normalized.
+- `user_profile_id` was resolved but never mapped to `user-data-dir`.
+- `StdioServer` duplicated the MCP transport read loop.
+- Shutdown called the deprecated `stop_browser`, never stopped the cleanup thread and exited from
+  inside a signal trap. Signals now interrupt the main loop, which runs the shutdown sequence.
+- Logs were written inside the installed gem directory.
+- The CLI required `bundler/setup`, breaking `gem install ferrum-mcp && ferrum-mcp start`.
+- `close_session` stopped Chrome while holding the global lock, blocking every other session; a closed
+  session could be resurrected by a concurrent call.
+- Rate limiter trusted `X-Forwarded-For` unconditionally (trivially bypassable).
+- `drag_and_drop` reported wrong coordinates for elements found through XPath.
+- `get_text` returned text with surrounding newlines and indentation (now collapsed, `raw: true` to opt out).
+- BotBrowser Docker image failed to build: the pinned upstream package had been removed (404). The latest
+  release is now resolved at build time (`BOTBROWSER_VERSION` build arg to pin one).
+- `snapshot` listed unlabeled radio buttons of one group with the same name; their `value` is now shown.
+
+### Removed
+- Deprecated `Server#start_browser` / `Server#stop_browser`.
+- `wait_for_selector` / `wait_for_text` were listed in the 1.0.0 notes before they existed; they now do.
+
+### CI
+- Docker images (standard and BotBrowser) are built on every pull request, and the standard image is
+  smoke-tested over HTTP and stdio with a real browser session.
+- The release workflow fails when the release tag does not match `FerrumMCP::VERSION`.
+
+### Upgrade notes
+- Custom tools must implement `#perform(params)` (params arrive with symbol keys) and declare their interface
+  with `tool_name` / `description` / `param` instead of overriding `.input_schema`.
+- `browser_options` keys are written without leading dashes (`"window-size"`); dashed keys are still accepted.
+- `get_text` now collapses whitespace; pass `raw: true` for the previous behaviour.
+
+## [1.0.0] - 2025-11-22
+
+
 ### Added
 - Comprehensive documentation structure in `docs/` directory
 - API reference with all 27+ tools documented
@@ -56,6 +122,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added session limit recommendations
 - Implemented XSS and XPath injection protections in multiple tools
 
+
 ## [0.1.0] - 2024-11-22
 
 Initial release of FerrumMCP - Browser automation server implementing the Model Context Protocol.
@@ -222,8 +289,12 @@ This is the initial release, but note for future versions:
 
 ## Release Links
 
+- [1.1.0] - Hardening, tool DSL, snapshot/waiting/tab tools (2026-09-28)
+- [1.0.0] - Multi-session, BotBrowser, docs, gem publishing (2025-11-22)
 - [0.1.0] - Initial release (2024-11-22)
 - [Unreleased] - Current development
 
-[Unreleased]: https://github.com/Eth3rnit3/FerrumMCP/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/Eth3rnit3/FerrumMCP/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/Eth3rnit3/FerrumMCP/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/Eth3rnit3/FerrumMCP/compare/v0.1.0...v1.0.0
 [0.1.0]: https://github.com/Eth3rnit3/FerrumMCP/releases/tag/v0.1.0

data/README.md

@@ -1,11 +1,13 @@
 # FerrumMCP 🌐
 
 [![CI](https://github.com/Eth3rnit3/FerrumMCP/actions/workflows/ci.yml/badge.svg)](https://github.com/Eth3rnit3/FerrumMCP/actions/workflows/ci.yml)
-[![Gem Version](https://badge.fury.io/rb/ferrum-mcp.svg)](https://rubygems.org/gems/ferrum-mcp)
+[![Release](https://github.com/Eth3rnit3/FerrumMCP/actions/workflows/release.yml/badge.svg)](https://github.com/Eth3rnit3/FerrumMCP/actions/workflows/release.yml)
+[![Gem Version](https://img.shields.io/gem/v/ferrum-mcp?color=red&logo=rubygems)](https://rubygems.org/gems/ferrum-mcp)
+[![Gem Downloads](https://img.shields.io/gem/dt/ferrum-mcp?logo=rubygems)](https://rubygems.org/gems/ferrum-mcp)
 [![Docker](https://github.com/Eth3rnit3/FerrumMCP/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/Eth3rnit3/FerrumMCP/actions/workflows/docker-publish.yml)
+[![Docker Hub](https://img.shields.io/docker/pulls/eth3rnit3/ferrum-mcp.svg)](https://hub.docker.com/r/eth3rnit3/ferrum-mcp)
 [![Ruby](https://img.shields.io/badge/ruby-3.2+-red.svg)](https://www.ruby-lang.org)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Docker Hub](https://img.shields.io/docker/pulls/eth3rnit3/ferrum-mcp.svg)](https://hub.docker.com/r/eth3rnit3/ferrum-mcp)
 
 > A browser automation server for the Model Context Protocol (MCP), enabling AI assistants to interact with web pages through a standardized interface.
 
@@ -17,7 +19,7 @@
 |---------------|-------------|
 | [**Getting Started**](docs/GETTING_STARTED.md) | Installation, setup, and first steps |
 | [**Docker Deployment**](docs/DOCKER.md) | Complete Docker guide with Claude Desktop integration |
-| [**API Reference**](docs/API_REFERENCE.md) | Complete documentation of all 27+ tools |
+| [**API Reference**](docs/API_REFERENCE.md) | Complete documentation of all 40 tools |
 | [**Configuration**](docs/CONFIGURATION.md) | Environment variables and advanced configuration |
 | [**Troubleshooting**](docs/TROUBLESHOOTING.md) | Common issues and solutions |
 | [**Deployment**](docs/DEPLOYMENT.md) | Production deployment guide |
@@ -65,6 +67,12 @@ FerrumMCP is a **browser automation server** that implements the **Model Context
 - URL navigation with network idle detection
 - Browser history (back/forward)
 - Page refresh
+- Tabs (open, list, switch, close) and viewport control
+- Optional host allow/block lists
+
+✅ **Agent-friendly page snapshot**
+- `snapshot` lists interactive elements with stable refs (`ref:e12`) usable by every other tool
+- Explicit waits: `wait_for_selector`, `wait_for_text`, `wait_for_network_idle`
 
 ✅ **Interaction**
 - Click, hover, drag-and-drop
@@ -186,7 +194,7 @@ ruby bin/ferrum-mcp
 
 ## Tools & Capabilities
 
-FerrumMCP provides **27+ browser automation tools** organized into 6 categories:
+FerrumMCP provides **40 browser automation tools** organized into 8 categories:
 
 ### 1. Session Management (4 tools)
 - `create_session` - Create browser sessions with custom config
@@ -200,16 +208,20 @@ FerrumMCP provides **27+ browser automation tools** organized into 6 categories:
 - `go_forward` - Browser forward button
 - `refresh` - Reload current page
 
-### 3. Interaction (7 tools)
-- `click` - Click elements
+### 3. Interaction (10 tools)
+- `click` - Click elements (CSS, XPath or snapshot ref)
 - `fill_form` - Fill form fields
 - `press_key` - Keyboard input
 - `hover` - Mouse hover
 - `drag_and_drop` - Drag elements
+- `scroll` - Scroll the page, a container, or an element into view
+- `select_option` - Pick options in `<select>` elements
+- `upload_file` - Attach files to file inputs
 - `accept_cookies` - **Smart cookie banner detection** (8 strategies)
 - `solve_captcha` - **AI-powered CAPTCHA solving** (⚠️ experimental, under development)
 
-### 4. Extraction (6 tools)
+### 4. Extraction (7 tools)
+- `snapshot` - **Compact page snapshot with stable element refs**
 - `get_text` - Extract text content
 - `get_html` - Get HTML content
 - `screenshot` - Capture screenshots
@@ -217,7 +229,16 @@ FerrumMCP provides **27+ browser automation tools** organized into 6 categories:
 - `get_url` - Get current URL
 - `find_by_text` - XPath text search
 
-### 5. Advanced (9 tools)
+### 5. Waiting (3 tools)
+- `wait_for_selector` - Wait for an element to be visible/hidden/attached/detached
+- `wait_for_text` - Wait for text to appear
+- `wait_for_network_idle` - Wait for pending requests to finish
+
+### 6. Tabs & Viewport (5 tools)
+- `list_tabs`, `new_tab`, `switch_tab`, `close_tab` - Tab management
+- `set_viewport` - Viewport size and mobile emulation
+
+### 7. Advanced (7 tools)
 - `execute_script` - Run JavaScript
 - `evaluate_js` - Evaluate JavaScript with return value
 - `get_cookies` - Get browser cookies
@@ -226,7 +247,7 @@ FerrumMCP provides **27+ browser automation tools** organized into 6 categories:
 - `get_attribute` - Get element attributes
 - `query_shadow_dom` - Interact with Shadow DOM
 
-### 6. MCP Resources (7 resources)
+### 8. MCP Resources (7 resources)
 - `ferrum://browsers` - Discover configured browsers
 - `ferrum://user-profiles` - Discover Chrome profiles
 - `ferrum://bot-profiles` - Discover BotBrowser profiles