@dizzlkheinz/ynab-mcpb 0.17.0 → 0.18.0

package/.env.example

@@ -1,36 +1,36 @@
-# YNAB MCP Server Environment Configuration
-# Copy this file to .env and fill in your actual values
-
-# Required: Your YNAB Personal Access Token
-# Get this from: https://app.youneedabudget.com/settings/developer
-YNAB_ACCESS_TOKEN=your_ynab_personal_access_token_here
-
-# Optional: Node.js environment (development, production, test)
-NODE_ENV=development
-
-# Optional: Logging level (error, warn, info, debug)
-LOG_LEVEL=info
-
-# Output formatting controls
-# Minify JSON output returned by tools (default: true)
-YNAB_MCP_MINIFY_OUTPUT=true
-# Number of spaces when pretty printing (used when minify=false)
-YNAB_MCP_PRETTY_SPACES=2
-
-# Export settings
-# Directory where exported transaction files are saved
-# Default: Windows/Mac = ~/Downloads, Linux/Unix = ~/Documents (or $XDG_DOCUMENTS_DIR)
-# Examples: C:\Users\YourName\Desktop, /home/user/exports, ./data, ~/Desktop
-YNAB_EXPORT_PATH=
-
-# Cache configuration
-# Maximum number of entries in the in-memory cache (default: 1000)
-# Set to 0 to disable caching entirely
-YNAB_MCP_CACHE_MAX_ENTRIES=1000
-
-# Default time-to-live for cache entries in milliseconds (default: 300000 = 5 minutes)
-YNAB_MCP_CACHE_DEFAULT_TTL_MS=300000
-
+# YNAB MCP Server Environment Configuration
+# Copy this file to .env and fill in your actual values
+
+# Required: Your YNAB Personal Access Token
+# Get this from: https://app.youneedabudget.com/settings/developer
+YNAB_ACCESS_TOKEN=your_ynab_personal_access_token_here
+
+# Optional: Node.js environment (development, production, test)
+NODE_ENV=development
+
+# Optional: Logging level (error, warn, info, debug)
+LOG_LEVEL=info
+
+# Output formatting controls
+# Minify JSON output returned by tools (default: true)
+YNAB_MCP_MINIFY_OUTPUT=true
+# Number of spaces when pretty printing (used when minify=false)
+YNAB_MCP_PRETTY_SPACES=2
+
+# Export settings
+# Directory where exported transaction files are saved
+# Default: Windows/Mac = ~/Downloads, Linux/Unix = ~/Documents (or $XDG_DOCUMENTS_DIR)
+# Examples: C:\Users\YourName\Desktop, /home/user/exports, ./data, ~/Desktop
+YNAB_EXPORT_PATH=
+
+# Cache configuration
+# Maximum number of entries in the in-memory cache (default: 1000)
+# Set to 0 to disable caching entirely
+YNAB_MCP_CACHE_MAX_ENTRIES=1000
+
+# Default time-to-live for cache entries in milliseconds (default: 300000 = 5 minutes)
+YNAB_MCP_CACHE_DEFAULT_TTL_MS=300000
+
 # Default stale-while-revalidate window in milliseconds (default: 120000 = 2 minutes)
 # Used when stale-while-revalidate is explicitly requested but not specified
 YNAB_MCP_CACHE_STALE_MS=120000

package/.github/workflows/ci-tests.yml

