@dizzlkheinz/ynab-mcpb 0.16.1 → 0.17.0

package/src/server/__tests__/toolRegistration.test.ts

@@ -0,0 +1,236 @@
+/**
+ * Unit tests for tool registration verification.
+ *
+ * Verifies that all expected tools are registered through the factory pattern
+ * and that tool metadata (annotations, schemas) are properly configured.
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+// Mock config before importing YNABMCPServer
+vi.mock('../config.js', () => ({
+  loadConfig: () => ({
+    YNAB_ACCESS_TOKEN: 'test-token-for-registration-tests',
+    YNAB_DEFAULT_BUDGET_ID: undefined,
+    LOG_LEVEL: 'info',
+  }),
+  config: {
+    YNAB_ACCESS_TOKEN: 'test-token-for-registration-tests',
+    YNAB_DEFAULT_BUDGET_ID: undefined,
+    LOG_LEVEL: 'info',
+  },
+}));
+
+import { YNABMCPServer } from '../YNABMCPServer.js';
+
+const DEFAULT_BUDGET_ID = '11111111-1111-1111-1111-111111111111';
+
+/**
+ * Expected tool names organized by domain.
+ * This serves as the authoritative list of all 30 registered tools.
+ */
+const EXPECTED_TOOLS_BY_DOMAIN = {
+  budget: ['list_budgets', 'get_budget'],
+  account: ['list_accounts', 'get_account', 'create_account'],
+  transaction: [
+    'list_transactions',
+    'export_transactions',
+    'get_transaction',
+    'create_transaction',
+    'create_transactions',
+    'update_transaction',
+    'update_transactions',
+    'delete_transaction',
+    'create_receipt_split_transaction',
+  ],
+  category: ['list_categories', 'get_category', 'update_category'],
+  payee: ['list_payees', 'get_payee'],
+  month: ['get_month', 'list_months'],
+  reconciliation: ['compare_transactions', 'reconcile_account'],
+  utility: ['get_user', 'convert_amount'],
+  server: [
+    'set_default_budget',
+    'get_default_budget',
+    'clear_cache',
+    'diagnostic_info',
+    'set_output_format',
+  ],
+} as const;
+
+/** Flat list of all expected tool names */
+const ALL_EXPECTED_TOOLS = Object.values(EXPECTED_TOOLS_BY_DOMAIN).flat();
+
+/** Expected total tool count */
+const EXPECTED_TOOL_COUNT = 30;
+
+describe('Tool Registration', () => {
+  // Config is mocked at module level, no env setup needed
+
+  describe('Tool Count Verification', () => {
+    it('registers exactly 30 tools', () => {
+      const server = new YNABMCPServer(false);
+      const tools = server.getToolRegistry().listTools();
+      expect(tools).toHaveLength(EXPECTED_TOOL_COUNT);
+    });
+
+    it('registers all expected tools with correct names', () => {
+      const server = new YNABMCPServer(false);
+      const tools = server.getToolRegistry().listTools();
+      const toolNames = tools.map((t) => t.name).sort();
+      const expectedNames = [...ALL_EXPECTED_TOOLS].sort();
+
+      expect(toolNames).toEqual(expectedNames);
+    });
+  });
+
+  describe('Domain Tool Registration', () => {
+    it.each([
+      ['budget', EXPECTED_TOOLS_BY_DOMAIN.budget],
+      ['account', EXPECTED_TOOLS_BY_DOMAIN.account],
+      ['transaction', EXPECTED_TOOLS_BY_DOMAIN.transaction],
+      ['category', EXPECTED_TOOLS_BY_DOMAIN.category],
+      ['payee', EXPECTED_TOOLS_BY_DOMAIN.payee],
+      ['month', EXPECTED_TOOLS_BY_DOMAIN.month],
+      ['reconciliation', EXPECTED_TOOLS_BY_DOMAIN.reconciliation],
+      ['utility', EXPECTED_TOOLS_BY_DOMAIN.utility],
+      ['server', EXPECTED_TOOLS_BY_DOMAIN.server],
+    ])('registers all %s domain tools', (domain: string, expectedTools: readonly string[]) => {
+      const server = new YNABMCPServer(false);
+      const tools = server.getToolRegistry().listTools();
+      const toolNames = tools.map((t) => t.name);
+
+      for (const toolName of expectedTools) {
+        expect(toolNames, `Missing ${domain} tool: ${toolName}`).toContain(toolName);
+      }
+    });
+  });
+
+  describe('Tool Metadata Verification', () => {
+    it('has descriptions for all tools', () => {
+      const server = new YNABMCPServer(false);
+      const tools = server.getToolRegistry().listTools();
+
+      for (const tool of tools) {
+        expect(tool.description, `${tool.name} missing description`).toBeDefined();
+        expect(tool.description.length, `${tool.name} has empty description`).toBeGreaterThan(0);
+      }
+    });
+
+    it('has input schemas for all tools', () => {
+      const server = new YNABMCPServer(false);
+      const tools = server.getToolRegistry().listTools();
+
+      for (const tool of tools) {
+        expect(tool.inputSchema, `${tool.name} missing inputSchema`).toBeDefined();
+        expect(tool.inputSchema.type, `${tool.name} inputSchema not object type`).toBe('object');
+      }
+    });
+
+    it('has annotations for all tools', () => {
+      const server = new YNABMCPServer(false);
+      const tools = server.getToolRegistry().listTools();
+
+      for (const tool of tools) {
+        expect(tool.annotations, `${tool.name} missing annotations`).toBeDefined();
+        expect(tool.annotations, `${tool.name} missing title`).toHaveProperty('title');
+        expect(tool.annotations, `${tool.name} missing readOnlyHint`).toHaveProperty(
+          'readOnlyHint',
+        );
+        expect(tool.annotations, `${tool.name} missing openWorldHint`).toHaveProperty(
+          'openWorldHint',
+        );
+      }
+    });
+
+    it('has YNAB prefix in all tool titles', () => {
+      const server = new YNABMCPServer(false);
+      const tools = server.getToolRegistry().listTools();
+
+      for (const tool of tools) {
+        expect(tool.annotations?.title, `${tool.name} title should start with "YNAB:"`).toMatch(
+          /^YNAB:/,
+        );
+      }
+    });
+  });
+
+  describe('No Duplicate Tools', () => {
+    it('does not have duplicate tool names', () => {
+      const server = new YNABMCPServer(false);
+      const tools = server.getToolRegistry().listTools();
+      const toolNames = tools.map((t) => t.name);
+      const uniqueNames = new Set(toolNames);
+
+      expect(uniqueNames.size).toBe(toolNames.length);
+    });
+  });
+
+  describe('Factory Registration Completeness', () => {
+    it('does not have unexpected tools registered', () => {
+      const server = new YNABMCPServer(false);
+      const tools = server.getToolRegistry().listTools();
+      const toolNames = tools.map((t) => t.name);
+
+      const unexpectedTools = toolNames.filter((name) => !ALL_EXPECTED_TOOLS.includes(name));
+      expect(unexpectedTools, 'Unexpected tools found').toEqual([]);
+    });
+
+    it('does not have missing expected tools', () => {
+      const server = new YNABMCPServer(false);
+      const tools = server.getToolRegistry().listTools();
+      const toolNames = tools.map((t) => t.name);
+
+      const missingTools = ALL_EXPECTED_TOOLS.filter((name) => !toolNames.includes(name));
+      expect(missingTools, 'Missing expected tools').toEqual([]);
+    });
+  });
+
+  describe('Default Argument Resolution', () => {
+    it('applies defaultArgumentResolver when budget_id is omitted', () => {
+      const server = new YNABMCPServer(false);
+      server.setDefaultBudget(DEFAULT_BUDGET_ID);
+
+      const listAccounts = server
+        .getToolRegistry()
+        .getToolDefinitions()
+        .find((tool) => tool.name === 'list_accounts');
+
+      expect(listAccounts?.defaultArgumentResolver).toBeDefined();
+
+      const resolved = listAccounts?.defaultArgumentResolver?.({
+        name: 'list_accounts',
+        accessToken: 'token',
+        rawArguments: {},
+      });
+
+      expect(resolved).toEqual({ budget_id: DEFAULT_BUDGET_ID });
+    });
+
+    it('budget-dependent tools have defaultArgumentResolver', () => {
+      const server = new YNABMCPServer(false);
+      const definitions = server.getToolRegistry().getToolDefinitions();
+
+      // Tools that require budget_id should have resolvers
+      const budgetDependentTools = [
+        'list_accounts',
+        'get_account',
+        'create_account',
+        'list_transactions',
+        'get_transaction',
+        'list_categories',
+        'get_category',
+        'list_payees',
+        'get_payee',
+        'get_month',
+        'list_months',
+      ];
+
+      for (const toolName of budgetDependentTools) {
+        const tool = definitions.find((t) => t.name === toolName);
+        expect(
+          tool?.defaultArgumentResolver,
+          `${toolName} should have defaultArgumentResolver`,
+        ).toBeDefined();
+      }
+    });
+  });
+});

