duckduckgo-backed web search with llm-optimized result formatting
Executes web searches against DuckDuckGo's HTML interface (not API-dependent) and returns formatted results with titles, URLs, and snippets cleaned for LLM consumption. The search tool implements query parameter handling with configurable max_results (default 10) and applies post-processing to remove ads and clean redirect URLs before returning structured text output. Built on FastMCP framework's @mcp.tool() decorator pattern for seamless MCP protocol integration.
Unique: Uses DuckDuckGo's HTML interface scraping instead of requiring API keys or paid search services, combined with LLM-specific result post-processing (ad removal, URL cleaning) rather than returning raw search results. Implements MCP protocol binding via FastMCP framework, making it a drop-in tool for MCP-compatible clients without additional orchestration.
vs alternatives: Eliminates API key management and cost overhead compared to Google Custom Search or Bing Search API, while providing privacy-first search without tracking; faster integration than building custom web search from scratch due to MCP protocol standardization.
webpage content fetching and html-to-text parsing
Retrieves raw HTML from specified URLs and parses it into cleaned, LLM-friendly text content using HTML parsing libraries. The fetch_content tool accepts a URL parameter, handles HTTP requests with error management, strips HTML markup, removes boilerplate (navigation, ads, scripts), and returns structured text suitable for LLM context injection. Implements rate limiting (20 requests/minute) and comprehensive error handling for network failures, invalid URLs, and parsing exceptions.
Unique: Combines HTTP fetching with HTML parsing and boilerplate removal in a single MCP tool, specifically optimized for LLM consumption (removes ads, scripts, navigation) rather than returning raw HTML. Integrates directly into MCP protocol flow, allowing LLMs to chain search → fetch → analyze without external tool orchestration.
vs alternatives: Simpler than building custom web scraping pipelines; more LLM-optimized than generic HTML-to-text converters by removing ads and boilerplate; integrated into MCP protocol unlike standalone libraries like Selenium or Puppeteer.
rate-limited request throttling with per-tool quotas
Implements token-bucket style rate limiting with separate quotas for search (30 req/min) and content fetching (20 req/min) operations. The rate limiter tracks request timestamps and enforces delays or rejections when quotas are exceeded, preventing service abuse and DuckDuckGo overload. Built into the tool execution pipeline before external requests are made, with error responses returned to the MCP client when limits are hit.
Unique: Implements dual-quota rate limiting (30 req/min search, 20 req/min content) at the MCP tool execution layer rather than at HTTP client level, providing tool-specific throttling that reflects actual service impact. Integrated into FastMCP framework's tool decorator pattern, making limits transparent to MCP clients without additional configuration.
vs alternatives: More granular than generic HTTP rate limiters (separate quotas per tool); simpler than distributed rate limiting systems (no Redis/external state needed); integrated into MCP protocol layer vs requiring separate middleware.
mcp protocol server implementation with fastmcp framework
Implements the Model Context Protocol (MCP) specification using the FastMCP framework, exposing search and content fetching as standardized MCP tools with schema validation, error handling, and protocol-compliant request/response serialization. The server initializes as a FastMCP instance with identifier 'ddg-search', decorates tool methods with @mcp.tool(), and handles MCP client communication including tool discovery, invocation, and result formatting. Supports multiple deployment modes (Smithery, Python package, Docker) with standardized MCP configuration.
Unique: Uses FastMCP framework to abstract MCP protocol complexity, allowing tool definitions via simple Python decorators (@mcp.tool()) rather than manual protocol handling. Provides standardized tool discovery and invocation without custom client integration code, supporting multiple deployment modes (Smithery, pip, Docker) with identical MCP interface.
vs alternatives: Simpler than building custom MCP servers from scratch (FastMCP handles protocol details); more standardized than REST API wrappers (MCP protocol ensures client compatibility); supports multiple deployment modes vs single-deployment-model tools.
multi-deployment packaging with smithery, pip, and docker support
Provides three deployment pathways: Smithery (simplified MCP server registry installation), Python pip package installation, and Docker containerization. Each deployment method maintains identical MCP tool interface and functionality while accommodating different infrastructure preferences. Smithery integration enables one-click installation in Claude Desktop; pip allows local Python environment installation; Docker enables containerized deployment with environment isolation. Configuration is standardized across all deployment modes via environment variables and MCP configuration files.
Unique: Supports three distinct deployment pathways (Smithery registry, pip package, Docker container) with unified MCP interface, allowing users to choose infrastructure based on preference without code changes. Smithery integration provides one-click Claude Desktop installation, eliminating manual configuration for non-technical users.
vs alternatives: More flexible than single-deployment-model tools (supports Smithery, pip, Docker); simpler than custom deployment scripts (standardized across modes); Smithery integration reduces friction vs manual MCP server setup.
error handling and graceful degradation with comprehensive exception management
Implements multi-layer error handling covering network failures (connection timeouts, DNS resolution), invalid inputs (malformed URLs, empty queries), parsing failures (corrupted HTML, encoding issues), and rate limit violations. Each error type is caught, logged, and returned to the MCP client with descriptive error messages rather than crashing the server. Includes fallback behaviors such as partial result return on parsing failures and clear error codes for client-side retry logic.
Unique: Implements comprehensive exception handling at the MCP tool layer, catching and converting Python exceptions into MCP-compliant error responses rather than propagating crashes. Provides descriptive error messages for network, parsing, and validation failures, enabling client-side retry logic and fallback strategies.
vs alternatives: More robust than tools without error handling (prevents server crashes); more informative than generic HTTP error codes (specific error types for client logic); integrated into MCP protocol vs requiring separate error handling middleware.