ynab-mcp-server: Instructions file for Codex

AGENTS.md

This is the shared instructions file for coding agents working in this repository (CLAUDE.md points here).

Development Commands

npm install          # Install dependencies
npm run build        # Compile TypeScript to ./dist
npm start            # Start the server
npm run watch        # Development build with file watching
npm run debug        # Debug with MCP inspector
npm test             # Run tests (watch mode)
npm run test:run     # Run tests once
npm run typecheck    # Typecheck both node and Worker targets
npm run dev:worker   # Run the Cloudflare Worker locally
npm run deploy       # Deploy the Worker
npm run test:watch   # Run tests with file watching
npm run test:coverage # Run tests with coverage report

Git Best Practices

ALWAYS use conventional commits format (Refer to https://www.conventionalcommits.org/en/v1.0.0/) when creating git commit messages.

Architecture Overview

This is a Model Context Protocol (MCP) server that provides AI tools for interacting with YNAB (You Need A Budget) plans. Built with @modelcontextprotocol/sdk.

Core Structure

• Tool registry: src/registry.ts - the single list of tools, shared by both entry points
• stdio entry: src/index.ts - local server for Claude Code / Claude Desktop
• Worker entry: src/worker/ - Cloudflare Worker serving the same tools over HTTP behind GitHub OAuth (see DEPLOY.md)
• Auto-budget service: src/worker/autobudget/ - Worker-only scheduled job and its MCP tools, with D1 schema in migrations/ (see DEPLOY.md)
• Tools: src/tools/*.ts - Each tool is a separate module exporting name, description, inputSchema, and execute function
• Tests: src/tests/*.test.ts - Vitest tests for each tool

Tool Module Pattern

Each tool in src/tools/ exports:

• name: Tool identifier (snake_case)
• description: Tool description
• inputSchema: Zod schema object for input validation
• execute(input, api): Async handler receiving input and YNAB API client