@dizzlkheinz/ynab-mcpb 0.12.1

package/src/server/__tests__/server-startup.integration.test.ts

@@ -0,0 +1,477 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { YNABMCPServer } from '../YNABMCPServer';
+import { AuthenticationError, ConfigurationError } from '../../types/index';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { skipOnRateLimit } from '../../__tests__/testUtils.js';
+// StdioServerTransport import removed as it's not used in tests
+
+/**
+ * Integration tests for server startup and transport setup
+ * Tests the complete server initialization process including:
+ * - Environment validation
+ * - YNAB API authentication
+ * - MCP server initialization
+ * - Tool registration
+ * - Transport connection setup
+ * Skips if YNAB_ACCESS_TOKEN is not set or if SKIP_E2E_TESTS is true
+ */
+const hasToken = !!process.env['YNAB_ACCESS_TOKEN'];
+const shouldSkip = process.env['SKIP_E2E_TESTS'] === 'true' || !hasToken;
+const describeIntegration = shouldSkip ? describe.skip : describe;
+
+describeIntegration('Server Startup and Transport Integration', () => {
+  const originalEnv = process.env;
+
+  afterEach(() => {
+    // Restore environment but keep API key
+    Object.keys(process.env).forEach((key) => {
+      if (key !== 'YNAB_ACCESS_TOKEN' && key !== 'YNAB_BUDGET_ID') {
+        if (originalEnv[key] !== undefined) {
+          process.env[key] = originalEnv[key];
+        } else {
+          process.env[key] = undefined;
+        }
+      }
+    });
+  });
+
+  describe('Server Initialization', () => {
+    it(
+      'should successfully initialize server with valid configuration',
+      { meta: { tier: 'domain', domain: 'server' } },
+      () => {
+        const server = new YNABMCPServer(false);
+
+        expect(server).toBeInstanceOf(YNABMCPServer);
+        expect(server.getYNABAPI()).toBeDefined();
+        expect(server.getServer()).toBeInstanceOf(Server);
+      },
+    );
+
+    it(
+      'should fail initialization with missing access token',
+      { meta: { tier: 'domain', domain: 'server' } },
+      () => {
+        const originalToken = process.env['YNAB_ACCESS_TOKEN'];
+        delete process.env['YNAB_ACCESS_TOKEN'];
+
+        expect(() => new YNABMCPServer(false)).toThrow(ConfigurationError);
+        expect(() => new YNABMCPServer(false)).toThrow(
+          'YNAB_ACCESS_TOKEN environment variable is required but not set',
+        );
+
+        // Restore token
+        process.env['YNAB_ACCESS_TOKEN'] = originalToken;
+      },
+    );
+
+    it(
+      'should fail initialization with invalid access token format',
+      { meta: { tier: 'domain', domain: 'server' } },
+      () => {
+        const originalToken = process.env['YNAB_ACCESS_TOKEN'];
+        process.env['YNAB_ACCESS_TOKEN'] = '';
+
+        expect(() => new YNABMCPServer(false)).toThrow(ConfigurationError);
+        expect(() => new YNABMCPServer(false)).toThrow(
+          'YNAB_ACCESS_TOKEN must be a non-empty string',
+        );
+
+        // Restore token
+        process.env['YNAB_ACCESS_TOKEN'] = originalToken;
+      },
+    );
+  });
+
+  describe('Server Startup Validation', () => {
+    let server: YNABMCPServer;
+
+    beforeEach(() => {
+      server = new YNABMCPServer(false);
+    });
+
+    it(
+      'should validate YNAB token during startup',
+      { meta: { tier: 'domain', domain: 'server' } },
+      async (ctx) => {
+        await skipOnRateLimit(async () => {
+          const isValid = await server.validateToken();
+          expect(isValid).toBe(true);
+        }, ctx);
+      },
+    );
+
+    it(
+      'should handle invalid token gracefully during startup',
+      { meta: { tier: 'domain', domain: 'server' } },
+      async (ctx) => {
+        await skipOnRateLimit(async () => {
+          const originalToken = process.env['YNAB_ACCESS_TOKEN'];
+          process.env['YNAB_ACCESS_TOKEN'] = 'invalid-token-12345';
+
+          try {
+            const invalidServer = new YNABMCPServer(false);
+            await expect(invalidServer.validateToken()).rejects.toThrow(AuthenticationError);
+          } finally {
+            process.env['YNAB_ACCESS_TOKEN'] = originalToken;
+          }
+        }, ctx);
+      },
+    );
+
+    it(
+      'should provide detailed error messages for authentication failures',
+      { meta: { tier: 'domain', domain: 'server' } },
+      async (ctx) => {
+        await skipOnRateLimit(async () => {
+          const originalToken = process.env['YNAB_ACCESS_TOKEN'];
+          process.env['YNAB_ACCESS_TOKEN'] = 'definitely-invalid-token';
+
+          try {
+            const invalidServer = new YNABMCPServer(false);
+            await expect(invalidServer.validateToken()).rejects.toThrow(AuthenticationError);
+
+            // Verify the error message contains relevant information
+            try {
+              await invalidServer.validateToken();
+            } catch (error) {
+              expect(error).toBeInstanceOf(AuthenticationError);
+              expect(error.message).toContain('Token validation failed');
+            }
+          } finally {
+            process.env['YNAB_ACCESS_TOKEN'] = originalToken;
+          }
+        }, ctx);
+      },
+    );
+  });
+
+  describe('Tool Registration', () => {
+    let server: YNABMCPServer;
+
+    beforeEach(() => {
+      server = new YNABMCPServer(false);
+    });
+
+    it(
+      'should register all expected YNAB tools',
+      { meta: { tier: 'domain', domain: 'server' } },
+      async () => {
+        const mcpServer = server.getServer();
+
+        // We can't directly call the handler, but we can verify the server has the right structure
+        expect(mcpServer).toBeDefined();
+
+        // Verify the server instance has been properly initialized
+        // The tools are registered in the constructor via setRequestHandler calls
+        expect(server.getYNABAPI()).toBeDefined();
+
+        // Test that the server can handle basic operations
+        expect(typeof server.validateToken).toBe('function');
+        expect(typeof server.run).toBe('function');
+      },
+    );
+
+    it(
+      'should register budget management tools',
+      { meta: { tier: 'domain', domain: 'server' } },
+      () => {
+        // Test that the server instance includes budget tools
+        const mcpServer = server.getServer();
+        expect(mcpServer).toBeDefined();
+
+        // The tools are registered in the constructor, so if the server initializes
+        // successfully, the tools should be registered
+        expect(server.getYNABAPI().budgets).toBeDefined();
+      },
+    );
+
+    it(
+      'should register account management tools',
+      { meta: { tier: 'domain', domain: 'server' } },
+      () => {
+        const mcpServer = server.getServer();
+        expect(mcpServer).toBeDefined();
+        expect(server.getYNABAPI().accounts).toBeDefined();
+      },
+    );
+
+    it(
+      'should register transaction management tools',
+      { meta: { tier: 'domain', domain: 'server' } },
+      () => {
+        const mcpServer = server.getServer();
+        expect(mcpServer).toBeDefined();
+        expect(server.getYNABAPI().transactions).toBeDefined();
+      },
+    );
+
+    it(
+      'should register category management tools',
+      { meta: { tier: 'domain', domain: 'server' } },
+      () => {
+        const mcpServer = server.getServer();
+        expect(mcpServer).toBeDefined();
+        expect(server.getYNABAPI().categories).toBeDefined();
+      },
+    );
+
+    it(
+      'should register payee management tools',
+      { meta: { tier: 'domain', domain: 'server' } },
+      () => {
+        const mcpServer = server.getServer();
+        expect(mcpServer).toBeDefined();
+        expect(server.getYNABAPI().payees).toBeDefined();
+      },
+    );
+
+    it('should register utility tools', { meta: { tier: 'domain', domain: 'server' } }, () => {
+      const mcpServer = server.getServer();
+      expect(mcpServer).toBeDefined();
+      expect(server.getYNABAPI().user).toBeDefined();
+    });
+  });
+
+  describe('Transport Setup', () => {
+    let server: YNABMCPServer;
+
+    beforeEach(() => {
+      server = new YNABMCPServer(false);
+    });
+
+    it(
+      'should attempt to connect with StdioServerTransport',
+      { meta: { tier: 'domain', domain: 'server' } },
+      async (ctx) => {
+        await skipOnRateLimit(async () => {
+          // Validate token first (this may skip if rate limited)
+          const isValid = await server.validateToken();
+          expect(isValid).toBe(true);
+
+          // If we get here, token is valid - now test transport connection
+          const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {
+            // Mock implementation for testing
+          });
+
+          try {
+            // The run method should attempt stdio connection
+            await server.run();
+
+            // In test environment, stdio connection will fail, but that's expected
+          } catch (error) {
+            // Expected to fail on stdio connection in test environment
+            // Token was already validated above, so this error should be transport-related
+            expect(error).not.toBeInstanceOf(ConfigurationError);
+          }
+
+          consoleSpy.mockRestore();
+        }, ctx);
+      },
+    );
+
+    it(
+      'should handle transport connection errors gracefully',
+      { meta: { tier: 'domain', domain: 'server' } },
+      async (ctx) => {
+        await skipOnRateLimit(async () => {
+          const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {
+            // Mock implementation for testing
+          });
+
+          try {
+            await server.run();
+          } catch (error) {
+            // Should handle transport errors without crashing
+            expect(error).toBeDefined();
+          }
+
+          consoleSpy.mockRestore();
+        }, ctx);
+      },
+    );
+
+    it(
+      'should validate token before attempting transport connection',
+      { meta: { tier: 'domain', domain: 'server' } },
+      async (ctx) => {
+        await skipOnRateLimit(async () => {
+          const validateTokenSpy = vi.spyOn(server, 'validateToken');
+          const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {
+            // Mock implementation for testing
+          });
+
+          try {
+            await server.run();
+          } catch {
+            // Transport will fail in test environment, but token validation should be called
+            expect(validateTokenSpy).toHaveBeenCalled();
+          }
+
+          validateTokenSpy.mockRestore();
+          consoleSpy.mockRestore();
+        }, ctx);
+      },
+    );
+  });
+
+  describe('Error Reporting', () => {
+    it(
+      'should report configuration errors clearly',
+      { meta: { tier: 'domain', domain: 'server' } },
+      () => {
+        const originalToken = process.env['YNAB_ACCESS_TOKEN'];
+        delete process.env['YNAB_ACCESS_TOKEN'];
+
+        expect(() => new YNABMCPServer(false)).toThrow(
+          expect.objectContaining({
+            message: 'YNAB_ACCESS_TOKEN environment variable is required but not set',
+          }),
+        );
+
+        process.env['YNAB_ACCESS_TOKEN'] = originalToken;
+      },
+    );
+
+    it(
+      'should report authentication errors clearly',
+      { meta: { tier: 'domain', domain: 'server' } },
+      async (ctx) => {
+        await skipOnRateLimit(async () => {
+          const originalToken = process.env['YNAB_ACCESS_TOKEN'];
+          process.env['YNAB_ACCESS_TOKEN'] = 'invalid-token';
+
+          try {
+            const server = new YNABMCPServer(false);
+            await expect(server.validateToken()).rejects.toThrow(AuthenticationError);
+          } finally {
+            process.env['YNAB_ACCESS_TOKEN'] = originalToken;
+          }
+        }, ctx);
+      },
+    );
+
+    it(
+      'should handle startup errors without exposing sensitive information',
+      { meta: { tier: 'domain', domain: 'server' } },
+      async (ctx) => {
+        await skipOnRateLimit(async () => {
+          const originalToken = process.env['YNAB_ACCESS_TOKEN'];
+          process.env['YNAB_ACCESS_TOKEN'] = 'invalid-token';
+
+          try {
+            const server = new YNABMCPServer(false);
+            await expect(server.run()).rejects.toThrow();
+
+            // Verify error doesn't contain the actual token
+            try {
+              await server.run();
+            } catch (error) {
+              expect(error.message).not.toContain('invalid-token');
+            }
+          } finally {
+            process.env['YNAB_ACCESS_TOKEN'] = originalToken;
+          }
+        }, ctx);
+      },
+    );
+  });
+
+  describe('Graceful Shutdown', () => {
+    it(
+      'should handle process signals gracefully',
+      { meta: { tier: 'domain', domain: 'server' } },
+      () => {
+        // Test that the server can be created without throwing
+        const server = new YNABMCPServer(false);
+        expect(server).toBeDefined();
+
+        // In a real scenario, the process signal handlers in index.ts would handle shutdown
+        // We can't easily test the actual signal handling in a unit test environment
+        // But we can verify the server initializes properly
+      },
+    );
+
+    it(
+      'should clean up resources on shutdown',
+      { meta: { tier: 'domain', domain: 'server' } },
+      () => {
+        const server = new YNABMCPServer(false);
+
+        // Verify server has the necessary components for cleanup
+        expect(server.getServer()).toBeDefined();
+        expect(server.getYNABAPI()).toBeDefined();
+      },
+    );
+  });
+
+  describe('Full Startup Workflow', () => {
+    it(
+      'should complete full startup sequence successfully',
+      { meta: { tier: 'domain', domain: 'server' } },
+      async (ctx) => {
+        await skipOnRateLimit(async () => {
+          const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {
+            // Mock implementation for testing
+          });
+
+          try {
+            // Create server
+            const server = new YNABMCPServer(false);
+            expect(server).toBeDefined();
+
+            // Validate token
+            const isValid = await server.validateToken();
+            expect(isValid).toBe(true);
+
+            // Attempt to run (will fail on transport in test environment)
+            try {
+              await server.run();
+            } catch {
+              // Expected to fail on stdio transport in test environment
+              // But authentication and initialization should succeed
+            }
+
+            console.warn('✅ Server startup workflow completed successfully');
+          } finally {
+            consoleSpy.mockRestore();
+          }
+        }, ctx);
+      },
+    );
+
+    it(
+      'should fail fast on configuration errors',
+      { meta: { tier: 'domain', domain: 'server' } },
+      () => {
+        const originalToken = process.env['YNAB_ACCESS_TOKEN'];
+        delete process.env['YNAB_ACCESS_TOKEN'];
+
+        // Should fail immediately on construction, not during run()
+        expect(() => new YNABMCPServer(false)).toThrow(ConfigurationError);
+
+        process.env['YNAB_ACCESS_TOKEN'] = originalToken;
+      },
+    );
+
+    it(
+      'should fail fast on authentication errors',
+      { meta: { tier: 'domain', domain: 'server' } },
+      async (ctx) => {
+        await skipOnRateLimit(async () => {
+          const originalToken = process.env['YNAB_ACCESS_TOKEN'];
+          process.env['YNAB_ACCESS_TOKEN'] = 'invalid-token';
+
+          try {
+            const server = new YNABMCPServer(false);
+
+            // Should fail on token validation, before transport setup
+            await expect(server.run()).rejects.toThrow(AuthenticationError);
+          } finally {
+            process.env['YNAB_ACCESS_TOKEN'] = originalToken;
+          }
+        }, ctx);
+      },
+    );
+  });
+});

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

