#280 feat(mcp): improve context discovery ergonomics

[Anonymous]

Originally created by: Avazbek22

Improves the v5.2 MCP read path after live tool-use testing showed avoidable retries, incomplete large-tree orientation, and a misleading mixed metrics basis.

What changed

• get_file and read_pack clamp an end_line beyond EOF and return the available text with a trusted [Showing lines ...; end_line ... exceeded the file.] trailer. Invalid starts and reversed ranges retain DPX-MCP-INVALID-RANGE.
• Implicit-depth Markdown/text trees now render the deepest complete depth that fits 2,000 lines. If depth 1 cannot fit, or when max_depth is explicit, the existing line truncation remains. JSON/XML still reject overflow, now with a fitting max_depth.
• analyze.topFiles marks files withheld from bounded inspection with optional uninspected: true. Their estimated characters now participate in the aggregate token basis, so an item cannot exceed the total merely because its content was withheld.
• All seven tool descriptions now distinguish purpose, named alternatives, result, and key limit in 40–60 words. Their combined size falls from 1,782 to 1,779 characters.
• initialize.instructions now publishes the recommended workflow, redaction grammar and allowlisted examples, trusted/untrusted boundary, response limits, and glob rules.
• The list_projects and analyze output schema fields have concise descriptions. Documentation specifies every new rule and cached-schema refresh requirement.

Security posture

• Source projects remain read-only. No new process, Git invocation, network path, redaction control, startup flag, tool parameter, or configuration mechanism was added.
• Mandatory redaction remains fail-closed. Uninspected file content is still withheld; only its existing size-based estimate and the new boolean are exposed.
• All range, depth, warning, and continuation notices remain trusted text outside project-controlled <untrusted-data-...> blocks.
• Existing DPX-MCP-* codes, filter semantics, startup flags, and tool input schemas remain unchanged.

Behavior changes and compatibility

• A range ending after EOF now succeeds instead of requiring a retry. Callers needing strict validation can first obtain the line count and send end_line <= N; no strict-range switch was added.
• Omitted max_depth now favors a complete shallower tree over the first 2,000 traversal lines. Pass an explicit max_depth to retain caller-selected depth and the prior truncation behavior.
• analyze.topFiles[].uninspected is additive and optional. Consumers caching output schemas should refresh them.

Validation

• MCP infrastructure: 108 passed, 6 platform skips.
• MCP integration: 129 passed, 4 platform skips.
• Published-process MCP: 44 passed, 1 publish-fixture skip.
• Documentation contracts: 19 passed.
• Release MCP build with warnings as errors: 0 warnings, 0 errors.
• No full local suite was run; cross-platform CI remains the final arbiter.