@dizzlkheinz/ynab-mcpb 0.17.0 → 0.18.0

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/__tests__/transactionTools.integration.test.ts

@@ -9,6 +9,7 @@ import {
   handleUpdateTransactions,
   CreateTransactionsSchema,
 } from '../transactionTools.js';
+import { waitFor } from '../../__tests__/testUtils.js';
 
 const isSkip = ['true', '1', 'yes', 'y', 'on'].includes(
   (process.env['SKIP_E2E_TESTS'] || '').toLowerCase().trim(),
@@ -325,9 +326,22 @@ describeIntegration('Transaction Tools Integration', () => {
           ],
         });
 
-        const afterList = await fetchBudgetTransactions();
-        const transactions =
-          afterList.transactions || afterList.preview_transactions || afterList.transaction_preview;
+        let transactions: any[] | undefined;
+        await waitFor(
+          async () => {
+            const afterList = await fetchBudgetTransactions();
+            transactions =
+              afterList.transactions ||
+              afterList.preview_transactions ||
+              afterList.transaction_preview;
+            return (
+              (transactions as any[])?.some((transaction) => transaction.memo === memo) ?? false
+            );
+          },
+          10000,
+          500,
+        );
+
         expect(transactions).toBeDefined();
         expect((transactions as any[]).some((transaction) => transaction.memo === memo)).toBe(true);
       },
