@dizzlkheinz/ynab-mcpb 0.12.1

package/.github/ISSUE_TEMPLATE/release_checklist.md

@@ -0,0 +1,31 @@
+---
+name: Release Checklist
+about: Track steps for a new release
+title: "Release vX.Y.Z"
+labels: release
+---
+
+## Version
+
+- Target: vX.Y.Z
+
+## Checks
+
+- [ ] Version bumped in `package.json` and `manifest.json`
+- [ ] Public API surface reviewed (see `docs/VERSIONING.md`)
+- [ ] Changelog entry prepared (Added/Changed/Fixed/Removed)
+- [ ] Tests and lint pass
+- [ ] Built with `npm run package:mcpb`
+- [ ] Manual sanity check in Claude Desktop (`get_env_status`, basic tool calls)
+
+## Publish
+
+- [ ] Tag pushed: `vX.Y.Z`
+- [ ] GitHub Release created with `.mcpb` attached
+- [ ] Release notes include upgrade/migration details if needed
+
+## Post‑release
+
+- [ ] Update docs if applicable
+- [ ] Monitor issues for regressions
+

package/.github/pull_request_template.md

@@ -0,0 +1,41 @@
+## Summary
+
+Describe the change and its motivation.
+
+## Type of change
+
+- [ ] Patch (backwards‑compatible fixes)
+- [ ] Minor (backwards‑compatible features)
+- [ ] Major (breaking changes)
+
+## Public API surface checklist
+
+For details, see `docs/VERSIONING.md`.
+
+- Tools
+  - [ ] No tool removals/renames, or deprecations documented
+  - [ ] No changes to required args; only additive optional args
+  - [ ] Output shapes preserved (only additive fields)
+- Resources
+  - [ ] URIs unchanged or deprecations documented
+  - [ ] Response shapes preserved (only additive fields)
+- Prompts
+  - [ ] Names/arguments unchanged or deprecations documented
+- Manifest/config
+  - [ ] `user_config.YNAB_ACCESS_TOKEN` remains the auth key
+  - [ ] `server.entry_point` and `mcp_config.env` remain compatible
+- Runtime behavior
+  - [ ] Auth and error semantics unchanged
+  - [ ] `get_env_status` still functional
+
+## Versioning and release
+
+- Proposed version bump: `X.Y.Z` → `X.Y.Z`
+- [ ] Changelog entry prepared (Added/Changed/Fixed/Removed)
+- [ ] Tests and lint pass locally
+- [ ] Built MCPB with `npm run package:mcpb` and sanity‑checked
+
+## Screenshots / Logs (optional)
+
+## Additional notes (optional)
+

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

@@ -0,0 +1,41 @@
+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
+        run: npm run test:integration:core

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

@@ -0,0 +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:*)"'
+

package/.github/workflows/claude.yml

@@ -0,0 +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:*)'
+

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

@@ -0,0 +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

package/.github/workflows/pr-description-check.yml

@@ -0,0 +1,88 @@
+name: PR Description Check
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: read
+
+jobs:
+  check-description:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check PR Description Format
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        with:
+          script: |
+            const body = context.payload.pull_request.body || '';
+
+            // Required sections from template
+            const requiredSections = [
+              'Type of change',
+              'Public API surface checklist',
+              'Versioning and release'
+            ];
+
+            const missingSections = requiredSections.filter(section =>
+              !body.includes(section)
+            );
+
+            if (missingSections.length > 0) {
+              // Build comment as array to avoid YAML indentation issues
+              const commentLines = [
+                '⚠️ **PR Description Check Failed**',
+                '',
+                'The PR description is missing required sections from the template:',
+                ...missingSections.map(s => `- ${s}`),
+                '',
+                'Please update the description to include these sections. You can view the template at:',
+                `https://github.com/${context.repo.owner}/${context.repo.repo}/blob/master/.github/pull_request_template.md`,
+                '',
+                'Or run this command to update it:',
+                '```bash',
+                `gh pr edit ${context.payload.pull_request.number} --body-file .github/pull_request_template.md`,
+                '```'
+              ];
+              const comment = commentLines.join('\n');
+
+              // Upsert comment: update existing bot comment or create new one
+              const botCommentPrefix = '⚠️ **PR Description Check Failed**';
+              // Paginate through all comments to handle PRs with >30 comments
+              const comments = await github.paginate(
+                github.rest.issues.listComments,
+                {
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: context.payload.pull_request.number,
+                  per_page: 100
+                }
+              );
+
+              const existingComment = comments.find(
+                c => c.user.type === 'Bot' && c.body.startsWith(botCommentPrefix)
+              );
+
+              if (existingComment) {
+                await github.rest.issues.updateComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  comment_id: existingComment.id,
+                  body: comment
+                });
+              } else {
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: context.payload.pull_request.number,
+                  body: comment
+                });
+              }
+
+              // Fail the check
+              core.setFailed(`Missing required sections: ${missingSections.join(', ')}`);
+            } else {
+              console.log('✅ All required sections present in PR description');
+            }