@@ -0,0 +1,174 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ServerKnowledgeStore } from '../serverKnowledgeStore.js';
+
+describe('ServerKnowledgeStore', () => {
+  let store: ServerKnowledgeStore;
+
+  beforeEach(() => {
+    store = new ServerKnowledgeStore();
+  });
+
+  describe('Basic Operations', () => {
+    it('should return undefined for non-existent keys', () => {
+      expect(store.get('non-existent-key')).toBeUndefined();
+    });
+
+    it('should store and retrieve knowledge values', () => {
+      store.update('transactions:list:budget-123', 1000);
+      expect(store.get('transactions:list:budget-123')).toBe(1000);
+    });
+
+    it('should update existing knowledge values', () => {
+      store.update('transactions:list:budget-123', 1000);
+      store.update('transactions:list:budget-123', 1005);
+      expect(store.get('transactions:list:budget-123')).toBe(1005);
+    });
+
+    it('should handle multiple cache keys independently', () => {
+      store.update('transactions:list:budget-123', 1000);
+      store.update('accounts:list:budget-123', 2000);
+      store.update('transactions:list:budget-456', 3000);
+
+      expect(store.get('transactions:list:budget-123')).toBe(1000);
+      expect(store.get('accounts:list:budget-123')).toBe(2000);
+      expect(store.get('transactions:list:budget-456')).toBe(3000);
+    });
+
+    it('should return correct stats with entryCount and entries object', () => {
+      store.update('key1', 100);
+      store.update('key2', 200);
+      store.update('key3', 300);
+
+      const stats = store.getStats();
+      expect(stats.entryCount).toBe(3);
+      expect(stats.entries).toEqual({
+        key1: 100,
+        key2: 200,
+        key3: 300,
+      });
+    });
+  });
+
+  describe('Validation', () => {
+    it('should throw error for negative server_knowledge values', () => {
+      expect(() => store.update('key', -1)).toThrow(
+        'server_knowledge must be non-negative, got: -1',
+      );
+    });
+
+    it('should accept zero as valid server_knowledge', () => {
+      expect(() => store.update('key', 0)).not.toThrow();
+      expect(store.get('key')).toBe(0);
+    });
+
+    it('should accept large positive integers', () => {
+      const largeValue = 999999;
+      expect(() => store.update('key', largeValue)).not.toThrow();
+      expect(store.get('key')).toBe(largeValue);
+    });
+  });
+
+  describe('Reset Operations', () => {
+    beforeEach(() => {
+      store.update('transactions:list:budget-123:all:all', 1000);
+      store.update('accounts:list:budget-123', 2000);
+      store.update('transactions:list:budget-456', 3000);
+      store.update('categories:list:budget-123', 4000);
+    });
+
+    it('should reset all knowledge when called without pattern', () => {
+      store.reset();
+      expect(store.get('transactions:list:budget-123:all:all')).toBeUndefined();
+      expect(store.get('accounts:list:budget-123')).toBeUndefined();
+      expect(store.get('transactions:list:budget-456')).toBeUndefined();
+      expect(store.get('categories:list:budget-123')).toBeUndefined();
+      expect(store.getStats().entryCount).toBe(0);
+    });
+
+    it('should reset only matching keys when pattern provided', () => {
+      store.reset('transactions:list:budget-123');
+
+      // Should match and delete
+      expect(store.get('transactions:list:budget-123:all:all')).toBeUndefined();
+
+      // Should not match and preserve
+      expect(store.get('accounts:list:budget-123')).toBe(2000);
+      expect(store.get('transactions:list:budget-456')).toBe(3000);
+      expect(store.get('categories:list:budget-123')).toBe(4000);
+    });
+
+    it('should not reset non-matching keys', () => {
+      store.reset('non-existent-pattern');
+
+      // All keys should remain
+      expect(store.get('transactions:list:budget-123:all:all')).toBe(1000);
+      expect(store.get('accounts:list:budget-123')).toBe(2000);
+      expect(store.get('transactions:list:budget-456')).toBe(3000);
+      expect(store.get('categories:list:budget-123')).toBe(4000);
+    });
+
+    it('should handle resetByBudgetId correctly', () => {
+      store.resetByBudgetId('budget-123');
+
+      // Should match all keys containing ':budget-123'
+      expect(store.get('transactions:list:budget-123:all:all')).toBeUndefined();
+      expect(store.get('accounts:list:budget-123')).toBeUndefined();
+      expect(store.get('categories:list:budget-123')).toBeUndefined();
+
+      // Should not match budget-456
+      expect(store.get('transactions:list:budget-456')).toBe(3000);
+    });
+
+    it('should not affect other budgets when resetting by budget ID', () => {
+      store.update('transactions:list:budget-789', 5000);
+
+      store.resetByBudgetId('budget-123');
+
+      // budget-456 and budget-789 should remain
+      expect(store.get('transactions:list:budget-456')).toBe(3000);
+      expect(store.get('transactions:list:budget-789')).toBe(5000);
+    });
+
+    it('should handle empty store gracefully', () => {
+      const emptyStore = new ServerKnowledgeStore();
+      expect(() => emptyStore.reset()).not.toThrow();
+      expect(() => emptyStore.reset('pattern')).not.toThrow();
+      expect(() => emptyStore.resetByBudgetId('budget-123')).not.toThrow();
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle very long cache keys', () => {
+      const longKey = 'a'.repeat(250);
+      store.update(longKey, 1000);
+      expect(store.get(longKey)).toBe(1000);
+    });
+
+    it('should handle special characters in cache keys', () => {
+      const specialKey = 'transactions:list:budget-123:date:2024-01-01_2024-12-31';
+      store.update(specialKey, 1000);
+      expect(store.get(specialKey)).toBe(1000);
+    });
+
+    it('should handle rapid updates to same key', () => {
+      store.update('key', 100);
+      store.update('key', 200);
+      store.update('key', 300);
+      store.update('key', 400);
+
+      // Last write wins
+      expect(store.get('key')).toBe(400);
+    });
+
+    it('should maintain isolation between different store instances', () => {
+      const store1 = new ServerKnowledgeStore();
+      const store2 = new ServerKnowledgeStore();
+
+      store1.update('key', 100);
+      store2.update('key', 200);
+
+      expect(store1.get('key')).toBe(100);
+      expect(store2.get('key')).toBe(200);
+    });
+  });
+});