@dizzlkheinz/ynab-mcpb 0.17.1 → 0.18.1

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

package/src/tools/reconciliation/__tests__/executor.integration.test.ts

@@ -78,9 +78,12 @@ describeIntegration('Reconciliation Executor - Bulk Create Integration', () => {
   );
 
   it(
-    'reports duplicates when import IDs already exist',
+    'creates transactions without import_id to allow bank matching',
     { meta: { tier: 'domain', domain: 'reconciliation' } },
     async function () {
+      // Note: import_id is intentionally omitted from reconciliation-created transactions
+      // so they can match with bank-imported transactions. YNAB-side duplicate detection
+      // is no longer used; the reconciliation matcher handles duplicate prevention.
       const analysis = buildIntegrationAnalysis(accountSnapshot, 2, 9);
       const params = buildIntegrationParams(
         accountId,
@@ -88,23 +91,7 @@ describeIntegration('Reconciliation Executor - Bulk Create Integration', () => {
         analysis.summary.target_statement_balance,
       );
 
-      const firstRun = await skipOnRateLimit(
-        () =>
-          executeReconciliation({
-            ynabAPI,
-            analysis,
-            params,
-            budgetId,
-            accountId,
-            initialAccount: accountSnapshot,
-            currencyCode: 'USD',
-          }),
-        this,
-      );
-      if (!firstRun) return;
-      trackCreatedTransactions(firstRun);
-
-      const duplicateAttempt = await skipOnRateLimit(
+      const result = await skipOnRateLimit(
         () =>
           executeReconciliation({
             ynabAPI,
@@ -117,15 +104,14 @@ describeIntegration('Reconciliation Executor - Bulk Create Integration', () => {
           }),
         this,
       );
-      if (!duplicateAttempt) return;
-      if (containsRateLimitFailure(duplicateAttempt)) return;
+      if (!result) return;
+      trackCreatedTransactions(result);
+      if (containsRateLimitFailure(result)) return;
 
-      const duplicateActions = duplicateAttempt.actions_taken.filter(
-        (action) => action.duplicate === true,
-      );
-      expect(duplicateActions.length).toBeGreaterThan(0);
-      expect(duplicateAttempt.bulk_operation_details?.duplicates_detected).toBeGreaterThan(0);
-      expect(duplicateAttempt.summary.transactions_created).toBe(0);
+      // Verify transactions were created successfully
+      expect(result.summary.transactions_created).toBe(2);
+      // Verify no YNAB-side duplicate detection occurred (because no import_id)
+      expect(result.bulk_operation_details?.duplicates_detected).toBe(0);
     },
     60000,
   );