@dizzlkheinz/ynab-mcpb 0.18.3 → 0.19.0

package/src/server/YNABMCPServer.ts

@@ -1,802 +1,829 @@
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import fs from 'fs';
-import path from 'path';
-import { z } from 'zod';
+import fs from "node:fs";
+import path from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-  ListResourcesRequestSchema,
-  ListResourceTemplatesRequestSchema,
-  ListPromptsRequestSchema,
-  ReadResourceRequestSchema,
-  GetPromptRequestSchema,
-  CompleteRequestSchema,
-  ErrorCode,
-  McpError,
-} from '@modelcontextprotocol/sdk/types.js';
-import type { Tool } from '@modelcontextprotocol/sdk/types.js';
-import * as ynab from 'ynab';
+	CallToolRequestSchema,
+	CompleteRequestSchema,
+	ErrorCode,
+	GetPromptRequestSchema,
+	ListPromptsRequestSchema,
+	ListResourceTemplatesRequestSchema,
+	ListResourcesRequestSchema,
+	ListToolsRequestSchema,
+	McpError,
+	ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import * as ynab from "ynab";
+import { z } from "zod";
+import { registerAccountTools } from "../tools/accountTools.js";
+import { registerBudgetTools } from "../tools/budgetTools.js";
+import { registerCategoryTools } from "../tools/categoryTools.js";
+import { DeltaFetcher } from "../tools/deltaFetcher.js";
+import { registerMonthTools } from "../tools/monthTools.js";
+import { registerPayeeTools } from "../tools/payeeTools.js";
+import { registerReconciliationTools } from "../tools/reconciliation/index.js";
+import { emptyObjectSchema } from "../tools/schemas/common.js";
+import { ToolAnnotationPresets } from "../tools/toolCategories.js";
+import { registerTransactionTools } from "../tools/transactionTools.js";
+import { registerUtilityTools } from "../tools/utilityTools.js";
+import { ValidationError, YNABErrorCode } from "../types/index.js";
+import type { ToolContext } from "../types/toolRegistration.js";
 import {
-  AuthenticationError,
-  ConfigurationError,
-  ValidationError as ConfigValidationError,
-} from '../utils/errors.js';
-import { YNABErrorCode, ValidationError } from '../types/index.js';
-import type { ToolContext } from '../types/toolRegistration.js';
-import { loadConfig, type AppConfig } from './config.js';
-import { createErrorHandler, ErrorHandler } from './errorHandler.js';
-import { BudgetResolver } from './budgetResolver.js';
-import { SecurityMiddleware, withSecurityWrapper } from './securityMiddleware.js';
-import { registerBudgetTools } from '../tools/budgetTools.js';
-import { registerAccountTools } from '../tools/accountTools.js';
-import { registerTransactionTools } from '../tools/transactionTools.js';
-import { registerReconciliationTools } from '../tools/reconciliation/index.js';
-import { registerCategoryTools } from '../tools/categoryTools.js';
-import { registerPayeeTools } from '../tools/payeeTools.js';
-import { registerMonthTools } from '../tools/monthTools.js';
-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, type ProgressCallback } from './toolRegistry.js';
-import { ResourceManager } from './resources.js';
-import { PromptManager } from './prompts.js';
-import { DiagnosticManager } from './diagnostics.js';
-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';
+	AuthenticationError,
+	ValidationError as ConfigValidationError,
+	ConfigurationError,
+} from "../utils/errors.js";
+import { CacheManager, cacheManager } from "./cacheManager.js";
+import { CompletionsManager } from "./completions.js";
+import { type AppConfig, loadConfig } from "./config.js";
+import { DeltaCache } from "./deltaCache.js";
+import { DiagnosticManager } from "./diagnostics.js";
+import { type ErrorHandler, createErrorHandler } from "./errorHandler.js";
+import { PromptManager } from "./prompts.js";
+import { ResourceManager } from "./resources.js";
+import { responseFormatter } from "./responseFormatter.js";
+import {
+	SecurityMiddleware,
+	withSecurityWrapper,
+} from "./securityMiddleware.js";
+import { ServerKnowledgeStore } from "./serverKnowledgeStore.js";
+import {
+	type ProgressCallback,
+	type ToolDefinition,
+	ToolRegistry,
+} from "./toolRegistry.js";
 
 /**
  * YNAB MCP Server class that provides integration with You Need A Budget API
  */
 export class YNABMCPServer {
-  private server: Server;
-  private ynabAPI: ynab.API;
-  private exitOnError: boolean;
-  private defaultBudgetId: string | undefined;
-  private configInstance: AppConfig;
-  private serverVersion: string;
-  private toolRegistry: ToolRegistry;
-  private resourceManager: ResourceManager;
-  private promptManager: PromptManager;
-  private serverKnowledgeStore: ServerKnowledgeStore;
-  private deltaCache: DeltaCache;
-  private deltaFetcher: DeltaFetcher;
-  private diagnosticManager: DiagnosticManager;
-  private errorHandler: ErrorHandler;
-  private completionsManager: CompletionsManager;
-
-  constructor(exitOnError: boolean = true) {
-    this.exitOnError = exitOnError;
-    this.configInstance = loadConfig();
-    // Config is now imported and validated at startup
-    this.defaultBudgetId = this.configInstance.YNAB_DEFAULT_BUDGET_ID;
-
-    // Initialize YNAB API
-    this.ynabAPI = new ynab.API(this.configInstance.YNAB_ACCESS_TOKEN);
-
-    // Determine server version (prefer package.json)
-    this.serverVersion = this.readPackageVersion() ?? '0.0.0';
-
-    // Initialize MCP Server
-    this.server = new Server(
-      {
-        name: 'ynab-mcp-server',
-        version: this.serverVersion,
-      },
-      {
-        capabilities: {
-          tools: { listChanged: false },
-          resources: {
-            subscribe: false, // YNAB API has no webhooks; subscriptions not applicable
-            listChanged: false,
-          },
-          prompts: { listChanged: false },
-          completions: {},
-        },
-      },
-    );
-
-    // Create ErrorHandler instance with formatter injection
-    this.errorHandler = createErrorHandler(responseFormatter);
-
-    // Set the global default for backward compatibility with static usage
-    ErrorHandler.setFormatter(responseFormatter);
-
-    this.toolRegistry = new ToolRegistry({
-      withSecurityWrapper,
-      errorHandler: this.errorHandler,
-      responseFormatter,
-      cacheHelpers: {
-        generateKey: (...segments: unknown[]) => {
-          const normalized = segments.map((segment) => {
-            if (
-              typeof segment === 'string' ||
-              typeof segment === 'number' ||
-              typeof segment === 'boolean' ||
-              segment === undefined
-            ) {
-              return segment;
-            }
-            return JSON.stringify(segment);
-          }) as (string | number | boolean | undefined)[];
-          return CacheManager.generateKey('tool', ...normalized);
-        },
-        invalidate: (key: string) => {
-          try {
-            cacheManager.delete(key);
-          } catch (error) {
-            console.error(`Failed to invalidate cache key "${key}":`, error);
-          }
-        },
-        clear: () => {
-          try {
-            cacheManager.clear();
-          } catch (error) {
-            console.error('Failed to clear cache:', error);
-          }
-        },
-      },
-      validateAccessToken: (token: string) => {
-        const expected = this.configInstance.YNAB_ACCESS_TOKEN.trim();
-        const provided = typeof token === 'string' ? token.trim() : '';
-        if (!provided) {
-          throw this.errorHandler.createYNABError(
-            YNABErrorCode.UNAUTHORIZED,
-            'validating access token',
-            new Error('Missing access token'),
-          );
-        }
-        if (provided !== expected) {
-          throw this.errorHandler.createYNABError(
-            YNABErrorCode.UNAUTHORIZED,
-            'validating access token',
-            new Error('Access token mismatch'),
-          );
-        }
-      },
-    });
-
-    // Initialize service modules
-    this.resourceManager = new ResourceManager({
-      ynabAPI: this.ynabAPI,
-      responseFormatter,
-      cacheManager,
-    });
-
-    this.promptManager = new PromptManager();
-
-    this.serverKnowledgeStore = new ServerKnowledgeStore();
-    this.deltaCache = new DeltaCache(cacheManager, this.serverKnowledgeStore);
-    this.deltaFetcher = new DeltaFetcher(this.ynabAPI, this.deltaCache);
-
-    this.diagnosticManager = new DiagnosticManager({
-      securityMiddleware: SecurityMiddleware,
-      cacheManager,
-      responseFormatter,
-      serverVersion: this.serverVersion,
-      serverKnowledgeStore: this.serverKnowledgeStore,
-      deltaCache: this.deltaCache,
-    });
-
-    this.completionsManager = new CompletionsManager(
-      this.ynabAPI,
-      cacheManager,
-      () => this.defaultBudgetId,
-    );
-
-    this.setupToolRegistry();
-    this.setupHandlers();
-  }
-
-  /**
-   * Validates the YNAB access token by making a test API call
-   */
-  async validateToken(): Promise<boolean> {
-    try {
-      await this.ynabAPI.user.getUser();
-      return true;
-    } catch (error) {
-      if (this.isMalformedTokenResponse(error)) {
-        throw new AuthenticationError('Unexpected response from YNAB during token validation');
-      }
-
-      if (error instanceof Error) {
-        // Check for authentication-related errors
-        if (error.message.includes('401') || error.message.includes('Unauthorized')) {
-          throw new AuthenticationError('Invalid or expired YNAB access token');
-        }
-        if (error.message.includes('403') || error.message.includes('Forbidden')) {
-          throw new AuthenticationError('YNAB access token has insufficient permissions');
-        }
-
-        const reason = error.message || String(error);
-        throw new AuthenticationError(`Token validation failed: ${reason}`);
-      }
-
-      throw new AuthenticationError(`Token validation failed: ${String(error)}`);
-    }
-  }
-
-  private isMalformedTokenResponse(error: unknown): boolean {
-    if (error instanceof SyntaxError) {
-      return true;
-    }
-
-    const message =
-      typeof error === 'string'
-        ? error
-        : typeof (error as { message?: unknown })?.message === 'string'
-          ? String((error as { message: unknown }).message)
-          : null;
-
-    if (!message) {
-      return false;
-    }
-
-    const normalized = message.toLowerCase();
-    return (
-      normalized.includes('unexpected token') ||
-      normalized.includes('unexpected end of json') ||
-      normalized.includes('<html')
-    );
-  }
-
-  /**
-   * Sets up MCP server request handlers
-   */
-  private setupHandlers(): void {
-    // Handle list resources requests
-    this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
-      return this.resourceManager.listResources();
-    });
-
-    // Handle list resource templates requests
-    this.server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
-      return this.resourceManager.listResourceTemplates();
-    });
-
-    // Handle read resource requests
-    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-      const { uri } = request.params;
-      return await this.resourceManager.readResource(uri);
-    });
-
-    // Handle list prompts requests
-    this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
-      return this.promptManager.listPrompts();
-    });
-
-    // Handle get prompt requests
-    this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-      const { name, arguments: args } = request.params;
-      const result = await this.promptManager.getPrompt(name, args);
-      // The SDK expects the result to match the protocol's PromptResponse shape
-      return result as unknown as { description?: string; messages: unknown[] };
-    });
-
-    // Handle list tools requests
-    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
-      return {
-        tools: this.toolRegistry.listTools(),
-      };
-    });
-
-    // Handle tool call requests
-    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;
-      const minifyOverride = this.extractMinifyOverride(rawArgs);
-
-      const sanitizedArgs = rawArgs
-        ? (() => {
-            const clone: Record<string, unknown> = { ...rawArgs };
-            delete clone['minify'];
-            delete clone['_minify'];
-            delete clone['__minify'];
-            return clone;
-          })()
-        : undefined;
-
-      const executionOptions: {
-        name: string;
-        accessToken: string;
-        arguments: Record<string, unknown>;
-        minifyOverride?: boolean;
-        sendProgress?: ProgressCallback;
-      } = {
-        name: request.params.name,
-        accessToken: this.configInstance.YNAB_ACCESS_TOKEN,
-        arguments: sanitizedArgs ?? {},
-      };
-
-      if (minifyOverride !== undefined) {
-        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,
-      };
-    });
-  }
-
-  /**
-   * Registers all tools with the registry to centralize handler execution
-   */
-  private setupToolRegistry(): void {
-    const register = <TInput extends Record<string, unknown>>(
-      definition: ToolDefinition<TInput>,
-    ): void => {
-      this.toolRegistry.register(definition);
-    };
-
-    const toolContext: ToolContext = {
-      ynabAPI: this.ynabAPI,
-      deltaFetcher: this.deltaFetcher,
-      deltaCache: this.deltaCache,
-      serverKnowledgeStore: this.serverKnowledgeStore,
-      getDefaultBudgetId: () => this.defaultBudgetId,
-      setDefaultBudget: (budgetId: string) => this.setDefaultBudget(budgetId),
-      cacheManager,
-      diagnosticManager: this.diagnosticManager,
-    };
-
-    const setDefaultBudgetSchema = z.object({ budget_id: z.string().min(1) }).strict();
-    const diagnosticInfoSchema = z
-      .object({
-        include_memory: z.boolean().default(true),
-        include_environment: z.boolean().default(true),
-        include_server: z.boolean().default(true),
-        include_security: z.boolean().default(true),
-        include_cache: z.boolean().default(true),
-        include_delta: z.boolean().default(true),
-      })
-      .strict();
-    const setOutputFormatSchema = z
-      .object({
-        default_minify: z.boolean().optional(),
-        pretty_spaces: z.number().int().min(0).max(10).optional(),
-      })
-      .strict();
-    registerBudgetTools(this.toolRegistry, toolContext);
-    registerPayeeTools(this.toolRegistry, toolContext);
-    registerCategoryTools(this.toolRegistry, toolContext);
-    registerAccountTools(this.toolRegistry, toolContext);
-    registerMonthTools(this.toolRegistry, toolContext);
-    registerTransactionTools(this.toolRegistry, toolContext);
-    registerReconciliationTools(this.toolRegistry, toolContext);
-    registerUtilityTools(this.toolRegistry, toolContext);
-
-    // Server-owned inline tools stay here because they depend on instance state (default budget,
-    // diagnostics manager, cache manager, response formatter) rather than the factory context.
-    register({
-      name: 'set_default_budget',
-      description: 'Set the default budget for subsequent operations',
-      inputSchema: setDefaultBudgetSchema,
-      handler: async ({ input }) => {
-        const { budget_id } = input;
-        await this.ynabAPI.budgets.getBudgetById(budget_id);
-        this.setDefaultBudget(budget_id);
-
-        // Cache warming for frequently accessed data (fire-and-forget)
-        this.warmCacheForBudget(budget_id).catch(() => {
-          // Silently handle cache warming errors to not affect main operation
-        });
-
-        return {
-          content: [
-            {
-              type: 'text',
-              text: responseFormatter.format({
-                success: true,
-                message: `Default budget set to: ${budget_id}`,
-                default_budget_id: budget_id,
-                cache_warm_started: true,
-              }),
-            },
-          ],
-        };
-      },
-      metadata: {
-        annotations: {
-          ...ToolAnnotationPresets.WRITE_EXTERNAL_UPDATE,
-          title: 'YNAB: Set Default Budget',
-        },
-      },
-    });
-
-    register({
-      name: 'get_default_budget',
-      description: 'Get the currently set default budget',
-      inputSchema: emptyObjectSchema,
-      handler: async () => {
-        try {
-          const defaultBudget = this.getDefaultBudget();
-          return {
-            content: [
-              {
-                type: 'text',
-                text: responseFormatter.format({
-                  default_budget_id: defaultBudget ?? null,
-                  has_default: !!defaultBudget,
-                  message: defaultBudget
-                    ? `Default budget is set to: ${defaultBudget}`
-                    : 'No default budget is currently set',
-                }),
-              },
-            ],
-          };
-        } catch (error) {
-          return this.errorHandler.createValidationError(
-            'Error getting default budget',
-            error instanceof Error ? error.message : 'Unknown error',
-          );
-        }
-      },
-      metadata: {
-        annotations: {
-          // Intentionally categorized as UTILITY_LOCAL (not READ_ONLY_EXTERNAL) because
-          // this tool only reads local server state without making any YNAB API calls.
-          // Compare with set_default_budget which calls ynabAPI.budgets.getBudgetById().
-          ...ToolAnnotationPresets.UTILITY_LOCAL,
-          title: 'YNAB: Get Default Budget',
-        },
-      },
-    });
-
-    register({
-      name: 'diagnostic_info',
-      description: 'Get comprehensive diagnostic information about the MCP server',
-      inputSchema: diagnosticInfoSchema,
-      handler: async ({ input }) => {
-        return this.diagnosticManager.collectDiagnostics(input);
-      },
-      metadata: {
-        annotations: {
-          ...ToolAnnotationPresets.UTILITY_LOCAL,
-          title: 'YNAB: Diagnostic Information',
-        },
-      },
-    });
-
-    register({
-      name: 'clear_cache',
-      description: 'Clear the in-memory cache (safe, no YNAB data is modified)',
-      inputSchema: emptyObjectSchema,
-      handler: async () => {
-        cacheManager.clear();
-        return {
-          content: [{ type: 'text', text: responseFormatter.format({ success: true }) }],
-        };
-      },
-      metadata: {
-        annotations: {
-          ...ToolAnnotationPresets.UTILITY_LOCAL,
-          title: 'YNAB: Clear Cache',
-        },
-      },
-    });
-
-    register({
-      name: 'set_output_format',
-      description: 'Configure default JSON output formatting (minify or pretty spaces)',
-      inputSchema: setOutputFormatSchema,
-      handler: async ({ input }) => {
-        const options: { defaultMinify?: boolean; prettySpaces?: number } = {};
-        if (typeof input.default_minify === 'boolean') {
-          options.defaultMinify = input.default_minify;
-        }
-        if (typeof input.pretty_spaces === 'number') {
-          options.prettySpaces = Math.max(0, Math.min(10, Math.floor(input.pretty_spaces)));
-        }
-        responseFormatter.configure(options);
-
-        // Build human-readable message describing the new configuration
-        const parts: string[] = [];
-        if (options.defaultMinify !== undefined) {
-          parts.push(`minify=${options.defaultMinify}`);
-        }
-        if (options.prettySpaces !== undefined) {
-          parts.push(`spaces=${options.prettySpaces}`);
-        }
-        const message =
-          parts.length > 0
-            ? `Output format configured: ${parts.join(', ')}`
-            : 'Output format configured';
-
-        return {
-          content: [
-            {
-              type: 'text',
-              text: responseFormatter.format({ success: true, message, options }),
-            },
-          ],
-        };
-      },
-      metadata: {
-        annotations: {
-          ...ToolAnnotationPresets.UTILITY_LOCAL,
-          title: 'YNAB: Set Output Format',
-        },
-      },
-    });
-  }
-
-  private extractMinifyOverride(args: Record<string, unknown> | undefined): boolean | undefined {
-    if (!args) {
-      return undefined;
-    }
-
-    for (const key of ['minify', '_minify', '__minify'] as const) {
-      const value = args[key];
-      if (typeof value === 'boolean') {
-        return value;
-      }
-    }
-
-    return undefined;
-  }
-
-  /**
-   * Starts the MCP server with stdio transport
-   */
-  async run(): Promise<void> {
-    try {
-      // Validate token before starting server
-      await this.validateToken();
-
-      const transport = new StdioServerTransport();
-      await this.server.connect(transport);
-
-      console.error('YNAB MCP Server started successfully');
-    } catch (error) {
-      if (
-        error instanceof AuthenticationError ||
-        error instanceof ConfigurationError ||
-        error instanceof ConfigValidationError ||
-        error instanceof ValidationError ||
-        (error as { name?: string })?.name === 'ValidationError'
-      ) {
-        console.error(`Server startup failed: ${error instanceof Error ? error.message : error}`);
-        if (this.exitOnError) {
-          process.exit(1);
-        } else {
-          throw error;
-        }
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * Gets the YNAB API instance (for testing purposes)
-   */
-  getYNABAPI(): ynab.API {
-    return this.ynabAPI;
-  }
-
-  /**
-   * Gets the MCP server instance (for testing purposes)
-   */
-  getServer(): Server {
-    return this.server;
-  }
-
-  /**
-   * Sets the default budget ID for operations
-   */
-  setDefaultBudget(budgetId: string): void {
-    this.defaultBudgetId = budgetId;
-  }
-
-  /**
-   * Gets the default budget ID
-   */
-  getDefaultBudget(): string | undefined {
-    return this.defaultBudgetId;
-  }
-
-  /**
-   * Clears the default budget ID (primarily for testing purposes)
-   */
-  clearDefaultBudget(): void {
-    this.defaultBudgetId = undefined;
-  }
-
-  /**
-   * Gets the tool registry instance (for testing purposes)
-   */
-  getToolRegistry(): ToolRegistry {
-    return this.toolRegistry;
-  }
-
-  /**
-   * Gets the budget ID to use - either provided or default
-   *
-   * @deprecated This method is deprecated and should not be used.
-   * Use BudgetResolver.resolveBudgetId() directly instead, which returns
-   * a CallToolResult for errors rather than throwing exceptions.
-   *
-   * @returns The resolved budget ID string or throws ValidationError
-   */
-  getBudgetId(providedBudgetId?: string): string {
-    const result = BudgetResolver.resolveBudgetId(providedBudgetId, this.defaultBudgetId);
-    if (typeof result === 'string') {
-      return result;
-    }
-
-    // Convert CallToolResult to ValidationError for consistency with ErrorHandler
-    const errorText =
-      result.content?.[0]?.type === 'text' ? result.content[0].text : 'Budget resolution failed';
-    const parsedError = (() => {
-      try {
-        return JSON.parse(errorText);
-      } catch {
-        return { error: { message: errorText } };
-      }
-    })();
-
-    const message = parsedError.error?.message || 'Budget resolution failed';
-    throw new ValidationError(message);
-  }
-
-  /**
-   * Warm cache for frequently accessed data after setting default budget
-   * Uses fire-and-forget pattern to avoid blocking the main operation
-   * Runs cache warming operations in parallel for faster completion
-   */
-  private async warmCacheForBudget(budgetId: string): Promise<void> {
-    try {
-      // Run all cache warming operations in parallel
-      await Promise.all([
-        this.deltaFetcher.fetchAccounts(budgetId, { forceFullRefresh: true }),
-        this.deltaFetcher.fetchCategories(budgetId, { forceFullRefresh: true }),
-        this.deltaFetcher.fetchPayees(budgetId, { forceFullRefresh: true }),
-      ]);
-    } catch {
-      // Cache warming failures should not affect the main operation
-      // Errors are handled by the caller with a catch block
-    }
-  }
-
-  /**
-   * Public handler methods for testing and external access
-   */
-
-  /**
-   * Handle list tools request - public method for testing
-   */
-  public async handleListTools() {
-    return {
-      tools: this.toolRegistry.listTools(),
-    };
-  }
-
-  /**
-   * Handle list resources request - public method for testing
-   */
-  public async handleListResources() {
-    return this.resourceManager.listResources();
-  }
-
-  /**
-   * Handle read resource request - public method for testing
-   */
-  public async handleReadResource(params: { uri: string }) {
-    const { uri } = params;
-    try {
-      return await this.resourceManager.readResource(uri);
-    } catch (error) {
-      return this.errorHandler.handleError(error, `reading resource: ${uri}`);
-    }
-  }
-
-  /**
-   * Handle list prompts request - public method for testing
-   */
-  public async handleListPrompts() {
-    return this.promptManager.listPrompts();
-  }
-
-  /**
-   * Handle get prompt request - public method for testing
-   */
-  public async handleGetPrompt(params: { name: string; arguments?: Record<string, unknown> }) {
-    const { name, arguments: args } = params;
-    try {
-      const prompt = await this.promptManager.getPrompt(name, args);
-      const tools = Array.isArray((prompt as { tools?: unknown[] }).tools)
-        ? ((prompt as { tools?: unknown[] }).tools as Tool[])
-        : undefined;
-      return tools ? { ...prompt, tools } : prompt;
-    } catch (error) {
-      return this.errorHandler.handleError(error, `getting prompt: ${name}`);
-    }
-  }
-
-  /**
-   * Try to read the package version for accurate server metadata
-   */
-  private readPackageVersion(): string | null {
-    const candidates = [path.resolve(process.cwd(), 'package.json')];
-    try {
-      // May fail in bundled CJS builds; guard accordingly
-      const metaUrl = (import.meta as unknown as { url?: string })?.url;
-      if (metaUrl) {
-        const maybe = path.resolve(path.dirname(new URL(metaUrl).pathname), '../../package.json');
-        candidates.push(maybe);
-      }
-    } catch {
-      // ignore
-    }
-    try {
-      // CJS bundles can rely on __dirname being defined; add nearby package.json fallbacks
-      const dir = typeof __dirname === 'string' ? __dirname : undefined;
-      if (dir) {
-        candidates.push(
-          path.resolve(dir, '../../package.json'),
-          path.resolve(dir, '../package.json'),
-          path.resolve(dir, 'package.json'),
-        );
-      }
-    } catch {
-      // ignore additional fallbacks
-    }
-    for (const p of candidates) {
-      try {
-        if (fs.existsSync(p)) {
-          const raw = fs.readFileSync(p, 'utf8');
-          const pkg = JSON.parse(raw) as { version?: string };
-          if (pkg.version && typeof pkg.version === 'string') return pkg.version;
-        }
-      } catch {
-        // ignore and try next
-      }
-    }
-    return null;
-  }
+	private server: Server;
+	private ynabAPI: ynab.API;
+	private exitOnError: boolean;
+	private defaultBudgetId: string | undefined;
+	private configInstance: AppConfig;
+	private serverVersion: string;
+	private toolRegistry: ToolRegistry;
+	private resourceManager: ResourceManager;
+	private promptManager: PromptManager;
+	private serverKnowledgeStore: ServerKnowledgeStore;
+	private deltaCache: DeltaCache;
+	private deltaFetcher: DeltaFetcher;
+	private diagnosticManager: DiagnosticManager;
+	private errorHandler: ErrorHandler;
+	private completionsManager: CompletionsManager;
+
+	constructor(exitOnError = true) {
+		this.exitOnError = exitOnError;
+		this.configInstance = loadConfig();
+		// Config is now imported and validated at startup
+		this.defaultBudgetId = this.configInstance.YNAB_DEFAULT_BUDGET_ID;
+
+		// Initialize YNAB API
+		this.ynabAPI = new ynab.API(this.configInstance.YNAB_ACCESS_TOKEN);
+
+		// Determine server version (prefer package.json)
+		this.serverVersion = this.readPackageVersion() ?? "0.0.0";
+
+		// Initialize MCP Server
+		this.server = new Server(
+			{
+				name: "ynab-mcp-server",
+				version: this.serverVersion,
+			},
+			{
+				capabilities: {
+					tools: { listChanged: false },
+					resources: {
+						subscribe: false, // YNAB API has no webhooks; subscriptions not applicable
+						listChanged: false,
+					},
+					prompts: { listChanged: false },
+					completions: {},
+				},
+			},
+		);
+
+		// Create ErrorHandler instance with formatter injection
+		this.errorHandler = createErrorHandler(responseFormatter);
+
+		this.toolRegistry = new ToolRegistry({
+			withSecurityWrapper,
+			errorHandler: this.errorHandler,
+			responseFormatter,
+			cacheHelpers: {
+				generateKey: (...segments: unknown[]) => {
+					const normalized = segments.map((segment) => {
+						if (
+							typeof segment === "string" ||
+							typeof segment === "number" ||
+							typeof segment === "boolean" ||
+							segment === undefined
+						) {
+							return segment;
+						}
+						return JSON.stringify(segment);
+					}) as (string | number | boolean | undefined)[];
+					return CacheManager.generateKey("tool", ...normalized);
+				},
+				invalidate: (key: string) => {
+					try {
+						cacheManager.delete(key);
+					} catch (error) {
+						console.error(`Failed to invalidate cache key "${key}":`, error);
+					}
+				},
+				clear: () => {
+					try {
+						cacheManager.clear();
+					} catch (error) {
+						console.error("Failed to clear cache:", error);
+					}
+				},
+			},
+			validateAccessToken: (token: string) => {
+				const expected = this.configInstance.YNAB_ACCESS_TOKEN.trim();
+				const provided = typeof token === "string" ? token.trim() : "";
+				if (!provided) {
+					throw this.errorHandler.createYNABError(
+						YNABErrorCode.UNAUTHORIZED,
+						"validating access token",
+						new Error("Missing access token"),
+					);
+				}
+				if (provided !== expected) {
+					throw this.errorHandler.createYNABError(
+						YNABErrorCode.UNAUTHORIZED,
+						"validating access token",
+						new Error("Access token mismatch"),
+					);
+				}
+			},
+		});
+
+		// Initialize service modules
+		this.resourceManager = new ResourceManager({
+			ynabAPI: this.ynabAPI,
+			responseFormatter,
+			cacheManager,
+		});
+
+		this.promptManager = new PromptManager();
+
+		this.serverKnowledgeStore = new ServerKnowledgeStore();
+		this.deltaCache = new DeltaCache(cacheManager, this.serverKnowledgeStore);
+		this.deltaFetcher = new DeltaFetcher(this.ynabAPI, this.deltaCache);
+
+		this.diagnosticManager = new DiagnosticManager({
+			securityMiddleware: SecurityMiddleware,
+			cacheManager,
+			responseFormatter,
+			serverVersion: this.serverVersion,
+			serverKnowledgeStore: this.serverKnowledgeStore,
+			deltaCache: this.deltaCache,
+		});
+
+		this.completionsManager = new CompletionsManager(
+			this.ynabAPI,
+			cacheManager,
+			() => this.defaultBudgetId,
+		);
+
+		this.setupToolRegistry();
+		this.setupHandlers();
+	}
+
+	/**
+	 * Validates the YNAB access token by making a test API call
+	 */
+	async validateToken(): Promise<boolean> {
+		try {
+			await this.ynabAPI.user.getUser();
+			return true;
+		} catch (error) {
+			if (this.isMalformedTokenResponse(error)) {
+				throw new AuthenticationError(
+					"Unexpected response from YNAB during token validation",
+				);
+			}
+
+			if (error instanceof Error) {
+				// Check for authentication-related errors
+				if (
+					error.message.includes("401") ||
+					error.message.includes("Unauthorized")
+				) {
+					throw new AuthenticationError("Invalid or expired YNAB access token");
+				}
+				if (
+					error.message.includes("403") ||
+					error.message.includes("Forbidden")
+				) {
+					throw new AuthenticationError(
+						"YNAB access token has insufficient permissions",
+					);
+				}
+
+				const reason = error.message || String(error);
+				throw new AuthenticationError(`Token validation failed: ${reason}`);
+			}
+
+			throw new AuthenticationError(
+				`Token validation failed: ${String(error)}`,
+			);
+		}
+	}
+
+	private isMalformedTokenResponse(error: unknown): boolean {
+		if (error instanceof SyntaxError) {
+			return true;
+		}
+
+		const message =
+			typeof error === "string"
+				? error
+				: typeof (error as { message?: unknown })?.message === "string"
+					? String((error as { message: unknown }).message)
+					: null;
+
+		if (!message) {
+			return false;
+		}
+
+		const normalized = message.toLowerCase();
+		return (
+			normalized.includes("unexpected token") ||
+			normalized.includes("unexpected end of json") ||
+			normalized.includes("<html")
+		);
+	}
+
+	/**
+	 * Sets up MCP server request handlers
+	 */
+	private setupHandlers(): void {
+		// Handle list resources requests
+		this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
+			return this.resourceManager.listResources();
+		});
+
+		// Handle list resource templates requests
+		this.server.setRequestHandler(
+			ListResourceTemplatesRequestSchema,
+			async () => {
+				return this.resourceManager.listResourceTemplates();
+			},
+		);
+
+		// Handle read resource requests
+		this.server.setRequestHandler(
+			ReadResourceRequestSchema,
+			async (request) => {
+				const { uri } = request.params;
+				return await this.resourceManager.readResource(uri);
+			},
+		);
+
+		// Handle list prompts requests
+		this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
+			return this.promptManager.listPrompts();
+		});
+
+		// Handle get prompt requests
+		this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+			const { name, arguments: args } = request.params;
+			const result = await this.promptManager.getPrompt(name, args);
+			// The SDK expects the result to match the protocol's PromptResponse shape
+			return result as unknown as { description?: string; messages: unknown[] };
+		});
+
+		// Handle list tools requests
+		this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+			return {
+				tools: this.toolRegistry.listTools(),
+			};
+		});
+
+		// Handle tool call requests
+		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;
+				const minifyOverride = this.extractMinifyOverride(rawArgs);
+
+				const sanitizedArgs = rawArgs
+					? (() => {
+							const clone: Record<string, unknown> = { ...rawArgs };
+							clone["minify"] = undefined;
+							clone["_minify"] = undefined;
+							clone["__minify"] = undefined;
+							return clone;
+						})()
+					: undefined;
+
+				const executionOptions: {
+					name: string;
+					accessToken: string;
+					arguments: Record<string, unknown>;
+					minifyOverride?: boolean;
+					sendProgress?: ProgressCallback;
+				} = {
+					name: request.params.name,
+					accessToken: this.configInstance.YNAB_ACCESS_TOKEN,
+					arguments: sanitizedArgs ?? {},
+				};
+
+				if (minifyOverride !== undefined) {
+					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,
+			};
+		});
+	}
+
+	/**
+	 * Registers all tools with the registry to centralize handler execution
+	 */
+	private setupToolRegistry(): void {
+		const register = <TInput extends Record<string, unknown>>(
+			definition: ToolDefinition<TInput>,
+		): void => {
+			this.toolRegistry.register(definition);
+		};
+
+		const toolContext: ToolContext = {
+			ynabAPI: this.ynabAPI,
+			deltaFetcher: this.deltaFetcher,
+			deltaCache: this.deltaCache,
+			serverKnowledgeStore: this.serverKnowledgeStore,
+			getDefaultBudgetId: () => this.defaultBudgetId,
+			setDefaultBudget: (budgetId: string) => this.setDefaultBudget(budgetId),
+			cacheManager,
+			errorHandler: this.errorHandler,
+			diagnosticManager: this.diagnosticManager,
+		};
+
+		const setDefaultBudgetSchema = z
+			.object({ budget_id: z.string().min(1) })
+			.strict();
+		const diagnosticInfoSchema = z
+			.object({
+				include_memory: z.boolean().default(true),
+				include_environment: z.boolean().default(true),
+				include_server: z.boolean().default(true),
+				include_security: z.boolean().default(true),
+				include_cache: z.boolean().default(true),
+				include_delta: z.boolean().default(true),
+			})
+			.strict();
+		const setOutputFormatSchema = z
+			.object({
+				default_minify: z.boolean().optional(),
+				pretty_spaces: z.number().int().min(0).max(10).optional(),
+			})
+			.strict();
+		registerBudgetTools(this.toolRegistry, toolContext);
+		registerPayeeTools(this.toolRegistry, toolContext);
+		registerCategoryTools(this.toolRegistry, toolContext);
+		registerAccountTools(this.toolRegistry, toolContext);
+		registerMonthTools(this.toolRegistry, toolContext);
+		registerTransactionTools(this.toolRegistry, toolContext);
+		registerReconciliationTools(this.toolRegistry, toolContext);
+		registerUtilityTools(this.toolRegistry, toolContext);
+
+		// Server-owned inline tools stay here because they depend on instance state (default budget,
+		// diagnostics manager, cache manager, response formatter) rather than the factory context.
+		register({
+			name: "set_default_budget",
+			description: "Set the default budget for subsequent operations",
+			inputSchema: setDefaultBudgetSchema,
+			handler: async ({ input }) => {
+				const { budget_id } = input;
+				await this.ynabAPI.budgets.getBudgetById(budget_id);
+				this.setDefaultBudget(budget_id);
+
+				// Cache warming for frequently accessed data (fire-and-forget)
+				this.warmCacheForBudget(budget_id).catch(() => {
+					// Silently handle cache warming errors to not affect main operation
+				});
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: responseFormatter.format({
+								success: true,
+								message: `Default budget set to: ${budget_id}`,
+								default_budget_id: budget_id,
+								cache_warm_started: true,
+							}),
+						},
+					],
+				};
+			},
+			metadata: {
+				annotations: {
+					...ToolAnnotationPresets.WRITE_EXTERNAL_UPDATE,
+					title: "YNAB: Set Default Budget",
+				},
+			},
+		});
+
+		register({
+			name: "get_default_budget",
+			description: "Get the currently set default budget",
+			inputSchema: emptyObjectSchema,
+			handler: async () => {
+				try {
+					const defaultBudget = this.getDefaultBudget();
+					return {
+						content: [
+							{
+								type: "text",
+								text: responseFormatter.format({
+									default_budget_id: defaultBudget ?? null,
+									has_default: !!defaultBudget,
+									message: defaultBudget
+										? `Default budget is set to: ${defaultBudget}`
+										: "No default budget is currently set",
+								}),
+							},
+						],
+					};
+				} catch (error) {
+					return this.errorHandler.createValidationError(
+						"Error getting default budget",
+						error instanceof Error ? error.message : "Unknown error",
+					);
+				}
+			},
+			metadata: {
+				annotations: {
+					// Intentionally categorized as UTILITY_LOCAL (not READ_ONLY_EXTERNAL) because
+					// this tool only reads local server state without making any YNAB API calls.
+					// Compare with set_default_budget which calls ynabAPI.budgets.getBudgetById().
+					...ToolAnnotationPresets.UTILITY_LOCAL,
+					title: "YNAB: Get Default Budget",
+				},
+			},
+		});
+
+		register({
+			name: "diagnostic_info",
+			description:
+				"Get comprehensive diagnostic information about the MCP server",
+			inputSchema: diagnosticInfoSchema,
+			handler: async ({ input }) => {
+				return this.diagnosticManager.collectDiagnostics(input);
+			},
+			metadata: {
+				annotations: {
+					...ToolAnnotationPresets.UTILITY_LOCAL,
+					title: "YNAB: Diagnostic Information",
+				},
+			},
+		});
+
+		register({
+			name: "clear_cache",
+			description: "Clear the in-memory cache (safe, no YNAB data is modified)",
+			inputSchema: emptyObjectSchema,
+			handler: async () => {
+				cacheManager.clear();
+				return {
+					content: [
+						{ type: "text", text: responseFormatter.format({ success: true }) },
+					],
+				};
+			},
+			metadata: {
+				annotations: {
+					...ToolAnnotationPresets.UTILITY_LOCAL,
+					title: "YNAB: Clear Cache",
+				},
+			},
+		});
+
+		register({
+			name: "set_output_format",
+			description:
+				"Configure default JSON output formatting (minify or pretty spaces)",
+			inputSchema: setOutputFormatSchema,
+			handler: async ({ input }) => {
+				const options: { defaultMinify?: boolean; prettySpaces?: number } = {};
+				if (typeof input.default_minify === "boolean") {
+					options.defaultMinify = input.default_minify;
+				}
+				if (typeof input.pretty_spaces === "number") {
+					options.prettySpaces = Math.max(
+						0,
+						Math.min(10, Math.floor(input.pretty_spaces)),
+					);
+				}
+				responseFormatter.configure(options);
+
+				// Build human-readable message describing the new configuration
+				const parts: string[] = [];
+				if (options.defaultMinify !== undefined) {
+					parts.push(`minify=${options.defaultMinify}`);
+				}
+				if (options.prettySpaces !== undefined) {
+					parts.push(`spaces=${options.prettySpaces}`);
+				}
+				const message =
+					parts.length > 0
+						? `Output format configured: ${parts.join(", ")}`
+						: "Output format configured";
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: responseFormatter.format({
+								success: true,
+								message,
+								options,
+							}),
+						},
+					],
+				};
+			},
+			metadata: {
+				annotations: {
+					...ToolAnnotationPresets.UTILITY_LOCAL,
+					title: "YNAB: Set Output Format",
+				},
+			},
+		});
+	}
+
+	private extractMinifyOverride(
+		args: Record<string, unknown> | undefined,
+	): boolean | undefined {
+		if (!args) {
+			return undefined;
+		}
+
+		for (const key of ["minify", "_minify", "__minify"] as const) {
+			const value = args[key];
+			if (typeof value === "boolean") {
+				return value;
+			}
+		}
+
+		return undefined;
+	}
+
+	/**
+	 * Starts the MCP server with stdio transport
+	 */
+	async run(): Promise<void> {
+		try {
+			// Validate token before starting server
+			await this.validateToken();
+
+			const transport = new StdioServerTransport();
+			await this.server.connect(transport);
+
+			console.error("YNAB MCP Server started successfully");
+		} catch (error) {
+			if (
+				error instanceof AuthenticationError ||
+				error instanceof ConfigurationError ||
+				error instanceof ConfigValidationError ||
+				error instanceof ValidationError ||
+				(error as { name?: string })?.name === "ValidationError"
+			) {
+				console.error(
+					`Server startup failed: ${error instanceof Error ? error.message : error}`,
+				);
+				if (this.exitOnError) {
+					process.exit(1);
+				} else {
+					throw error;
+				}
+			}
+			throw error;
+		}
+	}
+
+	/**
+	 * Gets the YNAB API instance (for testing purposes)
+	 */
+	getYNABAPI(): ynab.API {
+		return this.ynabAPI;
+	}
+
+	/**
+	 * Gets the MCP server instance (for testing purposes)
+	 */
+	getServer(): Server {
+		return this.server;
+	}
+
+	/**
+	 * Sets the default budget ID for operations
+	 */
+	setDefaultBudget(budgetId: string): void {
+		this.defaultBudgetId = budgetId;
+	}
+
+	/**
+	 * Gets the default budget ID
+	 */
+	getDefaultBudget(): string | undefined {
+		return this.defaultBudgetId;
+	}
+
+	/**
+	 * Clears the default budget ID (primarily for testing purposes)
+	 */
+	clearDefaultBudget(): void {
+		this.defaultBudgetId = undefined;
+	}
+
+	/**
+	 * Gets the tool registry instance (for testing purposes)
+	 */
+	getToolRegistry(): ToolRegistry {
+		return this.toolRegistry;
+	}
+
+	/**
+	 * Warm cache for frequently accessed data after setting default budget
+	 * Uses fire-and-forget pattern to avoid blocking the main operation
+	 * Runs cache warming operations in parallel for faster completion
+	 */
+	private async warmCacheForBudget(budgetId: string): Promise<void> {
+		try {
+			// Run all cache warming operations in parallel
+			await Promise.all([
+				this.deltaFetcher.fetchAccounts(budgetId, { forceFullRefresh: true }),
+				this.deltaFetcher.fetchCategories(budgetId, { forceFullRefresh: true }),
+				this.deltaFetcher.fetchPayees(budgetId, { forceFullRefresh: true }),
+			]);
+		} catch {
+			// Cache warming failures should not affect the main operation
+			// Errors are handled by the caller with a catch block
+		}
+	}
+
+	/**
+	 * Public handler methods for testing and external access
+	 */
+
+	/**
+	 * Handle list tools request - public method for testing
+	 */
+	public async handleListTools() {
+		return {
+			tools: this.toolRegistry.listTools(),
+		};
+	}
+
+	/**
+	 * Handle list resources request - public method for testing
+	 */
+	public async handleListResources() {
+		return this.resourceManager.listResources();
+	}
+
+	/**
+	 * Handle read resource request - public method for testing
+	 */
+	public async handleReadResource(params: { uri: string }) {
+		const { uri } = params;
+		try {
+			return await this.resourceManager.readResource(uri);
+		} catch (error) {
+			return this.errorHandler.handleError(error, `reading resource: ${uri}`);
+		}
+	}
+
+	/**
+	 * Handle list prompts request - public method for testing
+	 */
+	public async handleListPrompts() {
+		return this.promptManager.listPrompts();
+	}
+
+	/**
+	 * Handle get prompt request - public method for testing
+	 */
+	public async handleGetPrompt(params: {
+		name: string;
+		arguments?: Record<string, unknown>;
+	}) {
+		const { name, arguments: args } = params;
+		try {
+			const prompt = await this.promptManager.getPrompt(name, args);
+			const tools = Array.isArray((prompt as { tools?: unknown[] }).tools)
+				? ((prompt as { tools?: unknown[] }).tools as Tool[])
+				: undefined;
+			return tools ? { ...prompt, tools } : prompt;
+		} catch (error) {
+			return this.errorHandler.handleError(error, `getting prompt: ${name}`);
+		}
+	}
+
+	/**
+	 * Try to read the package version for accurate server metadata
+	 */
+	private readPackageVersion(): string | null {
+		const candidates = [path.resolve(process.cwd(), "package.json")];
+		try {
+			// May fail in bundled CJS builds; guard accordingly
+			const metaUrl = (import.meta as unknown as { url?: string })?.url;
+			if (metaUrl) {
+				const maybe = path.resolve(
+					path.dirname(new URL(metaUrl).pathname),
+					"../../package.json",
+				);
+				candidates.push(maybe);
+			}
+		} catch {
+			// ignore
+		}
+		try {
+			// CJS bundles can rely on __dirname being defined; add nearby package.json fallbacks
+			const dir = typeof __dirname === "string" ? __dirname : undefined;
+			if (dir) {
+				candidates.push(
+					path.resolve(dir, "../../package.json"),
+					path.resolve(dir, "../package.json"),
+					path.resolve(dir, "package.json"),
+				);
+			}
+		} catch {
+			// ignore additional fallbacks
+		}
+		for (const p of candidates) {
+			try {
+				if (fs.existsSync(p)) {
+					const raw = fs.readFileSync(p, "utf8");
+					const pkg = JSON.parse(raw) as { version?: string };
+					if (pkg.version && typeof pkg.version === "string")
+						return pkg.version;
+				}
+			} catch {
+				// ignore and try next
+			}
+		}
+		return null;
+	}
 }