@@ -576,6 +590,19 @@ describeIntegration('Transaction Tools Integration', () => {
         expect(updateResponse.results[1].correlation_key).toBe(transactionIds[1]);
 
         // Verify changes persisted
+        await waitFor(
+          async () => {
+            const getResult1 = await handleGetTransaction(ynabAPI, {
+              budget_id: testBudgetId,
+              transaction_id: transactionIds[0],
+            });
+            const transaction1 = parseToolResult(getResult1).transaction;
+            return transaction1.amount === -7.5 && transaction1.memo === 'Updated memo 1';
+          },
+          10000,
+          500,
+        );
+
         const getResult1 = await handleGetTransaction(ynabAPI, {
           budget_id: testBudgetId,
           transaction_id: transactionIds[0],
@@ -584,6 +611,19 @@ describeIntegration('Transaction Tools Integration', () => {
         expect(transaction1.amount).toBe(-7.5);
         expect(transaction1.memo).toBe('Updated memo 1');
 
+        await waitFor(
+          async () => {
+            const getResult2 = await handleGetTransaction(ynabAPI, {
+              budget_id: testBudgetId,
+              transaction_id: transactionIds[1],
+            });
+            const transaction2 = parseToolResult(getResult2).transaction;
+            return transaction2.memo === 'Updated memo 2' && transaction2.cleared === 'cleared';
+          },
+          10000,
+          500,
+        );
+
         const getResult2 = await handleGetTransaction(ynabAPI, {
           budget_id: testBudgetId,
           transaction_id: transactionIds[1],
@@ -635,6 +675,19 @@ describeIntegration('Transaction Tools Integration', () => {
         expect(updateResponse.summary.updated).toBe(1);
 
         // Verify change
+        await waitFor(
+          async () => {
+            const getResult = await handleGetTransaction(ynabAPI, {
+              budget_id: testBudgetId,
+              transaction_id: transactionId,
+            });
+            const transaction = parseToolResult(getResult).transaction;
+            return transaction.memo === 'Updated without metadata';
+          },
+          10000,
+          500,
+        );
+
         const getResult = await handleGetTransaction(ynabAPI, {
           budget_id: testBudgetId,
           transaction_id: transactionId,
@@ -749,6 +802,13 @@ describeIntegration('Transaction Tools Integration', () => {
         });
 
         const updateResponse = parseToolResult(updateResult);
+
+        if (updateResponse.error) {
+          throw new Error(
+            `Tool execution failed unexpectedly: ${JSON.stringify(updateResponse.error)}`,
+          );
+        }
+
         expect(updateResponse.summary.total_requested).toBe(2);
         expect(updateResponse.summary.updated).toBe(1);
         expect(updateResponse.summary.failed).toBeGreaterThan(0);

package/src/tools/__tests__/utilityTools.integration.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeAll } from 'vitest';
 import * as ynab from 'ynab';
-import { handleGetUser, handleConvertAmount } from '../utilityTools.js';
+import { handleGetUser } from '../utilityTools.js';
 import { skipOnRateLimit } from '../../__tests__/testUtils.js';
 
 /**
@@ -41,88 +41,4 @@ describeIntegration('Utility Tools Integration Tests', () => {
       },
     );
   });
-
-  describe('handleConvertAmount', () => {
-    it(
-      'should convert various dollar amounts to milliunits',
-      { meta: { tier: 'domain', domain: 'utility' } },
-      async () => {
-        const testCases = [
-          { dollars: 1.0, expectedMilliunits: 1000 },
-          { dollars: 0.01, expectedMilliunits: 10 },
-          { dollars: 10.5, expectedMilliunits: 10500 },
-          { dollars: 999.99, expectedMilliunits: 999990 },
-          { dollars: 0, expectedMilliunits: 0 },
-          { dollars: -5.25, expectedMilliunits: -5250 },
-        ];
-
-        for (const testCase of testCases) {
-          const result = await handleConvertAmount({
-            amount: testCase.dollars,
-            to_milliunits: true,
-          });
-          const response = JSON.parse(result.content[0].text);
-
-          expect(response.conversion.converted_amount).toBe(testCase.expectedMilliunits);
-          expect(response.conversion.to_milliunits).toBe(true);
-          expect(response.conversion.description).toContain(`$${testCase.dollars.toFixed(2)}`);
-          expect(response.conversion.description).toContain(
-            `${testCase.expectedMilliunits} milliunits`,
-          );
-        }
-      },
-    );
-
-    it(
-      'should convert various milliunit amounts to dollars',
-      { meta: { tier: 'domain', domain: 'utility' } },
-      async () => {
-        const testCases = [
-          { milliunits: 1000, expectedDollars: 1.0 },
-          { milliunits: 10, expectedDollars: 0.01 },
-          { milliunits: 10500, expectedDollars: 10.5 },
-          { milliunits: 999990, expectedDollars: 999.99 },
-          { milliunits: 0, expectedDollars: 0 },
-          { milliunits: -5250, expectedDollars: -5.25 },
-        ];
-
-        for (const testCase of testCases) {
-          const result = await handleConvertAmount({
-            amount: testCase.milliunits,
-            to_milliunits: false,
-          });
-          const response = JSON.parse(result.content[0].text);
-
-          expect(response.conversion.converted_amount).toBe(testCase.expectedDollars);
-          expect(response.conversion.to_milliunits).toBe(false);
-          expect(response.conversion.description).toContain(`${testCase.milliunits} milliunits`);
-          expect(response.conversion.description).toContain(
-            `$${testCase.expectedDollars.toFixed(2)}`,
-          );
-        }
-      },
-    );
-
-    it(
-      'should handle precision edge cases',
-      { meta: { tier: 'domain', domain: 'utility' } },
-      async () => {
-        // Test floating-point precision issues
-        const precisionTests = [
-          { amount: 0.1 + 0.2, to_milliunits: true }, // Should handle 0.30000000000000004
-          { amount: 1.005, to_milliunits: true }, // Should round correctly
-          { amount: 999.999, to_milliunits: true }, // Should handle near-integer values
-        ];
-
-        for (const test of precisionTests) {
-          const result = await handleConvertAmount(test);
-          const response = JSON.parse(result.content[0].text);
-
-          expect(response.conversion).toHaveProperty('converted_amount');
-          expect(typeof response.conversion.converted_amount).toBe('number');
-          expect(Number.isInteger(response.conversion.converted_amount)).toBe(true);
-        }
-      },
-    );
-  });
 });

package/src/tools/__tests__/utilityTools.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import * as ynab from 'ynab';
-import { handleGetUser, handleConvertAmount, ConvertAmountSchema } from '../utilityTools.js';
+import { handleGetUser } from '../utilityTools.js';
 
 // Mock the YNAB API
 const mockYnabAPI = {
@@ -80,126 +80,4 @@ describe('Utility Tools', () => {
       expect(result.content[0].text).toContain('Failed to get user information');
     });
   });
-
-  describe('handleConvertAmount', () => {
-    it('should convert dollars to milliunits correctly', async () => {
-      const params = { amount: 10.5, to_milliunits: true };
-
-      const result = await handleConvertAmount(mockYnabAPI, params);
-      const response = JSON.parse(result.content[0].text);
-
-      expect(response.conversion.original_amount).toBe(10.5);
-      expect(response.conversion.converted_amount).toBe(10500);
-      expect(response.conversion.to_milliunits).toBe(true);
-      expect(response.conversion.description).toBe('$10.50 = 10500 milliunits');
-    });
-
-    it('should convert milliunits to dollars correctly', async () => {
-      const params = { amount: 10500, to_milliunits: false };
-
-      const result = await handleConvertAmount(mockYnabAPI, params);
-      const response = JSON.parse(result.content[0].text);
-
-      expect(response.conversion.original_amount).toBe(10500);
-      expect(response.conversion.converted_amount).toBe(10.5);
-      expect(response.conversion.to_milliunits).toBe(false);
-      expect(response.conversion.description).toBe('10500 milliunits = $10.50');
-    });
-
-    it('should handle zero amounts', async () => {
-      const params = { amount: 0, to_milliunits: true };
-
-      const result = await handleConvertAmount(mockYnabAPI, params);
-      const response = JSON.parse(result.content[0].text);
-
-      expect(response.conversion.original_amount).toBe(0);
-      expect(response.conversion.converted_amount).toBe(0);
-      expect(response.conversion.description).toBe('$0.00 = 0 milliunits');
-    });
-
-    it('should handle negative amounts', async () => {
-      const params = { amount: -5.25, to_milliunits: true };
-
-      const result = await handleConvertAmount(mockYnabAPI, params);
-      const response = JSON.parse(result.content[0].text);
-
-      expect(response.conversion.original_amount).toBe(-5.25);
-      expect(response.conversion.converted_amount).toBe(-5250);
-      expect(response.conversion.description).toBe('$-5.25 = -5250 milliunits');
-    });
-
-    it('should handle floating-point precision correctly', async () => {
-      const params = { amount: 0.01, to_milliunits: true };
-
-      const result = await handleConvertAmount(mockYnabAPI, params);
-      const response = JSON.parse(result.content[0].text);
-
-      expect(response.conversion.converted_amount).toBe(10);
-    });
-
-    it('should handle large amounts', async () => {
-      const params = { amount: 999999.99, to_milliunits: true };
-
-      const result = await handleConvertAmount(mockYnabAPI, params);
-      const response = JSON.parse(result.content[0].text);
-
-      expect(response.conversion.converted_amount).toBe(999999990);
-    });
-
-    it('should round to nearest milliunit when converting from dollars', async () => {
-      const params = { amount: 10.5555, to_milliunits: true };
-
-      const result = await handleConvertAmount(mockYnabAPI, params);
-      const response = JSON.parse(result.content[0].text);
-
-      expect(response.conversion.converted_amount).toBe(10556); // Rounded from 10555.5
-    });
-  });
-
-  describe('ConvertAmountSchema validation', () => {
-    it('should validate correct parameters', () => {
-      const validParams = { amount: 10.5, to_milliunits: true };
-      const result = ConvertAmountSchema.safeParse(validParams);
-
-      expect(result.success).toBe(true);
-      if (result.success) {
-        expect(result.data).toEqual(validParams);
-      }
-    });
-
-    it('should reject non-finite numbers', () => {
-      const invalidParams = { amount: Infinity, to_milliunits: true };
-      const result = ConvertAmountSchema.safeParse(invalidParams);
-
-      expect(result.success).toBe(false);
-    });
-
-    it('should reject NaN values', () => {
-      const invalidParams = { amount: NaN, to_milliunits: true };
-      const result = ConvertAmountSchema.safeParse(invalidParams);
-
-      expect(result.success).toBe(false);
-    });
-
-    it('should reject missing amount parameter', () => {
-      const invalidParams = { to_milliunits: true };
-      const result = ConvertAmountSchema.safeParse(invalidParams);
-
-      expect(result.success).toBe(false);
-    });
-
-    it('should reject missing to_milliunits parameter', () => {
-      const invalidParams = { amount: 10.5 };
-      const result = ConvertAmountSchema.safeParse(invalidParams);
-
-      expect(result.success).toBe(false);
-    });
-
-    it('should reject non-boolean to_milliunits parameter', () => {
-      const invalidParams = { amount: 10.5, to_milliunits: 'true' };
-      const result = ConvertAmountSchema.safeParse(invalidParams);
-
-      expect(result.success).toBe(false);
-    });
-  });
 });

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> =>