@dizzlkheinz/ynab-mcpb 0.12.1

package/dist/tools/utilityTools.d.ts

@@ -0,0 +1,10 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import * as ynab from 'ynab';
+import { z } from 'zod/v4';
+export declare const ConvertAmountSchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    to_milliunits: z.ZodBoolean;
+}, z.core.$strict>;
+export type ConvertAmountParams = z.infer<typeof ConvertAmountSchema>;
+export declare function handleGetUser(ynabAPI: ynab.API): Promise<CallToolResult>;
+export declare function handleConvertAmount(params: ConvertAmountParams): Promise<CallToolResult>;

package/dist/tools/utilityTools.js

@@ -0,0 +1,56 @@
+import { z } from 'zod/v4';
+import { withToolErrorHandling } from '../types/index.js';
+import { responseFormatter } from '../server/responseFormatter.js';
+export const ConvertAmountSchema = z
+    .object({
+    amount: z.number().finite(),
+    to_milliunits: z.boolean(),
+})
+    .strict();
+export async function handleGetUser(ynabAPI) {
+    return await withToolErrorHandling(async () => {
+        const response = await ynabAPI.user.getUser();
+        const userInfo = response.data.user;
+        const user = {
+            id: userInfo.id,
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: responseFormatter.format({ user }),
+                },
+            ],
+        };
+    }, 'ynab:get_user', 'getting user information');
+}
+export async function handleConvertAmount(params) {
+    return await withToolErrorHandling(async () => {
+        const { amount, to_milliunits } = params;
+        let result;
+        let description;
+        if (to_milliunits) {
+            result = Math.round(amount * 1000);
+            description = `$${amount.toFixed(2)} = ${result} milliunits`;
+        }
+        else {
+            result = amount / 1000;
+            description = `${amount} milliunits = $${result.toFixed(2)}`;
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: responseFormatter.format({
+                        conversion: {
+                            original_amount: amount,
+                            converted_amount: result,
+                            to_milliunits,
+                            description,
+                        },
+                    }),
+                },
+            ],
+        };
+    }, 'ynab:convert_amount', 'converting amount');
+}

package/dist/types/index.d.ts

@@ -0,0 +1,20 @@
+export interface AuthenticationConfig {
+    accessToken: string;
+    validateToken(): Promise<boolean>;
+}
+export interface ServerConfig {
+    accessToken: string;
+    defaultBudgetId?: string;
+}
+export declare class AuthenticationError extends Error {
+    constructor(message: string);
+}
+export declare class ConfigurationError extends Error {
+    constructor(message: string);
+}
+export { ErrorHandler, YNABAPIError, ValidationError, YNABErrorCode, SecurityErrorCode, type ErrorResponse, handleToolError, withToolErrorHandling, } from '../server/errorHandler.js';
+export { RateLimiter, RateLimitError, globalRateLimiter, type RateLimitConfig, type RateLimitInfo, } from '../server/rateLimiter.js';
+export { RequestLogger, globalRequestLogger, type LogEntry, type LoggerConfig, } from '../server/requestLogger.js';
+export { SecurityMiddleware, withSecurityWrapper, type SecurityContext, } from '../server/securityMiddleware.js';
+export type { MCPToolAnnotations } from './toolAnnotations.js';
+export type { ToolDefinition } from '../server/toolRegistry.js';

package/dist/types/index.js

@@ -0,0 +1,16 @@
+export class AuthenticationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthenticationError';
+    }
+}
+export class ConfigurationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigurationError';
+    }
+}
+export { ErrorHandler, YNABAPIError, ValidationError, handleToolError, withToolErrorHandling, } from '../server/errorHandler.js';
+export { RateLimiter, RateLimitError, globalRateLimiter, } from '../server/rateLimiter.js';
+export { RequestLogger, globalRequestLogger, } from '../server/requestLogger.js';
+export { SecurityMiddleware, withSecurityWrapper, } from '../server/securityMiddleware.js';

package/dist/types/toolAnnotations.d.ts

@@ -0,0 +1,7 @@
+export interface MCPToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}

package/dist/types/toolAnnotations.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/amountUtils.d.ts

@@ -0,0 +1,3 @@
+export declare function milliunitsToAmount(milliunits: number): number;
+export declare function amountToMilliunits(amount: number): number;
+export declare function formatAmount(milliunits: number, currencySymbol?: string): string;

package/dist/utils/amountUtils.js

@@ -0,0 +1,10 @@
+export function milliunitsToAmount(milliunits) {
+    return Math.round(milliunits) / 1000;
+}
+export function amountToMilliunits(amount) {
+    return Math.round(amount * 1000);
+}
+export function formatAmount(milliunits, currencySymbol = '$') {
+    const amount = milliunitsToAmount(milliunits);
+    return `${currencySymbol}${amount.toFixed(2)}`;
+}

package/dist/utils/dateUtils.d.ts

@@ -0,0 +1,9 @@
+export declare function formatYNABMonth(date: Date): string;
+export declare function formatISODate(date: Date): string;
+export declare function getCurrentMonth(): string;
+export declare function getToday(): string;
+export declare function getHistoricalMonths(monthCount: number, startDate?: Date): string[];
+export declare function subtractMonths(date: Date, months: number): Date;
+export declare function isValidISODate(dateString: string): boolean;
+export declare function isValidYNABMonth(monthString: string): boolean;
+export declare function yearMonthToYNABMonth(yearMonth: string): string;

package/dist/utils/dateUtils.js

@@ -0,0 +1,43 @@
+import { format, subMonths, isValid, parse } from 'date-fns';
+export function formatYNABMonth(date) {
+    return format(date, "yyyy-MM-'01'");
+}
+export function formatISODate(date) {
+    return format(date, 'yyyy-MM-dd');
+}
+export function getCurrentMonth() {
+    return formatYNABMonth(new Date());
+}
+export function getToday() {
+    return formatISODate(new Date());
+}
+export function getHistoricalMonths(monthCount, startDate) {
+    const baseDate = startDate || new Date();
+    return Array.from({ length: monthCount }, (_, i) => {
+        const date = subMonths(baseDate, i);
+        return formatYNABMonth(date);
+    });
+}
+export function subtractMonths(date, months) {
+    return subMonths(date, months);
+}
+export function isValidISODate(dateString) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(dateString)) {
+        return false;
+    }
+    const parsed = parse(dateString, 'yyyy-MM-dd', new Date());
+    return isValid(parsed);
+}
+export function isValidYNABMonth(monthString) {
+    if (!/^\d{4}-\d{2}-01$/.test(monthString)) {
+        return false;
+    }
+    const parsed = parse(monthString, "yyyy-MM-'01'", new Date());
+    return isValid(parsed);
+}
+export function yearMonthToYNABMonth(yearMonth) {
+    if (!/^\d{4}-\d{2}$/.test(yearMonth)) {
+        throw new Error('Invalid year-month format. Expected YYYY-MM');
+    }
+    return `${yearMonth}-01`;
+}

package/dist/utils/money.d.ts

@@ -0,0 +1,21 @@
+import * as ynab from 'ynab';
+export type Milli = number;
+export type MoneyDirection = 'credit' | 'debit' | 'balanced';
+export interface MoneyValue {
+    value_milliunits: Milli;
+    value: number;
+    value_display: string;
+    currency: string;
+    direction: MoneyDirection;
+}
+export declare const getDecimalDigits: (currencyFormat: ynab.CurrencyFormat | null | undefined) => number;
+export declare const getCurrencyCode: (currencyFormat: ynab.CurrencyFormat | null | undefined) => string;
+export declare const toMilli: (x: number | string) => Milli;
+export declare const fromMilli: (m: Milli, decimalDigits?: number) => number;
+export declare const assertMilli: (m: number, msg?: string) => void;
+export declare const addMilli: (a: Milli, b: Milli) => Milli;
+export declare const inWindow: (iso: string, start?: string | undefined, end?: string | undefined) => boolean;
+export declare const moneyDirection: (value: Milli) => MoneyDirection;
+export declare const formatMoney: (value: Milli, currency?: string, decimalDigits?: number) => string;
+export declare const toMoneyValue: (value: Milli, currency?: string, decimalDigits?: number) => MoneyValue;
+export declare const toMoneyValueFromDecimal: (amount: number, currency?: string, decimalDigits?: number) => MoneyValue;

package/dist/utils/money.js

@@ -0,0 +1,51 @@
+import * as ynab from 'ynab';
+const DEFAULT_CURRENCY = 'USD';
+const DEFAULT_DECIMAL_DIGITS = 2;
+export const getDecimalDigits = (currencyFormat) => {
+    return currencyFormat?.decimal_digits ?? DEFAULT_DECIMAL_DIGITS;
+};
+export const getCurrencyCode = (currencyFormat) => {
+    return currencyFormat?.iso_code ?? DEFAULT_CURRENCY;
+};
+export const toMilli = (x) => {
+    const n = Number(x);
+    const m = Math.round(n * 1000);
+    if (!Number.isFinite(n) || !Number.isSafeInteger(m)) {
+        throw new Error(`Invalid/unsafe amount: ${x}`);
+    }
+    return m;
+};
+export const fromMilli = (m, decimalDigits = DEFAULT_DECIMAL_DIGITS) => {
+    return ynab.utils.convertMilliUnitsToCurrencyAmount(m, decimalDigits);
+};
+export const assertMilli = (m, msg = 'Expected safe integer milliunits') => {
+    if (!Number.isSafeInteger(m))
+        throw new Error(msg);
+};
+export const addMilli = (a, b) => {
+    const s = a + b;
+    if (!Number.isSafeInteger(s))
+        throw new Error('Milliunit sum overflow');
+    return s;
+};
+export const inWindow = (iso, start = undefined, end = undefined) => (!start || iso >= start) && (!end || iso <= end);
+export const moneyDirection = (value) => {
+    if (value === 0)
+        return 'balanced';
+    return value > 0 ? 'credit' : 'debit';
+};
+const makeFormatter = (currency, decimalDigits = DEFAULT_DECIMAL_DIGITS) => new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency,
+    minimumFractionDigits: decimalDigits,
+    maximumFractionDigits: decimalDigits,
+});
+export const formatMoney = (value, currency = DEFAULT_CURRENCY, decimalDigits = DEFAULT_DECIMAL_DIGITS) => makeFormatter(currency, decimalDigits).format(fromMilli(value, decimalDigits));
+export const toMoneyValue = (value, currency = DEFAULT_CURRENCY, decimalDigits = DEFAULT_DECIMAL_DIGITS) => ({
+    value_milliunits: value,
+    value: fromMilli(value, decimalDigits),
+    value_display: formatMoney(value, currency, decimalDigits),
+    currency,
+    direction: moneyDirection(value),
+});
+export const toMoneyValueFromDecimal = (amount, currency = DEFAULT_CURRENCY, decimalDigits = DEFAULT_DECIMAL_DIGITS) => toMoneyValue(toMilli(amount), currency, decimalDigits);

package/docs/README.md

