Summary

• config-read's list-fields action was failing with MCP error -32602: Output validation error: ... path: ["success"], message: "Required" , an opaque error that pointed nowhere near the actual problem.
• Root cause: Mastra's Tool.execute() validates a family tool's return value against its own outputSchema internally, and on a mismatch it doesn't throw , it silently returns an {error: true, message, validationErrors} envelope in place of the tool's real result. server.ts's toCallToolResult forwarded that envelope unchanged as structuredContent with no isError flag, so the MCP SDK then ran its own outputSchema check against the error object and failed on the missing success field.
• The actual trigger: FieldOptionDataSchema.color was a required z.string(), but CustomFieldDefinition.options[].color is stored in a jsonb column with no runtime enforcement of the TS type , a legacy/hand-edited field option missing color failed Mastra's internal validation.

Changes

• server.ts: toCallToolResult now detects Mastra's internal validation-failure envelope and converts it into a proper isError CallToolResult with a legible message, instead of letting the SDK reject it with a confusing schema error.
• config-tool-shared.ts: FieldOptionDataSchema.color is now optional, matching the reality of stored field options.
• server.test.ts: pins the envelope→isError translation, confirms a real {success, ...} result still passes through unchanged, and confirms a real result carrying its own domain-level error field alongside success isn't misclassified.

Went through a thermo-nuclear code review pass (dependency direction, false-positive risk against every other family tool's output schema, file size, type cleanliness) before opening.

Test plan

• pnpm --filter @zero/server exec vitest run src/mastra/mcp/external/__tests__/server.test.ts src/mastra/tools/config/__tests__/configTool.test.ts , 119 passed
• pnpm --filter @zero/server run types , clean
• pnpm deps:check , no violations
• Grepped all ~70 family-tool output schemas to confirm the new envelope-detection guard can't misclassify a legitimate result

🤖 Generated with Claude Code

https://claude.ai/code/session_01BJ92k9jHt3CmmqX1dji4Zc

Greptile Summary

This PR improves external MCP error handling and aligns config field-option validation with persisted legacy data.

• Recognizes Mastra output-validation envelopes and translates them into legible MCP error results.
• Allows legacy field options without a stored color to pass the config tool’s output schema.
• Adds regression coverage for validation envelopes, normal structured output, and domain results containing an error property.

Confidence Score: 5/5

The PR appears safe to merge, with the validation-envelope translation and legacy color handling covered by focused regression tests.

No actionable failure remains: the guard distinguishes current legitimate family-tool results, the MCP error shape matches existing server conventions, and optional color reflects persisted legacy data without breaking repository consumers.

Important Files Changed

Flowchart