Issue #262 opened: Structured tool output (outputSchema) — selective adoption with token budget guardrails

Why

Structured tool output (2025-06-18 spec: outputSchema on the tool definition, structuredContent in results) lets clients validate and machine-consume results instead of parsing JSON out of a text blob. Well supported by major clients now; SDK 1.x registerTool supports it.

The tension

outputSchema adds tokens to every tools/list response — and this repo's headline feature is the 85% token reduction (~6,600 total). Blanket adoption on 42 tools could claw back a big chunk of that saving. So: selective, measured.

Proposed approach

1. Adopt on the highest-value, stable-shape tools first:
   • get_infrastructure_overview (counts + summaries — the "start here" tool)
   • list_servers / list_applications / list_databases / list_services (small summary shapes)
   • deployment get (status polling loops benefit most from typed status)
   • get_mcp_version, get_version
2. Measure before/after: record tools/list token count in the PR description (we already track the 6,600 number in README). Set a budget: abort if total exceeds ~8k tokens.
3. Skip: consolidated CRUD tools (application, database, service, …) whose result shape varies wildly by action — schema unions would be huge and low-value.
4. Emit structuredContent alongside the existing text content (spec allows both; older clients keep working).

Note

The wrap() helper in mcp-server.ts centralizes result formatting — one change point for emitting structuredContent.

Refs: #259 (V3 epic), #260 (registerTool migration is a prerequisite).

🤖 Generated with Claude Code