package/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build package
+        run: npm run build
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          echo "CI detected, using unit tests only"
+          npm run test:unit
+          npm publish --provenance --access public

package/.github/workflows/release.yml

@@ -0,0 +1,89 @@
+name: Release MCPB
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: 'Tag name to publish (e.g., v0.1.1)'
+        required: true
+      ref:
+        description: 'Git ref to build from (branch or tag)'
+        required: false
+        default: 'master'
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build-and-attach-mcpb:
+    runs-on: ubuntu-latest
+    env:
+      # Provide a dummy token for build-time env validation.
+      # If you add a real secret YNAB token, it will override this when set at step-level.
+      YNAB_ACCESS_TOKEN: ci-build-token-1234567890
+      SKIP_ENV_VALIDATION: true
+    steps:
+      - name: Checkout (default ref)
+        uses: actions/checkout@v4
+
+      - name: Checkout (specified ref)
+        if: ${{ inputs.ref != '' }}
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: npm
+
+      - name: Install dependencies (no scripts)
+        run: npm ci --ignore-scripts
+
+      - name: Set build environment
+        run: echo "YNAB_ACCESS_TOKEN=${YNAB_ACCESS_TOKEN}" >> $GITHUB_ENV
+
+      - name: Build (format + lint + bundle)
+        run: npm run build:prod
+        env:
+          # Prefer secret if configured; otherwise use the job-level default above
+          YNAB_ACCESS_TOKEN: ${{ secrets.YNAB_ACCESS_TOKEN || env.YNAB_ACCESS_TOKEN }}
+          SKIP_ENV_VALIDATION: true
+
+      - name: Install MCPB CLI
+        run: npm i -g @anthropic-ai/mcpb
+
+      - name: Validate manifest
+        run: mcpb validate manifest.json
+
+      - name: Compute package metadata
+        id: meta
+        run: |
+          NAME=$(node -p "require('./package.json').name")
+          VERSION=$(node -p "require('./package.json').version")
+          FILE="dist/${NAME}-${VERSION}.mcpb"
+          echo "name=$NAME" >> $GITHUB_OUTPUT
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "file=$FILE" >> $GITHUB_OUTPUT
+
+      - name: Pack MCPB
+        run: mcpb pack . "${{ steps.meta.outputs.file }}"
+
+      - name: Upload or create release with asset
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ inputs.release_tag || github.ref_name }}
+          name: ${{ inputs.release_tag || github.ref_name }}
+          files: ${{ steps.meta.outputs.file }}
+          generate_release_notes: true
+          fail_on_unmatched_files: true

package/.mcpbignore

@@ -0,0 +1,58 @@
+node_modules/
+src/
+**/__tests__/
+**/*.test.*
+coverage/
+*.log
+.*/
+**/*.map
+tsconfig*.json
+vitest.config.ts
+vitest-reporters/
+eslint.config.js
+test-results.json
+test-results/
+README.md
+
+# Sensitive credential files
+.chunkhound.json
+.chunkhound/
+.mcp.json
+.env*
+
+# Build metadata
+meta.json
+bundle-analysis.html
+
+# Development-only markdown files
+AGENTS.md
+TESTING_NOTES.md
+CODEREVIEW_RESPONSE.md
+SCHEMA_IMPROVEMENT_SUMMARY.md
+
+# Test files and data
+test_*.js
+test_*.mjs
+test-*.js
+test-*.cjs
+test-*.csv
+test-exports/
+accountactivity-merged.csv
+
+# Temporary and development files
+temp/
+tmp/
+fix-types.sh
+NUL
+package-lock.json
+
+# Development plans (keep user-facing docs)
+docs/plans/
+docs/bulk-transaction-operations-plan.md
+docs/delta-request-plan.md
+docs/reconciliation-flow.md
+
+# Scripts (not needed for distribution)
+scripts/
+
+# keep dist/, manifest.json, CHANGELOG.md, CLAUDE.md, LICENSE, docs/ (except plans)

package/.prettierignore

@@ -0,0 +1,10 @@
+dist/
+node_modules/
+coverage/
+*.mcpb
+*.log
+.git/
+.github/
+docs/**/*.md
+scripts/analyze-bundle.mjs
+test-reconcile-with-csv.cjs

package/.prettierrc.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/prettierrc",
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}