[nick-nlb]

Overview

Before this PR, the Narratives application overloaded the identifier mcp for two distinct concepts: the Model Context Protocol client and server transport (McpConfig, narratives_agent/mcp/, and workflows/mcp_loop.py) and the data-gathering stage of a chat turn across GeminiRole.MCP, gemini.mcp_model, thinking.mcp_level, prompts.mcp, defaults/prompts/mcp.md, SSE "phase": "mcp" frames, TurnTelemetry phase spans, and the React UI.

This PR renames the data-gathering turn stage and its configuration keys, prompt file, GeminiRole, SSE phase, telemetry span, and UI status handling from mcp to discovery, while keeping the MCP protocol and transport layer (McpConfig, narratives_agent/mcp/, workflows/mcp_loop.py, MCP error codes, TurnTelemetry.mcp_iterations, and the /agent/health "mcp" key) named mcp.

Note: Looks bigger than it is, as it touches many files, but it is trivial.

Related Issues

• Follows #535, #537

Changes Made

• Turn-stage and configuration rename (mcp -> discovery): Renames the data-gathering stage and its GeminiRole from mcp to discovery across AgentConfig (gemini.discovery_model, thinking.discovery_level, prompts.discovery), the default prompt file (defaults/prompts/discovery.md), the JSON schema and example configs, SSE status and thought phase payloads, TurnTelemetry phase spans, and the React UI, while keeping MCP protocol/server configuration (McpConfig) and transport identifiers named mcp.
• Tests and documentation: Updates the agent and UI unit tests, docs/architecture.md, and docs/deployment.md to match the discovery stage name and configuration keys.

Testing Done

• pnpm test:agent (uv run pytest): 826 passed (matches narratives-gemini-roles at b322d698).
• pnpm test:ui (vitest run): 26 files, 286 passed.
• pnpm lint:ui (tsc --noEmit and biome check): passed across 48 checked files.
• pnpm lint:agent (ruff format --check, ruff check, and mypy --strict): passed across all 64 source files with no overrides.
• pnpm lint:deploy: terraform fmt -check, shellcheck, and hadolint passed (terraform validate has a pre-existing local Terraform 1.15 backend-config error unrelated to this PR; no deploy/ files are modified).
• pnpm build: compiled the UI bundle into ui/dist/ and staged ui/dist/ into agent/static/ and defaults/ (including defaults/prompts/discovery.md) into agent/defaults/ with a clean git status -s.
• npx --yes -p ajv-cli@5.0.0 -p ajv-formats@3.0.1 ajv validate --spec=draft2020 --strict=false -c ajv-formats -s schemas/agent-config.schema.json -d defaults/agent-config.json and -d schemas/agent-config.example.json: both valid.

Checklist:

• Unit tests passed
• Integration tests passed (N/A)
• Manual verification
• Any updated goldens or fixtures were reviewed and are intentional (no goldens; test fixtures and assertions updated from "mcp" / mcp_model / mcp_level to "discovery" / discovery_model / discovery_level)

Manual

Tested with pnpm dev:agent and pnpm dev:ui:

• Default configuration and end-to-end turn streaming: Started the agent and UI dev servers with defaults/agent-config.json and defaults/prompts/discovery.md and submitted "What is the population of France?" and "How has the population of California changed since 2010?". Verified in the network inspector that /agent/chat emitted status ({"phase": "discovery", "message": "Querying data tools..."}) and thought ({"phase": "discovery", ...}) SSE events, the UI ReasoningBlock and response card skeleton transitioned through classify -> discovery -> synthesis -> done without visual changes, and the turn telemetry log recorded phases_ms.discovery.

Risk & Rollback

There are no active production deployments of Narratives. Rollback is reverting the PR.

Follow-ups

• Decouple per-role Gemini model fields on GeminiConfig (synthesis_model, chart_config_model, follow_up_model) and continue with the agent loop updates.

Checklist

• I have read AGENTS.md and followed CODING_GUIDELINES.md, plus FRONTEND.md for UI changes.
• I have run the app's lint, test, and build commands, as documented in that application's guide.
• I have commented my code, particularly in hard-to-understand areas.
• My changes generate no new warnings.

---

Note: Only Maintainers can approve and merge PRs. Expected initial review time: 3 business days.

[gemini-code-assist]

Code Review

This pull request systematically renames references to 'mcp' to 'discovery' across the narratives agent codebase, including configuration models, schemas, workflows, telemetry, server routes, UI components, tests, and documentation. Key changes include renaming mcp_model to discovery_model, mcp_level to discovery_level, GeminiRole.MCP to GeminiRole.DISCOVERY, and run_mcp_phase to run_discovery_phase. I have no feedback to provide as there are no review comments.

[juliawu]

Thanks! This looks good. Adding one more instance in chat.py found by Gemini:

narratives/agent/src/narratives_agent/server/routes/chat.py:97 — [NIT] Stale phase name in _turn_events docstring. Line 97 still says "because the MCP phase reports model thoughts through a callback", whereas that phase is now the discovery phase. Update "the MCP phase" to "the discovery phase".