@dizzlkheinz/ynab-mcpb 0.17.1 → 0.18.0

package/src/server/YNABMCPServer.ts

@@ -11,6 +11,9 @@ import {
   ListPromptsRequestSchema,
   ReadResourceRequestSchema,
   GetPromptRequestSchema,
+  CompleteRequestSchema,
+  ErrorCode,
+  McpError,
 } from '@modelcontextprotocol/sdk/types.js';
 import type { Tool } from '@modelcontextprotocol/sdk/types.js';
 import * as ynab from 'ynab';
@@ -36,7 +39,7 @@ import { registerUtilityTools } from '../tools/utilityTools.js';
 import { emptyObjectSchema } from '../tools/schemas/common.js';
 import { cacheManager, CacheManager } from './cacheManager.js';
 import { responseFormatter } from './responseFormatter.js';
-import { ToolRegistry, type ToolDefinition } from './toolRegistry.js';
+import { ToolRegistry, type ToolDefinition, type ProgressCallback } from './toolRegistry.js';
 import { ResourceManager } from './resources.js';
 import { PromptManager } from './prompts.js';
 import { DiagnosticManager } from './diagnostics.js';
@@ -44,6 +47,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';
 
 /**
  * YNAB MCP Server class that provides integration with You Need A Budget API
@@ -63,6 +67,7 @@ export class YNABMCPServer {
   private deltaFetcher: DeltaFetcher;
   private diagnosticManager: DiagnosticManager;
   private errorHandler: ErrorHandler;
+  private completionsManager: CompletionsManager;
 
   constructor(exitOnError: boolean = true) {
     this.exitOnError = exitOnError;
@@ -84,9 +89,13 @@ export class YNABMCPServer {
       },
       {
         capabilities: {
-          tools: { listChanged: true },
-          resources: { listChanged: true },
-          prompts: { listChanged: true },
+          tools: { listChanged: false },
+          resources: {
+            subscribe: false, // YNAB API has no webhooks; subscriptions not applicable
+            listChanged: false,
+          },
+          prompts: { listChanged: false },
+          completions: {},
         },
       },
     );
@@ -173,6 +182,12 @@ export class YNABMCPServer {
       deltaCache: this.deltaCache,
     });
 
+    this.completionsManager = new CompletionsManager(
+      this.ynabAPI,
+      cacheManager,
+      () => this.defaultBudgetId,
+    );
+
     this.setupToolRegistry();
     this.setupHandlers();
   }
@@ -247,11 +262,7 @@ export class YNABMCPServer {
     // Handle read resource requests
     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);
     });
 
     // Handle list prompts requests
@@ -275,7 +286,10 @@ export class YNABMCPServer {
     });
 
     // Handle tool call requests
-    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) as
         | Record<string, unknown>
         | undefined;
@@ -296,6 +310,7 @@ export class YNABMCPServer {
         accessToken: string;
         arguments: Record<string, unknown>;
         minifyOverride?: boolean;
+        sendProgress?: ProgressCallback;
       } = {
         name: request.params.name,
         accessToken: this.configInstance.YNAB_ACCESS_TOKEN,
@@ -306,8 +321,47 @@ export class YNABMCPServer {
         executionOptions.minifyOverride = minifyOverride;
       }
 
+      // Create progress callback if client provided a progressToken
+      const progressToken = (request.params as { _meta?: { progressToken?: string | number } })
+        ._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 {
+            // Progress notifications are non-critical; allow tool execution to continue.
+          }
+        };
+      }
+
       return await this.toolRegistry.executeTool(executionOptions);
     });
+
+    // Handle completion requests for autocomplete
+    this.server.setRequestHandler(CompleteRequestSchema, async (request) => {
+      const { argument, context } = request.params;
+
+      // Get completions from the manager, handling optional context
+      const completionContext = context?.arguments ? { arguments: context.arguments } : undefined;
+      const result = await this.completionsManager.getCompletions(
+        argument.name,
+        argument.value,
+        completionContext,
+      );
+
+      // Return in MCP-compliant format
+      return {
+        completion: result.completion,
+      };
+    });
   }
 
   /**

package/src/server/__tests__/completions.integration.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+import type { YNABMCPServer } from '../YNABMCPServer.js';
+import { getTestConfig, createTestServer } from '../../__tests__/testUtils.js';
+
+/**
+ * Integration tests for CompletionsManager
+ * Tests completions functionality with real or mocked YNAB API
+ */
+describe('CompletionsManager Integration', () => {
+  let server: YNABMCPServer;
+  let testConfig: ReturnType<typeof getTestConfig>;
+
+  beforeAll(async () => {
+    testConfig = getTestConfig();
+
+    if (testConfig.skipE2ETests) {
+      console.warn('Skipping CompletionsManager integration tests - no real API key');
+      return;
+    }
+
+    server = await createTestServer();
+  });
+
+  beforeEach(() => {
+    if (testConfig.skipE2ETests) {
+      return;
+    }
+  });
+
+  describe('Budget Completions', () => {
+    it('should complete budget names from real API', async () => {
+      if (testConfig.skipE2ETests) return;
+
+      const completionsManager = (
+        server as unknown as {
+          completionsManager: {
+            getCompletions: (
+              arg: string,
+              val: string,
+            ) => Promise<{ completion: { values: string[]; total: number } }>;
+          };
+        }
+      ).completionsManager;
+
+      if (!completionsManager) {
+        console.warn('CompletionsManager not exposed on server - skipping test');
+        return;
+      }
+
+      const result = await completionsManager.getCompletions('budget_id', '');
+
+      expect(result.completion).toBeDefined();
+      expect(Array.isArray(result.completion.values)).toBe(true);
+      // Should have at least one budget
+      expect(result.completion.total).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe('Account Completions', () => {
+    it('should require budget context for account completions', async () => {
+      if (testConfig.skipE2ETests) return;
+
+      const completionsManager = (
+        server as unknown as {
+          completionsManager: {
+            getCompletions: (
+              arg: string,
+              val: string,
+              ctx?: unknown,
+            ) => Promise<{ completion: { values: string[]; total: number } }>;
+          };
+        }
+      ).completionsManager;
+
+      if (!completionsManager) {
+        console.warn('CompletionsManager not exposed on server - skipping test');
+        return;
+      }
+
+      // Without budget context, should return empty
+      const result = await completionsManager.getCompletions('account_id', 'check');
+
+      expect(result.completion).toBeDefined();
+      expect(Array.isArray(result.completion.values)).toBe(true);
+    });
+  });
+
+  describe('MCP Completion Handler Integration', () => {
+    it('should handle completion requests through MCP server', async () => {
+      if (testConfig.skipE2ETests) return;
+
+      const mcpServer = server.getServer();
+
+      // The MCP server should have completion capability
+      expect(mcpServer).toBeDefined();
+
+      // Note: Full MCP completion request testing would require
+      // setting up the complete MCP request/response flow
+      // This is a basic smoke test for integration
+    });
+  });
+});
+
+/**
+ * Mock-based integration tests that don't require real API
+ */
+describe('CompletionsManager Mock Integration', () => {
+  it('should be importable and constructible', async () => {
+    const { CompletionsManager } = await import('../completions.js');
+    expect(CompletionsManager).toBeDefined();
+  });
+
+  it('should export correct types', async () => {
+    const module = await import('../completions.js');
+    expect(module.CompletionsManager).toBeDefined();
+  });
+});

package/src/server/__tests__/completions.test.ts

@@ -0,0 +1,319 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { CompletionsManager } from '../completions.js';
+import type { CacheManager } from '../cacheManager.js';
+import type * as ynab from 'ynab';
+
+/**
+ * Unit tests for CompletionsManager
+ * Tests autocomplete functionality for YNAB entities
+ */
+describe('CompletionsManager', () => {
+  let manager: CompletionsManager;
+  let mockYnabAPI: Partial<ynab.API>;
+  let mockCacheManager: Partial<CacheManager>;
+  let getDefaultBudgetId: () => string | undefined;
+
+  const mockBudgets = [
+    { id: 'budget-1', name: 'Personal Budget' },
+    { id: 'budget-2', name: 'Business Budget' },
+    { id: 'budget-3', name: 'Savings' },
+  ];
+
+  const mockAccounts = [
+    { id: 'acc-1', name: 'Checking Account', deleted: false, closed: false },
+    { id: 'acc-2', name: 'Savings Account', deleted: false, closed: false },
+    { id: 'acc-3', name: 'Credit Card', deleted: false, closed: false },
+    { id: 'acc-deleted', name: 'Deleted Account', deleted: true, closed: false },
+    { id: 'acc-closed', name: 'Closed Account', deleted: false, closed: true },
+  ];
+
+  const mockCategories = {
+    category_groups: [
+      {
+        name: 'Bills',
+        hidden: false,
+        deleted: false,
+        categories: [
+          { id: 'cat-1', name: 'Rent', hidden: false, deleted: false },
+          { id: 'cat-2', name: 'Utilities', hidden: false, deleted: false },
+        ],
+      },
+      {
+        name: 'Food',
+        hidden: false,
+        deleted: false,
+        categories: [
+          { id: 'cat-3', name: 'Groceries', hidden: false, deleted: false },
+          { id: 'cat-4', name: 'Restaurants', hidden: false, deleted: false },
+        ],
+      },
+      {
+        name: 'Hidden Group',
+        hidden: true,
+        deleted: false,
+        categories: [{ id: 'cat-hidden', name: 'Hidden Category', hidden: false, deleted: false }],
+      },
+    ],
+  };
+
+  const mockPayees = [
+    { id: 'payee-1', name: 'Amazon', deleted: false },
+    { id: 'payee-2', name: 'Walmart', deleted: false },
+    { id: 'payee-3', name: 'Target', deleted: false },
+    { id: 'payee-deleted', name: 'Deleted Payee', deleted: true },
+  ];
+
+  beforeEach(() => {
+    mockYnabAPI = {
+      budgets: {
+        getBudgets: vi.fn().mockResolvedValue({ data: { budgets: mockBudgets } }),
+      } as unknown as ynab.BudgetsApi,
+      accounts: {
+        getAccounts: vi.fn().mockResolvedValue({ data: { accounts: mockAccounts } }),
+      } as unknown as ynab.AccountsApi,
+      categories: {
+        getCategories: vi.fn().mockResolvedValue({ data: mockCategories }),
+      } as unknown as ynab.CategoriesApi,
+      payees: {
+        getPayees: vi.fn().mockResolvedValue({ data: { payees: mockPayees } }),
+      } as unknown as ynab.PayeesApi,
+    };
+
+    // Mock cache manager that bypasses caching
+    mockCacheManager = {
+      wrap: vi.fn().mockImplementation(async (_key, { loader }) => loader()),
+    };
+
+    getDefaultBudgetId = vi.fn().mockReturnValue('default-budget-id');
+
+    manager = new CompletionsManager(
+      mockYnabAPI as ynab.API,
+      mockCacheManager as CacheManager,
+      getDefaultBudgetId,
+    );
+  });
+
+  describe('getCompletions', () => {
+    it('should return empty completion for unknown argument names', async () => {
+      const result = await manager.getCompletions('unknown_arg', 'test');
+      expect(result.completion.values).toEqual([]);
+      expect(result.completion.total).toBe(0);
+      expect(result.completion.hasMore).toBe(false);
+    });
+
+    it('should handle case-insensitive argument names', async () => {
+      const result = await manager.getCompletions('BUDGET_ID', 'pers');
+      expect(result.completion.values).toContain('Personal Budget');
+    });
+  });
+
+  describe('completeBudgets', () => {
+    it('should return matching budgets by name', async () => {
+      const result = await manager.getCompletions('budget_id', 'pers');
+      expect(result.completion.values).toContain('Personal Budget');
+      expect(result.completion.total).toBe(1);
+    });
+
+    it('should return all budgets when search value is empty', async () => {
+      const result = await manager.getCompletions('budget_id', '');
+      expect(result.completion.values).toHaveLength(3);
+      expect(result.completion.total).toBe(3);
+    });
+
+    it('should match by budget ID', async () => {
+      const result = await manager.getCompletions('budget_id', 'budget-1');
+      expect(result.completion.values.length).toBeGreaterThan(0);
+    });
+
+    it('should prioritize prefix matches over contains', async () => {
+      const result = await manager.getCompletions('budget_id', 'sav');
+      // "Savings" starts with "sav" so it should come before "Business Budget" (contains "sav" in "Business")
+      expect(result.completion.values[0]).toBe('Savings');
+    });
+  });
+
+  describe('completeAccounts', () => {
+    it('should return matching accounts by name', async () => {
+      const result = await manager.getCompletions('account_id', 'check');
+      expect(result.completion.values).toContain('Checking Account');
+    });
+
+    it('should filter out deleted accounts', async () => {
+      const result = await manager.getCompletions('account_id', 'deleted');
+      expect(result.completion.values).not.toContain('Deleted Account');
+      expect(result.completion.total).toBe(0);
+    });
+
+    it('should filter out closed accounts', async () => {
+      const result = await manager.getCompletions('account_id', 'closed');
+      expect(result.completion.values).not.toContain('Closed Account');
+      expect(result.completion.total).toBe(0);
+    });
+
+    it('should return empty when no budget context available', async () => {
+      getDefaultBudgetId = vi.fn().mockReturnValue(undefined);
+      manager = new CompletionsManager(
+        mockYnabAPI as ynab.API,
+        mockCacheManager as CacheManager,
+        getDefaultBudgetId,
+      );
+
+      const result = await manager.getCompletions('account_id', 'check');
+      expect(result.completion.values).toEqual([]);
+    });
+
+    it('should use budget_id from context if provided', async () => {
+      const context = { arguments: { budget_id: 'context-budget' } };
+      await manager.getCompletions('account_id', 'check', context);
+
+      expect(mockCacheManager.wrap).toHaveBeenCalledWith(
+        'completions:accounts:context-budget',
+        expect.any(Object),
+      );
+    });
+
+    it('should handle account_name argument', async () => {
+      const result = await manager.getCompletions('account_name', 'sav');
+      expect(result.completion.values).toContain('Savings Account');
+    });
+  });
+
+  describe('completeCategories', () => {
+    it('should return matching categories by name', async () => {
+      const result = await manager.getCompletions('category', 'groc');
+      expect(result.completion.values).toContain('Groceries');
+    });
+
+    it('should match by group:name format', async () => {
+      const result = await manager.getCompletions('category', 'Food: Groc');
+      expect(result.completion.total).toBeGreaterThan(0);
+    });
+
+    it('should filter out hidden categories', async () => {
+      const result = await manager.getCompletions('category', 'hidden');
+      expect(result.completion.values).not.toContain('Hidden Category');
+    });
+
+    it('should return empty when no budget context available', async () => {
+      getDefaultBudgetId = vi.fn().mockReturnValue(undefined);
+      manager = new CompletionsManager(
+        mockYnabAPI as ynab.API,
+        mockCacheManager as CacheManager,
+        getDefaultBudgetId,
+      );
+
+      const result = await manager.getCompletions('category', 'groc');
+      expect(result.completion.values).toEqual([]);
+    });
+
+    it('should handle category_id argument', async () => {
+      const result = await manager.getCompletions('category_id', 'rent');
+      expect(result.completion.values).toContain('Rent');
+    });
+
+    it('should prioritize name over ID in results', async () => {
+      // When searching for a category, we should get the name, not the ID
+      const result = await manager.getCompletions('category', 'cat-1');
+      // Even when matching by ID, the display value should prefer the name
+      expect(result.completion.total).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe('completePayees', () => {
+    it('should return matching payees by name', async () => {
+      const result = await manager.getCompletions('payee', 'amaz');
+      expect(result.completion.values).toContain('Amazon');
+    });
+
+    it('should filter out deleted payees', async () => {
+      const result = await manager.getCompletions('payee', 'deleted');
+      expect(result.completion.values).not.toContain('Deleted Payee');
+    });
+
+    it('should handle payee_id argument', async () => {
+      const result = await manager.getCompletions('payee_id', 'targ');
+      expect(result.completion.values).toContain('Target');
+    });
+
+    it('should return empty when no budget context available', async () => {
+      getDefaultBudgetId = vi.fn().mockReturnValue(undefined);
+      manager = new CompletionsManager(
+        mockYnabAPI as ynab.API,
+        mockCacheManager as CacheManager,
+        getDefaultBudgetId,
+      );
+
+      const result = await manager.getCompletions('payee', 'amaz');
+      expect(result.completion.values).toEqual([]);
+    });
+  });
+
+  describe('filterAndFormat', () => {
+    it('should respect MAX_COMPLETIONS limit', async () => {
+      // Create a large list of budgets
+      const manyBudgets = Array.from({ length: 150 }, (_, i) => ({
+        id: `budget-${i}`,
+        name: `Budget ${i}`,
+      }));
+
+      mockYnabAPI.budgets = {
+        getBudgets: vi.fn().mockResolvedValue({ data: { budgets: manyBudgets } }),
+      } as unknown as ynab.BudgetsApi;
+
+      manager = new CompletionsManager(
+        mockYnabAPI as ynab.API,
+        mockCacheManager as CacheManager,
+        getDefaultBudgetId,
+      );
+
+      const result = await manager.getCompletions('budget_id', 'Budget');
+      expect(result.completion.values.length).toBeLessThanOrEqual(100);
+      expect(result.completion.hasMore).toBe(true);
+      expect(result.completion.total).toBe(150);
+    });
+
+    it('should cache lowercased values for performance', async () => {
+      // This is tested implicitly by the fact that filtering works correctly
+      // The internal cache is not exposed, but we verify behavior is correct
+      const result = await manager.getCompletions('budget_id', 'PERSONAL');
+      expect(result.completion.values).toContain('Personal Budget');
+    });
+
+    it('should return unique values only', async () => {
+      const result = await manager.getCompletions('budget_id', 'budget');
+      const uniqueCount = new Set(result.completion.values).size;
+      expect(uniqueCount).toBe(result.completion.values.length);
+    });
+  });
+
+  describe('caching behavior', () => {
+    it('should use cache manager for budgets', async () => {
+      await manager.getCompletions('budget_id', 'test');
+      expect(mockCacheManager.wrap).toHaveBeenCalledWith('completions:budgets', expect.any(Object));
+    });
+
+    it('should use cache manager for accounts with budget-specific key', async () => {
+      await manager.getCompletions('account_id', 'test');
+      expect(mockCacheManager.wrap).toHaveBeenCalledWith(
+        'completions:accounts:default-budget-id',
+        expect.any(Object),
+      );
+    });
+
+    it('should use cache manager for categories with budget-specific key', async () => {
+      await manager.getCompletions('category', 'test');
+      expect(mockCacheManager.wrap).toHaveBeenCalledWith(
+        'completions:categories:default-budget-id',
+        expect.any(Object),
+      );
+    });
+
+    it('should use cache manager for payees with budget-specific key', async () => {
+      await manager.getCompletions('payee', 'test');
+      expect(mockCacheManager.wrap).toHaveBeenCalledWith(
+        'completions:payees:default-budget-id',
+        expect.any(Object),
+      );
+    });
+  });
+});

package/src/server/__tests__/resources.template.test.ts

@@ -109,7 +109,7 @@ describe('ResourceManager Templates', () => {
   it('should fallback to throwing error for unknown URIs', async () => {
     const uri = 'ynab://unknown/resource';
     await expect(resourceManager.readResource(uri)).rejects.toThrow(
-      'Unknown resource: ynab://unknown/resource',
+      'Resource not found: ynab://unknown/resource',
     );
   });
 
@@ -135,7 +135,7 @@ describe('ResourceManager Templates', () => {
       (mockYnabAPI.budgets.getBudgetById as any).mockRejectedValue(new Error('Budget not found'));
 
       await expect(resourceManager.readResource('ynab://budgets/invalid-id')).rejects.toThrow(
-        'Failed to resolve template resource ynab://budgets/invalid-id: Failed to fetch budget invalid-id: Budget not found',
+        'Failed to read resource ynab://budgets/invalid-id: Failed to fetch budget invalid-id: Budget not found',
       );
     });
 
@@ -147,7 +147,7 @@ describe('ResourceManager Templates', () => {
       await expect(
         resourceManager.readResource('ynab://budgets/budget-id/accounts/invalid-account'),
       ).rejects.toThrow(
-        'Failed to resolve template resource ynab://budgets/budget-id/accounts/invalid-account: Failed to fetch account invalid-account in budget budget-id: Account not found',
+        'Failed to read resource ynab://budgets/budget-id/accounts/invalid-account: Failed to fetch account invalid-account in budget budget-id: Account not found',
       );
     });
 

package/src/server/__tests__/resources.test.ts

@@ -212,18 +212,18 @@ describe('resources module', () => {
       describe('unknown resources', () => {
         it('should throw error for unknown resource URIs', async () => {
           await expect(resourceManager.readResource('ynab://unknown')).rejects.toThrow(
-            'Unknown resource: ynab://unknown',
+            'Resource not found: ynab://unknown',
           );
         });
 
         it('should throw error for invalid URIs', async () => {
           await expect(resourceManager.readResource('invalid-uri')).rejects.toThrow(
-            'Unknown resource: invalid-uri',
+            'Resource not found: invalid-uri',
           );
         });
 
         it('should throw error for empty URI', async () => {
-          await expect(resourceManager.readResource('')).rejects.toThrow('Unknown resource: ');
+          await expect(resourceManager.readResource('')).rejects.toThrow('Resource not found: ');
         });
       });
     });

package/src/server/__tests__/toolRegistration.test.ts

@@ -66,7 +66,7 @@ describe('Tool Registration', () => {
   // Config is mocked at module level, no env setup needed
 
   describe('Tool Count Verification', () => {
-    it('registers exactly 30 tools', () => {
+    it('registers exactly 29 tools', () => {
       const server = new YNABMCPServer(false);
       const tools = server.getToolRegistry().listTools();
       expect(tools).toHaveLength(EXPECTED_TOOL_COUNT);

package/src/server/cacheManager.ts

@@ -145,14 +145,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;
-      }
-      // Apply default stale window only when options object is provided and staleWhileRevalidate is undefined
-      if (staleWhileRevalidate === undefined && this.defaultStaleWindow > 0) {
-        staleWhileRevalidate = this.defaultStaleWindow;
+        staleWhileRevalidate = undefined;
       }
     }
     const entry: CacheEntry<T> = {