@dizzlkheinz/ynab-mcpb 0.12.1

package/dist/server/responseFormatter.d.ts

@@ -0,0 +1,14 @@
+declare class ResponseFormatter {
+    private defaultMinify;
+    private prettySpaces;
+    private als;
+    constructor();
+    configure(options?: {
+        defaultMinify?: boolean;
+        prettySpaces?: number;
+    }): void;
+    runWithMinifyOverride<T>(minify: boolean | undefined, fn: () => T): T;
+    format(value: unknown): string;
+}
+export declare const responseFormatter: ResponseFormatter;
+export {};

package/dist/server/responseFormatter.js

@@ -0,0 +1,42 @@
+import { AsyncLocalStorage } from 'async_hooks';
+function parseBool(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const v = value.trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+function parseIntSafe(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const n = Number.parseInt(value, 10);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+class ResponseFormatter {
+    constructor() {
+        this.als = new AsyncLocalStorage();
+        this.defaultMinify = parseBool(process.env['YNAB_MCP_MINIFY_OUTPUT'], true);
+        this.prettySpaces = parseIntSafe(process.env['YNAB_MCP_PRETTY_SPACES'], 2);
+    }
+    configure(options) {
+        if (!options)
+            return;
+        if (typeof options.defaultMinify === 'boolean')
+            this.defaultMinify = options.defaultMinify;
+        if (typeof options.prettySpaces === 'number' && options.prettySpaces >= 0) {
+            this.prettySpaces = options.prettySpaces;
+        }
+    }
+    runWithMinifyOverride(minify, fn) {
+        if (minify === undefined)
+            return fn();
+        return this.als.run({ minify }, fn);
+    }
+    format(value) {
+        const ctx = this.als.getStore();
+        const minify = ctx?.minify ?? this.defaultMinify;
+        if (minify)
+            return JSON.stringify(value);
+        return JSON.stringify(value, null, this.prettySpaces);
+    }
+}
+export const responseFormatter = new ResponseFormatter();

package/dist/server/securityMiddleware.d.ts

@@ -0,0 +1,87 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod/v4';
+export interface SecurityContext {
+    accessToken: string;
+    toolName: string;
+    operation: string;
+    parameters: Record<string, unknown>;
+    startTime: number;
+}
+export declare class SecurityMiddleware {
+    static withSecurity<T extends Record<string, unknown>>(context: SecurityContext, schema: z.ZodSchema<T>, operation: (..._args: unknown[]) => Promise<CallToolResult>): Promise<CallToolResult>;
+    private static validateInput;
+    private static checkRateLimit;
+    private static createRateLimitErrorResponse;
+    private static hashToken;
+    static getSecurityStats(): {
+        rateLimitStats: Record<string, unknown>;
+        requestStats: Record<string, unknown>;
+    };
+    static reset(): void;
+}
+export declare function withSecurityWrapper<T extends Record<string, unknown>>(toolName: string, operation: string, schema: z.ZodSchema<T>): (accessToken: string) => (params: Record<string, unknown>) => (handler: (validated: T) => Promise<CallToolResult>) => Promise<{
+    [x: string]: unknown;
+    content: ({
+        type: "text";
+        text: string;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        type: "image";
+        data: string;
+        mimeType: string;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        type: "audio";
+        data: string;
+        mimeType: string;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | {
+        type: "resource_link";
+        name: string;
+        uri: string;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+        mimeType?: string | undefined | undefined;
+        icons?: {
+            src: string;
+            mimeType?: string | undefined | undefined;
+            sizes?: string[] | undefined;
+        }[] | undefined;
+        title?: string | undefined | undefined;
+        description?: string | undefined | undefined;
+    } | {
+        type: "resource";
+        resource: {
+            uri: string;
+            text: string;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            mimeType?: string | undefined | undefined;
+        } | {
+            uri: string;
+            blob: string;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            mimeType?: string | undefined | undefined;
+        };
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    })[];
+    _meta?: {
+        [x: string]: unknown;
+    } | undefined;
+    structuredContent?: {
+        [x: string]: unknown;
+    } | undefined;
+    isError?: boolean | undefined;
+}>;

package/dist/server/securityMiddleware.js

@@ -0,0 +1,117 @@
+import { z } from 'zod/v4';
+import { globalRateLimiter, RateLimitError } from './rateLimiter.js';
+import { globalRequestLogger } from './requestLogger.js';
+import { ErrorHandler } from './errorHandler.js';
+import { responseFormatter } from './responseFormatter.js';
+export class SecurityMiddleware {
+    static async withSecurity(context, schema, operation) {
+        const startTime = Date.now();
+        try {
+            const validatedParams = await this.validateInput(schema, context.parameters);
+            await this.checkRateLimit(context.accessToken);
+            globalRateLimiter.recordRequest(this.hashToken(context.accessToken));
+            const result = await operation(validatedParams);
+            const duration = Date.now() - startTime;
+            const rateLimitInfo = globalRateLimiter.getStatus(this.hashToken(context.accessToken));
+            globalRequestLogger.logSuccess(context.toolName, context.operation, context.parameters, duration, {
+                remaining: rateLimitInfo.remaining,
+                isLimited: rateLimitInfo.isLimited,
+            });
+            return result;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            const rateLimitInfo = globalRateLimiter.getStatus(this.hashToken(context.accessToken));
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            globalRequestLogger.logError(context.toolName, context.operation, context.parameters, errorMessage, duration, {
+                remaining: rateLimitInfo.remaining,
+                isLimited: rateLimitInfo.isLimited,
+            });
+            if (error instanceof RateLimitError) {
+                return this.createRateLimitErrorResponse(error);
+            }
+            if (error instanceof Error && error.message.includes('Validation failed')) {
+                return ErrorHandler.createValidationError('Invalid parameters for ' + context.toolName, error.message);
+            }
+            throw error;
+        }
+    }
+    static async validateInput(schema, parameters) {
+        try {
+            return schema.parse(parameters);
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                const errorMessage = error.issues && error.issues.length > 0
+                    ? error.issues
+                        .map((err) => `${err.path.join('.')}: ${err.message}`)
+                        .join(', ')
+                    : error.message || 'Validation failed';
+                throw new Error(`Validation failed: ${errorMessage}`);
+            }
+            throw error;
+        }
+    }
+    static async checkRateLimit(accessToken) {
+        const tokenHash = this.hashToken(accessToken);
+        const rateLimitInfo = globalRateLimiter.isAllowed(tokenHash);
+        if (rateLimitInfo.isLimited) {
+            throw new RateLimitError('Rate limit exceeded. Please wait before making additional requests.', rateLimitInfo.resetTime, rateLimitInfo.remaining);
+        }
+    }
+    static createRateLimitErrorResponse(error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: responseFormatter.format({
+                        error: {
+                            code: 'RATE_LIMIT_EXCEEDED',
+                            message: error.message,
+                            details: {
+                                resetTime: error.resetTime.toISOString(),
+                                remaining: error.remaining,
+                            },
+                        },
+                    }),
+                },
+            ],
+        };
+    }
+    static hashToken(token) {
+        let hash = 0;
+        for (let i = 0; i < token.length; i++) {
+            const char = token.charCodeAt(i);
+            hash = (hash << 5) - hash + char;
+            hash = hash & hash;
+        }
+        return `token_${Math.abs(hash).toString(16)}`;
+    }
+    static getSecurityStats() {
+        return {
+            rateLimitStats: {
+                message: 'Rate limiting is active with YNAB API limits (200 requests/hour)',
+            },
+            requestStats: globalRequestLogger.getStats(),
+        };
+    }
+    static reset() {
+        globalRateLimiter.reset();
+        globalRequestLogger.clearLogs();
+    }
+}
+export function withSecurityWrapper(toolName, operation, schema) {
+    return (accessToken) => (params) => (handler) => {
+        const context = {
+            accessToken,
+            toolName,
+            operation,
+            parameters: params,
+            startTime: Date.now(),
+        };
+        const operationAdapter = async (validatedParams) => {
+            return handler(validatedParams);
+        };
+        return SecurityMiddleware.withSecurity(context, schema, operationAdapter);
+    };
+}

