enh: structured output go brr

[taylorwilsdon]

Closes #273

Fix content blocks display for string-returning tools

Problem

Tool results displayed as wrapped JSON instead of clean content blocks:

{"result": "Found 15 files for user..."}

Solution

Clear output_schema on tools with x-fastmcp-wrap-result flag during tool registration. FastMCP now returns clean TextContent
blocks per MCP spec:

  {"content": [{"type": "text", "text": "Found 15 files for user..."}]}

Changes

• Modified filter_server_tools() in core/tool_registry.py (+21 lines)
• Automatically applies to all 16 string-returning tools
• No changes to individual tool files

Result

Claude Code now displays tool output with proper formatting and expandable sections instead of JSON blobs.

  Before: {"result": "Found 15 files..."}
  After: Clean text with (ctrl+o to expand) UI

Summary by CodeRabbit

• Bug Fixes

  • Tool outputs no longer expose internal wrapper markers, so plain text responses display cleanly.
  • Server startup now normalizes tool output schemas to ensure consistent text formatting across modes.
  • Mode handling and tool accessibility labeling refined to avoid inconsistent behavior in read-only and OAuth modes.

• Tests

  • Added tests for email body content selection (HTML vs. plain text) and for output-schema normalization across modes.

[Copilot]

Pull request overview

This PR enhances the tool filtering logic to clear output schemas from string-wrapped tools, ensuring cleaner content block display. The change addresses issue #273 by preventing tools from returning output in the format {"result": "..."} when a simple string response is more appropriate.

Changes:

• Updated filter_server_tools to perform a two-pass process: first removing disabled tools, then clearing output schemas
• Added logic to identify and clear output schemas for string-wrapped tools marked with x-fastmcp-wrap-result
• Enhanced logging to report both tool removal and schema clearing operations

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e5ca7d7 and 26ef493.

📒 Files selected for processing (4)

• core/tool_registry.py
• fastmcp_server.py
• main.py
• tests/core/test_tool_registry.py

🚧 Files skipped from review as they are similar to previous changes (1)

• core/tool_registry.py

---

📝 Walkthrough

Walkthrough

Adds a normalization step to the tool registry that clears output schemas for tools returning wrapped string results, exposes normalize_string_tool_output_schemas(server), and invokes it during server startup; also adds tests for message body formatting and tool registry behaviors across modes.

Changes

Cohort / File(s)	Summary
Tool Registry & normalization core/tool_registry.py	Added _is_wrapped_string_output_schema helper and new public normalize_string_tool_output_schemas(server), changed filter_server_tools to compute read_only_mode locally and to call normalization logic that clears output_schema for wrapped string tools and counts/logs clears.
Server startup calls fastmcp_server.py, main.py	Imported and invoked normalize_string_tool_output_schemas(server) immediately after filter_server_tools(server) during server initialization/startup.
Tool registry tests tests/core/test_tool_registry.py	New tests validating normalization behavior (clearing string tool schemas), pipeline behavior in default and oauth modes, and that legacy auth entrypoints are filtered as expected.
Gmail body formatting tests tests/gmail/test_message_body_content.py	New tests for _format_body_content verifying selection between HTML and plain text across several scenarios (missing/plain-as-footer/meaningful/placeholder plain text).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I hopped through registry rows, sniffed a wrapped-up string,
Cleared its schema gently — now content can sing.
A tiny normalize hop, a startup-time cheer,
Tests nibble the crumbs and confirm all is clear. 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 3

❌ Failed checks (2 warnings, 1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description provides context and examples but does not follow the provided template structure with required sections like Type of Change, Testing, and Checklist.	Reorganize the description to match the template: add Type of Change, Testing checklist, and Checklist sections with appropriate selections and confirmations.
Docstring Coverage	⚠️ Warning	Docstring coverage is 21.05% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title 'enh: structured output go brr' is vague and does not clearly convey the specific technical change; it uses informal language that lacks clarity about what 'structured output' means.	Use a more descriptive title like 'Normalize string tool output schemas to fix content block display' to clearly communicate the main change.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR successfully addresses the core requirement from issue #273 by implementing content array normalization for string-returning tools via the new normalize_string_tool_output_schemas function.
Out of Scope Changes check	✅ Passed	Changes are properly scoped to the stated objective: core/tool_registry.py modifications, fastmcp_server.py and main.py integration, plus comprehensive tests for the new functionality.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch issues/273

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ustunb]

Closing — stale for 7 weeks, cleaning up branches.