duckduckgo-mcp

# CLAUDE.md This file provides guidance to Claude Code when working in this repository. ## Project Summary DuckDuckGo MCP server with two capabilities: - Web search via DuckDuckGo (ddgs) - URL fetch + conversion via Jina Reader Implements MCP over STDIO using FastMCP. ## Key Paths - `src/duckduckgo_mcp/cli.py`: CLI entry point (serve/search/fetch/version) - `src/duckduckgo_mcp/duckduckgo_search.py`: DuckDuckGo search implementation - `src/duckduckgo_mcp/jina_fetch.py`: Jina Reader fetch implementation - `src/duckduckgo_mcp/server.py`: MCP server setup - `src/duckduckgo_mcp/_version.py`: generated by setuptools_scm (do not edit) ## Common Commands ### Setup ```bash uv pip install -e . uv pip install -e ".[dev]" ``` ### Run ```bash duckduckgo-mcp serve duckduckgo-mcp serve --debug ``` ### CLI Smoke Tests ```bash duckduckgo-mcp search "your search query" --max-results 5 --safesearch moderate duckduckgo-mcp fetch "https://example.com" --format markdown --with-images duckduckgo-mcp fetch "https://example.com" --format json duckduckgo-mcp version ``` ### Quality ```bash black src isort src mypy src pytest pytest --cov=duckduckgo_mcp ``` ## Workflow Guidelines - Keep changes small and aligned with existing patterns. - Read relevant files before editing; avoid speculative edits. - Do not edit generated files (notably `src/duckduckgo_mcp/_version.py`). - Do not add or expose secrets in code or docs. - If you change CLI flags or MCP tool behavior, update README.md accordingly. - Prefer running targeted tests for the change when possible. ## Notes - Search uses the `ddgs` package (renamed from `duckduckgo-search`). - Fetch uses Jina Reader at `https://r.jina.ai/`.