@dizzlkheinz/ynab-mcpb 0.12.2 → 0.13.1

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

@@ -2,7 +2,7 @@ import { describe, it, expect, vi, beforeEach, afterEach, beforeAll } from 'vite
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 
 import { YNABMCPServer } from '../YNABMCPServer.js';
-import { AuthenticationError, ConfigurationError, ValidationError } from '../../types/index.js';
+import { AuthenticationError, ValidationError } from '../../types/index.js';
 import { ToolRegistry } from '../toolRegistry.js';
 import { cacheManager } from '../../server/cacheManager.js';
 import { responseFormatter } from '../../server/responseFormatter.js';
@@ -80,41 +80,56 @@ describe('YNABMCPServer', () => {
       expect(server.getYNABAPI()).toBeDefined();
     });
 
-    it('should throw ConfigurationError when YNAB_ACCESS_TOKEN is missing', () => {
+    it('should throw ValidationError when YNAB_ACCESS_TOKEN is missing', () => {
       const originalToken = process.env['YNAB_ACCESS_TOKEN'];
       delete process.env['YNAB_ACCESS_TOKEN'];
 
-      expect(() => new YNABMCPServer()).toThrow(ConfigurationError);
-      expect(() => new YNABMCPServer()).toThrow(
-        'YNAB_ACCESS_TOKEN environment variable is required but not set',
-      );
+      expect(() => new YNABMCPServer()).toThrow(/YNAB_ACCESS_TOKEN/i);
 
       // Restore token
       process.env['YNAB_ACCESS_TOKEN'] = originalToken;
     });
 
-    it('should throw ConfigurationError when YNAB_ACCESS_TOKEN is empty string', () => {
+    it('should throw ValidationError when YNAB_ACCESS_TOKEN is empty string', () => {
       const originalToken = process.env['YNAB_ACCESS_TOKEN'];
       process.env['YNAB_ACCESS_TOKEN'] = '';
 
-      expect(() => new YNABMCPServer()).toThrow(ConfigurationError);
       expect(() => new YNABMCPServer()).toThrow('YNAB_ACCESS_TOKEN must be a non-empty string');
 
       // Restore token
       process.env['YNAB_ACCESS_TOKEN'] = originalToken;
     });
 
-    it('should throw ConfigurationError when YNAB_ACCESS_TOKEN is only whitespace', () => {
+    it('should throw ValidationError when YNAB_ACCESS_TOKEN is only whitespace', () => {
       const originalToken = process.env['YNAB_ACCESS_TOKEN'];
       process.env['YNAB_ACCESS_TOKEN'] = '   ';
 
-      expect(() => new YNABMCPServer()).toThrow(ConfigurationError);
       expect(() => new YNABMCPServer()).toThrow('YNAB_ACCESS_TOKEN must be a non-empty string');
 
       // Restore token
       process.env['YNAB_ACCESS_TOKEN'] = originalToken;
     });
 
+    it('should reload configuration for each server instance', () => {
+      const originalToken = process.env['YNAB_ACCESS_TOKEN'];
+
+      process.env['YNAB_ACCESS_TOKEN'] = 'token-one';
+      const firstServer = new YNABMCPServer(false);
+      const firstConfig = (
+        firstServer as unknown as { configInstance: { YNAB_ACCESS_TOKEN: string } }
+      ).configInstance;
+      expect(firstConfig.YNAB_ACCESS_TOKEN).toBe('token-one');
+
+      process.env['YNAB_ACCESS_TOKEN'] = 'token-two';
+      const secondServer = new YNABMCPServer(false);
+      const secondConfig = (
+        secondServer as unknown as { configInstance: { YNAB_ACCESS_TOKEN: string } }
+      ).configInstance;
+      expect(secondConfig.YNAB_ACCESS_TOKEN).toBe('token-two');
+
+      process.env['YNAB_ACCESS_TOKEN'] = originalToken;
+    });
+
     it('should trim whitespace from access token', () => {
       const originalToken = process.env['YNAB_ACCESS_TOKEN'];
       process.env['YNAB_ACCESS_TOKEN'] = `  ${originalToken}  `;
@@ -193,7 +208,7 @@ describe('YNABMCPServer', () => {
         // Expected to fail on stdio connection in test environment
         // But should not fail on token validation
         expect(error).not.toBeInstanceOf(AuthenticationError);
-        expect(error).not.toBeInstanceOf(ConfigurationError);
+        expect(error).not.toBeInstanceOf(ValidationError);
       }
 
       consoleSpy.mockRestore();
@@ -739,10 +754,7 @@ describe('YNABMCPServer', () => {
       delete process.env['YNAB_ACCESS_TOKEN'];
 
       try {
-        expect(() => new YNABMCPServer()).toThrow(ConfigurationError);
-        expect(() => new YNABMCPServer()).toThrow(
-          'YNAB_ACCESS_TOKEN environment variable is required but not set',
-        );
+        expect(() => new YNABMCPServer()).toThrow(/YNAB_ACCESS_TOKEN/i);
       } finally {
         // Restore token
         process.env['YNAB_ACCESS_TOKEN'] = originalToken;

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

@@ -1,166 +1,90 @@
-/**
- * Unit tests for config module
- *
- * Tests environment validation and server configuration.
- */
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
 
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { validateEnvironment } from '../config.js';
-import { ConfigurationError } from '../../types/index.js';
-
-describe('config module', () => {
-  const originalEnv = process.env;
+const originalEnv = { ...process.env };
 
+describe('Config Module', () => {
   beforeEach(() => {
-    // Reset modules and environment
     vi.resetModules();
     process.env = { ...originalEnv };
+    if (!process.env.YNAB_ACCESS_TOKEN) {
+      process.env.YNAB_ACCESS_TOKEN = 'test-token-placeholder';
+    }
   });
 
   afterEach(() => {
-    // Restore original environment
-    process.env = originalEnv;
+    process.env = { ...originalEnv };
   });
 
-  describe('validateEnvironment', () => {
-    it('should return valid configuration when YNAB_ACCESS_TOKEN is set', () => {
-      const testToken = 'test-token-12345';
-      process.env.YNAB_ACCESS_TOKEN = testToken;
-
-      const result = validateEnvironment();
-
-      expect(result).toEqual({
-        accessToken: testToken,
-        defaultBudgetId: undefined,
-      });
-    });
-
-    it('should trim whitespace from access token', () => {
-      const testToken = '  test-token-with-spaces  ';
-      const expectedToken = 'test-token-with-spaces';
-      process.env.YNAB_ACCESS_TOKEN = testToken;
-
-      const result = validateEnvironment();
-
-      expect(result).toEqual({
-        accessToken: expectedToken,
-        defaultBudgetId: undefined,
-      });
-    });
-
-    it('should throw ConfigurationError when YNAB_ACCESS_TOKEN is not set', () => {
-      delete process.env.YNAB_ACCESS_TOKEN;
-
-      expect(() => validateEnvironment()).toThrow(ConfigurationError);
-      expect(() => validateEnvironment()).toThrow(
-        'YNAB_ACCESS_TOKEN environment variable is required but not set',
-      );
-    });
-
-    it('should throw ConfigurationError when YNAB_ACCESS_TOKEN is undefined', () => {
-      delete process.env.YNAB_ACCESS_TOKEN;
-
-      expect(() => validateEnvironment()).toThrow(ConfigurationError);
-      expect(() => validateEnvironment()).toThrow(
-        'YNAB_ACCESS_TOKEN environment variable is required but not set',
-      );
-    });
-
-    it('should throw ConfigurationError when YNAB_ACCESS_TOKEN is empty string', () => {
-      process.env.YNAB_ACCESS_TOKEN = '';
-
-      expect(() => validateEnvironment()).toThrow(ConfigurationError);
-      expect(() => validateEnvironment()).toThrow('YNAB_ACCESS_TOKEN must be a non-empty string');
-    });
-
-    it('should throw ConfigurationError when YNAB_ACCESS_TOKEN is only whitespace', () => {
-      process.env.YNAB_ACCESS_TOKEN = '   ';
-
-      expect(() => validateEnvironment()).toThrow(ConfigurationError);
-      expect(() => validateEnvironment()).toThrow('YNAB_ACCESS_TOKEN must be a non-empty string');
-    });
-
-    it('should throw ConfigurationError when YNAB_ACCESS_TOKEN is not a string', () => {
-      // TypeScript normally prevents this, but test runtime validation
-      (process.env as any).YNAB_ACCESS_TOKEN = 123;
-
-      expect(() => validateEnvironment()).toThrow(ConfigurationError);
-      expect(() => validateEnvironment()).toThrow('YNAB_ACCESS_TOKEN must be a non-empty string');
-    });
-
-    it('should handle various valid token formats', () => {
-      const validTokens = [
-        'abc123',
-        'token-with-dashes',
-        'token_with_underscores',
-        'MixedCaseToken',
-        '1234567890',
-        'very-long-token-with-many-characters-abcdefghijklmnopqrstuvwxyz',
-      ];
-
-      validTokens.forEach((token) => {
-        process.env.YNAB_ACCESS_TOKEN = token;
-        const result = validateEnvironment();
-        expect(result.accessToken).toBe(token);
-        expect(result.defaultBudgetId).toBeUndefined();
-      });
-    });
-
-    it('should handle edge cases with leading and trailing whitespace', () => {
-      const testCases = [
-        { input: '\ntest-token\n', expected: 'test-token' },
-        { input: '\ttest-token\t', expected: 'test-token' },
-        { input: ' \t\ntest-token \t\n', expected: 'test-token' },
-      ];
-
-      testCases.forEach(({ input, expected }) => {
-        process.env.YNAB_ACCESS_TOKEN = input;
-        const result = validateEnvironment();
-        expect(result.accessToken).toBe(expected);
-        expect(result.defaultBudgetId).toBeUndefined();
-      });
-    });
+  it('reloads environment variables on each loadConfig call', async () => {
+    const { loadConfig } = await import('../config');
+    process.env.YNAB_ACCESS_TOKEN = 'test-token-123';
+    expect(loadConfig().YNAB_ACCESS_TOKEN).toBe('test-token-123');
+
+    process.env.YNAB_ACCESS_TOKEN = 'updated-token-456';
+    expect(loadConfig().YNAB_ACCESS_TOKEN).toBe('updated-token-456');
   });
 
-  describe('error handling', () => {
-    it('should throw proper ConfigurationError instances', () => {
-      delete process.env.YNAB_ACCESS_TOKEN;
-
-      try {
-        validateEnvironment();
-        throw new Error('Should have thrown an error');
-      } catch (error) {
-        expect(error).toBeInstanceOf(ConfigurationError);
-        expect(error).toBeInstanceOf(Error);
-        expect((error as ConfigurationError).name).toBe('ConfigurationError');
-      }
-    });
-
-    it('should provide helpful error messages', () => {
-      const testCases = [
-        {
-          setup: () => delete process.env.YNAB_ACCESS_TOKEN,
-          expectedMessage: 'YNAB_ACCESS_TOKEN environment variable is required but not set',
-        },
-        {
-          setup: () => (process.env.YNAB_ACCESS_TOKEN = ''),
-          expectedMessage: 'YNAB_ACCESS_TOKEN must be a non-empty string',
-        },
-        {
-          setup: () => (process.env.YNAB_ACCESS_TOKEN = '   '),
-          expectedMessage: 'YNAB_ACCESS_TOKEN must be a non-empty string',
-        },
-      ];
-
-      testCases.forEach(({ setup, expectedMessage }) => {
-        setup();
-        try {
-          validateEnvironment();
-          expect.fail('Should have thrown an error');
-        } catch (error) {
-          expect((error as Error).message).toBe(expectedMessage);
-        }
-      });
-    });
+  it('keeps the config singleton as a one-time parse', async () => {
+    process.env.YNAB_ACCESS_TOKEN = 'initial-token';
+    const { config, loadConfig } = await import('../config');
+    expect(config.YNAB_ACCESS_TOKEN).toBe('initial-token');
+
+    process.env.YNAB_ACCESS_TOKEN = 'later-token';
+    expect(config.YNAB_ACCESS_TOKEN).toBe('initial-token');
+    expect(loadConfig().YNAB_ACCESS_TOKEN).toBe('later-token');
+  });
+
+  it('throws a detailed error if YNAB_ACCESS_TOKEN is missing', async () => {
+    const { loadConfig } = await import('../config');
+    const env = { ...process.env };
+    delete env.YNAB_ACCESS_TOKEN;
+
+    expect.assertions(2);
+    try {
+      loadConfig(env);
+    } catch (error) {
+      expect((error as { name?: string }).name).toBe('ValidationError');
+      expect((error as Error).message).toMatch(/YNAB_ACCESS_TOKEN/i);
+    }
+  });
+
+  it('parses optional MCP_PORT correctly', async () => {
+    const { loadConfig } = await import('../config');
+    const env = { ...process.env, YNAB_ACCESS_TOKEN: 'token', MCP_PORT: '8080' };
+
+    const parsed = loadConfig(env);
+    expect(parsed.MCP_PORT).toBe(8080);
+  });
+
+  it('handles missing optional MCP_PORT', async () => {
+    const { loadConfig } = await import('../config');
+    const env = { ...process.env, YNAB_ACCESS_TOKEN: 'token' };
+    delete env.MCP_PORT;
+
+    const parsed = loadConfig(env);
+    expect(parsed.MCP_PORT).toBeUndefined();
+  });
+
+  it('throws an error for an invalid MCP_PORT', async () => {
+    const { loadConfig } = await import('../config');
+    const env = { ...process.env, YNAB_ACCESS_TOKEN: 'token', MCP_PORT: 'invalid-port' };
+
+    expect.assertions(2);
+    try {
+      loadConfig(env);
+    } catch (error) {
+      expect((error as { name?: string }).name).toBe('ValidationError');
+      expect((error as Error).message).toMatch(/MCP_PORT/i);
+    }
+  });
+
+  it('parses LOG_LEVEL and defaults to info', async () => {
+    const { loadConfig } = await import('../config');
+    const envWithLog = { ...process.env, YNAB_ACCESS_TOKEN: 'token', LOG_LEVEL: 'debug' };
+    expect(loadConfig(envWithLog).LOG_LEVEL).toBe('debug');
+
+    const envWithoutLog = { ...envWithLog };
+    delete envWithoutLog.LOG_LEVEL; // Ensure LOG_LEVEL is not set
+    expect(loadConfig(envWithoutLog).LOG_LEVEL).toBe('info');
   });
 });

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

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { YNABMCPServer } from '../YNABMCPServer';
-import { AuthenticationError, ConfigurationError } from '../../types/index';
+import { ValidationError } 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
@@ -55,10 +55,7 @@ describeIntegration('Server Startup and Transport Integration', () => {
         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',
-        );
+        expect(() => new YNABMCPServer(false)).toThrow(/YNAB_ACCESS_TOKEN/i);
 
         // Restore token
         process.env['YNAB_ACCESS_TOKEN'] = originalToken;
@@ -72,7 +69,6 @@ describeIntegration('Server Startup and Transport Integration', () => {
         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',
         );
@@ -111,7 +107,10 @@ describeIntegration('Server Startup and Transport Integration', () => {
 
           try {
             const invalidServer = new YNABMCPServer(false);
-            await expect(invalidServer.validateToken()).rejects.toThrow(AuthenticationError);
+            await expect(invalidServer.validateToken()).rejects.toHaveProperty(
+              'name',
+              'AuthenticationError',
+            );
           } finally {
             process.env['YNAB_ACCESS_TOKEN'] = originalToken;
           }
@@ -129,13 +128,16 @@ describeIntegration('Server Startup and Transport Integration', () => {
 
           try {
             const invalidServer = new YNABMCPServer(false);
-            await expect(invalidServer.validateToken()).rejects.toThrow(AuthenticationError);
+            await expect(invalidServer.validateToken()).rejects.toHaveProperty(
+              'name',
+              'AuthenticationError',
+            );
 
             // Verify the error message contains relevant information
             try {
               await invalidServer.validateToken();
             } catch (error) {
-              expect(error).toBeInstanceOf(AuthenticationError);
+              expect((error as { name?: string }).name).toBe('AuthenticationError');
               expect(error.message).toContain('Token validation failed');
             }
           } finally {
@@ -144,6 +146,29 @@ describeIntegration('Server Startup and Transport Integration', () => {
         }, 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', () => {
@@ -262,7 +287,7 @@ describeIntegration('Server Startup and Transport Integration', () => {
           } 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);
+            expect(error).not.toBeInstanceOf(ValidationError);
           }
 
           consoleSpy.mockRestore();
@@ -325,7 +350,7 @@ describeIntegration('Server Startup and Transport Integration', () => {
 
         expect(() => new YNABMCPServer(false)).toThrow(
           expect.objectContaining({
-            message: 'YNAB_ACCESS_TOKEN environment variable is required but not set',
+            message: expect.stringMatching(/YNAB_ACCESS_TOKEN/i),
           }),
         );
 
@@ -343,7 +368,10 @@ describeIntegration('Server Startup and Transport Integration', () => {
 
           try {
             const server = new YNABMCPServer(false);
-            await expect(server.validateToken()).rejects.toThrow(AuthenticationError);
+            await expect(server.validateToken()).rejects.toHaveProperty(
+              'name',
+              'AuthenticationError',
+            );
           } finally {
             process.env['YNAB_ACCESS_TOKEN'] = originalToken;
           }
@@ -448,7 +476,7 @@ describeIntegration('Server Startup and Transport Integration', () => {
         delete process.env['YNAB_ACCESS_TOKEN'];
 
         // Should fail immediately on construction, not during run()
-        expect(() => new YNABMCPServer(false)).toThrow(ConfigurationError);
+        expect(() => new YNABMCPServer(false)).toThrow(/YNAB_ACCESS_TOKEN/i);
 
         process.env['YNAB_ACCESS_TOKEN'] = originalToken;
       },
@@ -466,7 +494,7 @@ describeIntegration('Server Startup and Transport Integration', () => {
             const server = new YNABMCPServer(false);
 
             // Should fail on token validation, before transport setup
-            await expect(server.run()).rejects.toThrow(AuthenticationError);
+            await expect(server.run()).rejects.toHaveProperty('name', 'AuthenticationError');
           } finally {
             process.env['YNAB_ACCESS_TOKEN'] = originalToken;
           }

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

@@ -169,9 +169,9 @@ describe('ToolRegistry', () => {
     expect(tools[0]?.name).toBe('sample_tool');
     const schema = tools[0]?.inputSchema as Record<string, unknown> | undefined;
     expect(schema).toBeDefined();
+    // Input schemas use io:'input' mode which doesn't set additionalProperties
     expect(schema).toMatchObject({
       type: 'object',
-      additionalProperties: false,
       properties: expect.objectContaining({
         id: expect.objectContaining({ type: 'string' }),
         minify: expect.objectContaining({ type: 'boolean' }),

package/src/server/cacheKeys.ts

@@ -0,0 +1,8 @@
+export const CacheKeys = {
+  ACCOUNTS: 'accounts',
+  BUDGETS: 'budgets',
+  CATEGORIES: 'categories',
+  PAYEES: 'payees',
+  TRANSACTIONS: 'transactions',
+  MONTHS: 'months',
+} as const;

package/src/server/config.ts

@@ -1,41 +1,23 @@
-/**
- * Configuration module for YNAB MCP Server
- *
- * Handles environment validation and server configuration.
- * Extracted from YNABMCPServer to provide focused, testable configuration management.
- */
-
-import { ServerConfig, ConfigurationError } from '../types/index.js';
-
-/**
- * Create a ServerConfig from environment variables after validating required values.
- *
- * @returns The validated ServerConfig.
- * @throws ConfigurationError if `YNAB_ACCESS_TOKEN` is missing or not a non-empty string.
- */
-export function validateEnvironment(): ServerConfig {
-  const accessToken = process.env['YNAB_ACCESS_TOKEN'];
-  const defaultBudgetId = process.env['YNAB_DEFAULT_BUDGET_ID'];
-
-  if (accessToken === undefined) {
-    throw new ConfigurationError('YNAB_ACCESS_TOKEN environment variable is required but not set');
-  }
-
-  if (typeof accessToken !== 'string' || accessToken.trim().length === 0) {
-    throw new ConfigurationError('YNAB_ACCESS_TOKEN must be a non-empty string');
+import 'dotenv/config';
+import { z } from 'zod';
+import { fromZodError } from 'zod-validation-error';
+import { ValidationError } from '../utils/errors.js';
+
+const envSchema = z.object({
+  YNAB_ACCESS_TOKEN: z.string().trim().min(1, 'YNAB_ACCESS_TOKEN must be a non-empty string'),
+  MCP_PORT: z.coerce.number().int().positive().optional(),
+  LOG_LEVEL: z.enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal']).default('info'),
+});
+
+export type AppConfig = z.infer<typeof envSchema>;
+
+export function loadConfig(env: NodeJS.ProcessEnv = process.env): AppConfig {
+  const result = envSchema.safeParse(env);
+  if (!result.success) {
+    const validationError = fromZodError(result.error);
+    throw new ValidationError(validationError.toString());
   }
-
-  const trimmedDefaultBudgetId = defaultBudgetId?.trim();
-
-  const config: ServerConfig = {
-    accessToken: accessToken.trim(),
-  };
-
-  if (trimmedDefaultBudgetId && trimmedDefaultBudgetId.length > 0) {
-    config.defaultBudgetId = trimmedDefaultBudgetId;
-  }
-
-  return config;
+  return result.data;
 }
 
-export type { ServerConfig } from '../types/index.js';
+export const config = loadConfig();

package/src/server/securityMiddleware.ts

@@ -4,6 +4,7 @@
 
 import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod/v4';
+import { fromZodError } from 'zod-validation-error';
 import { globalRateLimiter, RateLimitError } from './rateLimiter.js';
 import { globalRequestLogger } from './requestLogger.js';
 import { ErrorHandler } from './errorHandler.js';
@@ -112,13 +113,8 @@ export class SecurityMiddleware {
       return schema.parse(parameters);
     } catch (error) {
       if (error instanceof z.ZodError) {
-        const errorMessage =
-          error.issues && error.issues.length > 0
-            ? error.issues
-                .map((err: z.ZodIssue) => `${err.path.join('.')}: ${err.message}`)
-                .join(', ')
-            : error.message || 'Validation failed';
-        throw new Error(`Validation failed: ${errorMessage}`);
+        const validationError = fromZodError(error);
+        throw new Error(`Validation failed: ${validationError.message}`);
       }
       throw error;
     }

package/src/server/toolRegistry.ts

@@ -1,5 +1,6 @@
 import type { CallToolResult, Tool } from '@modelcontextprotocol/sdk/types.js';
 import { z, toJSONSchema } from 'zod/v4';
+import { fromZodError } from 'zod-validation-error';
 import type { MCPToolAnnotations } from '../types/toolAnnotations.js';
 
 export type SecurityWrapperFactory = <T extends Record<string, unknown>>(
@@ -162,7 +163,10 @@ export class ToolRegistry {
         inputSchema,
       };
       if (tool.outputSchema) {
-        const outputSchema = this.generateJsonSchema(tool.outputSchema) as Tool['outputSchema'];
+        const outputSchema = this.generateJsonSchema(
+          tool.outputSchema,
+          'output',
+        ) as Tool['outputSchema'];
         result.outputSchema = outputSchema;
       }
       if (tool.metadata?.annotations) {
@@ -311,9 +315,10 @@ export class ToolRegistry {
     tool: RegisteredTool<Record<string, unknown>, Record<string, unknown>>,
   ): CallToolResult {
     if (error instanceof z.ZodError) {
+      const validationError = fromZodError(error);
       return this.deps.errorHandler.createValidationError(
         `Invalid parameters for ${tool.name}`,
-        error.message,
+        validationError.message,
       );
     }
 
@@ -388,9 +393,12 @@ export class ToolRegistry {
     }
   }
 
-  private generateJsonSchema(schema: z.ZodTypeAny): Record<string, unknown> {
+  private generateJsonSchema(
+    schema: z.ZodTypeAny,
+    ioMode: 'input' | 'output' = 'input',
+  ): Record<string, unknown> {
     try {
-      return toJSONSchema(schema, { target: 'draft-2020-12', io: 'output' });
+      return toJSONSchema(schema, { target: 'draft-2020-12', io: ioMode });
     } catch (error) {
       console.warn(`Failed to generate JSON schema for tool: ${error}`);
       return { type: 'object', additionalProperties: true };
@@ -467,12 +475,8 @@ export class ToolRegistry {
     // Validate against schema
     const result = validator.safeParse(parsedOutput);
     if (!result.success) {
-      const validationErrors = result.error.issues
-        .map((err) => {
-          const path = err.path.join('.');
-          return path ? `${path}: ${err.message}` : err.message;
-        })
-        .join('; ');
+      const validationError = fromZodError(result.error);
+      const validationErrors = validationError.message;
       return this.deps.errorHandler.createValidationError(
         `Output validation failed for ${toolName}`,
         `Handler output does not match declared output schema: ${validationErrors}`,