brave-answers-mcp: Instructions file for Codex

brave-answers-mcp

TypeScript MCP server (stdio) for the Brave Answers API — async research submit/status/result + cited one-shot answers. Full docs: README.md; resume map, cost ledger, and open items: HANDOFF.md.

Build / test / run

npm install
npm run build        # tsc → dist/  — rebuild after ANY src/ change
npm run test:parser  # offline SSE parser unit tests (no API calls)
node dist/smoke.js   # LIVE end-to-end: tool listing + one real call (~$0.05)

There is no test runner — test:parser executes node dist/test-parser.js, so it always tests the last build, not the current sources. Order matters: build → test:parser. There is no lint, formatter, or typecheck step beyond tsc itself (it typechecks during build).

The MCP speaks stdio; dist/index.js is what hosts launch. A running host (opencode) keeps the pre-restart build in memory — restart the host after rebuilding to pick up changes.

Secrets

• API key = BRAVE_ANSWERS_KEY env var (Brave Answers plan, billed separately from Brave Search). Never print, commit, or log it.
• smoke.ts and any test client MUST pass env: explicitly — the MCP SDK's StdioClientTransport sanitizes child env by default (inherits only HOME/LOGNAME/PATH/SHELL/TERM/USER); forward TMPDIR too or raw SSE tees land in /tmp/brave-answers-mcp/ instead of the shell's $TMPDIR.

Cost & latency

Every API call costs real money (Answers plan): simple ~$0.05, research ≈ $0.07 × queries run (narrow ~$0.07, broad $0.77+). Do not call the API in loops or without need; test:parser is the zero-cost test path. See README cost model.

Research jobs are long-running (~90–300s; second budgets are SOFT, not walls): research_submit returns immediately — never block or wait on it. End the turn, then poll research_status and fetch research_result in a LATER turn once completed. Simple answers (~2–30s) is safe within one turn.

Conventions

• Source of truth for API params/tag formats: references/official-brave-skills/answers-SKILL.md (pinned from brave/brave-search-skills). Re-fetch from upstream rather than editing the pinned copy.
• Raw SSE evidence lives in artifacts/sse/ (named by research_id / uuid); add new probe files with an artifacts/README.md row.
• Display normalization (citation dedup by URL, <answer> unwrap, progress collapse) is intentional and tested in src/test-parser.ts — keep tests in lockstep with parser changes.
• Keep dist/ and node_modules/ git-ignored; commit only sources, docs, lockfile, and artifacts.