Skip to content

Clarify capability execute snippets - #447

Merged
kentcdodds merged 3 commits into
mainfrom
cursor/clarify-capability-execute-calls-606c
May 12, 2026
Merged

kentcdodds merged 3 commits into
mainfrom
cursor/clarify-capability-execute-calls-606c

Conversation

@kentcdodds

@kentcdodds kentcdodds commented May 12, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • Adds a full executable execute module snippet to capability detail responses from search.
  • Reinforces the codemode.<capability_id>(input) pattern in search/execute tool descriptions, MCP server instructions, and usage docs.
  • Updates MCP search formatting tests to assert the new snippet appears in markdown and structured output.

Testing

  • npm test -- --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/server-instructions.node.test.ts
  • npm run format:check
  • npm test -- --run packages/worker/src/mcp/tools/search-format.node.test.ts packages/worker/src/mcp/server-instructions.node.test.ts
  • npm run validate
Open in Web Open in Cursor 

Summary by CodeRabbit

  • New Features

    • Capability search results now include an executeExample: a ready-to-run TypeScript snippet showing how to call the capability at runtime.
  • Documentation

    • Clarified runtime invocation patterns: use dot notation for identifier IDs (await codemode.capability_id(input)) and bracket notation for non-identifier IDs (await codemode"capability-id").
    • Expanded search/execute docs with full execute-module snippets and input guidance.
  • Tests

    • Updated tests to assert presence and formats of executeExample in capability details.

Review Change Stack

Co-authored-by: Kent C. Dodds <me+github@kentcdodds.com>
@coderabbitai

coderabbitai Bot commented May 12, 2026 •

Copy link
Copy Markdown

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 03b3ad8f-cd70-421f-8761-d80a4ce4cb4d

📥 Commits

Reviewing files that changed from the base of the PR and between a7547f3 and fbcaf0e.

📒 Files selected for processing (1)
  • packages/worker/src/mcp/tools/search-format.ts
🚧 Files skipped from review as they are similar to previous changes (1)
  • packages/worker/src/mcp/tools/search-format.ts

📝 Walkthrough

Walkthrough

This PR adds an executeExample field to capability search results, generates ready-to-run TypeScript execute-module snippets with safe codemode accessors, updates search markdown and tests to include an "Execute from execute" section, and clarifies runtime invocation via codemode (dot or bracket notation).

Changes

Capability execution examples in search output

Layer / File(s) Summary
Capability execution type and generation helpers
packages/worker/src/mcp/tools/search-format.ts
Type SearchEntityDetailStructured adds executeExample: string. New helpers generate safe codemode accessor expressions and full TypeScript execute-module examples with import, async function wrapper, and return call.
Search result markdown and structured output
packages/worker/src/mcp/tools/search-format.ts
Capability detail markdown adds an "Execute from execute" section with a TS code block and input argument guidance. Structured response populates executeExample.
Test assertions for capability execution examples
packages/worker/src/mcp/tools/search-format.node.test.ts
Tests verify executeExample and usage fields in structured output and confirm markdown includes the "Execute from execute" section with codemode import and invocation syntax (dot and bracket forms).
MCP tool descriptions and server instructions
packages/worker/src/mcp/tools/execute.ts, packages/worker/src/mcp/tools/search.ts, packages/worker/src/mcp/server-instructions.ts
Execute and search tool descriptions clarify that capability discovery returns an executable snippet plus TypeScript call-shape definitions. Server instruction template explicitly lists allowed entity types and refines ESM module guidance.
User-facing documentation
docs/use/execute.md, docs/use/search.md
Docs clarify runtime invocation via the imported codemode object (await codemode.<capability_id>(input) or await codemode["capability-id"](input) for non-identifiers), note capability details include full execute-module snippets, and show example request/execute flows.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

  • kentcdodds/kody#279: Both PRs modify capability detail formatting and the search tooling/docs (including changes in packages/worker/src/mcp/tools/search-format.ts and search.ts) and are related at the code level.
  • kentcdodds/kody#343: Both PRs modify the execute documentation and the execute tool's descriptive text (docs/use/execute.md and packages/worker/src/mcp/tools/execute.ts).
  • kentcdodds/kody#381: Both PRs modify the execute tool documentation and user-facing description in packages/worker/src/mcp/tools/execute.ts and docs/use/execute.md.

Poem

