@dizzlkheinz/ynab-mcpb 0.26.6 → 0.26.7

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.26.7] - 2026-04-03
+
+### Changed
+
+- **Improved `ynab_create_transaction` tool description** — Documents `flag_color`, `subtransactions`, and `import_id` parameters; clarifies when to use subtransactions vs `create_receipt_split_transaction`
+- **Improved `ynab_create_transactions` tool description** — Clarifies `import_id` guidance for YNAB-side duplicate detection
+- **Improved `ynab_create_receipt_split_transaction` tool description** — Documents `memo`, `receipt_subtotal`, `cleared`, `approved`, `flag_color` parameters; adds cross-reference to `create_transaction` for generic splits
+- **API reference documentation** — Adds subtransaction and `import_id` guidance to `create_transaction`; cross-references `create_receipt_split_transaction` for receipt workflows
+
 ## [0.26.6] - 2026-04-03
 
 ### Changed

package/CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 This is a Model Context Protocol (MCP) server for YNAB (You Need A Budget) integration, enabling AI assistants to interact with YNAB budgets, accounts, transactions, and categories. The codebase uses TypeScript with a modular, service-oriented architecture.
 
-**Current Version:** 0.26.6
+**Current Version:** 0.26.7
 
 ## Essential Commands
 

package/dist/bundle/index.cjs

@@ -319,7 +319,12 @@ Args:
   - memo (string, optional): Memo text.
   - cleared (string, optional): "cleared", "uncleared", or "reconciled". Default: "uncleared".
   - approved (boolean, optional): Mark as approved. Default: false.
+  - flag_color (string, optional): Transaction flag color ("red", "orange", "yellow", "green", "blue", "purple").
   - dry_run (boolean, optional): Preview without saving. Default: false.
+  - subtransactions (array, optional): Manual split lines. Each entry accepts "amount" (integer milliunits), plus optional "memo", "category_id", "payee_id", and "payee_name".
+
+Use "subtransactions" for manual split transactions. Use "ynab_create_receipt_split_transaction" when you have itemized receipt data and want proportional tax allocation handled for you.
+Advanced: "import_id" is supported, but it is intentionally not part of normal guidance. Usually omit it if you want the transaction to remain eligible for later bank-import matching.
 
 Returns: created transaction with account_balance.
 
@@ -335,18 +340,25 @@ Returns: summary (created, duplicates, failed), results[], transactions[].
 
 Examples:
   - Dry run first: set dry_run=true to validate before committing
-  - Avoid duplicate import: set import_id on each transaction`,inputSchema:v4,outputSchema:gv,handler:n(yF),defaultArgumentResolver:a(),metadata:{annotations:{...We.WRITE_EXTERNAL_CREATE,title:"YNAB: Create Multiple Transactions"}}}),e.register({name:"ynab_create_receipt_split_transaction",description:`Create a split transaction from itemized receipt data with proportional tax allocation.
+  - If you explicitly want YNAB-side duplicate import detection, set import_id on each transaction`,inputSchema:v4,outputSchema:gv,handler:n(yF),defaultArgumentResolver:a(),metadata:{annotations:{...We.WRITE_EXTERNAL_CREATE,title:"YNAB: Create Multiple Transactions"}}}),e.register({name:"ynab_create_receipt_split_transaction",description:`Create a split transaction from itemized receipt data with proportional tax allocation.
 
 Args:
   - budget_id (string, optional): Budget UUID. Omit to use the default budget.
   - account_id (string, required): Account UUID.
-  - payee_name (string, optional): Store/payee name.
+  - payee_name (string, required): Store/payee name.
   - receipt_total (number, required): Total amount in dollars (positive).
   - receipt_tax (number, required): Tax amount in dollars (0 if none).
   - categories (array, required): Category groups with items. Each item needs name, amount.
   - date (string, optional): ISO date. Default: today.
+  - memo (string, optional): Memo applied to the parent transaction.
+  - receipt_subtotal (number, optional): Pre-tax subtotal for validation.
+  - cleared (string, optional): "cleared", "uncleared", or "reconciled". Default: "uncleared".
+  - approved (boolean, optional): Mark as approved. Default: false.
+  - flag_color (string, optional): Transaction flag color ("red", "orange", "yellow", "green", "blue", "purple").
   - dry_run (boolean, optional): Preview subtransactions without saving. Default: false.
 
