@dizzlkheinz/ynab-mcpb 0.12.1

package/src/tools/schemas/shared/commonOutputs.ts

@@ -0,0 +1,140 @@
+/**
+ * Common/shared Zod schemas for tool output structures
+ *
+ * Purpose: Provides reusable schema components for composing tool-specific output schemas
+ * Usage: Import these schemas to build consistent output structures across tools
+ * Pattern: These schemas represent common elements like cache metadata, success responses,
+ *          pagination info, and standard response structures
+ *
+ * References:
+ * - MCP Structured Output Specification: https://spec.modelcontextprotocol.io/specification/2025-11-05/server/tools/
+ * - Existing cache patterns: src/tools/budgetTools.ts (lines 55-58)
+ * - Success response patterns: src/server/YNABMCPServer.ts (lines 456-460)
+ */
+
+import { z } from 'zod/v4';
+
+/**
+ * CacheMetadataSchema
+ *
+ * Represents cache-related metadata returned by tools that support caching.
+ * Used to provide transparency about whether data was served from cache,
+ * cache status, and whether delta merge optimization was applied.
+ *
+ * Fields:
+ * - cached: Boolean indicating if the response data came from cache
+ * - cache_info: Human-readable message describing cache status (e.g., "Cache hit", "Cache miss")
+ * - usedDelta: Boolean indicating if delta merge was applied (for budgets with delta support)
+ *
+ * Example usage in tool output:
+ * ```typescript
+ * {
+ *   budgets: [...],
+ *   cached: true,
+ *   cache_info: "Cache hit",
+ *   usedDelta: false
+ * }
+ * ```
+ */
+export const CacheMetadataSchema = z.object({
+  cached: z.boolean().optional().describe('Indicates if data was served from cache'),
+  cache_info: z
+    .string()
+    .optional()
+    .describe('Human-readable cache status message (e.g., "Cache hit", "Cache miss")'),
+  usedDelta: z
+    .boolean()
+    .optional()
+    .describe('Indicates if delta merge optimization was applied for budgets'),
+});
+
+export type CacheMetadata = z.infer<typeof CacheMetadataSchema>;
+
+/**
+ * SuccessResponseSchema
+ *
+ * Standard schema for simple success confirmation responses.
+ * Used by tools that perform operations and need to confirm success
+ * with a human-readable message.
+ *
+ * Fields:
+ * - success: Boolean indicating operation success (always true for success responses)
+ * - message: Human-readable success message describing what was accomplished
+ *
+ * Example usage:
+ * ```typescript
+ * {
+ *   success: true,
+ *   message: "Default budget set to 'My Budget' (id: abc123)"
+ * }
+ * ```
+ */
+export const SuccessResponseSchema = z.object({
+  success: z.boolean().describe('Indicates operation success'),
+  message: z.string().describe('Human-readable success message'),
+});
+
+export type SuccessResponse = z.infer<typeof SuccessResponseSchema>;
+
+/**
+ * ConfirmationResponseSchema
+ *
+ * Extended success response schema with optional additional details.
+ * Used by tools that need to return success confirmation along with
+ * structured context or metadata about the operation.
+ *
+ * Fields:
+ * - success: Boolean indicating operation success
+ * - message: Human-readable success message
+ * - details: Optional record of additional confirmation details
+ *
+ * Example usage:
+ * ```typescript
+ * {
+ *   success: true,
+ *   message: "Account reconciled successfully",
+ *   details: {
+ *     cleared_balance: 1250.50,
+ *     reconciliation_date: "2025-01-15"
+ *   }
+ * }
+ * ```
+ */
+export const ConfirmationResponseSchema = SuccessResponseSchema.extend({
+  details: z
+    .record(z.string(), z.unknown())
+    .optional()
+    .describe('Additional confirmation details as key-value pairs'),
+});
+
+export type ConfirmationResponse = z.infer<typeof ConfirmationResponseSchema>;
+
+/**
+ * ErrorDetailsSchema
+ *
+ * Structured schema for error responses.
+ * Note: Most error handling is done by ErrorHandler (src/server/errorHandler.ts),
+ * but this schema provides a standard structure for tools that need to return
+ * error information as part of their normal output.
+ *
+ * Fields:
+ * - error: Error message string
+ * - code: Optional error code for categorization
+ * - details: Optional additional error details or context
+ *
+ * Example usage:
+ * ```typescript
+ * {
+ *   error: "Transaction not found",
+ *   code: "NOT_FOUND",
+ *   details: "Transaction ID 'xyz789' does not exist in budget 'abc123'"
+ * }
+ * ```
+ */
+export const ErrorDetailsSchema = z.object({
+  error: z.string().describe('Error message'),
+  code: z.string().optional().describe('Error code for categorization'),
+  details: z.string().optional().describe('Additional error context or details'),
+});
+
+export type ErrorDetails = z.infer<typeof ErrorDetailsSchema>;