@@ -1,45 +1,45 @@
-name: CI Tests
-
-on:
-  push:
-    branches:
-      - master
-  pull_request:
-
-jobs:
-  unit-tests:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: npm
-      - name: Install dependencies
-        run: npm ci
-      - name: Run unit tests
-        # Temporarily allow failures while DeltaFetcher architecture tests are updated
-        # See: docs/plans/2025-11-15-cache-test-alignment.md
-        continue-on-error: true
-        run: npm run test:unit
-
-  integration-core:
-    runs-on: ubuntu-latest
-    needs: unit-tests
-    if: always()
-    env:
-      YNAB_ACCESS_TOKEN: ${{ secrets.YNAB_ACCESS_TOKEN }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: npm
-      - name: Install dependencies
-        run: npm ci
-      - name: Run core integration tests (throttled)
-        # Integration tests with real YNAB API may hit rate limits (200/hour)
-        # causing 60-minute waits. Tests provide visibility but don't block merges.
-        continue-on-error: true
-        run: npm run test:integration:full
-        timeout-minutes: 90
+name: CI Tests
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Run unit tests
+        # Temporarily allow failures while DeltaFetcher architecture tests are updated
+        # See: docs/plans/2025-11-15-cache-test-alignment.md
+        continue-on-error: true
+        run: npm run test:unit
+
+  integration-core:
+    runs-on: ubuntu-latest
+    needs: unit-tests
+    if: always()
+    env:
+      YNAB_ACCESS_TOKEN: ${{ secrets.YNAB_ACCESS_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Run core integration tests (throttled)
+        # Integration tests with real YNAB API may hit rate limits (200/hour)
+        # causing 60-minute waits. Tests provide visibility but don't block merges.
+        continue-on-error: true
+        run: npm run test:integration:full
+        timeout-minutes: 90

package/.github/workflows/claude-code-review.yml

@@ -1,57 +1,57 @@
-name: Claude Code Review
-
-on:
-  pull_request:
-    types: [opened, synchronize]
-    # Optional: Only run on specific file changes
-    # paths:
-    #   - "src/**/*.ts"
-    #   - "src/**/*.tsx"
-    #   - "src/**/*.js"
-    #   - "src/**/*.jsx"
-
-jobs:
-  claude-review:
-    # Optional: Filter by PR author
-    # if: |
-    #   github.event.pull_request.user.login == 'external-contributor' ||
-    #   github.event.pull_request.user.login == 'new-developer' ||
-    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
-
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: read
-      issues: read
-      id-token: write
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-
-      - name: Run Claude Code Review
-        id: claude-review
-        uses: anthropics/claude-code-action@v1
-        with:
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          prompt: |
-            REPO: ${{ github.repository }}
-            PR NUMBER: ${{ github.event.pull_request.number }}
-
-            Please review this pull request and provide feedback on:
-            - Code quality and best practices
-            - Potential bugs or issues
-            - Performance considerations
-            - Security concerns
-            - Test coverage
-
-            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
-
-            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
-
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
-          claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
-
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Please review this pull request and provide feedback on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Performance considerations
+            - Security concerns
+            - Test coverage
+
+            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
+
+            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
+
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
+

package/.github/workflows/claude.yml

@@ -1,50 +1,50 @@
-name: Claude Code
-
-on:
-  issue_comment:
-    types: [created]
-  pull_request_review_comment:
-    types: [created]
-  issues:
-    types: [opened, assigned]
-  pull_request_review:
-    types: [submitted]
-
-jobs:
-  claude:
-    if: |
-      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
-      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: read
-      issues: read
-      id-token: write
-      actions: read # Required for Claude to read CI results on PRs
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-
-      - name: Run Claude Code
-        id: claude
-        uses: anthropics/claude-code-action@v1
-        with:
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-
-          # This is an optional setting that allows Claude to read CI results on PRs
-          additional_permissions: |
-            actions: read
-
-          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
-          # prompt: 'Update the pull request description to include a summary of changes.'
-
-          # Optional: Add claude_args to customize behavior and configuration
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
-          # claude_args: '--allowed-tools Bash(gh pr:*)'
-
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'
+

package/.github/workflows/full-integration.yml

@@ -1,22 +1,22 @@
-name: Full Integration Suite
-
-on:
-  schedule:
-    - cron: '0 2 * * *'
-  workflow_dispatch:
-
-jobs:
-  run-full-suite:
-    runs-on: ubuntu-latest
-    env:
-      YNAB_ACCESS_TOKEN: ${{ secrets.YNAB_ACCESS_TOKEN }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: npm
-      - name: Install dependencies
-        run: npm ci
-      - name: Run throttled full integration suite
-        run: npm run test:integration:full
+name: Full Integration Suite
+
+on:
+  schedule:
+    - cron: '0 2 * * *'
+  workflow_dispatch:
+
+jobs:
+  run-full-suite:
+    runs-on: ubuntu-latest
+    env:
+      YNAB_ACCESS_TOKEN: ${{ secrets.YNAB_ACCESS_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Run throttled full integration suite
+        run: npm run test:integration:full

package/.github/workflows/publish.yml

@@ -1,11 +1,18 @@
 name: Publish to npm
 
 on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag or ref to publish (e.g., v0.17.0)'
+        required: true
   release:
     types: [published]
 
 jobs:
   publish:
+    # Required to satisfy npm Trusted Publisher matching (environment name left blank in npm)
+    environment: npm-publish
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -14,11 +21,14 @@ jobs:
       YNAB_ACCESS_TOKEN: ${{ secrets.YNAB_ACCESS_TOKEN }}
     steps:
       - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag || github.ref }}
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
-          node-version: 18
+          node-version: 24
           registry-url: https://registry.npmjs.org
+          scope: '@dizzlkheinz'
 
       - name: Install dependencies
         run: npm ci
@@ -28,6 +38,5 @@ jobs:
 
       - name: Publish to npm
         run: |
-          echo "Using npm Trusted Publishing (OIDC)"
           npm run test:unit
           npm publish --provenance --access public

package/.github/workflows/release.yml

@@ -42,9 +42,9 @@ jobs:
           ref: ${{ inputs.ref }}
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
-          node-version: 18
+          node-version: 24
           cache: npm
 
       - name: Install dependencies (no scripts)

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **MCP Completions** - Autocomplete support for budgets, accounts, categories, and payees
+  - Improves client-side UX for tools that accept IDs or names
+  - Uses cached data to keep suggestions responsive
+- **Progress Notifications** - Long-running operations can emit MCP progress updates
+  - Reconciliation workflows now report progress during bulk create/update/unclear steps
+  - Clients can surface progress bars when providing a progress token
+
 ## [0.16.0] - 2025-12-01
 
 ### Added
@@ -160,7 +169,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Structured Output Schemas** - Zod-based output validation for all 30 tools
+- **Structured Output Schemas** - Zod-based output validation for all tools
   - Output schemas in `src/tools/schemas/outputs/` with centralized exports
   - Automatic validation in ToolRegistry (toolRegistry.ts:401-483) using `z.safeParse()`
   - Type-safe responses with TypeScript inference

package/CLAUDE.md

@@ -172,11 +172,14 @@ return cacheManager.wrap('cache_key', {
 
 Cache TTL constants are defined in `cacheManager.ts`:
 
-- `CACHE_TTLS.BUDGETS` - 1 hour (rarely changes)
-- `CACHE_TTLS.ACCOUNTS` - 30 minutes
-- `CACHE_TTLS.CATEGORIES` - 30 minutes
-- `CACHE_TTLS.SHORT` - 5 minutes (transactions)
-- `CACHE_TTLS.LONG` - 1 hour
+- `CACHE_TTLS.BUDGETS` - 10 minutes (rarely changes)
+- `CACHE_TTLS.ACCOUNTS` - 5 minutes
+- `CACHE_TTLS.CATEGORIES` - 5 minutes
+- `CACHE_TTLS.PAYEES` - 10 minutes
+- `CACHE_TTLS.TRANSACTIONS` - 2 minutes
+- `CACHE_TTLS.SCHEDULED_TRANSACTIONS` - 5 minutes
+- `CACHE_TTLS.USER_INFO` - 30 minutes
+- `CACHE_TTLS.MONTHS` - 5 minutes
 
 ### Delta Caching Pattern
 
@@ -286,12 +289,12 @@ The system defines 5 preset annotation patterns in `src/tools/toolCategories.ts`
   - Characteristics: Write operations, destructive, idempotent, external API
 
 - **UTILITY_LOCAL** - Local utility tools without external API calls
-  - Examples: `convert_amount`, `clear_cache`, `diagnostic_info`
+  - Examples: `clear_cache`, `diagnostic_info`, `set_output_format`
   - Characteristics: Local operations, no external API dependencies
 
 ### Complete Tool Classification
 
-All 30 tools are classified into the following categories:
+All 29 tools are classified into the following categories:
 
 **Read-Only External (15 tools):**
 
@@ -309,9 +312,9 @@ All 30 tools are classified into the following categories:
 
 - `delete_transaction` ⚠️
 
-**Utility Local (5 tools):**
+**Utility Local (4 tools):**
 
-- `get_default_budget`, `convert_amount`, `diagnostic_info`, `clear_cache`, `set_output_format`
+- `get_default_budget`, `diagnostic_info`, `clear_cache`, `set_output_format`
 
 ### Usage Example
 
@@ -387,7 +390,7 @@ Required:
 Optional (Caching):
 
 - `YNAB_MCP_CACHE_MAX_ENTRIES` (default: 1000)
-- `YNAB_MCP_CACHE_DEFAULT_TTL_MS` (default: 1800000 / 30 min)
+- `YNAB_MCP_CACHE_DEFAULT_TTL_MS` (default: 300000 / 5 min)
 - `YNAB_MCP_CACHE_STALE_MS` (default: 120000 / 2 min)
 
 Optional (Output):
@@ -429,7 +432,8 @@ Strict mode enabled with extensive safety checks:
 
 1. Create Zod schema in appropriate tool file (e.g., `src/tools/myTools.ts`)
 2. Implement handler function following existing patterns
-3. Register tool in `YNABMCPServer.ts` using `ToolRegistry`
+3. Register the tool in the appropriate domain factory (e.g., `registerBudgetTools` in
+   `src/tools/budgetTools.ts`) using `ToolRegistry`
 4. Add unit tests in `src/tools/__tests__/myTools.test.ts`
 5. Add integration tests in `src/tools/__tests__/myTools.integration.test.ts`
 6. Update API documentation in `docs/reference/API.md`
@@ -480,7 +484,7 @@ See `docs/technical/reconciliation-system-architecture.md` for detailed document
 
 - ✅ **Always do**: Run `npm test` before commits, use milliunits for YNAB amounts, follow existing patterns
 - ✅ **Always do**: Use `.js` extensions in imports, validate inputs with Zod schemas
-- ⚠️ **Ask first**: Adding new dependencies, changing API response formats, modifying cache TTLs
+- ⚠️ **Ask first**: Adding new dependencies, changing API response formats, modifying cache TTLs (see `src/server/cacheManager.ts`)
 - 🚫 **Never do**: Commit `.env` or secrets, edit `dist/` or `node_modules/`, skip type checking
 - 🚫 **Never do**: Remove failing tests without fixing, use `any` type without justification
 

package/README.md

@@ -162,7 +162,7 @@ For advanced configuration options (caching, output formatting), see the `.env.e
 
 ## What's Available
 
-The server gives Claude access to 30 tools organized by function. You don't need to know the tool names - just ask Claude in natural language and it will use the right tools.
+The server gives Claude access to 29 tools organized by function. You don't need to know the tool names - just ask Claude in natural language and it will use the right tools.
 
 **Budget & Account Info**
 
@@ -190,6 +190,11 @@ The server gives Claude access to 30 tools organized by function. You don't need
 
 For the complete list with technical details, see the [API Reference](docs/reference/API.md).
 
+## MCP Client Features
+
+- **Autocomplete (Completions)**: Clients that support MCP completions can suggest budgets, accounts, categories, and payees while filling tool arguments.
+- **Progress Notifications**: Long-running operations (notably reconciliation) emit progress updates when the client provides a progress token.
+
 ## Need Help?
 
 - **[API Reference](docs/reference/API.md)** - Complete tool documentation