web-researcher-mcp: Instructions file for Claude Code

CLAUDE.md — web-researcher-mcp

An MCP server in Go that gives AI assistants web search, content extraction, and multi-source research capabilities over STDIO or HTTP transport.

Commands

go build -o web-researcher-mcp ./cmd/web-researcher-mcp    # Build
go test ./...                                               # Unit + integration tests
go test -race ./...                                         # Race detector
go test -tags=e2e -count=1 ./tests/e2e/...                  # E2E (needs e2e build tag + API keys)
go test -tags=live ./...                                    # Live external-API tests (needs API keys)
go tool golangci-lint run                                   # Lint (pinned version)
go tool govulncheck ./...                                   # Vulnerability scan (pinned version)
make verify                                                 # Full CI gate: fmt-check + vet + lint + sec + vuln + validate-lenses + test-race + test-e2e + check-python-drift + test-python + build
make test-python                                            # Python SDK unit + integration tests (mock HTTP server, no binary)
make test-python-live                                       # Python SDK live E2E tests (builds Go binary; needs internet)
make rebuild-local                                          # Clear caches + rebuild + reinstall (macOS-SIGKILL-safe); ARGS="--no-install" to build only

Prefer make for CI-gated targets — they carry the right flags, pinned tools, and correct sequencing. Use raw go commands for one-off interactive use only.

Contribution Rules

• Never push directly to main. All changes go through a branch and a pull request — no exceptions, including chore commits and one-liners.
• Commit format: type(scope): subject [(#PR)] — types: feat, fix, chore, docs, refactor, test, ci. Examples: fix(config): validate CACHE_ENCRYPTION_KEY · chore: bump VERSION to 1.36.4 · docs: full zero-drift audit.
• After any edit to lenses/: run make sync-lenses before committing — copies changes into internal/search/lenses_embed/. TestEmbeddedLensesMatchRoot fails CI if they diverge.
• After any tool schema change: run make gen-python-client, then stage and commit the regenerated python/web_researcher_mcp/{models.py,client.py,__init__.py} in the same commit. The python-drift CI job and the pre-commit hook both fail if you skip this.
• GitHub issues are specs, not scratchpads. An issue body states current codebase state and what to build — concise, concrete, ready to implement. Never post a comment narrating your own investigation, hedges, or "here's what I checked" reasoning — that's internal process, not spec content, and it wastes tokens for every agent that reads the issue afterward. When an issue's cited state goes stale (a blocker ships, a file moves), edit the body in place to reflect current reality — don't append a comment layering old-vs-new. Comments are for genuine back-and-forth with external contributors only.