mcp-server-for-ynab: Instructions file for Codex

AGENTS.md

This file tells AI agents and contributors how this repository works and how to extend it correctly.

What this document is for

Read this page if you need:

• implementation rules
• extension paths for raw or enriched tools
• architecture invariants that docs must match
• guidance for updating diagrams and repo docs

Adjacent docs:

• README.md
• Architecture
• Repo Structure
• Tool Surface
• Testing

Mission

mcp-server-for-ynab is an MCP server for AI agents to interact with YNAB budgets. It exposes the YNAB API through raw tools and adds enriched AI-friendly helpers on top. The goal is safe, explicit budget management rather than autonomous financial decision-making.

Start Here If You Are Modifying the Repo

1. Read Architecture.
2. Read Repo Structure.
3. Read Tool Surface if you are touching tools.
4. Read Testing before changing behavior.
5. Update docs and diagrams when the structure or request flow changes.

Architecture Map

src/mcp_server_for_ynab/
├── auth/         auth abstraction + PAT implementation
├── cli/          stdio/http entrypoints and smoke helper
├── config/       env loading, runtime validation, default plan resolution
├── enriched/     AI-friendly read workflows
├── http_client/  async httpx wrapper: retries, error normalization, redaction
├── models/       typed YNAB shapes, shared error model, milliunit helpers
├── server/       MCPServer app, context, registry, error boundary, tool registration
└── ynab_client/  async wrappers for YNAB resource families

Trace a Tool from MCP Name to YNAB Request

sequenceDiagram
    participant Client as MCP client
    participant Server as server/app.py
    participant Handler as server/tools/*
    participant YClient as ynab_client/*
    participant Http as http_client/client.py
    participant API as YNAB API

    Client->>Server: invoke tool name
    Server->>Handler: registered MCPServer handler
    Handler->>YClient: call resource or enriched workflow
    YClient->>Http: request(...)
    Http->>API: HTTP call
    API-->>Http: JSON response
    Http-->>YClient: dict or structured exception
    YClient-->>Handler: typed model
    Handler-->>Server: dict payload
    Server-->>Client: MCP tool result