Make capability validation errors agent-readable

[kentcdodds]

Intent

Make Zod-backed capability input validation failures actionable for agents instead of exposing raw serialized issue arrays, while keeping invalid capability outputs reportable as server defects.

Summary

• Wrap Zod input validation failures in McpCallerError with the capability name, prettified field-level issues, and a search repair hint.
• Format Zod output validation failures as readable system errors so observability continues reporting capability implementation bugs to Sentry.
• Preserve parse_input and parse_output observability phases.
• Cover wrong-key input and invalid output behavior with Node unit tests.

Testing

• npx vitest run packages/worker/src/mcp/capabilities/define-capability.node.test.ts --project node-unit — 1 file / 1 test passed after reviewer fixes.
• PR CI — all checks green, including Node, Workers, E2E, MCP, Static, Validate, Bugbot, and CodeRabbit.
• Post-merge main validation and production deployment passed, including production healthcheck and execute smoke check.
• The authoritative local npm run validate passed before the reviewer adjustment. Two post-adjustment attempts were blocked by the Cloud VM's workerd DNS failure for artifacts-mock.test; the focused changed test and the equivalent split CI gates passed.

System changes

System recap — extends an existing primitive (medium risk)

Mode: recap · Base: main @ be5e29d5 · Head: 6d5f86a2

Classification: extends — changes the capability registry's runtime validation error contract without adding a primitive.

Primitives touched

Primitive	Group	Impact
capability-registry	assistant	extends — Zod input failures become caller-readable; invalid outputs remain reportable system errors

System map

Capability execution enters the registry, where this change formats schema failures before they cross back to the MCP caller while preserving server-error reporting for invalid outputs.

Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context (unchanged, included only when an edge crosses it).

flowchart LR
	mcpServer["mcp-server<br/>MCP endpoint (/mcp)"]:::untouched
	capabilityRegistry["capability-registry<br/>Capability registry"]:::extended
	mcpServer -->|"execute input/output validation"| capabilityRegistry
	capabilityRegistry -->|"caller-readable input errors; reportable output errors"| mcpServer
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

Before / after

Before	After
Raw JSON-stringified Zod input issue array	Capability name, prettified field issues, and exact-schema search hint
Raw JSON-stringified Zod output issue array	Readable implementation-error message that remains eligible for Sentry

Conductor report

Status: DONE — squash-merged and deployed.

Evidence: merged commit eee75d1fc75b09020b4b685b1335c8d13991eca9; both valid Bugbot findings fixed in 6d5f86a2; focused regression test passed; PR CI, post-merge main validation, and production deploy all passed. Production healthcheck, execute smoke, Sentry source-map upload, and capability-vector reindex succeeded. Discord summary message 1536452436217303100 was posted to channel 1491568683737157683.

Remains: nothing. The required createRun report returned Cursor API 409 both initially and after the mandated one-minute retry, so this full report is recorded here and in Discord per fallback policy.

  

Summary by CodeRabbit

• Bug Fixes
  • Improved error handling for invalid capability inputs and outputs.
  • Error messages now identify the affected capability and provide guidance for correcting validation failures.
  • Preserved detailed validation information and underlying error causes for clearer troubleshooting.
  • Prevented handlers from running when input validation fails.
  • Added clearer guidance when capability output validation fails, indicating an implementation issue.

[coderabbitai]

📝 Walkthrough

Walkthrough

MCP capabilities now wrap Zod input failures as McpCallerError and output failures as standard Error instances. Both errors preserve Zod causes and include validation guidance. Tests verify error details and handler behavior.

Changes

MCP capability validation

Layer / File(s)	Summary
Wrap capability validation errors packages/worker/src/mcp/capabilities/define-capability.ts	Input Zod errors use McpCallerError with repair guidance. Output Zod errors use standard Error with implementation guidance. Both preserve the original error as the cause, while non-Zod errors pass through unchanged.
Test validation failures packages/worker/src/mcp/capabilities/define-capability.node.test.ts	Tests verify error types, Zod causes, invalid field details, repair guidance, and handler invocation behavior.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• kentcdodds/kody#1305: Both changes wrap caller-related MCP capability failures as McpCallerError and preserve unrelated errors.
• kentcdodds/kody#1318: Both changes modify MCP capability error handling and use McpCallerError for caller-caused failures.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Title check	✅ Passed	The title clearly and concisely describes the main change: making capability validation errors readable for agents.
Description check	✅ Passed	The description includes complete Intent, Summary, Testing, and System changes sections with relevant implementation and verification details.

✨ 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/kody-capability-error-messages-8679

---

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

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

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

^{Reviewed by Cursor Bugbot for commit 738080e. Configure here.}

[github-actions]

🔎 Preview deployed: https://kody-pr-1376.kody-a99.workers.dev

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

Mocks:

• cloudflare: https://kody-pr-1376-mock-cloudflare.kody-a99.workers.dev/__mocks (kody-pr-1376-mock-cloudflare)