Make MCP search query results concise

[kentcdodds]

Summary

• Render broad search({ query }) responses as a compact ranked list with type, title/name, one-line summary, and entity refs for entity-backed hits.
• Keep verbose warnings, memories, and recommended guidance out of query markdown while preserving them in structured content.
• Keep detailed capability/package/connector/etc. output behind search({ entity }), remove unused README enrichment for ranked query hits, and update search docs accordingly.

Test plan

• npx vitest run packages/worker/src/mcp/tools/search-format.node.test.ts packages/worker/src/mcp/tools/search-handler.node.test.ts packages/worker/src/mcp/tools/search.node.test.ts
• npm run format:check -- packages/worker/src/mcp/tools/search-format.ts packages/worker/src/mcp/tools/search.ts packages/worker/src/mcp/tools/search-format.node.test.ts packages/worker/src/mcp/tools/search-handler.node.test.ts docs/use/search.md
• npm run typecheck
• git diff --check
• PR CI: Lint, Typecheck, Unit Tests, E2E, MCP E2E, Deploy Preview Resources

  

Summary by CodeRabbit

• Improvements

  • Search results now render as compact one-line summaries; low-ranked matches are trimmed first when sizing responses.
  • Ranked package/connector hits are summary-only; exact entity lookups return full package/connector details.
  • Warnings and notices are condensed to a single concise line in the plain-text output; detailed warnings remain available in structured output.

• Documentation

  • Updated search docs to describe compact ranked output, memory metadata placement, and response-sizing semantics.

• Tests

  • Updated tests to assert compact markdown output and preserved structured details.

[coderabbitai]

📝 Walkthrough

Walkthrough

Search result output was changed to produce compact, single-line ranked markdown entries while moving detailed auxiliary information (warnings, memories, README/connector details) into structuredContent. Package README enrichment for ranked matches was removed and maxResponseSize trimming now targets low-ranked matches.

Changes

Search Result Formatting Refactor

Layer / File(s)	Summary
Docs / Specification docs/use/search.md	Query docs updated to specify compact ranked markdown (type, title, one-line summary, optional entity ref), memoryContext flows into structured content, and maxResponseSize trims low-ranked matches; exact entity lookups documented with richer package/connector details.
Data/Shape (handler-level) packages/worker/src/mcp/tools/search.ts	Removed package README enrichment from ranked matches; introduced structuredWarnings (full array) and conciseWarnings (single-count message); payload for trimming uses conciseWarnings while full warnings are exposed in structuredContent.result.
Core Formatting Implementation packages/worker/src/mcp/tools/search-format.ts	Rewrote formatSearchMarkdown to emit compact single-line match items via formatMatchListItem; added formatOneLineSummary/formatOneLineSentence; warnings rendered as a single count line and prior auxiliary sections (detailed blocks, guidance, memories, README excerpts) removed from plaintext output; new warningCount?: number input.
Handler Integration / Wiring packages/worker/src/mcp/tools/search.ts	Formatting now called with warningCount: structuredWarnings.length; list-mode returns original result.matches (no README enrichment) and assembles payload using concise warnings for trimming/serialization while populating structuredContent.result with full structured details.
Tests / Validation packages/worker/src/mcp/tools/search-format.node.test.ts, packages/worker/src/mcp/tools/search-handler.node.test.ts	Updated and added tests to assert compact plaintext markdown (single-line entries, excluded README/token/secret/guidance/memories), ensure package detail README text matches expected snippet, and verify structuredContent retains warnings/guidance/memory IDs; retriever test ensures removal of raw backtick-containing URL.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor Client
  participant Handler as SearchHandler
  participant Formatter as formatSearchMarkdown
  participant Structured as structuredContent

  Client->>Handler: send query (maybe entity, maxResponseSize)
  Handler->>Handler: collect matches, warnings, memories
  Handler->>Structured: assemble structuredWarnings, memories, match details
  Handler->>Formatter: call with matches + warningCount
  Formatter->>Handler: return compact markdown (single-line matches)
  Handler->>Client: respond with { content: compact markdown, structuredContent: Structured }

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• kentcdodds/kody#242: Modifies the same search-format/search handler area; related to changing how package/connector hits and README enrichment are rendered.
• kentcdodds/kody#252: Also touches guidance/nextStep and package/connector enrichment in formatSearchMarkdown and search.ts; concerns overlap with compact vs. rich output choices.
• kentcdodds/kody#272: Refactors search handler logic and capability candidate generation; related to changes in how matches and structured results are produced.

Poem

🐇 I tidy the hits to a single fine line,

compact and quick, like a hop in a vine.
Warnings tucked neat in a structured den,
README and secrets saved for when—
The rabbit keeps order, and speeds up your time.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Make MCP search query results concise' accurately summarizes the main objective of the PR, which is to render search responses as compact ranked lists with streamlined content.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
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 cursor/search-results-conciseness-0a64

---

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

[github-actions]

🔎 Preview deployed: https://kody-pr-362.kentcdodds.workers.dev

Worker: kody-pr-362
D1: kody-pr-362-db
KV: kody-pr-362-oauth-kv

Mocks:

• ai: https://kody-pr-362-mock-ai.kentcdodds.workers.dev/__mocks (kody-pr-362-mock-ai)
• cloudflare: https://kody-pr-362-mock-cloudflare.kentcdodds.workers.dev/__mocks (kody-pr-362-mock-cloudflare)

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/worker/src/mcp/tools/search-format.ts`:
- Line 497: The current follow-up text incorrectly implies the `entity`
follow-up works for all hits; change the message string to clarify that "For
full detail on entity-backed hits, call `search` with `entity:
\"{id}:{type}\"`." and/or only append that follow-up when the result actually
has an entity ref. Locate the message construction in search-format.ts (the
string currently "'For full detail on one hit, call `search` with `entity:
\"{id}:{type}\"`.'") and update it to mention "entity-backed hits" or add a
guard that checks for an entity ref (avoid offering the follow-up for
`retriever_result` rows which lack an entity ref and are not supported by
parseEntityRef).

In `@packages/worker/src/mcp/tools/search.ts`:
- Around line 1768-1774: The compact markdown currently collapses multiple
warnings into a single message because conciseWarnings is built as a single
string when warnings.length > 0; update formatSearchMarkdown logic so
conciseWarnings reflects the actual warning count instead of always showing 1:
use warnings.length (or structuredContent.result.warnings.length) to create a
message like `${warnings.length} auxiliary search warning(s) available in
structuredContent.result.warnings.` and ensure the same fix is applied where
conciseWarnings is constructed again (the other occurrence referencing
warnings/structuredWarnings). Locate identifiers structuredWarnings,
conciseWarnings, formatSearchMarkdown and the use of
warnings.length/structuredContent.result.warnings and replace the single-entry
fallback with a count-aware message.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d7e036c-aaa0-4c8f-8843-e4771148b6b1

📥 Commits

Reviewing files that changed from the base of the PR and between ea10c63 and 198c924.

📒 Files selected for processing (5)

• docs/use/search.md
• packages/worker/src/mcp/tools/search-format.node.test.ts
• packages/worker/src/mcp/tools/search-format.ts
• packages/worker/src/mcp/tools/search-handler.node.test.ts
• packages/worker/src/mcp/tools/search.ts

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 16ad5b6. Configure here.}