ferrum-mcp 1.0.0

data/README.md

@@ -0,0 +1,334 @@
+# 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)
+[![Docker](https://github.com/Eth3rnit3/FerrumMCP/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/Eth3rnit3/FerrumMCP/actions/workflows/docker-publish.yml)
+[![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.
+
+---
+
+## 🚀 Quick Links
+
+| Documentation | Description |
+|---------------|-------------|
+| [**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 |
+| [**Configuration**](docs/CONFIGURATION.md) | Environment variables and advanced configuration |
+| [**Troubleshooting**](docs/TROUBLESHOOTING.md) | Common issues and solutions |
+| [**Deployment**](docs/DEPLOYMENT.md) | Production deployment guide |
+| [**BotBrowser Integration**](docs/DOCKER_BOTBROWSER.md) | Anti-detection browser setup |
+
+---
+
+## 📖 Table of Contents
+
+- [What is FerrumMCP?](#what-is-ferrummcp)
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Documentation](#documentation)
+- [Tools & Capabilities](#tools--capabilities)
+- [Project Resources](#project-resources)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## What is FerrumMCP?
+
+FerrumMCP is a **browser automation server** that implements the **Model Context Protocol (MCP)** by Anthropic. It provides AI assistants with the ability to navigate websites, interact with elements, extract content, and perform complex browser automation tasks through a simple, standardized interface.
+
+**Key Benefits:**
+- 🤖 **AI-Native Design**: Purpose-built for AI assistants like Claude
+- 🔄 **Session-Based**: Multiple concurrent browser sessions with isolated configurations
+- 🌐 **Multi-Browser**: Support for Chrome, Edge, Brave, and BotBrowser
+- 🧩 **Smart Automation**: Cookie banner detection and CAPTCHA solving (⚠️ experimental)
+- 📦 **Easy Deployment**: Docker, systemd, or Kubernetes ready
+- 🔌 **Dual Transport**: HTTP and STDIO for maximum compatibility
+
+---
+
+## Features
+
+### Core Capabilities
+
+✅ **Session Management**
+- Create/manage multiple browser sessions
+- Automatic cleanup (30min idle timeout)
+- Custom browser configurations per session
+
+✅ **Navigation**
+- URL navigation with network idle detection
+- Browser history (back/forward)
+- Page refresh
+
+✅ **Interaction**
+- Click, hover, drag-and-drop
+- Form filling with typing delays
+- Keyboard input simulation
+- **Smart cookie banner acceptance** (8 strategies, multi-language)
+- **AI-powered CAPTCHA solving** (Whisper integration - ⚠️ experimental, under development)
+
+✅ **Extraction**
+- Text and HTML content extraction
+- Screenshot capture (base64)
+- Page metadata (title, URL)
+- XPath-based text search
+
+✅ **Advanced**
+- JavaScript execution and evaluation
+- Cookie management (get/set/clear)
+- Shadow DOM querying
+- Element attribute retrieval
+
+### Enterprise Features
+
+🦾 **BotBrowser Integration**
+- Anti-detection browser automation
+- Fingerprint management with encrypted profiles
+- **Note**: Requires valid trial/premium profiles (demo profiles cause session instability)
+
+🔒 **Security** (v1.0+)
+- Session limits
+- Rate limiting
+- Health check endpoint
+- Non-root Docker user
+
+📊 **Observability**
+- File-based logging
+- Health checks
+- Metrics endpoint (planned)
+
+---
+
+## Quick Start
+
+### Option 1: Docker (Recommended)
+
+**Standard Image** (Chromium only):
+```bash
+docker pull eth3rnit3/ferrum-mcp:latest
+docker run --security-opt seccomp=unconfined -p 3000:3000 eth3rnit3/ferrum-mcp:latest
+```
+
+**BotBrowser Image** (Anti-detection):
+```bash
+docker pull eth3rnit3/ferrum-mcp:botbrowser
+docker run --security-opt seccomp=unconfined -p 3000:3000 \
+  -v /path/to/bot_profiles:/profiles:ro \
+  -e "BROWSER_BOTBROWSER=botbrowser:/opt/botbrowser/chrome:BotBrowser:Anti-detection browser" \
+  -e "BOT_PROFILE_MACOS_1=/profiles/profile_1.enc:Profile 1:Trial profile 1" \
+  eth3rnit3/ferrum-mcp:botbrowser
+```
+### Option 2: Gem Installation
+
+```bash
+gem install ferrum-mcp
+ferrum-mcp start
+```
+
+### Option 3: From Source
+
+```bash
+git clone https://github.com/Eth3rnit3/FerrumMCP.git
+cd FerrumMCP
+bundle install
+ruby bin/ferrum-mcp
+```
+
+**➡️ [Full installation guide](docs/GETTING_STARTED.md)**
+
+---
+
+## Documentation
+
+### Getting Started
+
+| Guide | Description |
+|-------|-------------|
+| [**Installation**](docs/GETTING_STARTED.md#quick-start) | Docker, gem, and source installation |
+| [**Claude Desktop Setup**](docs/GETTING_STARTED.md#claude-desktop) | Integrate with Claude Desktop (STDIO) |
+| [**First Session**](docs/GETTING_STARTED.md#usage-examples) | Create your first browser automation |
+
+### Configuration
+
+| Topic | Link |
+|-------|------|
+| **Environment Variables** | [Configuration Guide](docs/CONFIGURATION.md) |
+| **Multi-Browser Setup** | [Multi-Browser Config](docs/CONFIGURATION.md#multi-browser-configuration) |
+| **BotBrowser Integration** | [BotBrowser Guide](docs/DOCKER_BOTBROWSER.md) |
+| **Resource Discovery** | [Resource Config](docs/CONFIGURATION.md#resource-discovery) |
+
+### API Documentation
+
+| Resource | Description |
+|----------|-------------|
+| [**API Reference**](docs/API_REFERENCE.md) | Complete tool documentation with examples |
+| [**Session Management**](docs/API_REFERENCE.md#session-management) | Create, list, and manage browser sessions |
+| [**Navigation Tools**](docs/API_REFERENCE.md#navigation-tools) | URL navigation and history |
+| [**Interaction Tools**](docs/API_REFERENCE.md#interaction-tools) | Click, fill forms, solve CAPTCHAs |
+| [**Extraction Tools**](docs/API_REFERENCE.md#extraction-tools) | Get content, screenshots, metadata |
+| [**Advanced Tools**](docs/API_REFERENCE.md#advanced-tools) | JavaScript, cookies, Shadow DOM |
+
+### Operations
+
+| Guide | Description |
+|-------|-------------|
+| [**Troubleshooting**](docs/TROUBLESHOOTING.md) | Common issues and solutions |
+| [**Deployment**](docs/DEPLOYMENT.md) | Docker, K8s, systemd deployment |
+| [**Migration**](docs/MIGRATION.md) | Upgrade between versions |
+
+---
+
+## Tools & Capabilities
+
+FerrumMCP provides **27+ browser automation tools** organized into 6 categories:
+
+### 1. Session Management (4 tools)
+- `create_session` - Create browser sessions with custom config
+- `list_sessions` - List all active sessions
+- `get_session_info` - Get detailed session information
+- `close_session` - Manually close a session
+
+### 2. Navigation (4 tools)
+- `navigate` - Navigate to URLs
+- `go_back` - Browser back button
+- `go_forward` - Browser forward button
+- `refresh` - Reload current page
+
+### 3. Interaction (7 tools)
+- `click` - Click elements
+- `fill_form` - Fill form fields
+- `press_key` - Keyboard input
+- `hover` - Mouse hover
+- `drag_and_drop` - Drag elements
+- `accept_cookies` - **Smart cookie banner detection** (8 strategies)
+- `solve_captcha` - **AI-powered CAPTCHA solving** (⚠️ experimental, under development)
+
+### 4. Extraction (6 tools)
+- `get_text` - Extract text content
+- `get_html` - Get HTML content
+- `screenshot` - Capture screenshots
+- `get_title` - Get page title
+- `get_url` - Get current URL
+- `find_by_text` - XPath text search
+
+### 5. Advanced (9 tools)
+- `execute_script` - Run JavaScript
+- `evaluate_js` - Evaluate JavaScript with return value
+- `get_cookies` - Get browser cookies
+- `set_cookie` - Set cookies
+- `clear_cookies` - Clear cookies
+- `get_attribute` - Get element attributes
+- `query_shadow_dom` - Interact with Shadow DOM
+
+### 6. MCP Resources (7 resources)
+- `ferrum://browsers` - Discover configured browsers
+- `ferrum://user-profiles` - Discover Chrome profiles
+- `ferrum://bot-profiles` - Discover BotBrowser profiles
+- `ferrum://capabilities` - Server capabilities
+
+**➡️ [Complete API Reference](docs/API_REFERENCE.md)**
+
+---
+
+## Project Resources
+
+### Development
+
+| Resource | Link |
+|----------|------|
+| **Contributing Guide** | [CONTRIBUTING.md](CONTRIBUTING.md) |
+| **Security Policy** | [SECURITY.md](SECURITY.md) |
+| **Changelog** | [CHANGELOG.md](CHANGELOG.md) |
+| **AI Development Guide** | [CLAUDE.md](CLAUDE.md) |
+
+### Community
+
+| Platform | Link |
+|----------|------|
+| **GitHub Issues** | [Report bugs](https://github.com/Eth3rnit3/FerrumMCP/issues) |
+| **GitHub Discussions** | [Ask questions](https://github.com/Eth3rnit3/FerrumMCP/discussions) |
+| **Docker Hub** | [eth3rnit3/ferrum-mcp](https://hub.docker.com/r/eth3rnit3/ferrum-mcp) |
+
+### Links
+
+| Resource | URL |
+|----------|-----|
+| **Repository** | https://github.com/Eth3rnit3/FerrumMCP |
+| **Documentation** | https://github.com/Eth3rnit3/FerrumMCP/tree/main/docs |
+| **Releases** | https://github.com/Eth3rnit3/FerrumMCP/releases |
+| **RubyGems** | https://rubygems.org/gems/ferrum-mcp |
+
+---
+
+## Requirements
+
+### System Requirements
+- **Ruby**: 3.2 or higher
+- **Browser**: Chrome, Chromium, Edge, or Brave
+- **OS**: Linux, macOS, or Windows
+
+### Optional Dependencies
+- **whisper-cli**: For CAPTCHA solving
+- **BotBrowser**: For anti-detection automation
+- **Docker**: For containerized deployment
+
+---
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+**Quick contribution checklist:**
+- 📖 Read [CONTRIBUTING.md](CONTRIBUTING.md)
+- 🐛 Use issue templates for bugs
+- ✨ Use feature request template
+- ✅ Run tests: `bundle exec rspec`
+- 📝 Update documentation
+- 🎨 Follow RuboCop style
+
+---
+
+## Security
+
+For security vulnerabilities, please email [eth3rnit3@gmail.com](mailto:eth3rnit3@gmail.com). See [SECURITY.md](SECURITY.md) for our security policy.
+
+---
+
+## License
+
+FerrumMCP is released under the [MIT License](LICENSE).
+
+---
+
+## Credits
+
+Built with:
+- [Ferrum](https://github.com/rubycdp/ferrum) - Ruby Chrome DevTools Protocol
+- [Model Context Protocol](https://github.com/anthropics/mcp) by Anthropic
+- [Whisper](https://github.com/ggerganov/whisper.cpp) for CAPTCHA solving
+- [BotBrowser](https://botbrowser.com) for anti-detection (optional)
+
+---
+
+## Support
+
+- 📚 **Documentation**: [docs/](docs/)
+- 💬 **Discussions**: [GitHub Discussions](https://github.com/Eth3rnit3/FerrumMCP/discussions)
+- 🐛 **Issues**: [GitHub Issues](https://github.com/Eth3rnit3/FerrumMCP/issues)
+- 📧 **Email**: [eth3rnit3@gmail.com](mailto:eth3rnit3@gmail.com)
+
+---
+
+<p align="center">
+  <strong>Made with ❤️ by <a href="https://github.com/Eth3rnit3">Eth3rnit3</a></strong>
+</p>
+
+<p align="center">
+  <a href="#-quick-links">Back to Top</a>
+</p>

data/SECURITY.md

@@ -0,0 +1,286 @@
+# Security Policy
+
+## Supported Versions
+
+We release patches for security vulnerabilities for the following versions:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+| < 0.1   | :x:                |
+
+## Security Model and Trust Assumptions
+
+FerrumMCP is designed to operate in **trusted environments** with the following security assumptions:
+
+### Trust Model
+
+1. **Trusted Environment**: FerrumMCP assumes it runs in a controlled environment where all clients are trusted
+2. **No Public Exposure**: The server should NOT be exposed to the public internet without additional security layers
+3. **Trusted Input**: Tool inputs are assumed to come from trusted AI assistants, not untrusted users
+4. **Local Network**: HTTP transport is intended for localhost or private network use only
+
+### What FerrumMCP Does NOT Provide
+
+- ❌ **Authentication**: No API keys, tokens, or user authentication
+- ❌ **Authorization**: No role-based access control or permissions
+- ❌ **Rate Limiting**: No built-in protection against DoS attacks
+- ❌ **Input Sanitization**: Limited validation of user-provided selectors and scripts
+- ❌ **Audit Logging**: No security event logging or monitoring
+- ❌ **Encryption**: No TLS/SSL for HTTP transport (use reverse proxy if needed)
+
+### Security Boundaries
+
+FerrumMCP provides security at the following levels:
+
+✅ **Browser Sandbox**: Relies on Chrome's built-in sandbox for isolation
+✅ **Thread Safety**: Mutex-protected session management prevents race conditions
+✅ **Session Isolation**: Each browser session is isolated from others
+✅ **Dependency Pinning**: All gems use pessimistic version constraints
+✅ **Input Validation**: Session IDs and basic parameters are validated
+
+## Known Security Considerations
+
+### 1. Arbitrary JavaScript Execution
+
+**Tools affected**: `execute_script`, `evaluate_js`
+
+**Risk**: These tools allow execution of arbitrary JavaScript in the browser context.
+
+**Mitigation**:
+- Only use in trusted environments
+- Do not expose to untrusted users
+- Consider disabling these tools if not needed
+
+### 2. File System Access
+
+**Tools affected**: `screenshot`, potential future download features
+
+**Risk**: Screenshots are saved to disk and could fill storage or access sensitive paths.
+
+**Mitigation**:
+- Screenshots are temporary and base64-encoded
+- No direct file path control by users
+- Consider implementing storage quotas
+
+### 3. Network Access
+
+**Tools affected**: `navigate`, all browser operations
+
+**Risk**: Browser can access arbitrary URLs including internal networks.
+
+**Mitigation**:
+- Use browser's built-in protections
+- Consider firewall rules to restrict browser network access
+- Monitor for suspicious navigation patterns
+
+### 4. XPath Injection
+
+**Tools affected**: `find_by_text`
+
+**Risk**: User-provided text could manipulate XPath queries.
+
+**Mitigation**:
+- Partial escaping implemented for quotes
+- Use CSS selectors when possible
+- Full XPath sanitization planned for v1.1
+
+### 5. Session Resource Exhaustion
+
+**Risk**: Unlimited session creation could exhaust system resources (DoS).
+
+**Current Status**: No hard limits enforced
+**Planned**: `MAX_CONCURRENT_SESSIONS` configuration in v1.1
+
+**Temporary Mitigation**:
+- Sessions auto-close after 30 minutes idle
+- Background cleanup every 5 minutes
+- Monitor session count via `list_sessions`
+
+### 6. Docker Root Execution
+
+**Risk**: Docker container runs as root by default.
+
+**Current Status**: No USER directive in Dockerfile
+**Planned**: Non-root user in v1.1
+
+**Temporary Mitigation**:
+- Use Docker user namespaces
+- Run with `--user` flag: `docker run --user 1000:1000 ...`
+- Apply SELinux or AppArmor policies
+
+### 7. Cookie and Credential Exposure
+
+**Tools affected**: `get_cookies`, `set_cookie`
+
+**Risk**: Cookies containing session tokens or credentials could be extracted.
+
+**Mitigation**:
+- Use httpOnly and secure flags when setting cookies
+- Consider restricting cookie access to specific domains
+- Avoid storing sensitive data in cookies
+
+## Reporting a Vulnerability
+
+We take security vulnerabilities seriously. If you discover a security issue, please follow responsible disclosure:
+
+### How to Report
+
+**Email**: [eth3rnit3@gmail.com](mailto:eth3rnit3@gmail.com)
+
+**Subject**: `[SECURITY] FerrumMCP Vulnerability Report`
+
+### What to Include
+
+Please provide as much information as possible:
+
+1. **Description**: Clear description of the vulnerability
+2. **Impact**: What can an attacker do with this vulnerability?
+3. **Affected Versions**: Which versions are affected?
+4. **Reproduction Steps**: Detailed steps to reproduce the issue
+5. **Proof of Concept**: Code or commands demonstrating the vulnerability (if applicable)
+6. **Suggested Fix**: Any ideas for fixing the issue (optional)
+
+### Example Report
+
+```
+Subject: [SECURITY] FerrumMCP Vulnerability Report
+
+Description:
+The execute_script tool does not validate JavaScript syntax, allowing
+injection of malicious code that could access internal network services.
+
+Impact:
+An attacker could use the browser to scan internal networks or exfiltrate
+data from internal services.
+
+Affected Versions: 0.1.0
+
+Reproduction Steps:
+1. Create a session: create_session(headless: false)
+2. Execute: execute_script("fetch('http://internal-server/secrets')", session_id)
+3. Browser makes request to internal server
+
+Suggested Fix:
+Implement URL allowlist or blocklist for browser network access.
+```
+
+### Response Timeline
+
+- **Initial Response**: Within 48 hours
+- **Status Update**: Within 7 days
+- **Fix Timeline**: Depends on severity
+  - **Critical**: Emergency patch within 7 days
+  - **High**: Patch within 30 days
+  - **Medium**: Patch in next minor release
+  - **Low**: Patch in next release
+
+### Disclosure Policy
+
+- **Coordination**: We will work with you to understand and fix the issue
+- **Credit**: You will be credited in the security advisory (unless you prefer to remain anonymous)
+- **Public Disclosure**: We will coordinate public disclosure timing with you
+- **CVE Assignment**: We will request CVE assignment for confirmed vulnerabilities
+- **Security Advisory**: Published on GitHub Security Advisories
+
+### What Happens Next
+
+1. **Acknowledgment**: We confirm receipt of your report
+2. **Validation**: We validate and reproduce the vulnerability
+3. **Assessment**: We assess severity using CVSS scoring
+4. **Development**: We develop and test a fix
+5. **Notification**: We notify you when fix is ready
+6. **Release**: We release patched version
+7. **Disclosure**: We publish security advisory with your credit
+
+## Security Best Practices
+
+If you're deploying FerrumMCP, follow these best practices:
+
+### Network Security
+
+✅ **Bind to localhost**: Use `MCP_SERVER_HOST=127.0.0.1` for local-only access
+✅ **Use firewall**: Restrict access to port 3000
+✅ **Reverse proxy**: Use nginx/Apache with TLS for remote access
+✅ **VPN/SSH tunnel**: For remote access, use VPN or SSH tunneling
+
+### Deployment Security
+
+✅ **Minimal privileges**: Run as non-root user
+✅ **Resource limits**: Set ulimits for memory and CPU
+✅ **Read-only filesystem**: Mount system directories read-only in Docker
+✅ **Secrets management**: Use environment variables, not config files
+✅ **Update regularly**: Keep FerrumMCP and dependencies updated
+
+### Monitoring
+
+✅ **Session monitoring**: Track active sessions via `list_sessions`
+✅ **Log monitoring**: Monitor `logs/ferrum_mcp.log` for errors
+✅ **Resource monitoring**: Watch CPU, memory, and disk usage
+✅ **Network monitoring**: Monitor browser network activity
+
+### Configuration
+
+✅ **Disable unused tools**: Remove tools you don't need from `TOOL_CLASSES`
+✅ **Browser sandboxing**: Ensure Chrome sandbox is enabled
+✅ **Timeouts**: Set appropriate `BROWSER_TIMEOUT` values
+✅ **Headless mode**: Use `BROWSER_HEADLESS=true` in production
+
+## Security Roadmap
+
+Planned security improvements for future versions:
+
+### v1.1 (Planned)
+- [ ] Session limits (`MAX_CONCURRENT_SESSIONS`)
+- [ ] Rate limiting for HTTP transport
+- [ ] XPath input sanitization
+- [ ] Non-root Docker user
+- [ ] Health check endpoint with optional authentication
+
+### v1.2 (Planned)
+- [ ] Optional API key authentication
+- [ ] Tool-level permissions system
+- [ ] Audit logging for security events
+- [ ] URL allowlist/blocklist for navigation
+- [ ] Resource usage quotas
+
+### v2.0 (Future)
+- [ ] Role-based access control (RBAC)
+- [ ] TLS/SSL for HTTP transport
+- [ ] Session encryption at rest
+- [ ] Security event webhooks
+- [ ] Integration with SIEM systems
+
+## Acknowledgments
+
+We thank the following security researchers for responsible disclosure:
+
+- *No vulnerabilities reported yet*
+
+## Contact
+
+For security-related questions or concerns:
+
+- **Security Email**: [eth3rnit3@gmail.com](mailto:eth3rnit3@gmail.com)
+- **GitHub Issues**: For non-security bugs only
+- **GitHub Discussions**: For general questions
+
+## Legal
+
+By reporting a vulnerability, you agree to:
+
+- Give us reasonable time to fix the issue before public disclosure
+- Not exploit the vulnerability beyond proof of concept
+- Not access, modify, or delete data belonging to others
+
+We commit to:
+
+- Acknowledge your report within 48 hours
+- Keep you informed of our progress
+- Credit you in the security advisory (if you wish)
+- Not pursue legal action for responsible disclosure
+
+---
+
+**Last Updated**: 2024-11-22
+**Version**: 1.0

data/bin/ferrum-mcp

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+# Load main module first to enable eager loading in production
+require_relative '../lib/ferrum_mcp'
+require_relative '../lib/ferrum_mcp/cli/command_handler'
+
+# Default options
+options = {
+  transport: 'http',
+  host: ENV.fetch('MCP_SERVER_HOST', '0.0.0.0'),
+  port: ENV.fetch('MCP_SERVER_PORT', '3000').to_i,
+  log_level: ENV.fetch('LOG_LEVEL', 'info')
+}
+
+command = ARGV[0]
+
+# Parse options for 'start' command
+if command == 'start' || command.nil?
+  ARGV.shift if command == 'start'
+
+  OptionParser.new do |opts|
+    opts.banner = "Usage: ferrum-mcp start [options]"
+    opts.separator ""
+    opts.separator "Options:"
+
+    opts.on('-t', '--transport TYPE', [:http, :stdio],
+            'Transport type (http or stdio)',
+            "  Default: #{options[:transport]}") do |t|
+      options[:transport] = t.to_s
+    end
+
+    opts.on('-H', '--host HOST',
+            'Server host (HTTP only)',
+            "  Default: #{options[:host]}") do |h|
+      options[:host] = h
+    end
+
+    opts.on('-p', '--port PORT', Integer,
+            'Server port (HTTP only)',
+            "  Default: #{options[:port]}") do |p|
+      options[:port] = p
+    end
+
+    opts.on('-l', '--log-level LEVEL', [:debug, :info, :warn, :error],
+            'Log level (debug, info, warn, error)',
+            "  Default: #{options[:log_level]}") do |l|
+      options[:log_level] = l.to_s
+    end
+
+    opts.on('-h', '--help', 'Show this help message') do
+      puts opts
+      exit
+    end
+
+    opts.on('-v', '--version', 'Show version') do
+      require_relative '../lib/ferrum_mcp/version'
+      puts "FerrumMCP #{FerrumMCP::VERSION}"
+      exit
+    end
+  end.parse!
+end
+
+# Delegate to command handler
+FerrumMCP::CLI::CommandHandler.handle(command, options)

data/bin/lint

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+# Run RuboCop with optional auto-correct
+if [ "$1" = "--fix" ]; then
+    echo "Running RuboCop with auto-correct..."
+    bundle exec rubocop -A .
+else
+    echo "Running RuboCop..."
+    bundle exec rubocop .
+fi

data/bin/serve

@@ -0,0 +1,3 @@
+#!/bin/bash
+
+bundle exec ruby bin/ferrum-mcp

data/bin/test

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+echo "Running tests..."
+bundle exec rspec "$@"