package/src/tools/toolCategories.ts

@@ -0,0 +1,140 @@
+import type { MCPToolAnnotations } from '../types/toolAnnotations.js';
+
+/**
+ * Preset annotation patterns for common tool categories.
+ *
+ * These presets provide standardized annotation values for different types of tools
+ * based on their interaction patterns with the YNAB API and their operational characteristics.
+ *
+ * Note: The `title` field is intentionally not included in presets. Each tool should specify
+ * its own descriptive title at registration time. When using a preset, spread it first and
+ * then add tool-specific fields like `title` to ensure proper property precedence.
+ *
+ * @example
+ * // In tool registration (recommended property order):
+ * registry.register({
+ *   name: 'list_budgets',
+ *   ...ToolAnnotationPresets.READ_ONLY_EXTERNAL,  // Spread preset first
+ *   title: 'YNAB: List All Budgets',              // Then add tool-specific fields
+ *   // ... other tool properties
+ * });
+ */
+export const ToolAnnotationPresets = {
+  /**
+   * Preset for read-only tools that query the YNAB API without modifications.
+   *
+   * Use this for tools that only retrieve data from YNAB without making any changes.
+   *
+   * Examples:
+   * - list_budgets: Retrieves all budgets
+   * - get_account: Retrieves account details
+   * - list_transactions: Retrieves transaction data
+   * - list_categories: Retrieves category information
+   * - get_month: Retrieves monthly budget data
+   *
+   * Annotation rationale:
+   * - readOnlyHint: true - Tool only reads data, never modifies
+   * - destructiveHint: false - No destructive operations performed
+   * - idempotentHint: true - Same query returns same data (barring external changes)
+   * - openWorldHint: true - Calls external YNAB API over network
+   */
+  READ_ONLY_EXTERNAL: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+
+  /**
+   * Preset for tools that create new resources in YNAB.
+   *
+   * Use this for tools that add new entities to YNAB without modifying existing ones.
+   *
+   * Examples:
+   * - create_transaction: Creates a new transaction
+   * - create_account: Creates a new account
+   * - create_category: Creates a new budget category
+   *
+   * Annotation rationale:
+   * - readOnlyHint: false - Tool modifies data by creating resources
+   * - destructiveHint: false - Creation is not destructive (doesn't delete/overwrite)
+   * - idempotentHint: false - Repeated calls create multiple distinct resources
+   * - openWorldHint: true - Calls external YNAB API over network
+   */
+  WRITE_EXTERNAL_CREATE: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+
+  /**
+   * Preset for tools that update existing resources in YNAB.
+   *
+   * Use this for tools that modify existing entities without deleting them.
+   *
+   * Examples:
+   * - update_transaction: Updates an existing transaction
+   * - set_default_budget: Sets the default budget preference
+   * - reconcile_account: Updates account balances and transaction states
+   *
+   * Annotation rationale:
+   * - readOnlyHint: false - Tool modifies existing data
+   * - destructiveHint: false - Updates are not destructive (reversible/editable)
+   * - idempotentHint: true - Repeated identical updates have same final state
+   * - openWorldHint: true - Calls external YNAB API over network
+   */
+  WRITE_EXTERNAL_UPDATE: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+
+  /**
+   * Preset for tools that delete resources from YNAB.
+   *
+   * Use this for tools that permanently remove entities from YNAB.
+   *
+   * Examples:
+   * - delete_transaction: Permanently deletes a transaction
+   * - delete_account: Removes an account
+   *
+   * Annotation rationale:
+   * - readOnlyHint: false - Tool modifies data by deleting
+   * - destructiveHint: true - Deletion is irreversible and destructive
+   * - idempotentHint: true - Deleting same resource multiple times has same effect
+   * - openWorldHint: true - Calls external YNAB API over network
+   */
+  WRITE_EXTERNAL_DELETE: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+
+  /**
+   * Preset for local utility tools that don't call external APIs.
+   *
+   * Use this for tools that perform local operations or calculations without
+   * interacting with the YNAB API.
+   *
+   * Examples:
+   * - convert_amount: Converts between dollars and milliunits
+   * - set_output_format: Configures local output formatting
+   * - diagnostic_info: Returns local server diagnostic information
+   * - clear_cache: Clears local in-memory cache
+   *
+   * Annotation rationale:
+   * - readOnlyHint: true - No external/YNAB data modifications (may modify local server state/config)
+   * - destructiveHint: false - No destructive operations on external data
+   * - idempotentHint: true - Deterministic operations with same inputs (or safe to repeat)
+   * - openWorldHint: false - No external API calls, purely local operations
+   */
+  UTILITY_LOCAL: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+} as const satisfies Record<string, Omit<MCPToolAnnotations, 'title'>>;