🐰 A rabbit hops through code with cheer,
Adding codemode examples so clear!
Snippets neat, tests in sight,
Call with dot or bracket right—
Search, import, run with glee! 🥕

🚥 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
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'Clarify capability execute snippets' directly aligns with the PR's core objective of adding and clarifying executable capability snippets in the search response and documentation.
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.

✏️ 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/clarify-capability-execute-calls-606c

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

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

@kody-bot
kody-bot marked this pull request as ready for review May 12, 2026 05:43
@github-actions

github-actions Bot commented May 12, 2026 •

Copy link
Copy Markdown
Contributor

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

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

Mocks:

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
packages/worker/src/mcp/tools/search-format.node.test.ts (1)

165-234: ⚡ Quick win

Add one capability-detail test for non-identifier capability IDs.

The new accessor builder has a branch for bracket notation, but current additions only assert dot-notation IDs. Please add one test (e.g. foo-bar) asserting both usage and executeExample use codemode["foo-bar"](...).

Also applies to: 251-262

🤖 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.node.test.ts` around lines 165 -
234, Add a new test that calls formatEntityDetailMarkdown with a capability
whose id contains a non-identifier character (e.g., 'foo-bar') and assert that
the returned structured.usage and structured.executeExample use bracket notation
(codemode["foo-bar"]) rather than dot notation; mirror the existing capability
test (the test around formatEntityDetailMarkdown) but set id to 'foo-bar' and
assert usage === 'execute with codemode["foo-bar"](args)' (or stringContaining)
and that executeExample contains 'return await codemode["foo-bar"](input)'; also
duplicate the same assertion pattern for the second similar test block
referenced (lines ~251-262) so both code paths (dot vs bracket) are covered.
🤖 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/execute.ts`:
- Line 50: The guidance text only documents dot notation for calling discovered
capabilities; update the wording to explain both dot notation for valid
identifier names and bracket notation for non-identifier names (e.g.,
codemode.capability_id(input) and codemode["capability-id"](input)) to match how
buildCodemodeCapabilityAccessor generates accessors. Edit the guidance line in
packages/worker/src/mcp/tools/execute.ts (and mirror the change in
packages/worker/src/mcp/server-instructions.ts, docs/use/execute.md, and
docs/use/search.md) so it mentions both patterns and includes the two short
examples; reference buildCodemodeCapabilityAccessor and the codemode accessor
examples in the updated text.

---

Nitpick comments:
In `@packages/worker/src/mcp/tools/search-format.node.test.ts`:
- Around line 165-234: Add a new test that calls formatEntityDetailMarkdown with
a capability whose id contains a non-identifier character (e.g., 'foo-bar') and
assert that the returned structured.usage and structured.executeExample use
bracket notation (codemode["foo-bar"]) rather than dot notation; mirror the
existing capability test (the test around formatEntityDetailMarkdown) but set id
to 'foo-bar' and assert usage === 'execute with codemode["foo-bar"](args)' (or
stringContaining) and that executeExample contains 'return await
codemode["foo-bar"](input)'; also duplicate the same assertion pattern for the
second similar test block referenced (lines ~251-262) so both code paths (dot vs
bracket) are covered.
🪄 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: f677a188-25cd-47d5-98e7-9783a1ad3cd2

📥 Commits

Reviewing files that changed from the base of the PR and between 23a9864 and e8c014e.

📒 Files selected for processing (7)
  • docs/use/execute.md
  • docs/use/search.md
  • packages/worker/src/mcp/server-instructions.ts
  • packages/worker/src/mcp/tools/execute.ts
  • packages/worker/src/mcp/tools/search-format.node.test.ts
  • packages/worker/src/mcp/tools/search-format.ts
  • packages/worker/src/mcp/tools/search.ts

Comment thread packages/worker/src/mcp/tools/execute.ts Outdated
Co-authored-by: Kent C. Dodds <me+github@kentcdodds.com>

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Fix All in Cursor

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

Reviewed by Cursor Bugbot for commit a7547f3. Configure here.

Comment thread packages/worker/src/mcp/tools/search-format.ts
Co-authored-by: Kent C. Dodds <me+github@kentcdodds.com>
@kentcdodds
kentcdodds merged commit dbd2ce6 into main May 12, 2026
5 checks passed
@kentcdodds
kentcdodds deleted the cursor/clarify-capability-execute-calls-606c branch May 12, 2026 06:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants