@dizzlkheinz/ynab-mcpb 0.17.0 → 0.18.0

package/dist/server/YNABMCPServer.d.ts

@@ -16,6 +16,7 @@ export declare class YNABMCPServer {
     private deltaFetcher;
     private diagnosticManager;
     private errorHandler;
+    private completionsManager;
     constructor(exitOnError?: boolean);
     validateToken(): Promise<boolean>;
     private isMalformedTokenResponse;
@@ -33,39 +34,44 @@ export declare class YNABMCPServer {
     private warmCacheForBudget;
     handleListTools(): Promise<{
         tools: {
-            name: string;
             inputSchema: {
+                [x: string]: unknown;
                 type: "object";
-                required?: string[] | undefined;
                 properties?: {
                     [x: string]: object;
                 } | undefined;
+                required?: string[] | undefined;
             };
-            _meta?: {
-                [x: string]: unknown;
-            } | undefined;
-            icons?: {
-                src: string;
-                mimeType?: string | undefined | undefined;
-                sizes?: string[] | undefined;
-            }[] | undefined;
-            title?: string | undefined | undefined;
-            description?: string | undefined | undefined;
+            name: string;
+            description?: string | undefined;
             outputSchema?: {
+                [x: string]: unknown;
                 type: "object";
-                required?: string[] | undefined;
                 properties?: {
                     [x: string]: object;
                 } | undefined;
-                additionalProperties?: boolean | undefined | undefined;
+                required?: string[] | undefined;
             } | undefined;
             annotations?: {
-                title?: string | undefined | undefined;
-                readOnlyHint?: boolean | undefined | undefined;
-                destructiveHint?: boolean | undefined | undefined;
-                idempotentHint?: boolean | undefined | undefined;
-                openWorldHint?: boolean | undefined | undefined;
+                title?: string | undefined;
+                readOnlyHint?: boolean | undefined;
+                destructiveHint?: boolean | undefined;
+                idempotentHint?: boolean | undefined;
+                openWorldHint?: boolean | undefined;
+            } | undefined;
+            execution?: {
+                taskSupport?: "optional" | "forbidden" | "required" | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
             } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
         }[];
     }>;
     handleListResources(): Promise<{
@@ -78,6 +84,11 @@ export declare class YNABMCPServer {
         content: ({
             type: "text";
             text: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
             _meta?: {
                 [x: string]: unknown;
             } | undefined;
@@ -85,6 +96,11 @@ export declare class YNABMCPServer {
             type: "image";
             data: string;
             mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
             _meta?: {
                 [x: string]: unknown;
             } | undefined;
@@ -92,47 +108,67 @@ export declare class YNABMCPServer {
             type: "audio";
             data: string;
             mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
             _meta?: {
                 [x: string]: unknown;
             } | undefined;
         } | {
-            type: "resource_link";
-            name: string;
             uri: string;
+            name: string;
+            type: "resource_link";
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
             _meta?: {
                 [x: string]: unknown;
             } | undefined;
-            mimeType?: string | undefined | undefined;
             icons?: {
                 src: string;
-                mimeType?: string | undefined | undefined;
+                mimeType?: string | undefined;
                 sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
             }[] | undefined;
-            title?: string | undefined | undefined;
-            description?: string | undefined | undefined;
+            title?: string | undefined;
         } | {
             type: "resource";
             resource: {
                 uri: string;
                 text: string;
+                mimeType?: string | undefined;
                 _meta?: {
                     [x: string]: unknown;
                 } | undefined;
-                mimeType?: string | undefined | undefined;
             } | {
                 uri: string;
                 blob: string;
+                mimeType?: string | undefined;
                 _meta?: {
                     [x: string]: unknown;
                 } | undefined;
-                mimeType?: string | undefined | undefined;
             };
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
             _meta?: {
                 [x: string]: unknown;
             } | undefined;
         })[];
         _meta?: {
             [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
         } | undefined;
         structuredContent?: {
             [x: string]: unknown;
@@ -152,6 +188,11 @@ export declare class YNABMCPServer {
         content: ({
             type: "text";
             text: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
             _meta?: {
                 [x: string]: unknown;
             } | undefined;
@@ -159,6 +200,11 @@ export declare class YNABMCPServer {
             type: "image";
             data: string;
             mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
             _meta?: {
                 [x: string]: unknown;
             } | undefined;
@@ -166,47 +212,67 @@ export declare class YNABMCPServer {
             type: "audio";
             data: string;
             mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
             _meta?: {
                 [x: string]: unknown;
             } | undefined;
         } | {
-            type: "resource_link";
-            name: string;
             uri: string;
+            name: string;
+            type: "resource_link";
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
             _meta?: {
                 [x: string]: unknown;
             } | undefined;
-            mimeType?: string | undefined | undefined;
             icons?: {
                 src: string;
-                mimeType?: string | undefined | undefined;
+                mimeType?: string | undefined;
                 sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
             }[] | undefined;
-            title?: string | undefined | undefined;
-            description?: string | undefined | undefined;
+            title?: string | undefined;
         } | {
             type: "resource";
             resource: {
                 uri: string;
                 text: string;
+                mimeType?: string | undefined;
                 _meta?: {
                     [x: string]: unknown;
                 } | undefined;
-                mimeType?: string | undefined | undefined;
             } | {
                 uri: string;
                 blob: string;
+                mimeType?: string | undefined;
                 _meta?: {
                     [x: string]: unknown;
                 } | undefined;
-                mimeType?: string | undefined | undefined;
             };
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
             _meta?: {
                 [x: string]: unknown;
             } | undefined;
         })[];
         _meta?: {
             [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
         } | undefined;
         structuredContent?: {
             [x: string]: unknown;
@@ -214,39 +280,44 @@ export declare class YNABMCPServer {
         isError?: boolean | undefined;
     } | import("./prompts.js").PromptResponse | {
         tools: {
-            name: string;
             inputSchema: {
+                [x: string]: unknown;
                 type: "object";
-                required?: string[] | undefined;
                 properties?: {
                     [x: string]: object;
                 } | undefined;
+                required?: string[] | undefined;
             };
-            _meta?: {
-                [x: string]: unknown;
-            } | undefined;
-            icons?: {
-                src: string;
-                mimeType?: string | undefined | undefined;
-                sizes?: string[] | undefined;
-            }[] | undefined;
-            title?: string | undefined | undefined;
-            description?: string | undefined | undefined;
+            name: string;
+            description?: string | undefined;
             outputSchema?: {
+                [x: string]: unknown;
                 type: "object";
-                required?: string[] | undefined;
                 properties?: {
                     [x: string]: object;
                 } | undefined;
-                additionalProperties?: boolean | undefined | undefined;
+                required?: string[] | undefined;
             } | undefined;
             annotations?: {
-                title?: string | undefined | undefined;
-                readOnlyHint?: boolean | undefined | undefined;
-                destructiveHint?: boolean | undefined | undefined;
-                idempotentHint?: boolean | undefined | undefined;
-                openWorldHint?: boolean | undefined | undefined;
+                title?: string | undefined;
+                readOnlyHint?: boolean | undefined;
+                destructiveHint?: boolean | undefined;
+                idempotentHint?: boolean | undefined;
+                openWorldHint?: boolean | undefined;
+            } | undefined;
+            execution?: {
+                taskSupport?: "optional" | "forbidden" | "required" | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
             } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
         }[];
         description: string;
         messages: {

package/dist/server/YNABMCPServer.js

@@ -3,7 +3,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import fs from 'fs';
 import path from 'path';
 import { z } from 'zod';
-import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListPromptsRequestSchema, ReadResourceRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListPromptsRequestSchema, ReadResourceRequestSchema, GetPromptRequestSchema, CompleteRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import * as ynab from 'ynab';
 import { AuthenticationError, ConfigurationError, ValidationError as ConfigValidationError, } from '../utils/errors.js';
 import { ValidationError } from '../types/index.js';
@@ -30,6 +30,7 @@ import { ServerKnowledgeStore } from './serverKnowledgeStore.js';
 import { DeltaCache } from './deltaCache.js';
 import { DeltaFetcher } from '../tools/deltaFetcher.js';
 import { ToolAnnotationPresets } from '../tools/toolCategories.js';
+import { CompletionsManager } from './completions.js';
 export class YNABMCPServer {
     constructor(exitOnError = true) {
         this.exitOnError = exitOnError;
@@ -42,9 +43,13 @@ export class YNABMCPServer {
             version: this.serverVersion,
         }, {
             capabilities: {
-                tools: { listChanged: true },
-                resources: { listChanged: true },
-                prompts: { listChanged: true },
+                tools: { listChanged: false },
+                resources: {
+                    subscribe: false,
+                    listChanged: false,
+                },
+                prompts: { listChanged: false },
+                completions: {},
             },
         });
         this.errorHandler = createErrorHandler(responseFormatter);
@@ -111,6 +116,7 @@ export class YNABMCPServer {
             serverKnowledgeStore: this.serverKnowledgeStore,
             deltaCache: this.deltaCache,
         });
+        this.completionsManager = new CompletionsManager(this.ynabAPI, cacheManager, () => this.defaultBudgetId);
         this.setupToolRegistry();
         this.setupHandlers();
     }
@@ -162,12 +168,7 @@ export class YNABMCPServer {
         });
         this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
             const { uri } = request.params;
-            try {
-                return await this.resourceManager.readResource(uri);
-            }
-            catch (error) {
-                return this.errorHandler.handleError(error, `reading resource: ${uri}`);
-            }
+            return await this.resourceManager.readResource(uri);
         });
         this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
             return this.promptManager.listPrompts();
@@ -182,7 +183,10 @@ export class YNABMCPServer {
                 tools: this.toolRegistry.listTools(),
             };
         });
-        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+            if (!this.toolRegistry.hasTool(request.params.name)) {
+                throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${request.params.name}`);
+            }
             const rawArgs = (request.params.arguments ?? undefined);
             const minifyOverride = this.extractMinifyOverride(rawArgs);
             const sanitizedArgs = rawArgs
@@ -202,8 +206,35 @@ export class YNABMCPServer {
             if (minifyOverride !== undefined) {
                 executionOptions.minifyOverride = minifyOverride;
             }
+            const progressToken = request.params
+                ._meta?.progressToken;
+            if (progressToken !== undefined && extra.sendNotification) {
+                executionOptions.sendProgress = async (params) => {
+                    try {
+                        await extra.sendNotification({
+                            method: 'notifications/progress',
+                            params: {
+                                progressToken,
+                                progress: params.progress,
+                                ...(params.total !== undefined && { total: params.total }),
+                                ...(params.message !== undefined && { message: params.message }),
+                            },
+                        });
+                    }
+                    catch {
+                    }
+                };
+            }
             return await this.toolRegistry.executeTool(executionOptions);
         });
+        this.server.setRequestHandler(CompleteRequestSchema, async (request) => {
+            const { argument, context } = request.params;
+            const completionContext = context?.arguments ? { arguments: context.arguments } : undefined;
+            const result = await this.completionsManager.getCompletions(argument.name, argument.value, completionContext);
+            return {
+                completion: result.completion,
+            };
+        });
     }
     setupToolRegistry() {
         const register = (definition) => {

package/dist/server/cacheManager.js

@@ -79,14 +79,15 @@ export class CacheManager {
         else {
             const providedTtl = ttlOrOptions?.ttl;
             ttl = providedTtl !== undefined ? providedTtl : this.defaultTTL;
-            if (ttlOrOptions && 'staleWhileRevalidate' in ttlOrOptions) {
+            const hasStaleWhileRevalidate = ttlOrOptions !== undefined && 'staleWhileRevalidate' in ttlOrOptions;
+            if (hasStaleWhileRevalidate) {
                 staleWhileRevalidate = ttlOrOptions.staleWhileRevalidate;
+                if (staleWhileRevalidate === undefined && this.defaultStaleWindow > 0) {
+                    staleWhileRevalidate = this.defaultStaleWindow;
+                }
             }
             else {
-                staleWhileRevalidate = ttlOrOptions?.staleWhileRevalidate;
-            }
-            if (staleWhileRevalidate === undefined && this.defaultStaleWindow > 0) {
-                staleWhileRevalidate = this.defaultStaleWindow;
+                staleWhileRevalidate = undefined;
             }
         }
         const entry = {

package/dist/server/completions.d.ts

@@ -0,0 +1,25 @@
+import type * as ynab from 'ynab';
+import type { CacheManager } from './cacheManager.js';
+export interface CompletionResult {
+    completion: {
+        values: string[];
+        total?: number;
+        hasMore?: boolean;
+    };
+}
+interface CompletionContext {
+    arguments?: Record<string, string> | undefined;
+}
+export declare class CompletionsManager {
+    private readonly ynabAPI;
+    private readonly cacheManager;
+    private readonly getDefaultBudgetId;
+    constructor(ynabAPI: ynab.API, cacheManager: CacheManager, getDefaultBudgetId: () => string | undefined);
+    getCompletions(argumentName: string, value: string, context?: CompletionContext): Promise<CompletionResult>;
+    private completeBudgets;
+    private completeAccounts;
+    private completeCategories;
+    private completePayees;
+    private filterAndFormat;
+}
+export {};

package/dist/server/completions.js

@@ -0,0 +1,160 @@
+import { CACHE_TTLS } from './cacheManager.js';
+const MAX_COMPLETIONS = 100;
+export class CompletionsManager {
+    constructor(ynabAPI, cacheManager, getDefaultBudgetId) {
+        this.ynabAPI = ynabAPI;
+        this.cacheManager = cacheManager;
+        this.getDefaultBudgetId = getDefaultBudgetId;
+    }
+    async getCompletions(argumentName, value, context) {
+        const normalizedName = argumentName.toLowerCase();
+        switch (normalizedName) {
+            case 'budget_id':
+                return this.completeBudgets(value);
+            case 'account_id':
+            case 'account_name':
+                return this.completeAccounts(value, context);
+            case 'category':
+            case 'category_id':
+                return this.completeCategories(value, context);
+            case 'payee':
+            case 'payee_id':
+                return this.completePayees(value, context);
+            default:
+                return { completion: { values: [], total: 0, hasMore: false } };
+        }
+    }
+    async completeBudgets(value) {
+        const budgets = await this.cacheManager.wrap('completions:budgets', {
+            ttl: CACHE_TTLS.BUDGETS,
+            loader: async () => {
+                const response = await this.ynabAPI.budgets.getBudgets();
+                return response.data.budgets.map((b) => ({
+                    id: b.id,
+                    name: b.name,
+                }));
+            },
+        });
+        return this.filterAndFormat(budgets, value, (b) => [b.name, b.id]);
+    }
+    async completeAccounts(value, context) {
+        const budgetId = context?.arguments?.['budget_id'] ?? this.getDefaultBudgetId();
+        if (!budgetId) {
+            return { completion: { values: [], total: 0, hasMore: false } };
+        }
+        const accounts = await this.cacheManager.wrap(`completions:accounts:${budgetId}`, {
+            ttl: CACHE_TTLS.ACCOUNTS,
+            loader: async () => {
+                const response = await this.ynabAPI.accounts.getAccounts(budgetId);
+                return response.data.accounts
+                    .filter((a) => !a.deleted && !a.closed)
+                    .map((a) => ({
+                    id: a.id,
+                    name: a.name,
+                }));
+            },
+        });
+        return this.filterAndFormat(accounts, value, (a) => [a.name, a.id]);
+    }
+    async completeCategories(value, context) {
+        const budgetId = context?.arguments?.['budget_id'] ?? this.getDefaultBudgetId();
+        if (!budgetId) {
+            return { completion: { values: [], total: 0, hasMore: false } };
+        }
+        const categories = await this.cacheManager.wrap(`completions:categories:${budgetId}`, {
+            ttl: CACHE_TTLS.CATEGORIES,
+            loader: async () => {
+                const response = await this.ynabAPI.categories.getCategories(budgetId);
+                const result = [];
+                for (const group of response.data.category_groups) {
+                    if (group.hidden || group.deleted)
+                        continue;
+                    for (const cat of group.categories) {
+                        if (cat.hidden || cat.deleted)
+                            continue;
+                        result.push({
+                            id: cat.id,
+                            name: cat.name,
+                            group: group.name,
+                        });
+                    }
+                }
+                return result;
+            },
+        });
+        return this.filterAndFormat(categories, value, (c) => [c.name, `${c.group}: ${c.name}`, c.id]);
+    }
+    async completePayees(value, context) {
+        const budgetId = context?.arguments?.['budget_id'] ?? this.getDefaultBudgetId();
+        if (!budgetId) {
+            return { completion: { values: [], total: 0, hasMore: false } };
+        }
+        const payees = await this.cacheManager.wrap(`completions:payees:${budgetId}`, {
+            ttl: CACHE_TTLS.PAYEES,
+            loader: async () => {
+                const response = await this.ynabAPI.payees.getPayees(budgetId);
+                return response.data.payees
+                    .filter((p) => !p.deleted)
+                    .map((p) => ({
+                    id: p.id,
+                    name: p.name,
+                }));
+            },
+        });
+        return this.filterAndFormat(payees, value, (p) => [p.name, p.id]);
+    }
+    filterAndFormat(items, value, getSearchableValues) {
+        const lowerValue = value.toLowerCase();
+        const itemCache = new Map();
+        const getCachedValues = (item) => {
+            let cached = itemCache.get(item);
+            if (!cached) {
+                const values = getSearchableValues(item);
+                cached = { values, lowerValues: values.map((v) => v.toLowerCase()) };
+                itemCache.set(item, cached);
+            }
+            return cached;
+        };
+        const matches = items.filter((item) => {
+            const { lowerValues } = getCachedValues(item);
+            return lowerValues.some((v) => v.includes(lowerValue));
+        });
+        matches.sort((a, b) => {
+            const aCache = getCachedValues(a);
+            const bCache = getCachedValues(b);
+            const aStartsWith = aCache.lowerValues.some((v) => v.startsWith(lowerValue));
+            const bStartsWith = bCache.lowerValues.some((v) => v.startsWith(lowerValue));
+            if (aStartsWith && !bStartsWith)
+                return -1;
+            if (!aStartsWith && bStartsWith)
+                return 1;
+            return (aCache.values[0] ?? '').localeCompare(bCache.values[0] ?? '');
+        });
+        const uniqueValues = new Set();
+        for (const item of matches) {
+            const { values, lowerValues } = getCachedValues(item);
+            let selectedValue;
+            for (let i = 0; i < values.length; i++) {
+                if (lowerValues[i]?.includes(lowerValue)) {
+                    if (selectedValue === undefined || i < values.indexOf(selectedValue)) {
+                        selectedValue = values[i];
+                    }
+                    break;
+                }
+            }
+            if (selectedValue) {
+                uniqueValues.add(selectedValue);
+            }
+            if (uniqueValues.size >= MAX_COMPLETIONS)
+                break;
+        }
+        const resultValues = Array.from(uniqueValues).slice(0, MAX_COMPLETIONS);
+        return {
+            completion: {
+                values: resultValues,
+                total: matches.length,
+                hasMore: matches.length > MAX_COMPLETIONS,
+            },
+        };
+    }
+}

package/dist/server/config.d.ts

@@ -5,10 +5,10 @@ declare const envSchema: z.ZodObject<{
     YNAB_DEFAULT_BUDGET_ID: z.ZodOptional<z.ZodString>;
     MCP_PORT: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
     LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
+        debug: "debug";
         error: "error";
         warn: "warn";
         info: "info";
-        debug: "debug";
         trace: "trace";
         fatal: "fatal";
     }>>;
@@ -17,7 +17,7 @@ export type AppConfig = z.infer<typeof envSchema>;
 export declare function loadConfig(env?: NodeJS.ProcessEnv): AppConfig;
 export declare const config: {
     YNAB_ACCESS_TOKEN: string;
-    LOG_LEVEL: "error" | "warn" | "info" | "debug" | "trace" | "fatal";
+    LOG_LEVEL: "debug" | "error" | "warn" | "info" | "trace" | "fatal";
     YNAB_DEFAULT_BUDGET_ID?: string | undefined;
     MCP_PORT?: number | undefined;
 };

package/dist/server/errorHandler.js

@@ -44,6 +44,7 @@ export class ErrorHandler {
             }
         }
         return {
+            isError: true,
             content: [
                 {
                     type: 'text',

package/dist/server/rateLimiter.js

@@ -78,5 +78,7 @@ export class RateLimitError extends Error {
     }
 }
 export const globalRateLimiter = new RateLimiter({
-    enableLogging: process.env['NODE_ENV'] !== 'production',
+    enableLogging: process.env['RATE_LIMIT_LOGGING'] === 'true' ||
+        process.env['LOG_LEVEL'] === 'debug' ||
+        process.env['VERBOSE_TESTS'] === 'true',
 });