@@ -0,0 +1,72 @@
+# YNAB MCP Server Documentation
+
+Complete documentation for the YNAB Model Context Protocol Server.
+
+## 📚 Documentation Overview
+
+### Getting Started
+New to the YNAB MCP Server? Start here:
+
+- **[Quick Start](getting-started/QUICKSTART.md)** - Fast path to testing with Claude Desktop
+- **[Installation](getting-started/INSTALLATION.md)** - Detailed installation instructions
+- **[Configuration](getting-started/CONFIGURATION.md)** - Environment variables and settings
+
+### Guides
+Learn how to develop with and extend the server:
+
+- **[Architecture](guides/ARCHITECTURE.md)** - Server architecture and core components
+- **[Testing](guides/TESTING.md)** - Automated and manual testing strategies
+- **[Deployment](guides/DEPLOYMENT.md)** - Production deployment instructions
+
+### Reference
+Complete API and technical reference:
+
+- **[API Reference](reference/API.md)** - Complete tool documentation with examples
+- **[Tools Quick Reference](reference/TOOLS.md)** - Quick tool catalog and parameter guide
+- **[Examples](reference/EXAMPLES.md)** - Practical usage examples and workflows
+- **[Troubleshooting](reference/TROUBLESHOOTING.md)** - Common issues, solutions, and debugging
+
+## 🎯 Quick Navigation by Task
+
+### I want to...
+
+**Get Started**
+- Install and configure → [Installation](getting-started/INSTALLATION.md)
+- Test quickly → [Quick Start](getting-started/QUICKSTART.md)
+- Understand the architecture → [Architecture](guides/ARCHITECTURE.md)
+
+**Develop**
+- Create a new tool → [Architecture Guide](guides/ARCHITECTURE.md#developing-tools-with-v08x)
+- Understand the architecture → [Architecture](guides/ARCHITECTURE.md)
+
+**Troubleshoot**
+- Common issues → [Troubleshooting](reference/TROUBLESHOOTING.md)
+
+**Test**
+- Run automated tests → [Testing Guide](guides/TESTING.md)
+
+**Deploy**
+- Deploy to production → [Deployment Guide](guides/DEPLOYMENT.md)
+- Configure for Claude Desktop → [Quick Start](getting-started/QUICKSTART.md#claude-desktop-integration)
+
+## 🔗 External Resources
+
+- **[YNAB API Documentation](https://api.youneedabudget.com/)** - Official YNAB API docs
+- **[Model Context Protocol](https://modelcontextprotocol.io/)** - MCP specification
+- **[Project Repository](https://github.com/dizzlkheinz/mcp-for-ynab)** - GitHub repository
+- **[Release Notes](https://github.com/dizzlkheinz/mcp-for-ynab/releases)** - Version history and changelog
+
+## 💡 Need Help?
+
+- **Documentation Issue?** Check the [Troubleshooting Guide](reference/TROUBLESHOOTING.md)
+- **Bug Report?** [Open an issue](https://github.com/dizzlkheinz/mcp-for-ynab/issues/new?template=bug_report.md)
+- **Feature Request?** [Request a feature](https://github.com/dizzlkheinz/mcp-for-ynab/issues/new?template=feature_request.md)
+- **Question?** Check existing [GitHub Discussions](https://github.com/dizzlkheinz/mcp-for-ynab/discussions)
+
+## 📄 License
+
+This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the [LICENSE](../LICENSE) file for details.
+
+---
+
+**Quick Links**: [Main README](../README.md) | [API Reference](reference/API.md) | [Quick Start](getting-started/QUICKSTART.md) | [Architecture](guides/ARCHITECTURE.md)

package/docs/assets/examples/reconciliation-with-recommendations.json

@@ -0,0 +1,68 @@
+{
+  "version": "2.0",
+  "schema_url": "https://raw.githubusercontent.com/dizzlkheinz/ynab-mcp-mcpb/master/docs/schemas/reconciliation-v2.json",
+  "timestamp": "2024-01-31T10:30:00Z",
+  "data": {
+    "balance_info": {
+      "current_cleared": {
+        "value": 100.0,
+        "value_display": "$100.00",
+        "currency": "USD",
+        "direction": "debit"
+      },
+      "target_statement": {
+        "value": 122.22,
+        "value_display": "$122.22",
+        "currency": "USD",
+        "direction": "debit"
+      },
+      "discrepancy": {
+        "value": 22.22,
+        "value_display": "$22.22",
+        "currency": "USD",
+        "direction": "debit"
+      },
+      "on_track": false
+    },
+    "insights": [
+      {
+        "id": "insight-1",
+        "type": "near_match",
+        "severity": "high",
+        "title": "Unmatched Transaction Found",
+        "description": "Transaction 'EvoCarShare' for $22.22 has no match in YNAB"
+      }
+    ],
+    "recommendations": [
+      {
+        "id": "rec-abc123",
+        "action_type": "create_transaction",
+        "priority": "high",
+        "confidence": 0.95,
+        "message": "Create transaction for EvoCarShare",
+        "reason": "Transaction appears on bank statement but not in YNAB",
+        "estimated_impact": {
+          "value": 22.22,
+          "value_display": "$22.22",
+          "currency": "USD",
+          "direction": "debit"
+        },
+        "account_id": "account-xyz",
+        "source_insight_id": "insight-1",
+        "metadata": {
+          "version": "1.0",
+          "created_at": "2024-01-31T10:30:00Z"
+        },
+        "parameters": {
+          "account_id": "account-xyz",
+          "date": "2024-01-15",
+          "amount": 22.22,
+          "payee_name": "EvoCarShare",
+          "memo": "Car rental",
+          "cleared": "cleared",
+          "approved": true
+        }
+      }
+    ]
+  }
+}