+Use this helper when you have receipt line items and want tax allocated across categories automatically. For generic manual split transactions without receipt/tax logic, use "ynab_create_transaction" with "subtransactions".
+
 Returns: transaction with subtransactions and receipt_summary.`,inputSchema:D7,outputSchema:bv,handler:n(hF),defaultArgumentResolver:a(),metadata:{annotations:{...We.WRITE_EXTERNAL_CREATE,title:"YNAB: Create Split Transaction from Receipt"}}}),e.register({name:"ynab_update_transaction",description:`Update fields on an existing YNAB transaction.
 
 Args:

package/dist/tools/transactionWriteTools.js

@@ -1309,7 +1309,12 @@ Args:
   - memo (string, optional): Memo text.
   - cleared (string, optional): "cleared", "uncleared", or "reconciled". Default: "uncleared".
   - approved (boolean, optional): Mark as approved. Default: false.
+  - flag_color (string, optional): Transaction flag color ("red", "orange", "yellow", "green", "blue", "purple").
   - dry_run (boolean, optional): Preview without saving. Default: false.
+  - subtransactions (array, optional): Manual split lines. Each entry accepts "amount" (integer milliunits), plus optional "memo", "category_id", "payee_id", and "payee_name".
+
+Use "subtransactions" for manual split transactions. Use "ynab_create_receipt_split_transaction" when you have itemized receipt data and want proportional tax allocation handled for you.
+Advanced: "import_id" is supported, but it is intentionally not part of normal guidance. Usually omit it if you want the transaction to remain eligible for later bank-import matching.
 
 Returns: created transaction with account_balance.
 
@@ -1339,7 +1344,7 @@ Returns: summary (created, duplicates, failed), results[], transactions[].
 
 Examples:
   - Dry run first: set dry_run=true to validate before committing
-  - Avoid duplicate import: set import_id on each transaction`,
+  - If you explicitly want YNAB-side duplicate import detection, set import_id on each transaction`,
         inputSchema: CreateTransactionsSchema,
         outputSchema: CreateTransactionsOutputSchema,
         handler: adaptWrite(handleCreateTransactions),
@@ -1358,13 +1363,20 @@ Examples:
 Args:
   - budget_id (string, optional): Budget UUID. Omit to use the default budget.
   - account_id (string, required): Account UUID.
-  - payee_name (string, optional): Store/payee name.
+  - payee_name (string, required): Store/payee name.
   - receipt_total (number, required): Total amount in dollars (positive).
   - receipt_tax (number, required): Tax amount in dollars (0 if none).
   - categories (array, required): Category groups with items. Each item needs name, amount.
   - date (string, optional): ISO date. Default: today.
+  - memo (string, optional): Memo applied to the parent transaction.
+  - receipt_subtotal (number, optional): Pre-tax subtotal for validation.
+  - cleared (string, optional): "cleared", "uncleared", or "reconciled". Default: "uncleared".
+  - approved (boolean, optional): Mark as approved. Default: false.
+  - flag_color (string, optional): Transaction flag color ("red", "orange", "yellow", "green", "blue", "purple").
   - dry_run (boolean, optional): Preview subtransactions without saving. Default: false.
 
+Use this helper when you have receipt line items and want tax allocated across categories automatically. For generic manual split transactions without receipt/tax logic, use "ynab_create_transaction" with "subtransactions".
+
 Returns: transaction with subtransactions and receipt_summary.`,
         inputSchema: CreateReceiptSplitTransactionSchema,
         outputSchema: CreateReceiptSplitTransactionOutputSchema,

package/docs/reference/API.md

@@ -915,6 +915,8 @@ Creates a new transaction in the specified budget and account.
 - `subtransactions` (array, optional): Split line items; each entry accepts `amount` (integer milliunits), plus optional `memo`, `category_id`, `payee_id`, and `payee_name`
 
 When `subtransactions` are supplied, their `amount` values must sum to the parent `amount` in milliunits, matching YNAB API requirements.
+Use `subtransactions` for manual split transactions. Use `create_receipt_split_transaction` when you have itemized receipt data and want proportional tax allocation handled automatically.
+Advanced: `import_id` is supported, but it is intentionally not part of normal guidance. Usually omit it if you want the transaction to remain eligible for later bank-import matching.
 
 **Example Request:**
 ```json