package/dist/server/serverKnowledgeStore.d.ts

@@ -0,0 +1,11 @@
+export declare class ServerKnowledgeStore {
+    private knowledge;
+    get(cacheKey: string): number | undefined;
+    update(cacheKey: string, value: number): void;
+    reset(keyPattern?: string): void;
+    resetByBudgetId(budgetId: string): void;
+    getStats(): {
+        entryCount: number;
+        entries: Record<string, number>;
+    };
+}

package/dist/server/serverKnowledgeStore.js

@@ -0,0 +1,42 @@
+export class ServerKnowledgeStore {
+    constructor() {
+        this.knowledge = new Map();
+    }
+    get(cacheKey) {
+        return this.knowledge.get(cacheKey);
+    }
+    update(cacheKey, value) {
+        if (value < 0) {
+            throw new Error(`server_knowledge must be non-negative, got: ${value}`);
+        }
+        this.knowledge.set(cacheKey, value);
+    }
+    reset(keyPattern) {
+        if (keyPattern === undefined || keyPattern === '') {
+            this.knowledge.clear();
+            return;
+        }
+        const keysToDelete = [];
+        for (const key of this.knowledge.keys()) {
+            if (key.includes(keyPattern)) {
+                keysToDelete.push(key);
+            }
+        }
+        for (const key of keysToDelete) {
+            this.knowledge.delete(key);
+        }
+    }
+    resetByBudgetId(budgetId) {
+        this.reset(`:${budgetId}`);
+    }
+    getStats() {
+        const entries = {};
+        for (const [key, value] of this.knowledge.entries()) {
+            entries[key] = value;
+        }
+        return {
+            entryCount: this.knowledge.size,
+            entries,
+        };
+    }
+}

