API Reference

FerrumMCP provides 40 browser automation tools through the Model Context Protocol (MCP). All tools return responses in a standardized JSON format with a success boolean and either data or error fields.

Important Notes

1. Session-Based Architecture: All browser operation tools (except session management tools) require a valid session_id parameter
2. Session Creation: You must create a session using create_session before using any browser automation tools
3. Session Lifecycle: Sessions auto-close after 30 minutes of inactivity or can be manually closed with close_session
4. Multiple Sessions: You can run multiple concurrent browser sessions with different configurations
5. Screenshot Format: The screenshot tool returns base64-encoded image data
6. Selector Support: Every element-based tool accepts a CSS selector, an XPath (xpath: prefix or starting with //) or a snapshot ref (ref:e12, see snapshot)
7. Tabs: tools act on the session's current tab; use new_tab / switch_tab to change it

Tools

Category	Tools
Session Management	create_session list_sessions get_session_info close_session
Navigation	navigate go_back go_forward refresh
Interaction	click fill_form press_key hover drag_and_drop scroll select_option upload_file accept_cookies solve_captcha
Extraction	snapshot get_text get_html screenshot get_title get_url find_by_text
Waiting	wait_for_selector wait_for_text wait_for_network_idle
Tabs & Viewport	list_tabs new_tab switch_tab close_tab set_viewport
Advanced	execute_script evaluate_js get_cookies set_cookie clear_cookies get_attribute query_shadow_dom

Response Format

All tools return responses in this standard format:

Success Response:

{
  "success": true,
  "data": {
    // Tool-specific data
  }
}

Error Response:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Image Response (screenshot tool):

{
  "type": "image",
  "data": "base64-encoded-image-data",
  "mime_type": "image/png"
}

Common Error Scenarios

1. Missing session_id: "session_id is required. Create a session first using create_session tool."
2. Invalid session: "Session not found: {session_id}"
3. Element not found: "Element not found: {selector}"
4. Timeout errors: "Navigation timed out" / "Timed out after 10s waiting for #x to be visible"
5. Any other tool failure: "{tool_name} failed: {error}" (e.g. "execute_script failed: ReferenceError: foo is not defined")

Best Practices

1. Always create a session first: Use create_session before any browser operations
2. Use resource discovery: Query ferrum://browsers and ferrum://bot-profiles to see available configurations
3. Handle sessions properly: Close sessions when done to free resources
4. Snapshot before acting: call snapshot and use the returned refs (ref:e12) instead of guessing selectors
5. Wait explicitly: use wait_for_selector / wait_for_text / wait_for_network_idle rather than fixed delays
6. Use appropriate selectors: Prefer CSS selectors for performance, XPath for complex queries
7. Set timeouts wisely: Increase timeout for slow-loading pages
8. Force clicks sparingly: Only use force: true when necessary, as it bypasses visibility checks
9. Screenshot optimization: Use jpeg format for smaller file sizes when quality is not critical