package/src/server/config.ts

@@ -5,6 +5,7 @@ import { ValidationError } from '../utils/errors.js';
 
 const envSchema = z.object({
   YNAB_ACCESS_TOKEN: z.string().trim().min(1, 'YNAB_ACCESS_TOKEN must be a non-empty string'),
+  YNAB_DEFAULT_BUDGET_ID: z.string().uuid('YNAB_DEFAULT_BUDGET_ID must be a valid UUID').optional(),
   MCP_PORT: z.coerce.number().int().positive().optional(),
   LOG_LEVEL: z.enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal']).default('info'),
 });

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

@@ -0,0 +1,113 @@
+import { describe, expect, it, vi } from 'vitest';
+import { DefaultArgumentResolutionError } from '../../server/toolRegistry.js';
+import type { ToolContext } from '../../types/toolRegistration.js';
+import { createAdapters, createBudgetResolver } from '../adapters.js';
+
+const createMockContext = (overrides: Partial<ToolContext> = {}): ToolContext => {
+  return {
+    ynabAPI: (overrides.ynabAPI ?? ({ budgets: {} } as unknown as any)) as ToolContext['ynabAPI'],
+    deltaFetcher: overrides.deltaFetcher ?? ({} as any),
+    deltaCache: overrides.deltaCache ?? ({} as any),
+    serverKnowledgeStore: overrides.serverKnowledgeStore ?? ({} as any),
+    getDefaultBudgetId:
+      overrides.getDefaultBudgetId ?? vi.fn(() => '123e4567-e89b-12d3-a456-426614174000'),
+    setDefaultBudget: overrides.setDefaultBudget ?? vi.fn(),
+    cacheManager: overrides.cacheManager ?? ({} as any),
+    diagnosticManager: overrides.diagnosticManager,
+  } satisfies ToolContext;
+};
+
+describe('createAdapters', () => {
+  it('adapt passes api and params to handler', async () => {
+    const context = createMockContext();
+    const { adapt } = createAdapters(context);
+    const handler = vi.fn().mockResolvedValue({ content: [] });
+
+    const adapted = adapt(handler);
+    await adapted({ input: { foo: 'bar' }, context: {} as any });
+
+    expect(handler).toHaveBeenCalledWith(context.ynabAPI, { foo: 'bar' });
+  });
+
+  it('adaptNoInput passes api without params', async () => {
+    const context = createMockContext();
+    const { adaptNoInput } = createAdapters(context);
+    const handler = vi.fn().mockResolvedValue({ content: [] });
+
+    const adapted = adaptNoInput(handler);
+    await adapted({ input: {}, context: {} as any });
+
+    expect(handler).toHaveBeenCalledWith(context.ynabAPI);
+  });
+
+  it('adaptWithDelta passes deltaFetcher to handler', async () => {
+    const deltaFetcher = { fetch: vi.fn() } as any;
+    const context = createMockContext({ deltaFetcher });
+    const { adaptWithDelta } = createAdapters(context);
+    const handler = vi.fn().mockResolvedValue({ content: [] });
+
+    const adapted = adaptWithDelta(handler);
+    await adapted({ input: { a: 1 }, context: {} as any });
+
+    expect(handler).toHaveBeenCalledWith(context.ynabAPI, deltaFetcher, { a: 1 });
+  });
+
+  it('adaptWrite passes cache and knowledge store to handler', async () => {
+    const deltaCache = { invalidate: vi.fn() } as any;
+    const serverKnowledgeStore = { update: vi.fn() } as any;
+    const context = createMockContext({ deltaCache, serverKnowledgeStore });
+    const { adaptWrite } = createAdapters(context);
+    const handler = vi.fn().mockResolvedValue({ content: [] });
+
+    const adapted = adaptWrite(handler);
+    await adapted({ input: { a: 2 }, context: {} as any });
+
+    expect(handler).toHaveBeenCalledWith(context.ynabAPI, deltaCache, serverKnowledgeStore, {
+      a: 2,
+    });
+  });
+});
+
+describe('createBudgetResolver', () => {
+  it('returns provided budget_id when supplied', () => {
+    const context = createMockContext({ getDefaultBudgetId: () => 'default-budget' });
+    const resolverFactory = createBudgetResolver(context);
+    const resolver = resolverFactory<{ budget_id?: string }>();
+
+    const result = resolver({
+      name: 'tool',
+      accessToken: 'token',
+      rawArguments: { budget_id: '123e4567-e89b-12d3-a456-426614174000' },
+    });
+
+    expect(result).toEqual({ budget_id: '123e4567-e89b-12d3-a456-426614174000' });
+  });
+
+  it('falls back to default budget id when not provided', () => {
+    const context = createMockContext({
+      getDefaultBudgetId: () => '89abcdef-0123-4567-89ab-cdef01234567',
+    });
+    const resolver = createBudgetResolver(context)<{ budget_id?: string }>();
+
+    const result = resolver({
+      name: 'tool',
+      accessToken: 'token',
+      rawArguments: {},
+    });
+
+    expect(result).toEqual({ budget_id: '89abcdef-0123-4567-89ab-cdef01234567' });
+  });
+
+  it('throws DefaultArgumentResolutionError when no budget id available', () => {
+    const context = createMockContext({ getDefaultBudgetId: () => undefined });
+    const resolver = createBudgetResolver(context)<{ budget_id?: string }>();
+
+    expect(() =>
+      resolver({
+        name: 'tool',
+        accessToken: 'token',
+        rawArguments: {},
+      }),
+    ).toThrow(DefaultArgumentResolutionError);
+  });
+});

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

