@dizzlkheinz/ynab-mcpb 0.17.1 → 0.18.0

package/src/server/completions.ts

@@ -0,0 +1,279 @@
+/**
+ * @fileoverview MCP Completions Manager
+ * Provides autocomplete suggestions for prompts and resource templates.
+ * @module server/completions
+ */
+
+import type * as ynab from 'ynab';
+import type { CacheManager } from './cacheManager.js';
+import { CACHE_TTLS } from './cacheManager.js';
+
+/**
+ * Completion result structure following MCP spec
+ */
+export interface CompletionResult {
+  completion: {
+    values: string[];
+    total?: number;
+    hasMore?: boolean;
+  };
+}
+
+/**
+ * Arguments that can be completed
+ */
+type CompletableArgument =
+  | 'budget_id'
+  | 'account_id'
+  | 'account_name'
+  | 'category'
+  | 'category_id'
+  | 'payee'
+  | 'payee_id';
+
+/**
+ * Context for completions - previously resolved arguments
+ * The arguments property may be undefined when no prior context exists
+ */
+interface CompletionContext {
+  arguments?: Record<string, string> | undefined;
+}
+
+/**
+ * Maximum number of completion values to return (per MCP spec)
+ */
+const MAX_COMPLETIONS = 100;
+
+/**
+ * CompletionsManager handles autocomplete requests for YNAB entities.
+ * Provides completions for budgets, accounts, categories, and payees.
+ */
+export class CompletionsManager {
+  constructor(
+    private readonly ynabAPI: ynab.API,
+    private readonly cacheManager: CacheManager,
+    private readonly getDefaultBudgetId: () => string | undefined,
+  ) {}
+
+  /**
+   * Get completions for an argument based on the current value
+   */
+  async getCompletions(
+    argumentName: string,
+    value: string,
+    context?: CompletionContext,
+  ): Promise<CompletionResult> {
+    const normalizedName = argumentName.toLowerCase() as CompletableArgument;
+
+    switch (normalizedName) {
+      case 'budget_id':
+        return this.completeBudgets(value);
+
+      case 'account_id':
+      case 'account_name':
+        return this.completeAccounts(value, context);
+
+      case 'category':
+      case 'category_id':
+        return this.completeCategories(value, context);
+
+      case 'payee':
+      case 'payee_id':
+        return this.completePayees(value, context);
+
+      default:
+        return { completion: { values: [], total: 0, hasMore: false } };
+    }
+  }
+
+  /**
+   * Complete budget names/IDs
+   */
+  private async completeBudgets(value: string): Promise<CompletionResult> {
+    const budgets = await this.cacheManager.wrap('completions:budgets', {
+      ttl: CACHE_TTLS.BUDGETS,
+      loader: async () => {
+        const response = await this.ynabAPI.budgets.getBudgets();
+        return response.data.budgets.map((b) => ({
+          id: b.id,
+          name: b.name,
+        }));
+      },
+    });
+
+    return this.filterAndFormat(budgets, value, (b) => [b.name, b.id]);
+  }
+
+  /**
+   * Complete account names/IDs within a budget
+   */
+  private async completeAccounts(
+    value: string,
+    context?: CompletionContext,
+  ): Promise<CompletionResult> {
+    const budgetId = context?.arguments?.['budget_id'] ?? this.getDefaultBudgetId();
+    if (!budgetId) {
+      return { completion: { values: [], total: 0, hasMore: false } };
+    }
+
+    const accounts = await this.cacheManager.wrap(`completions:accounts:${budgetId}`, {
+      ttl: CACHE_TTLS.ACCOUNTS,
+      loader: async () => {
+        const response = await this.ynabAPI.accounts.getAccounts(budgetId);
+        return response.data.accounts
+          .filter((a) => !a.deleted && !a.closed)
+          .map((a) => ({
+            id: a.id,
+            name: a.name,
+          }));
+      },
+    });
+
+    return this.filterAndFormat(accounts, value, (a) => [a.name, a.id]);
+  }
+
+  /**
+   * Complete category names/IDs within a budget
+   */
+  private async completeCategories(
+    value: string,
+    context?: CompletionContext,
+  ): Promise<CompletionResult> {
+    const budgetId = context?.arguments?.['budget_id'] ?? this.getDefaultBudgetId();
+    if (!budgetId) {
+      return { completion: { values: [], total: 0, hasMore: false } };
+    }
+
+    const categories = await this.cacheManager.wrap(`completions:categories:${budgetId}`, {
+      ttl: CACHE_TTLS.CATEGORIES,
+      loader: async () => {
+        const response = await this.ynabAPI.categories.getCategories(budgetId);
+        const result: { id: string; name: string; group: string }[] = [];
+        for (const group of response.data.category_groups) {
+          if (group.hidden || group.deleted) continue;
+          for (const cat of group.categories) {
+            if (cat.hidden || cat.deleted) continue;
+            result.push({
+              id: cat.id,
+              name: cat.name,
+              group: group.name,
+            });
+          }
+        }
+        return result;
+      },
+    });
+
+    // For categories, include group name in display for clarity
+    return this.filterAndFormat(categories, value, (c) => [c.name, `${c.group}: ${c.name}`, c.id]);
+  }
+
+  /**
+   * Complete payee names/IDs within a budget
+   */
+  private async completePayees(
+    value: string,
+    context?: CompletionContext,
+  ): Promise<CompletionResult> {
+    const budgetId = context?.arguments?.['budget_id'] ?? this.getDefaultBudgetId();
+    if (!budgetId) {
+      return { completion: { values: [], total: 0, hasMore: false } };
+    }
+
+    const payees = await this.cacheManager.wrap(`completions:payees:${budgetId}`, {
+      ttl: CACHE_TTLS.PAYEES,
+      loader: async () => {
+        const response = await this.ynabAPI.payees.getPayees(budgetId);
+        return response.data.payees
+          .filter((p) => !p.deleted)
+          .map((p) => ({
+            id: p.id,
+            name: p.name,
+          }));
+      },
+    });
+
+    return this.filterAndFormat(payees, value, (p) => [p.name, p.id]);
+  }
+
+  /**
+   * Filter items by value match and format as completion result.
+   * Searches case-insensitively across all searchable fields.
+   * Caches lowercased values to avoid repeated toLowerCase() calls.
+   */
+  private filterAndFormat<T>(
+    items: T[],
+    value: string,
+    getSearchableValues: (item: T) => string[],
+  ): CompletionResult {
+    const lowerValue = value.toLowerCase();
+
+    // Cache lowercased values to avoid repeated toLowerCase() calls during filtering and sorting
+    const itemCache = new Map<T, { values: string[]; lowerValues: string[] }>();
+    const getCachedValues = (item: T) => {
+      let cached = itemCache.get(item);
+      if (!cached) {
+        const values = getSearchableValues(item);
+        cached = { values, lowerValues: values.map((v) => v.toLowerCase()) };
+        itemCache.set(item, cached);
+      }
+      return cached;
+    };
+
+    // Filter items that match the search value
+    const matches = items.filter((item) => {
+      const { lowerValues } = getCachedValues(item);
+      return lowerValues.some((v) => v.includes(lowerValue));
+    });
+
+    // Sort by relevance (exact prefix matches first, then contains)
+    matches.sort((a, b) => {
+      const aCache = getCachedValues(a);
+      const bCache = getCachedValues(b);
+
+      const aStartsWith = aCache.lowerValues.some((v) => v.startsWith(lowerValue));
+      const bStartsWith = bCache.lowerValues.some((v) => v.startsWith(lowerValue));
+
+      if (aStartsWith && !bStartsWith) return -1;
+      if (!aStartsWith && bStartsWith) return 1;
+
+      // Secondary sort by first value (name)
+      return (aCache.values[0] ?? '').localeCompare(bCache.values[0] ?? '');
+    });
+
+    // Get unique display values, prioritizing names over IDs
+    // The first value in the array should be the human-readable name
+    const uniqueValues = new Set<string>();
+    for (const item of matches) {
+      const { values, lowerValues } = getCachedValues(item);
+      // Find the first (name) value if it matches, otherwise find any matching value
+      // This ensures we prefer "Groceries" over the UUID when both match
+      let selectedValue: string | undefined;
+      for (let i = 0; i < values.length; i++) {
+        if (lowerValues[i]?.includes(lowerValue)) {
+          // Prefer the first matching value (typically the name), not the ID
+          // Only select this value if we haven't found a better one yet
+          if (selectedValue === undefined || i < values.indexOf(selectedValue)) {
+            selectedValue = values[i];
+          }
+          // Stop at first match - prioritizes name over ID since name comes first
+          break;
+        }
+      }
+      if (selectedValue) {
+        uniqueValues.add(selectedValue);
+      }
+      if (uniqueValues.size >= MAX_COMPLETIONS) break;
+    }
+
+    const resultValues = Array.from(uniqueValues).slice(0, MAX_COMPLETIONS);
+
+    return {
+      completion: {
+        values: resultValues,
+        total: matches.length,
+        hasMore: matches.length > MAX_COMPLETIONS,
+      },
+    };
+  }
+}