@@ -954,7 +956,7 @@ When `subtransactions` are supplied, their `amount` values must sum to the paren
 
 ### create_receipt_split_transaction
 
-Creates a split transaction from categorized receipt data and allocates taxes proportionally across the selected categories. Use this helper after the user has confirmed the receipt breakdown and category assignments.
+Creates a split transaction from categorized receipt data and allocates taxes proportionally across the selected categories. Use this helper after the user has confirmed the receipt breakdown and category assignments. For generic manual splits without receipt-tax logic, use `create_transaction` with `subtransactions`.
 
 **Parameters:**
 - `budget_id` (string, optional): The ID of the budget. Omit to use the default budget

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dizzlkheinz/ynab-mcpb",
-	"version": "0.26.6",
+	"version": "0.26.7",
 	"mcpName": "io.github.dizzlkheinz/ynab-mcpb",
 	"description": "Model Context Protocol server for YNAB (You Need A Budget) integration",
 	"main": "dist/index.js",

package/src/tools/transactionWriteTools.ts

@@ -2069,7 +2069,12 @@ Args:
   - memo (string, optional): Memo text.
   - cleared (string, optional): "cleared", "uncleared", or "reconciled". Default: "uncleared".
   - approved (boolean, optional): Mark as approved. Default: false.
+  - flag_color (string, optional): Transaction flag color ("red", "orange", "yellow", "green", "blue", "purple").
   - dry_run (boolean, optional): Preview without saving. Default: false.
+  - subtransactions (array, optional): Manual split lines. Each entry accepts "amount" (integer milliunits), plus optional "memo", "category_id", "payee_id", and "payee_name".
+
+Use "subtransactions" for manual split transactions. Use "ynab_create_receipt_split_transaction" when you have itemized receipt data and want proportional tax allocation handled for you.
+Advanced: "import_id" is supported, but it is intentionally not part of normal guidance. Usually omit it if you want the transaction to remain eligible for later bank-import matching.
 
 Returns: created transaction with account_balance.
 
@@ -2101,7 +2106,7 @@ Returns: summary (created, duplicates, failed), results[], transactions[].
 
 Examples:
   - Dry run first: set dry_run=true to validate before committing
-  - Avoid duplicate import: set import_id on each transaction`,
+  - If you explicitly want YNAB-side duplicate import detection, set import_id on each transaction`,
 		inputSchema: CreateTransactionsSchema,
 		outputSchema: CreateTransactionsOutputSchema,
 		handler: adaptWrite(handleCreateTransactions),
@@ -2122,13 +2127,20 @@ Examples:
 Args:
   - budget_id (string, optional): Budget UUID. Omit to use the default budget.
   - account_id (string, required): Account UUID.
-  - payee_name (string, optional): Store/payee name.
+  - payee_name (string, required): Store/payee name.
   - receipt_total (number, required): Total amount in dollars (positive).
   - receipt_tax (number, required): Tax amount in dollars (0 if none).
   - categories (array, required): Category groups with items. Each item needs name, amount.
   - date (string, optional): ISO date. Default: today.
+  - memo (string, optional): Memo applied to the parent transaction.
+  - receipt_subtotal (number, optional): Pre-tax subtotal for validation.
+  - cleared (string, optional): "cleared", "uncleared", or "reconciled". Default: "uncleared".
+  - approved (boolean, optional): Mark as approved. Default: false.
+  - flag_color (string, optional): Transaction flag color ("red", "orange", "yellow", "green", "blue", "purple").
   - dry_run (boolean, optional): Preview subtransactions without saving. Default: false.
 
+Use this helper when you have receipt line items and want tax allocated across categories automatically. For generic manual split transactions without receipt/tax logic, use "ynab_create_transaction" with "subtransactions".
+
 Returns: transaction with subtransactions and receipt_summary.`,
 		inputSchema: CreateReceiptSplitTransactionSchema,
 		outputSchema: CreateReceiptSplitTransactionOutputSchema,