package/dist/server/toolRegistry.d.ts

@@ -0,0 +1,85 @@
+import type { CallToolResult, Tool } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod/v4';
+import type { MCPToolAnnotations } from '../types/toolAnnotations.js';
+export type SecurityWrapperFactory = <T extends Record<string, unknown>>(namespace: string, operation: string, schema: z.ZodSchema<T>) => (accessToken: string) => (params: Record<string, unknown>) => (handler: (validated: T) => Promise<CallToolResult>) => Promise<CallToolResult>;
+export interface ErrorHandlerContract {
+    handleError(error: unknown, context: string): CallToolResult;
+    createValidationError(message: string, details?: string, suggestions?: string[]): CallToolResult;
+}
+export interface ResponseFormatterContract {
+    runWithMinifyOverride<T>(minifyOverride: boolean | undefined, fn: () => T): T;
+}
+export interface ToolRegistryCacheHelpers {
+    generateKey?: (...segments: unknown[]) => string;
+    invalidate?: (key: string) => void | Promise<void>;
+    clear?: () => void | Promise<void>;
+}
+export interface DefaultArgumentResolverContext {
+    name: string;
+    accessToken: string;
+    rawArguments: Record<string, unknown>;
+}
+export declare class DefaultArgumentResolutionError extends Error {
+    readonly result: CallToolResult;
+    constructor(result: CallToolResult);
+}
+export type DefaultArgumentResolver<TInput extends Record<string, unknown>> = (context: DefaultArgumentResolverContext) => Partial<TInput> | Promise<Partial<TInput> | undefined> | undefined;
+export interface ToolSecurityOptions {
+    namespace?: string;
+    operation?: string;
+}
+export interface ToolMetadataOptions {
+    inputJsonSchema?: Record<string, unknown>;
+    annotations?: MCPToolAnnotations;
+}
+export interface ToolExecutionContext {
+    accessToken: string;
+    name: string;
+    operation: string;
+    rawArguments: Record<string, unknown>;
+    cache?: ToolRegistryCacheHelpers;
+}
+export interface ToolExecutionPayload<TInput extends Record<string, unknown>> {
+    input: TInput;
+    context: ToolExecutionContext;
+}
+export type ToolHandler<TInput extends Record<string, unknown>> = (payload: ToolExecutionPayload<TInput>) => Promise<CallToolResult>;
+export interface ToolDefinition<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = Record<string, unknown>> {
+    name: string;
+    description: string;
+    inputSchema: z.ZodSchema<TInput>;
+    outputSchema?: z.ZodSchema<TOutput>;
+    handler: ToolHandler<TInput>;
+    security?: ToolSecurityOptions;
+    metadata?: ToolMetadataOptions;
+    defaultArgumentResolver?: DefaultArgumentResolver<TInput>;
+}
+export interface ToolExecutionOptions {
+    name: string;
+    accessToken: string;
+    arguments?: Record<string, unknown>;
+    minifyOverride?: boolean;
+}
+export interface ToolRegistryDependencies {
+    withSecurityWrapper: SecurityWrapperFactory;
+    errorHandler: ErrorHandlerContract;
+    responseFormatter: ResponseFormatterContract;
+    cacheHelpers?: ToolRegistryCacheHelpers;
+    validateAccessToken?: (token: string) => Promise<void> | void;
+}
+export declare class ToolRegistry {
+    private readonly deps;
+    private readonly tools;
+    private readonly outputValidators;
+    constructor(deps: ToolRegistryDependencies);
+    register<TInput extends Record<string, unknown>, TOutput extends Record<string, unknown>>(definition: ToolDefinition<TInput, TOutput>): void;
+    listTools(): Tool[];
+    getToolDefinitions(): ToolDefinition[];
+    executeTool(options: ToolExecutionOptions): Promise<CallToolResult>;
+    private isCallToolResult;
+    private normalizeSecurityError;
+    private extractMinifyOverride;
+    private assertValidDefinition;
+    private generateJsonSchema;
+    private validateOutput;
+}

