feat: MCP text format v2 — XML envelopes, relevance tiers, source context (R71)

[EtanHey]

Summary

Complete redesign of MCP text output format based on R71 research spec. Same data, much better presentation.

Before → After

brain_search:

Before: ├─ [1] rt-9102edee-  score:20.81  imp: 4  2026-04-03
         │  orchestrator     │ This chunk displays knowledge graph...

After:  ### ◇ [1] This chunk displays knowledge graph information about Cantaloupe AI...
        ●●● │ from: conversation │ 2026-04-03 │ project: orchestrator

brain_entity:

Before: ┌─ Entity: Etan Heyman
        │ id: 018c1da2868e75db  type: person
        ├─ Relations (10)
        │   ← coaches: coachClaude
        │   → owns: brainClaude

After:  ## ◆ Etan Heyman [Person]
        ### Outgoing relationships (9)
        → OWNS: brainClaude, voicelayer, etanheyman.com, songscript, domica, golems
        ### Incoming relationships (1)
        ← COACHES: coachClaude

Changes

• XML envelopes: <brain_search query=... tool="brain_search"> / <brain_entity name=... tool="brain_entity">
• Markers: ◆ entities, ◇ chunks (pattern-matchable)
• Relevance tiers: ●●●/●●○/●○○ (replaces raw score numbers)
• Source + date: "from: conversation │ 2026-04-03 │ project: orchestrator"
• Grouped relations: outgoing/incoming sections, UPPERCASE labels
• Smart sentence-boundary content cutting
• Chunk IDs hidden from display (still in XML attributes)

Test plan

• swift build compiles
• Live socat: brain_search('who works at Cantaloupe AI') → v2 format with KG + XML
• Live socat: brain_entity('brainlayer') → grouped relations, metadata, XML envelope
• Live socat: brain_entity('Etan Heyman') → outgoing/incoming sections
• Live socat: brain_search('best practices TDD') → no KG card, clean text results

Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com

🤖 Generated with Claude Code

Note

Reformat MCP text output to use XML envelopes, relevance tiers, and source context

• Rewrites TextFormatter.formatSearchResults to emit a <brain_search> XML envelope with markdown-style content, including relevance tier indicators (●●●/●●○/●○○), source labels, tags, and smart word/sentence-boundary truncation.
• Rewrites TextFormatter.formatEntitySimple to emit a <brain_entity> XML envelope with grouped outgoing/incoming relationships and bullet-list metadata, replacing ASCII box drawing.
• Rewrites TextFormatter.formatKGFacts to group facts into outgoing/incoming sections with uppercased relation type labels and arrow indicators.
• Adds relevanceTier and sourceLabel computed properties to SearchResult, and parses content_type and session_id from search payloads.
• In MCPRouter.handleBrainSearch, KG facts are now separated from the <brain_search> block with a horizontal rule.
• Behavioral Change: All MCP text output format changes are breaking for any downstream consumer parsing the previous ASCII box-drawn format.

^{Macroscope summarized b5bd9ba.}

Summary by CodeRabbit

New Features

• Enhanced search results display with improved structured formatting and clearer organization of related information
• Added relevance tier indicators and source labels to help identify result context and origin
• Improved knowledge graph facts presentation with directional relationship indicators for better clarity
• Better entity information display with cleaner formatting and well-organized metadata sections

[EtanHey]

@coderabbitai review

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

📝 Walkthrough

Walkthrough

Output formatting has been overhauled across the TextFormatter to use XML-like wrappers and structured metadata rendering. SearchResult model now includes content type and session tracking with derived relevance tier and source labels. MCPRouter integrates a separator line between knowledge graph facts and search results.

Changes

Cohort / File(s)	Summary
TextFormatter Formatting Overhaul brain-bar/Sources/BrainBar/Formatting/TextFormatter.swift	Replaced box-drawing output with XML-like wrappers (<brain_search>, <brain_entity>). Refactored formatSearchResults to include metadata composition from relevance tier, source label, and project. Updated formatKGFacts with section headers and directional relation arrows. Enhanced formatEntitySimple with grouped outgoing/incoming relations and bullet-list metadata. Added escapeXML(_:) and smartTruncate(_:maxLen:) helper functions.
MCPRouter Integration brain-bar/Sources/BrainBar/MCPRouter.swift	Added separator line (━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━) between KG facts and search result sections in handleBrainSearch output.
SearchResult Model Extension brain-bar/Sources/BrainBar/Models/SearchResult.swift	Added stored properties contentType and sessionID to track content source and session context. Added computed properties relevanceTier (score-derived discrete levels) and sourceLabel (human-readable content type mapping). Updated all initializer paths to populate new fields with defaults.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: entity detection + KG-augmented search in BrainBar (R70 PR2) #195: Modifies knowledge graph fact formatting and MCPRouter KG-section handling with direct overlap in code paths.
• feat: filter co_occurs_with in BrainBar Swift MCP + entity metadata (R70 PR1) #193: Updates entity description and relation rendering logic in TextFormatter.formatEntitySimple with related metadata changes.
• feat: port MCP output formatters to Swift with ANSI colors #132: Affects MCPRouter brain_search output formatting and section concatenation logic.

Poem

🐰 Twitches whiskers with glee
XML tags wrap the search so neat,
Relevance tiers hop with grace,
Relations arrow through the space,
Smart truncation bounds our words—
The finest formatting ever heard! 🌟

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 18.18% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: a redesign of MCP text output format to v2 with XML envelopes, relevance tiers, and source context, as confirmed by the detailed changes across TextFormatter, SearchResult, and MCPRouter files.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/mcp-text-format-v2

---

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.}