mcp-compliant http content fetching with stdio transport
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.
Unique: Implements MCP server pattern with stdio-based communication and Zod schema validation, enabling seamless integration with MCP-aware clients without requiring HTTP server infrastructure or custom protocol negotiation
vs alternatives: Simpler deployment than REST API servers (no port management, firewall rules) and more standardized than custom tool protocols, but less flexible than HTTP APIs for cross-language integration
html-to-plain-text extraction with dom parsing
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.
Unique: Leverages JSDOM's full DOM implementation rather than regex or simple HTML stripping, enabling accurate text extraction from complex nested structures and handling of edge cases like nested tags and entity encoding
vs alternatives: More accurate than regex-based HTML stripping (handles nested tags, entities correctly) but slower than lightweight parsers like cheerio; better for content extraction than for performance-critical scenarios
html-to-markdown conversion with semantic preservation
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.
Unique: Uses TurndownService's rule-based HTML-to-Markdown mapping rather than simple regex replacement, enabling semantic preservation of document structure (headings, lists, links, emphasis) and handling of edge cases through configurable conversion rules
vs alternatives: Preserves more semantic structure than plain text extraction, making output more useful for LLMs; more reliable than regex-based converters but slower than simple text extraction
json response parsing and validation
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.
Unique: Combines native JSON.parse() with Zod schema validation in a single tool, enabling both parsing and structural validation without requiring separate validation steps or custom error handling in client code
vs alternatives: More robust than raw JSON.parse() (includes validation) but adds latency vs simple parsing; simpler than full OpenAPI client generation but less feature-rich
raw html content retrieval with custom headers
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.
Unique: Exposes native fetch API through MCP tool interface with support for custom headers, enabling agents to handle authentication, content negotiation, and server-specific requirements without custom HTTP client code
vs alternatives: Simpler than full HTTP client libraries (no dependency bloat) but less feature-rich than axios or node-fetch wrappers; native fetch is faster than alternatives but offers fewer convenience methods
request validation with zod schema enforcement
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.
Unique: Implements Zod-based request validation at the MCP server layer before tool execution, providing type-safe input handling and structured error messages without requiring validation logic in individual tool implementations
vs alternatives: More robust than manual validation (catches edge cases) and provides better error messages than simple type checking; adds minimal latency vs runtime validation
tool registration and mcp protocol handler binding
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.
Unique: Implements MCP tool registration pattern with static schema definitions and handler binding, enabling clients to discover and invoke tools through a standardized protocol without custom negotiation or discovery mechanisms
vs alternatives: More standardized than custom tool protocols but less flexible than dynamic tool registration; simpler than REST API servers but requires MCP-aware clients
error handling and graceful failure reporting
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.
Unique: Implements error handling at the MCP server layer with descriptive error messages and no stack trace exposure, enabling clients to handle failures gracefully while maintaining security and debuggability
vs alternatives: More user-friendly than raw exception propagation but less detailed than structured error codes; simpler than full retry logic but requires client-side retry implementation