ynab-mcp-server CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

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
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) budgets. Built with @modelcontextprotocol/sdk.

Core Structure

• Entry Point: src/index.ts - Server setup and tool registration
• 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

Tools are registered in src/index.ts which passes the shared YNAB api instance to each handler.

Environment Variables

• YNAB_API_TOKEN (required) - Personal Access Token from YNAB API
• YNAB_BUDGET_ID (optional) - Default budget ID

Adding New Tools

1. Create src/tools/MyTool.ts:

import { z } from "zod";
import * as ynab from "ynab";

export const name = "my_tool";
export const description = "What this tool does";
export const inputSchema = {
  budgetId: z.string().optional().describe("Budget ID (optional, uses YNAB_BUDGET_ID env var if not provided)"),
  requiredParam: z.string().describe("Description of required param"),
};

interface MyToolInput {
  budgetId?: string;
  requiredParam: string;
}

export async function execute(input: MyToolInput, api: ynab.API) {
  try {
    const budgetId = input.budgetId || process.env.YNAB_BUDGET_ID;
    if (!budgetId) throw new Error("No budget ID provided");

    const result = await api.someMethod(budgetId, input.requiredParam);

    return {
      content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }]
    };
  } catch (error) {
    return {
      content: [{ type: "text" as const, text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }]
    };
  }
}