Repository navigation
Reduce search discovery round trips: batch entity detail, inline call shapes, related operations, package maintain pointer - #769
Merged
Conversation
Batch entity detail (up to 10 refs), inline top capability call shapes, surface related synthesized-provider operations, and add a package Maintain pointer so agents need fewer search round trips.
Document batch entity lookup and inlined call shapes, and add colocated coverage for batch success/partial/all-fail, top-3 inline shapes, related operations, and package Maintain pointers.
📝 WalkthroughWalkthroughThe MCP search tool now inlines compact capability call shapes, exposes related provider operations and package maintenance commands, supports batched entity detail lookups, and documents the resulting markdown and structured response formats. ChangesSearch enrichment and batching
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant Client
participant search
participant resolveEntityDetail
participant formatEntityDetailMarkdown
Client->>search: Submit entity refs
search->>resolveEntityDetail: Resolve refs concurrently
resolveEntityDetail-->>search: Return details or per-ref errors
search->>formatEntityDetailMarkdown: Format successful details
formatEntityDetailMarkdown-->>Client: Return markdown and structured results
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
kody-bot
marked this pull request as ready for review
July 16, 2026 21:30
Contributor
|
🔎 Preview deployed: https://kody-pr-769.kody-a99.workers.dev Worker: Mocks:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 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 `@docs/use/search.md`:
- Around line 50-54: Revise the search documentation around the entity lookup
guidance so capability entities are the only ones described as providing execute
call shapes and input/output definitions. Describe values, integrations,
packages, and secrets as detail lookups, while preserving the existing
"{id}:{type}" entity format and capability metadata examples.
In `@packages/worker/src/mcp/tools/search-format.ts`:
- Around line 930-935: The Markdown output at
packages/worker/src/mcp/tools/search-format.ts:930-935 must use
formatMarkdownInlineCode for the externally supplied operation name, HTTP
method/path, and entityRef instead of literal backticks; preserve the existing
description escaping. At packages/worker/src/mcp/tools/search.ts:2395-2402,
apply formatMarkdownInlineCode to entry.entityRef and escape the one-line error
message with the existing Markdown safety helper.
- Line 125: Preserve truncation metadata and prevent incomplete call
recommendations: in packages/worker/src/mcp/tools/search-format.ts:125-125 add
inputTypeDefinitionTruncated?: boolean to the slim capability contract, and at
760-762 propagate it with the definition; in
packages/worker/src/mcp/tools/search.ts:409-413 route truncated direct matches
to entity-detail guidance before execution; update
packages/worker/src/mcp/tools/search-format.node.test.ts:941-944 to assert the
flag, and packages/worker/src/mcp/tools/search.node.test.ts:1199-1205 to rank a
truncated capability first and verify detail-first guidance.
In `@packages/worker/src/mcp/tools/search.ts`:
- Around line 2406-2408: Bound the aggregate payload built by structuredResults
in the batch search flow around formatEntityDetailMarkdown, not just the
markdown text. Track the cumulative structured-result size and, once the budget
is exceeded, replace additional entries with per-reference errors directing
callers to individual lookup; apply the same behavior to the corresponding path
around the later structuredResults push.
🪄 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: 6cd56380-6e3b-4ada-b8a1-596b9d70b196
📒 Files selected for processing (6)
docs/use/search.mdpackages/worker/src/mcp/tools/search-format.node.test.tspackages/worker/src/mcp/tools/search-format.tspackages/worker/src/mcp/tools/search-handler.node.test.tspackages/worker/src/mcp/tools/search.node.test.tspackages/worker/src/mcp/tools/search.ts
Comment on lines
+930
to
+935
| const openApiSuffix = | ||
| related.method && related.path | ||
| ? ` — \`${related.method.toUpperCase()} ${related.path}\`` | ||
| : '' | ||
| lines.push( | ||
| `- \`${related.name}\`${openApiSuffix} — ${escapeMarkdownText(formatOneLineSentence(related.description))} Entity: \`${related.entityRef}\``, |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Render externally supplied values with the Markdown safety helpers.
Literal backticks allow provider paths or caller-supplied entity references to break or spoof the generated Markdown.
packages/worker/src/mcp/tools/search-format.ts#L930-L935: useformatMarkdownInlineCodefor operation names, HTTP method/path, and entity references.packages/worker/src/mcp/tools/search.ts#L2395-L2402: safely formatentry.entityRefand escape the one-line error message.
📍 Affects 2 files
packages/worker/src/mcp/tools/search-format.ts#L930-L935(this comment)packages/worker/src/mcp/tools/search.ts#L2395-L2402
🤖 Prompt for 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.
In `@packages/worker/src/mcp/tools/search-format.ts` around lines 930 - 935, The
Markdown output at packages/worker/src/mcp/tools/search-format.ts:930-935 must
use formatMarkdownInlineCode for the externally supplied operation name, HTTP
method/path, and entityRef instead of literal backticks; preserve the existing
description escaping. At packages/worker/src/mcp/tools/search.ts:2395-2402,
apply formatMarkdownInlineCode to entry.entityRef and escape the one-line error
message with the existing Markdown safety helper.
Propagate truncation flags and avoid recommending truncated call shapes, escape batch/related-ops markdown safely, bound batch structured payload size, and clarify capability-only call-shape docs.
This was referenced Jul 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Cuts the MCP
search“entity ladder” that showed up in real agent transcripts (query → 1–2entity:detail calls per new API surface, plus rediscovery of package-maintenance capabilities mid-task).entitydetail —entityacceptsstring | string[](1–10). Single-string behavior unchanged. Arrays resolve each ref independently; markdown joins with---; structured content is an array of detail or{ entityRef, error }. All-fail →isError: true. Batch structured payload is size-bounded (overflow entries become per-ref errors).inputTypeDefinition(~500 char cap). Rendered as one indented list line; present on slim structured matches (with truncation flag). Guidance prefers calling via the accessor only when the inlined shape is complete.openapi/mcp-server/remote-connectorcapability detail only, list up to 20 sibling ops from the same provider (create/poll pairs without a second entity lookup). Builtins intentionally skipped.## Maintainpointer — ~2 lines after Summary: git lane (package_get_git_remote→ … →package_publish_external_push) and tool-only alternative; structuredmaintain.{gitLane,publish}.Token discipline
Test plan
search-format.node.test.ts— inline shapes, truncation flag, related ops present/absent, Maintain sectionsearch.node.test.ts— top-3 inline attach, truncation → detail-first guidance, complete shape → direct call guidancesearch-handler.node.test.ts— batch success / partial failure / all-failure; single-entity shape unchangednpm run typecheckSystem recap — extends existing primitives (medium risk)
Mode: recap · Base:
main@71930296· Head:4b6eff1bClassification: extends — changes the MCP
searchtool contract and response shapes (batchentity, inlined call shapes, related ops, package Maintain) without adding primitives.Primitives touched
mcp-serversearchinput/output contract and formattingcapability-registrysaved-packagesSystem map
Query and entity detail enrichment stay inside the MCP search tool; registry specs supply call shapes and related synthesized-provider operations, while package detail only adds a maintenance pointer.
Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context (unchanged, included only when an edge crosses it).
Change flow
Before / after
entityinputstringonlystring | string[](1–10)Invariants
Per-user isolation unchanged: package/secret/value/integration entity paths remain
userId-scoped; batch mode only parallelizes the same resolvers.Summary by CodeRabbit
New Features
Documentation