@dizzlkheinz/ynab-mcpb 0.18.3 → 0.19.0

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

@@ -1,8 +1,8 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { YNABMCPServer } from '../YNABMCPServer';
-import { ValidationError } from '../../types/index';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { skipOnRateLimit } from '../../__tests__/testUtils.js';
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { skipOnRateLimit } from "../../__tests__/testUtils.js";
+import { ValidationError } from "../../types/index";
+import { YNABMCPServer } from "../YNABMCPServer";
 // StdioServerTransport import removed as it's not used in tests
 
 /**
@@ -15,491 +15,510 @@ import { skipOnRateLimit } from '../../__tests__/testUtils.js';
  * - 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 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(/YNAB_ACCESS_TOKEN/i);
-
-        // 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(
-          '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.toHaveProperty(
-              'name',
-              '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.toHaveProperty(
-              'name',
-              'AuthenticationError',
-            );
-
-            // Verify the error message contains relevant information
-            try {
-              await invalidServer.validateToken();
-            } catch (error) {
-              expect((error as { name?: string }).name).toBe('AuthenticationError');
-              expect(error.message).toContain('Token validation failed');
-            }
-          } finally {
-            process.env['YNAB_ACCESS_TOKEN'] = originalToken;
-          }
-        }, ctx);
-      },
-    );
-
-    it(
-      'should surface malformed token responses as AuthenticationError',
-      { meta: { tier: 'domain', domain: 'server' } },
-      async () => {
-        const syntaxError = new SyntaxError('Unexpected token < in JSON at position 0');
-        const getUserSpy = vi
-          .spyOn(server.getYNABAPI().user, 'getUser')
-          .mockRejectedValue(syntaxError);
-
-        try {
-          await expect(server.validateToken()).rejects.toHaveProperty(
-            'name',
-            'AuthenticationError',
-          );
-          await expect(server.validateToken()).rejects.toThrow(
-            'Unexpected response from YNAB during token validation',
-          );
-        } finally {
-          getUserSpy.mockRestore();
-        }
-      },
-    );
-  });
-
-  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(ValidationError);
-          }
-
-          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: expect.stringMatching(/YNAB_ACCESS_TOKEN/i),
-          }),
-        );
-
-        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.toHaveProperty(
-              'name',
-              '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(/YNAB_ACCESS_TOKEN/i);
-
-        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.toHaveProperty('name', 'AuthenticationError');
-          } finally {
-            process.env['YNAB_ACCESS_TOKEN'] = originalToken;
-          }
-        }, ctx);
-      },
-    );
-  });
+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;
+				process.env.YNAB_ACCESS_TOKEN = undefined;
+
+				expect(() => new YNABMCPServer(false)).toThrow(/YNAB_ACCESS_TOKEN/i);
+
+				// 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(
+					"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.toHaveProperty(
+							"name",
+							"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.toHaveProperty(
+							"name",
+							"AuthenticationError",
+						);
+
+						// Verify the error message contains relevant information
+						try {
+							await invalidServer.validateToken();
+						} catch (error) {
+							expect((error as { name?: string }).name).toBe(
+								"AuthenticationError",
+							);
+							expect(error.message).toContain("Token validation failed");
+						}
+					} finally {
+						process.env.YNAB_ACCESS_TOKEN = originalToken;
+					}
+				}, ctx);
+			},
+		);
+
+		it(
+			"should surface malformed token responses as AuthenticationError",
+			{ meta: { tier: "domain", domain: "server" } },
+			async () => {
+				const syntaxError = new SyntaxError(
+					"Unexpected token < in JSON at position 0",
+				);
+				const getUserSpy = vi
+					.spyOn(server.getYNABAPI().user, "getUser")
+					.mockRejectedValue(syntaxError);
+
+				try {
+					await expect(server.validateToken()).rejects.toHaveProperty(
+						"name",
+						"AuthenticationError",
+					);
+					await expect(server.validateToken()).rejects.toThrow(
+						"Unexpected response from YNAB during token validation",
+					);
+				} finally {
+					getUserSpy.mockRestore();
+				}
+			},
+		);
+	});
+
+	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(ValidationError);
+					}
+
+					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;
+				process.env.YNAB_ACCESS_TOKEN = undefined;
+
+				expect(() => new YNABMCPServer(false)).toThrow(
+					expect.objectContaining({
+						message: expect.stringMatching(/YNAB_ACCESS_TOKEN/i),
+					}),
+				);
+
+				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.toHaveProperty(
+							"name",
+							"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;
+				process.env.YNAB_ACCESS_TOKEN = undefined;
+
+				// Should fail immediately on construction, not during run()
+				expect(() => new YNABMCPServer(false)).toThrow(/YNAB_ACCESS_TOKEN/i);
+
+				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.toHaveProperty(
+							"name",
+							"AuthenticationError",
+						);
+					} finally {
+						process.env.YNAB_ACCESS_TOKEN = originalToken;
+					}
+				}, ctx);
+			},
+		);
+	});
 });