fetch-mcp

Implements a Model Context Protocol server that exposes HTTP fetching as standardized tools via stdin/stdout communication. The server registers tool handlers with the MCP SDK, validates incoming requests using Zod schemas, and returns responses formatted according to MCP specification. This enables any MCP-compatible client (Claude, custom agents, etc.) to invoke web fetching without custom HTTP client implementation.

Uses JSDOM to parse HTML documents into a virtual DOM, then extracts text content while removing HTML markup, scripts, and styling. The Fetcher class instantiates a JSDOM window, traverses the DOM tree, and returns cleaned text. This approach preserves text structure and readability while stripping all HTML artifacts, making content suitable for LLM processing without markup noise.

Integrates TurndownService to convert HTML documents into Markdown format while preserving semantic structure (headings, lists, links, emphasis). The service maps HTML elements to Markdown equivalents and applies configurable rules for handling edge cases. This enables LLMs to work with structured content that retains formatting cues without raw HTML complexity.

Fetches content from a URL, parses the response as JSON using native JSON.parse(), and validates the structure using Zod schemas. If parsing fails, returns an error response. This capability enables agents to reliably consume JSON APIs and validate response schemas before passing data downstream.

Fetches HTTP content from a URL using the native fetch API and returns the raw HTML response body. Supports optional custom HTTP headers (User-Agent, Authorization, etc.) to handle authentication, content negotiation, and server-specific requirements. This is the foundational capability that other transformations (text, Markdown, JSON) build upon.

Uses Zod schemas to validate all incoming tool requests before processing. Each tool (fetch_html, fetch_json, fetch_txt, fetch_markdown) has a corresponding Zod schema that validates URL format, header structure, and required fields. Invalid requests are rejected with structured error messages before reaching the fetcher logic, preventing malformed requests from consuming resources.

Registers four tools (fetch_html, fetch_json, fetch_txt, fetch_markdown) with the MCP SDK and binds request handlers to each tool. The server implements the MCP tool listing protocol (returning tool schemas) and tool calling protocol (executing tools and returning results). This enables MCP clients to discover available tools and invoke them with proper request/response formatting.

Catches exceptions during fetch operations (network errors, timeouts, parsing failures) and returns structured error responses through the MCP protocol. Errors include descriptive messages indicating the failure type (network error, invalid URL, parsing failure, etc.) without exposing internal stack traces. This enables clients to handle failures gracefully and retry or fallback appropriately.