git:20260306.d94d5f5 to git:20260524.7538095

# CLAUDE.md

This file provides guidance to Claude Code when working in this repository.

## Project Summary

Web Forager — a search-and-fetch toolkit for AI agents with three MCP capabilities:

- Web search via DuckDuckGo (ddgs)

- News search via DuckDuckGo (ddgs)

- URL fetch + conversion via direct HTTP/trafilatura (Jina Reader as fallback)

Also includes five Agent Skills (in `skills/`) that orchestrate search + fetch into

Implements MCP over STDIO using FastMCP.

## Key Paths

- `src/web_forager/cli.py`: CLI entry point (serve/search/news/fetch/version)

- `src/web_forager/duckduckgo_search.py`: DuckDuckGo web search implementation

- `src/web_forager/duckduckgo_news.py`: DuckDuckGo news search implementation

- `src/web_forager/web_fetch.py`: URL fetch (direct HTTP + trafilatura, Jina Reader fallback)

- `src/web_forager/server.py`: MCP server setup

- `src/web_forager/_version.py`: generated by setuptools_scm (do not edit)

- `skills/`: Agent Skills (each has a SKILL.md following the Agent Skills spec)

## Common Commands

### Setup

```bash

uv pip install -e .

uv pip install -e ".[dev]"

```

### Run

```bash

web-forager serve

web-forager serve --debug

```

### CLI Smoke Tests

```bash

web-forager search "your search query" --max-results 5 --safesearch moderate

web-forager news "your search query" --max-results 10

web-forager fetch "https://example.com" --format markdown --with-images

web-forager fetch "https://example.com" --format json

web-forager version

```

### Quality

```bash

black src

isort src

mypy src

pytest

pytest --cov=web_forager

```

## 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/web_forager/_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 and news search use the `ddgs` package (renamed from `duckduckgo-search`).

- Fetch tries direct HTTP + trafilatura first, falls back to Jina Reader at `https://r.jina.ai/`.

- Skills work standalone (ddgs + direct HTTP/Jina) and prefer MCP tools when available.