duckduckgo-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A Model Context Protocol (MCP) server providing DuckDuckGo web search and webpage content fetching. Built with Python on the MCP Python SDK's MCPServer (formerly FastMCP). Published to PyPI as duckduckgo-mcp-server.

Commands

# Install dependencies
uv sync

# Run the server
uv run duckduckgo-mcp-server

# Run with MCP Inspector (for interactive testing)
mcp dev src/duckduckgo_mcp_server/server.py

# Run all tests (unit + e2e)
uv run python -m pytest src/duckduckgo_mcp_server/ -v

# Run only unit tests
uv run python -m pytest src/duckduckgo_mcp_server/test_server.py -v

# Run only e2e MCP protocol tests
uv run python -m pytest src/duckduckgo_mcp_server/test_e2e.py -v

# Run a single test
uv run python -m pytest src/duckduckgo_mcp_server/test_server.py::TestRateLimiter::test_acquire_removes_expired_entries

# Build package
uv build

# Lint (ruff) — matches the CI `quality` job
uv run ruff check .

# Audit dependencies for known vulnerabilities (informational)
uv run --with pip-audit pip-audit --desc

Architecture

Single-module server in src/duckduckgo_mcp_server/server.py with these main classes:

• DuckDuckGoSearcher — Scrapes DuckDuckGo's HTML endpoint (html.duckduckgo.com/html) via POST requests. Parses results with BeautifulSoup. Handles SafeSearch (kp param) and region (kl param) configuration.
• WebContentFetcher — Fetches arbitrary URLs, strips non-content elements (script, style, nav, header, footer), and returns cleaned text truncated to 8000 chars. Parsed pages are kept in an in-memory TTLCache so pagination does not re-download.
• RateLimiter — Sliding-window limiter (default). TokenBucketLimiter is the optional burst-then-smooth strategy. HostRateLimiter adds a per-host fetch cap. HTTP 429 honors Retry-After and retries once. Cache hits skip the fetch limiter.
• TTLCache — TTL + LRU cache used by fetch_content. Disabled when TTL or max entries is 0.
• LinkRegistry — In-memory LRU map behind ref://<id> tokens (issue #43). Search output replaces URLs longer than DDG_REF_URL_THRESHOLD with tokens; fetch_content resolves them before the SSRF guard; expand_link returns the original. Shared module-level instance links.