feat(mcp): add omniroute_web_fetch tool for URL content extraction

[ponkcore]

Summary

Exposes the existing POST /v1/web/fetch REST endpoint as an MCP tool (omniroute_web_fetch), enabling AI agents to fetch and extract web page content through OmniRoute's gateway.

Background

OmniRoute already has a working REST endpoint at /v1/web/fetch that supports three providers (Firecrawl, Jina Reader, Tavily) for URL content extraction. However, this endpoint is not exposed as an MCP tool — only omniroute_web_search is available. This means AI agents connected via MCP cannot fetch URL content without falling back to external tools or curl.

Changes

open-sse/mcp-server/schemas/tools.ts

• Added webFetchInput schema: url (required), provider, format (markdown/html/links/screenshot), include_metadata, depth, wait_for_selector
• Added webFetchOutput schema: provider, url, content, links, metadata, screenshot_url
• Added webFetchTool definition (Phase 1, scope: execute:search)
• Added webFetchTool to MCP_TOOLS array

open-sse/mcp-server/server.ts

• Added handleWebFetch() handler — calls omniRouteFetch("/v1/web/fetch", ...) following the same pattern as handleWebSearch()
• Registered omniroute_web_fetch tool with withScopeEnforcement
• Added webFetchInput to imports

src/shared/constants/mcpScopes.ts

• Added omniroute_web_fetch: ["execute:search"] — reuses the existing search scope

Design Decisions

• Scope: Reuses execute:search since web fetch is a search-adjacent capability (content extraction)
• Phase: Phase 1 (essential) — content fetching is fundamental for agent workflows
• Handler pattern: Mirrors handleWebSearch exactly — same error handling, logging, timeout (60s), and response format
• No new endpoints: The REST endpoint already exists and works. This PR only wraps it as an MCP tool

Testing

The REST endpoint has been verified working:

curl -s -X POST http://localhost:20128/v1/web/fetch \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","provider":"firecrawl"}'
# Returns: {"provider":"firecrawl","url":"https://example.com","content":"# Example Domain\n...","links":[],"metadata":null}

[gemini-code-assist]

Code Review

This pull request introduces the omniroute_web_fetch MCP tool, which allows fetching and extracting content from a URL using OmniRoute's web fetch gateway. It defines the input and output schemas, implements the handler, and registers the tool. The review feedback suggests adding a .max(2) constraint to the depth parameter in the Zod schema to match the handler's type limits, and requests adding unit tests for the new tool and handler to comply with the repository style guide's testing requirements.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The depth parameter in WebFetchRequest (defined in open-sse/handlers/webFetch.ts) is strictly typed as 0 | 1 | 2. Restricting the Zod schema's depth with .max(2) ensures that invalid depth values are caught during input validation before hitting the handler or the external provider.

  depth: z
    .number()
    .int()
    .min(0)
    .max(2)
    .optional()
    .describe("Crawl depth for Firecrawl (0 = single page, max 2)"),

[gemini-code-assist]

According to the Repository Style Guide (Rule 9), tests must always be included when changing production code in src/ or open-sse/. Please add unit tests (e.g., in tests/unit/) to verify the behavior of the new omniroute_web_fetch tool and its handler handleWebFetch.

References

1. Always include tests when changing production code (src/, open-sse/, electron/, bin/). ^(link)