fix: plan_file_info returns empty for report artifact on HTTP server

[neoneye]

Summary

• Root cause: FastMCP derives outputSchema from Annotated[CallToolResult, OutputModel] return type annotations, producing a schema that only covers the success shape. Tools like plan_file_info and plan_status have multiple response shapes (oneOf: success, not-ready, error). The derived schema misses the other shapes, causing MCP clients to see non-conforming responses as empty.
• Fix: Remove output model annotations from all 8 tool functions, inject canonical oneOf schemas from TOOL_DEFINITIONS into FastMCP tools after registration.
• Defense: Add JSON-RPC guard in strip_redundant_content to prevent accidental stripping of MCP protocol envelopes.
• Tests: 16 new tests covering all response shapes, schema structure, return-type regression, and content stripping edge cases (51 → 67 tests across the 3 files).
• Docs: New AGENTS.md section documenting the injection pattern, rules, and potential issues with private FastMCP internals.
• Cleanup: Rename legacy "task-id" → "plan-id" in test fixtures.

Test plan

• test_http_utils.py — 10 tests: JSON-RPC guard (error, notification, content-only), non-JSON-RPC stripping, value preservation
• test_plan_file_info_tool.py — 15 tests: every response shape (pending, processing, completed, failed, not-found) for both report and zip, structuredContent presence, content/structuredContent consistency
• test_tool_surface_consistency.py — 45 tests: FastMCP schema matches TOOL_DEFINITIONS, oneOf variant counts, no Annotated return types, schema not derived from flat Pydantic model

SQLALCHEMY_DATABASE_URI=sqlite:// PLANEXE_MCP_REQUIRE_AUTH=false \
python -m pytest mcp_cloud/tests/test_http_utils.py \
mcp_cloud/tests/test_plan_file_info_tool.py \
mcp_cloud/tests/test_tool_surface_consistency.py -v

🤖 Generated with Claude Code