@@ -85,7 +85,7 @@ describe('Utility Tools', () => {
     it('should convert dollars to milliunits correctly', async () => {
       const params = { amount: 10.5, to_milliunits: true };
 
-      const result = await handleConvertAmount(params);
+      const result = await handleConvertAmount(mockYnabAPI, params);
       const response = JSON.parse(result.content[0].text);
 
       expect(response.conversion.original_amount).toBe(10.5);
@@ -97,7 +97,7 @@ describe('Utility Tools', () => {
     it('should convert milliunits to dollars correctly', async () => {
       const params = { amount: 10500, to_milliunits: false };
 
-      const result = await handleConvertAmount(params);
+      const result = await handleConvertAmount(mockYnabAPI, params);
       const response = JSON.parse(result.content[0].text);
 
       expect(response.conversion.original_amount).toBe(10500);
@@ -109,7 +109,7 @@ describe('Utility Tools', () => {
     it('should handle zero amounts', async () => {
       const params = { amount: 0, to_milliunits: true };
 
-      const result = await handleConvertAmount(params);
+      const result = await handleConvertAmount(mockYnabAPI, params);
       const response = JSON.parse(result.content[0].text);
 
       expect(response.conversion.original_amount).toBe(0);
@@ -120,7 +120,7 @@ describe('Utility Tools', () => {
     it('should handle negative amounts', async () => {
       const params = { amount: -5.25, to_milliunits: true };
 
-      const result = await handleConvertAmount(params);
+      const result = await handleConvertAmount(mockYnabAPI, params);
       const response = JSON.parse(result.content[0].text);
 
       expect(response.conversion.original_amount).toBe(-5.25);
@@ -131,7 +131,7 @@ describe('Utility Tools', () => {
     it('should handle floating-point precision correctly', async () => {
       const params = { amount: 0.01, to_milliunits: true };
 
-      const result = await handleConvertAmount(params);
+      const result = await handleConvertAmount(mockYnabAPI, params);
       const response = JSON.parse(result.content[0].text);
 
       expect(response.conversion.converted_amount).toBe(10);
@@ -140,7 +140,7 @@ describe('Utility Tools', () => {
     it('should handle large amounts', async () => {
       const params = { amount: 999999.99, to_milliunits: true };
 
-      const result = await handleConvertAmount(params);
+      const result = await handleConvertAmount(mockYnabAPI, params);
       const response = JSON.parse(result.content[0].text);
 
       expect(response.conversion.converted_amount).toBe(999999990);
@@ -149,7 +149,7 @@ describe('Utility Tools', () => {
     it('should round to nearest milliunit when converting from dollars', async () => {
       const params = { amount: 10.5555, to_milliunits: true };
 
-      const result = await handleConvertAmount(params);
+      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

package/src/tools/accountTools.ts

@@ -10,6 +10,9 @@ import type { DeltaCache } from '../server/deltaCache.js';
 import type { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
 import { CacheKeys } from '../server/cacheKeys.js';
 import { resolveDeltaFetcherArgs, resolveDeltaWriteArgs } from './deltaSupport.js';
+import type { ToolFactory } from '../types/toolRegistration.js';
+import { createAdapters, createBudgetResolver } from './adapters.js';
+import { ToolAnnotationPresets } from './toolCategories.js';
 
 /**
  * Schema for ynab:list_accounts tool parameters
@@ -286,3 +289,53 @@ export async function handleCreateAccount(
     'creating account',
   );
 }
+
+/**
+ * Registers all account-related tools with the registry.
+ */
+export const registerAccountTools: ToolFactory = (registry, context) => {
+  const { adapt, adaptWithDelta, adaptWrite } = createAdapters(context);
+  const budgetResolver = createBudgetResolver(context);
+
+  registry.register({
+    name: 'list_accounts',
+    description: 'List all accounts for a specific budget',
+    inputSchema: ListAccountsSchema,
+    handler: adaptWithDelta(handleListAccounts),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof ListAccountsSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: List Accounts',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'get_account',
+    description: 'Get detailed information for a specific account',
+    inputSchema: GetAccountSchema,
+    handler: adapt(handleGetAccount),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof GetAccountSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: Get Account Details',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'create_account',
+    description: 'Create a new account in the specified budget',
+    inputSchema: CreateAccountSchema,
+    handler: adaptWrite(handleCreateAccount),
+    defaultArgumentResolver: budgetResolver<z.infer<typeof CreateAccountSchema>>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
+        title: 'YNAB: Create Account',
+      },
+    },
+  });
+};

package/src/tools/adapters.ts

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview Adapter utilities for tool factory functions.
+ * Provides createAdapters() to reduce boilerplate when registering tools,
+ * and createBudgetResolver() for consistent budget ID resolution.
+ * @module tools/adapters
+ */
+
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolExecutionPayload, DefaultArgumentResolver } from '../server/toolRegistry.js';
+import { BudgetResolver } from '../server/budgetResolver.js';
+import { DefaultArgumentResolutionError } from '../server/toolRegistry.js';
+import type {
+  ToolContext,
+  Handler,
+  DeltaHandler,
+  WriteHandler,
+  NoInputHandler,
+} from '../types/toolRegistration.js';
+
+/**
+ * Creates adapter functions bound to the provided context. These helpers reduce
+ * boilerplate inside tool factory modules by partially applying shared
+ * dependencies to handlers.
+ */
+export function createAdapters(context: ToolContext) {
+  const { ynabAPI, deltaFetcher, deltaCache, serverKnowledgeStore } = context;
+
+  return {
+    adapt:
+      <TInput extends Record<string, unknown>>(handler: Handler<TInput>) =>
+      async ({ input }: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>
+        handler(ynabAPI, input),
+
+    adaptNoInput:
+      (handler: NoInputHandler) =>
+      async (_payload: ToolExecutionPayload<Record<string, unknown>>): Promise<CallToolResult> =>
+        handler(ynabAPI),
+
+    adaptWithDelta:
+      <TInput extends Record<string, unknown>>(handler: DeltaHandler<TInput>) =>
+      async ({ input }: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>
+        handler(ynabAPI, deltaFetcher, input),
+
+    adaptWrite:
+      <TInput extends Record<string, unknown>>(handler: WriteHandler<TInput>) =>
+      async ({ input }: ToolExecutionPayload<TInput>): Promise<CallToolResult> =>
+        handler(ynabAPI, deltaCache, serverKnowledgeStore, input),
+  };
+}
+
+/**
+ * Creates a budget ID resolver bound to the provided context. The returned
+ * resolver matches the ToolRegistry defaultArgumentResolver signature.
+ */
+export function createBudgetResolver(
+  context: ToolContext,
+): <TInput extends { budget_id?: string | undefined }>() => DefaultArgumentResolver<TInput> {
+  return <TInput extends { budget_id?: string | undefined }>(): DefaultArgumentResolver<TInput> => {
+    return ({ rawArguments }) => {
+      const provided =
+        typeof rawArguments['budget_id'] === 'string' && rawArguments['budget_id'].length > 0
+          ? rawArguments['budget_id']
+          : undefined;
+
+      const result = BudgetResolver.resolveBudgetId(provided, context.getDefaultBudgetId());
+
+      if (typeof result === 'string') {
+        return { budget_id: result } as Partial<TInput>;
+      }
+
+      throw new DefaultArgumentResolutionError(result);
+    };
+  };
+}

package/src/tools/budgetTools.ts

@@ -5,6 +5,10 @@ import { withToolErrorHandling } from '../types/index.js';
 import { responseFormatter } from '../server/responseFormatter.js';
 import type { DeltaFetcher } from './deltaFetcher.js';
 import { resolveDeltaFetcherArgs } from './deltaSupport.js';
+import type { ToolFactory } from '../types/toolRegistration.js';
+import { createAdapters } from './adapters.js';
+import { ToolAnnotationPresets } from './toolCategories.js';
+import { emptyObjectSchema } from './schemas/common.js';
 
 /**
  * Schema for ynab:get_budget tool parameters
@@ -110,3 +114,36 @@ export async function handleGetBudget(
     'getting budget details',
   );
 }
+
+/**
+ * Registers all budget-related tools with the provided registry.
+ */
+export const registerBudgetTools: ToolFactory = (registry, context) => {
+  const { adapt, adaptWithDelta } = createAdapters(context);
+
+  registry.register({
+    name: 'list_budgets',
+    description: "List all budgets associated with the user's account",
+    inputSchema: emptyObjectSchema,
+    handler: adaptWithDelta(handleListBudgets),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: List Budgets',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'get_budget',
+    description: 'Get detailed information for a specific budget',
+    inputSchema: GetBudgetSchema,
+    handler: adapt(handleGetBudget),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: Get Budget Details',
+      },
+    },
+  });
+};

package/src/tools/categoryTools.ts

@@ -10,6 +10,9 @@ import type { DeltaCache } from '../server/deltaCache.js';
 import type { ServerKnowledgeStore } from '../server/serverKnowledgeStore.js';
 import { CacheKeys } from '../server/cacheKeys.js';
 import { resolveDeltaFetcherArgs, resolveDeltaWriteArgs } from './deltaSupport.js';
+import type { ToolFactory } from '../types/toolRegistration.js';
+import { createAdapters, createBudgetResolver } from './adapters.js';
+import { ToolAnnotationPresets } from './toolCategories.js';
 
 /**
  * Schema for ynab:list_categories tool parameters
@@ -336,6 +339,56 @@ export async function handleUpdateCategory(
   }
 }
 
+/**
+ * Registers all category-related tools with the registry.
+ */
+export const registerCategoryTools: ToolFactory = (registry, context) => {
+  const { adapt, adaptWithDelta, adaptWrite } = createAdapters(context);
+  const budgetResolver = createBudgetResolver(context);
+
+  registry.register({
+    name: 'list_categories',
+    description: 'List all categories for a specific budget',
+    inputSchema: ListCategoriesSchema,
+    handler: adaptWithDelta(handleListCategories),
+    defaultArgumentResolver: budgetResolver<ListCategoriesParams>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: List Categories',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'get_category',
+    description: 'Get detailed information for a specific category',
+    inputSchema: GetCategorySchema,
+    handler: adapt(handleGetCategory),
+    defaultArgumentResolver: budgetResolver<GetCategoryParams>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,
+        title: 'YNAB: Get Category Details',
+      },
+    },
+  });
+
+  registry.register({
+    name: 'update_category',
+    description: 'Update the budgeted amount for a category in the current month',
+    inputSchema: UpdateCategorySchema,
+    handler: adaptWrite(handleUpdateCategory),
+    defaultArgumentResolver: budgetResolver<UpdateCategoryParams>(),
+    metadata: {
+      annotations: {
+        ...ToolAnnotationPresets.WRITE_EXTERNAL_UPDATE,
+        title: 'YNAB: Update Category Budget',
+      },
+    },
+  });
+};
+
 /**
  * Handles errors from category-related API calls
  */