Expose individual status-field explanations through MCP

[Widthdom]

Problem and priority

P3 — posting order 9/10. Audit candidates: D08.

MCP clients can ask for aggregate freshness/readiness explanations but cannot retrieve the typed explanation of a particular status field available through CLI. An additive field-explanation surface would make readiness interpretation and recovery guidance discoverable without a separate CLI call.

Reproduction and actual results

dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll status --explain index_complete --json --compact --db .cdidx/codeindex.db

The CLI returns a typed compact explanation. In the initialized MCP session, this tools/call input:

{"name":"status","arguments":{"explain":"index_complete","format":"compact"}}

is rejected with explain must be one of freshness, readiness, all. A control request with explain: "readiness" succeeds. This is a missing MCP capability; its existing aggregate explain modes work.

Implementation instructions and cautions

Start with the status contract in src/CodeIndex/Mcp/McpToolArgumentContracts.cs and the shared CLI status-explanation/serializer metadata.

• Add an unambiguous field-explanation argument or dedicated tool, retaining the established freshness, readiness and all meanings.
• Share the CLI's accepted top-level keys and bounded dot-separated member paths derived from StatusResult serializer metadata. Do not maintain a drifting MCP field allowlist.
• Reuse typed meaning/source/dependencies/interpretation/remediation output; explaining a field should not require reading its runtime value.
• Preserve compact required fields, omission accounting and global output bounds. If even the compact schema cannot fit, retain the measured E028_RESPONSE_BUDGET_TOO_SMALL retry contract rather than returning an empty success.
• Keep bounded unknown-key candidates and sanitization. Do not leak database paths, runtime values, timings or indexed HEAD metadata through a static explanation.

Acceptance and validation

• Compare CLI and real MCP calls for index_complete and a nested field such as db_pragma_settings.busy_timeout_ms, in normal and compact/bounded forms.
• Cover unknown/overlong paths, ignored properties, case/alias behavior, too-small budgets and tools/list discovery.
• Confirm that existing aggregate explain modes keep their original behavior and update MCP documentation/examples.

Prior issues

Closed #5093 fixed compact/bounded CLI explanation loss, building on #4891 and #3936. Reuse that contract. The audited CLI explanation works; this request concerns MCP access and is not a recurrence of the old empty CLI payload.

Baseline and delivery

Observed during the 2026-09-12 dogfood audit on macOS arm64, using repository-built cdidx 1.49.0 / Debug net8.0 at 36f2e68cb0d7f17bc9591d01ad3045abe870da9b. The build passed with zero warnings/errors. The root database and workspace-manifest freshness checks were healthy, with index and reference-graph completeness true. Counts/timings describe that checkout. Validation during discovery used focused CLI/MCP/LSP reproductions, not the full test suite.

Implement one focused PR for this issue. Follow AGENT_GUIDE.md and the relevant workflows, use the repository-built cdidx for discovery, preserve supported .NET 8/.NET 9 and cross-platform behavior, and avoid new runtime dependencies outside repository policy. Add focused behavioral tests for changed contracts, update affected help/documentation, and include a bilingual changelog.d/unreleased/ fragment for user-visible changes.