package/dist/server/toolRegistry.js

@@ -0,0 +1,272 @@
+import { z, toJSONSchema } from 'zod/v4';
+export class DefaultArgumentResolutionError extends Error {
+    constructor(result) {
+        super('Default argument resolution failed');
+        this.result = result;
+        this.name = 'DefaultArgumentResolutionError';
+    }
+}
+const MINIFY_HINT_KEYS = ['minify', '_minify', '__minify'];
+export class ToolRegistry {
+    constructor(deps) {
+        this.deps = deps;
+        this.tools = new Map();
+        this.outputValidators = new Map();
+    }
+    register(definition) {
+        this.assertValidDefinition(definition);
+        if (this.tools.has(definition.name)) {
+            throw new Error(`Tool '${definition.name}' is already registered`);
+        }
+        const resolved = {
+            ...definition,
+            security: {
+                namespace: definition.security?.namespace ?? 'ynab',
+                operation: definition.security?.operation ?? definition.name,
+            },
+        };
+        const registeredTool = resolved;
+        this.tools.set(definition.name, registeredTool);
+        if (definition.outputSchema) {
+            this.outputValidators.set(definition.name, definition.outputSchema);
+        }
+    }
+    listTools() {
+        return Array.from(this.tools.values()).map((tool) => {
+            const inputSchema = tool.metadata?.inputJsonSchema ??
+                this.generateJsonSchema(tool.inputSchema);
+            const result = {
+                name: tool.name,
+                description: tool.description,
+                inputSchema,
+            };
+            if (tool.outputSchema) {
+                const outputSchema = this.generateJsonSchema(tool.outputSchema);
+                result.outputSchema = outputSchema;
+            }
+            if (tool.metadata?.annotations) {
+                result.annotations = tool.metadata.annotations;
+            }
+            return result;
+        });
+    }
+    getToolDefinitions() {
+        return Array.from(this.tools.values()).map((tool) => {
+            const definition = {
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+                handler: tool.handler,
+                security: tool.security,
+            };
+            if (tool.outputSchema) {
+                definition.outputSchema = tool.outputSchema;
+            }
+            if (tool.metadata) {
+                definition.metadata = tool.metadata;
+            }
+            if (tool.defaultArgumentResolver) {
+                definition.defaultArgumentResolver = tool.defaultArgumentResolver;
+            }
+            return definition;
+        });
+    }
+    async executeTool(options) {
+        const tool = this.tools.get(options.name);
+        if (!tool) {
+            return this.deps.errorHandler.createValidationError(`Unknown tool: ${options.name}`, 'The requested tool is not registered with the server');
+        }
+        if (this.deps.validateAccessToken) {
+            try {
+                await this.deps.validateAccessToken(options.accessToken);
+            }
+            catch (error) {
+                if (this.isCallToolResult(error)) {
+                    return error;
+                }
+                return this.deps.errorHandler.handleError(error, `authenticating ${tool.name}`);
+            }
+        }
+        let defaults;
+        if (tool.defaultArgumentResolver) {
+            try {
+                defaults = await tool.defaultArgumentResolver({
+                    name: tool.name,
+                    accessToken: options.accessToken,
+                    rawArguments: options.arguments ?? {},
+                });
+            }
+            catch (error) {
+                if (error instanceof DefaultArgumentResolutionError) {
+                    return error.result;
+                }
+                if (this.isCallToolResult(error)) {
+                    return error;
+                }
+                return this.deps.errorHandler.createValidationError('Invalid parameters', error instanceof Error
+                    ? error.message
+                    : 'Unknown error during default argument resolution');
+            }
+        }
+        const rawArguments = {
+            ...(defaults ?? {}),
+            ...(options.arguments ?? {}),
+        };
+        const minifyOverride = this.extractMinifyOverride(options, rawArguments);
+        const run = async () => {
+            try {
+                const secured = this.deps.withSecurityWrapper(tool.security.namespace, tool.security.operation, tool.inputSchema)(options.accessToken)(rawArguments);
+                return await secured(async (validated) => {
+                    try {
+                        const context = {
+                            accessToken: options.accessToken,
+                            name: tool.name,
+                            operation: tool.security.operation,
+                            rawArguments,
+                        };
+                        if (this.deps.cacheHelpers) {
+                            context.cache = this.deps.cacheHelpers;
+                        }
+                        const handlerResult = await tool.handler({
+                            input: validated,
+                            context,
+                        });
+                        if (handlerResult.isError) {
+                            return handlerResult;
+                        }
+                        return this.validateOutput(tool.name, handlerResult);
+                    }
+                    catch (handlerError) {
+                        return this.deps.errorHandler.handleError(handlerError, `executing ${tool.name} - ${tool.security.operation}`);
+                    }
+                });
+            }
+            catch (securityError) {
+                return this.normalizeSecurityError(securityError, tool);
+            }
+        };
+        try {
+            return await this.deps.responseFormatter.runWithMinifyOverride(minifyOverride, run);
+        }
+        catch (formatterError) {
+            return this.deps.errorHandler.handleError(formatterError, `formatting response for ${tool.name}`);
+        }
+    }
+    isCallToolResult(value) {
+        return (typeof value === 'object' &&
+            value !== null &&
+            'content' in value &&
+            Array.isArray(value.content));
+    }
+    normalizeSecurityError(error, tool) {
+        if (error instanceof z.ZodError) {
+            return this.deps.errorHandler.createValidationError(`Invalid parameters for ${tool.name}`, error.message);
+        }
+        if (error instanceof Error && error.message.includes('Validation failed')) {
+            return this.deps.errorHandler.createValidationError(`Invalid parameters for ${tool.name}`, error.message);
+        }
+        return this.deps.errorHandler.handleError(error, `executing ${tool.name}`);
+    }
+    extractMinifyOverride(options, args) {
+        if (typeof options.minifyOverride === 'boolean') {
+            return options.minifyOverride;
+        }
+        for (const key of MINIFY_HINT_KEYS) {
+            const value = args[key];
+            if (typeof value === 'boolean') {
+                delete args[key];
+                return value;
+            }
+        }
+        return undefined;
+    }
+    assertValidDefinition(definition) {
+        if (!definition || typeof definition !== 'object') {
+            throw new Error('Tool definition must be an object');
+        }
+        if (!definition.name || typeof definition.name !== 'string') {
+            throw new Error('Tool definition requires a non-empty name');
+        }
+        if (!definition.description || typeof definition.description !== 'string') {
+            throw new Error(`Tool '${definition.name}' requires a description`);
+        }
+        if (!definition.inputSchema || typeof definition.inputSchema.parse !== 'function') {
+            throw new Error(`Tool '${definition.name}' requires a valid Zod schema`);
+        }
+        if (definition.outputSchema && typeof definition.outputSchema.parse !== 'function') {
+            throw new Error(`Tool '${definition.name}' outputSchema must be a valid Zod schema when provided`);
+        }
+        if (typeof definition.handler !== 'function') {
+            throw new Error(`Tool '${definition.name}' requires a handler function`);
+        }
+        if (definition.defaultArgumentResolver &&
+            typeof definition.defaultArgumentResolver !== 'function') {
+            throw new Error(`Tool '${definition.name}' defaultArgumentResolver must be a function when provided`);
+        }
+    }
+    generateJsonSchema(schema) {
+        try {
+            return toJSONSchema(schema, { target: 'draft-2020-12', io: 'output' });
+        }
+        catch (error) {
+            console.warn(`Failed to generate JSON schema for tool: ${error}`);
+            return { type: 'object', additionalProperties: true };
+        }
+    }
+    validateOutput(toolName, output) {
+        const validator = this.outputValidators.get(toolName);
+        if (!validator) {
+            return output;
+        }
+        if (!output.content || output.content.length === 0) {
+            return this.deps.errorHandler.createValidationError(`Output validation failed for ${toolName}`, 'Handler returned empty content', ['Ensure the handler returns valid content in the response']);
+        }
+        const invalidItems = [];
+        for (let i = 0; i < output.content.length; i++) {
+            const item = output.content[i];
+            if (!item) {
+                invalidItems.push({ index: i, reason: 'item is null or undefined' });
+            }
+            else if (item.type !== 'text') {
+                invalidItems.push({ index: i, reason: `type is "${item.type}" instead of "text"` });
+            }
+            else if (typeof item.text !== 'string') {
+                invalidItems.push({
+                    index: i,
+                    reason: `text property is ${typeof item.text} instead of string`,
+                });
+            }
+        }
+        if (invalidItems.length > 0) {
+            const invalidItemsDetails = invalidItems
+                .map((inv) => `  - Item ${inv.index}: ${inv.reason}`)
+                .join('\n');
+            return this.deps.errorHandler.createValidationError(`Output validation failed for ${toolName}`, `Handler returned invalid content items (${invalidItems.length} of ${output.content.length} failed):\n${invalidItemsDetails}`, ['Ensure all content items have type="text" and a valid text property']);
+        }
+        const firstContent = output.content[0];
+        if (firstContent.type !== 'text') {
+            throw new Error('Unexpected: firstContent is not text after validation');
+        }
+        let parsedOutput;
+        try {
+            parsedOutput = JSON.parse(firstContent.text);
+        }
+        catch (parseError) {
+            return this.deps.errorHandler.createValidationError(`Output validation failed for ${toolName}`, `Invalid JSON in handler output: ${parseError instanceof Error ? parseError.message : String(parseError)}`, ['Ensure the handler returns valid JSON']);
+        }
+        const result = validator.safeParse(parsedOutput);
+        if (!result.success) {
+            const validationErrors = result.error.issues
+                .map((err) => {
+                const path = err.path.join('.');
+                return path ? `${path}: ${err.message}` : err.message;
+            })
+                .join('; ');
+            return this.deps.errorHandler.createValidationError(`Output validation failed for ${toolName}`, `Handler output does not match declared output schema: ${validationErrors}`, [
+                'Check that the handler returns data matching the output schema',
+                'Review the tool definition output schema',
+            ]);
+        }
+        return output;
+    }
+}