package/src/server/errorHandler.ts

@@ -121,6 +121,7 @@ export class ErrorHandler {
     }
 
     return {
+      isError: true,
       content: [
         {
           type: 'text',

package/src/server/rateLimiter.ts

@@ -152,5 +152,8 @@ export class RateLimitError extends Error {
  * Global rate limiter instance
  */
 export const globalRateLimiter = new RateLimiter({
-  enableLogging: process.env['NODE_ENV'] !== 'production',
+  enableLogging:
+    process.env['RATE_LIMIT_LOGGING'] === 'true' ||
+    process.env['LOG_LEVEL'] === 'debug' ||
+    process.env['VERBOSE_TESTS'] === 'true',
 });

package/src/server/resources.ts

@@ -10,9 +10,18 @@ import {
   ResourceTemplate as MCPResourceTemplate,
   Resource as MCPResource,
   ResourceContents,
+  ErrorCode,
+  McpError,
 } from '@modelcontextprotocol/sdk/types.js';
 import { CacheManager, CACHE_TTLS } from './cacheManager.js';
 
+/**
+ * Custom MCP error code for resource not found.
+ * Uses JSON-RPC reserved range (-32000 to -32099) for server errors.
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
+const RESOURCE_NOT_FOUND_ERROR_CODE = -32002;
+
 /**
  * Response formatter interface to avoid direct dependency on concrete implementation
  */
@@ -155,7 +164,9 @@ const defaultResourceTemplates: ResourceTemplateDefinition[] = [
     mimeType: 'application/json',
     handler: async (uri, params, { ynabAPI, responseFormatter, cacheManager }) => {
       const budget_id = params['budget_id'];
-      if (!budget_id) throw new Error('Missing budget_id parameter');
+      if (!budget_id) {
+        throw new McpError(ErrorCode.InvalidParams, 'Missing budget_id parameter');
+      }
       const cacheKey = CacheManager.generateKey('resources', 'budgets', 'get', budget_id);
       return cacheManager.wrap<ResourceContents[]>(cacheKey, {
         ttl: CACHE_TTLS.BUDGETS,
@@ -184,7 +195,9 @@ const defaultResourceTemplates: ResourceTemplateDefinition[] = [
     mimeType: 'application/json',
     handler: async (uri, params, { ynabAPI, responseFormatter, cacheManager }) => {
       const budget_id = params['budget_id'];
-      if (!budget_id) throw new Error('Missing budget_id parameter');
+      if (!budget_id) {
+        throw new McpError(ErrorCode.InvalidParams, 'Missing budget_id parameter');
+      }
       const cacheKey = CacheManager.generateKey('resources', 'accounts', 'list', budget_id);
       return cacheManager.wrap<ResourceContents[]>(cacheKey, {
         ttl: CACHE_TTLS.ACCOUNTS,
@@ -214,8 +227,12 @@ const defaultResourceTemplates: ResourceTemplateDefinition[] = [
     handler: async (uri, params, { ynabAPI, responseFormatter, cacheManager }) => {
       const budget_id = params['budget_id'];
       const account_id = params['account_id'];
-      if (!budget_id) throw new Error('Missing budget_id parameter');
-      if (!account_id) throw new Error('Missing account_id parameter');
+      if (!budget_id) {
+        throw new McpError(ErrorCode.InvalidParams, 'Missing budget_id parameter');
+      }
+      if (!account_id) {
+        throw new McpError(ErrorCode.InvalidParams, 'Missing account_id parameter');
+      }
       const cacheKey = CacheManager.generateKey(
         'resources',
         'accounts',
@@ -317,24 +334,43 @@ export class ResourceManager {
     // 1. Try exact match first
     const handler = this.resourceHandlers[uri];
     if (handler) {
-      return { contents: await handler(uri, this.dependencies) };
+      return {
+        contents: await this.executeResourceHandler(
+          () => handler(uri, this.dependencies),
+          `resource ${uri}`,
+        ),
+      };
     }
 
     // 2. Try template matching
     for (const template of this.resourceTemplates) {
       const params = this.matchTemplate(template.uriTemplate, uri);
       if (params) {
-        try {
-          return { contents: await template.handler(uri, params, this.dependencies) };
-        } catch (error) {
-          throw new Error(
-            `Failed to resolve template resource ${uri}: ${error instanceof Error ? error.message : String(error)}`,
-          );
-        }
+        return {
+          contents: await this.executeResourceHandler(
+            () => template.handler(uri, params, this.dependencies),
+            `resource ${uri}`,
+          ),
+        };
       }
     }
 
-    throw new Error(`Unknown resource: ${uri}`);
+    throw new McpError(RESOURCE_NOT_FOUND_ERROR_CODE, `Resource not found: ${uri}`);
+  }
+
+  private async executeResourceHandler(
+    handler: () => Promise<ResourceContents[]>,
+    label: string,
+  ): Promise<ResourceContents[]> {
+    try {
+      return await handler();
+    } catch (error) {
+      if (error instanceof McpError) {
+        throw error;
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      throw new McpError(ErrorCode.InternalError, `Failed to read ${label}: ${message}`);
+    }
   }
 
   /**

package/src/server/securityMiddleware.ts

@@ -141,6 +141,7 @@ export class SecurityMiddleware {
    */
   private static createRateLimitErrorResponse(error: RateLimitError): CallToolResult {
     return {
+      isError: true,
       content: [
         {
           type: 'text',

package/src/server/toolRegistry.ts

@@ -54,12 +54,27 @@ export interface ToolMetadataOptions {
   annotations?: MCPToolAnnotations;
 }
 
+/**
+ * Progress notification callback for long-running operations.
+ * Follows MCP spec: notifications/progress
+ */
+export type ProgressCallback = (params: {
+  progress: number;
+  total?: number;
+  message?: string;
+}) => Promise<void>;
+
 export interface ToolExecutionContext {
   accessToken: string;
   name: string;
   operation: string;
   rawArguments: Record<string, unknown>;
   cache?: ToolRegistryCacheHelpers;
+  /**
+   * Optional progress callback for emitting MCP progress notifications.
+   * Available when the client provides a progressToken in the request.
+   */
+  sendProgress?: ProgressCallback;
 }
 
 export interface ToolExecutionPayload<TInput extends Record<string, unknown>> {
@@ -97,6 +112,11 @@ export interface ToolExecutionOptions {
   accessToken: string;
   arguments?: Record<string, unknown>;
   minifyOverride?: boolean;
+  /**
+   * Optional progress callback for emitting MCP progress notifications.
+   * Should be provided when the request includes a progressToken.
+   */
+  sendProgress?: ProgressCallback;
 }
 
 export interface ToolRegistryDependencies {
@@ -176,6 +196,10 @@ export class ToolRegistry {
     });
   }
 
+  hasTool(name: string): boolean {
+    return this.tools.has(name);
+  }
+
   getToolDefinitions(): ToolDefinition[] {
     return Array.from(this.tools.values()).map((tool) => {
       const definition: ToolDefinition = {
@@ -269,6 +293,9 @@ export class ToolRegistry {
             if (this.deps.cacheHelpers) {
               context.cache = this.deps.cacheHelpers;
             }
+            if (options.sendProgress) {
+              context.sendProgress = options.sendProgress;
+            }
             const handlerResult = await tool.handler({
               input: validated,
               context,
@@ -353,6 +380,13 @@ export class ToolRegistry {
     return undefined;
   }
 
+  /**
+   * Regex pattern for MCP-compliant tool names.
+   * Tool names SHOULD be 1-128 chars, case-sensitive, only [a-zA-Z0-9_.-]
+   * @see https://spec.modelcontextprotocol.io/specification/2024-11-05/server/tools/
+   */
+  private static readonly MCP_TOOL_NAME_REGEX = /^[a-zA-Z0-9_.-]{1,128}$/;
+
   private assertValidDefinition<
     TInput extends Record<string, unknown>,
     TOutput extends Record<string, unknown>,
@@ -365,6 +399,14 @@ export class ToolRegistry {
       throw new Error('Tool definition requires a non-empty name');
     }
 
+    // Validate tool name follows MCP specification guidelines
+    if (!ToolRegistry.MCP_TOOL_NAME_REGEX.test(definition.name)) {
+      throw new Error(
+        `Tool name '${definition.name}' violates MCP guidelines: ` +
+          `must be 1-128 chars using only [a-zA-Z0-9_.-]`,
+      );
+    }
+
     if (!definition.description || typeof definition.description !== 'string') {
       throw new Error(`Tool '${definition.name}' requires a description`);
     }

package/src/tools/adapters.ts

@@ -6,7 +6,11 @@
  */
 
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import type { ToolExecutionPayload, DefaultArgumentResolver } from '../server/toolRegistry.js';
+import type {
+  ToolExecutionPayload,
+  DefaultArgumentResolver,
+  ProgressCallback,
+} from '../server/toolRegistry.js';
 import { BudgetResolver } from '../server/budgetResolver.js';
 import { DefaultArgumentResolutionError } from '../server/toolRegistry.js';
 import type {
@@ -16,6 +20,7 @@ import type {
   WriteHandler,
   NoInputHandler,
 } from '../types/toolRegistration.js';
+import type { DeltaFetcher } from './deltaFetcher.js';
 
 /**
  * Creates adapter functions bound to the provided context. These helpers reduce
@@ -41,6 +46,22 @@ export function createAdapters(context: ToolContext) {
       async ({ input }: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>
         handler(ynabAPI, deltaFetcher, input),
 
+    /**
+     * Adapter for delta operations that may emit progress notifications.
+     * Passes the optional sendProgress callback from the execution context.
+     */
+    adaptWithDeltaAndProgress:
+      <TInput extends Record<string, unknown>>(
+        handler: (
+          api: typeof ynabAPI,
+          deltaFetcher: DeltaFetcher,
+          params: TInput,
+          sendProgress?: ProgressCallback,
+        ) => Promise<CallToolResult>,
+      ) =>
+      async ({ input, context }: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>
+        handler(ynabAPI, deltaFetcher, input, context.sendProgress),
+
     adaptWrite:
       <TInput extends Record<string, unknown>>(handler: WriteHandler<TInput>) =>
       async ({ input }: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>