mcp-server-for-ynab: Skill for Claude Code

Live API Verification

Use this skill whenever a change touches how a YNAB response is parsed, or how an agent connects to the server. The test suite cannot catch drift between a response model and the real API, because every payload in it was written by hand: the model and the fixture are the same guess.

Use When

• Adding or editing a model under src/mcp_server_for_ynab/models/ynab/
• Adding a raw tool or a ynab_client wrapper for a new route
• Upgrading the mcp SDK, or changing transport/CLI startup
• Reviewing a claim that a tool "works" when only unit tests were run
• Investigating a tool that fails in a client but passes in CI

The Failures This Prevents

The money movement models were written by analogy with transactions. They required date on a movement and name/amount on a group. The real API sends none of those — it sends month, moved_at, and category endpoints. All four money movement tools failed at validation on every call, while the suite passed, because no test used a real payload and no test touched the family at all.

Two properties made this invisible:

1. Hand-written fixtures agree with the model by construction.
2. The tool boundary returns failures as a structured error payload with isError: False, so a caller that only checks the MCP result looks fine.

The write tools failed four more ways, each invisible to the same suite:

• category-groups in the path where the API wants category_groups, so YNAB answered "Invalid URI" for create and update alike
• categories_create could not send category_group_id, which the API requires, so no category could ever be created
• the bulk update model expected data.bulk, a shape this route does not return, so the write succeeded and the response failed to parse
• the group create and update routes return a group without its categories, which the response model required

None of these are visible from the request side. Three of the four failed after YNAB had already accepted the write.