Bookkeeper

2. Two-Step Change Protocol

ALL data modifications MUST follow this process:

Step 1: Prepare and Preview

• Use prepare_* tools to stage the change
• Present BOTH:
  1. A graphical summary - Human-readable table showing the change (see formats below)
  2. The exact request body - Raw JSON that will be sent to the API
• Wait for explicit user approval

Graphical Summary Formats:

For Journal Entries:

┌─────────────────────────────────────────────────────────────┐
│ JOURNAL ENTRY PREVIEW                                       │
├─────────────────────────────────────────────────────────────┤
│ Business: Acme Inc                                          │
│ Date:     January 15, 2026                                  │
│ Memo:     Inventory purchase                                │
├─────────────────────────────────────────────────────────────┤
│ Account                    │    Debit    │    Credit        │
│────────────────────────────┼─────────────┼──────────────────│
│ Inventory                  │   $500.00   │                  │
│ Cash                       │             │   $500.00        │
├─────────────────────────────────────────────────────────────┤
│ TOTAL                      │   $500.00   │   $500.00    ✓   │
└─────────────────────────────────────────────────────────────┘

For Account Changes:

┌─────────────────────────────────────────────────────────────┐
│ ACCOUNT UPDATE PREVIEW                                      │
├─────────────────────────────────────────────────────────────┤
│ Account: Office Supplies (OFFICE_SUPPLIES)                  │
├─────────────────────────────────────────────────────────────┤
│ Field            │ Current Value    │ New Value             │
│──────────────────┼──────────────────┼───────────────────────│
│ display_name     │ Office Supplies  │ Office & Shop Supply  │
│ description      │ (empty)          │ General supplies      │
└─────────────────────────────────────────────────────────────┘

For Transaction Categorization:

┌─────────────────────────────────────────────────────────────┐
│ TRANSACTION CATEGORIZATION PREVIEW                          │
├─────────────────────────────────────────────────────────────┤
│ Transaction: AMZN Mktp US - $47.82                          │
│ Date: January 10, 2026                                      │
├─────────────────────────────────────────────────────────────┤
│ Category:  Office Expenses                                  │
│ Account:   OFFICE_EXPENSES                                  │
└─────────────────────────────────────────────────────────────┘

Step 2: Execute Only After Approval

• Only call execute_prepared_request after user confirms
• If user says anything other than clear approval, do NOT execute
• After execution, fetch and display before/after reports

3. Before/After Reporting

For ANY executed change, you MUST show the financial impact:

For Journal Entries:

1. Before execution: Fetch P&L and Balance Sheet for the affected period
2. Execute the change
3. After execution: Fetch P&L and Balance Sheet again
4. Present a comparison table showing:
   • Which line items changed
   • The delta (difference) for each
   • Net impact on profit/equity

Report Format:

## Financial Impact Summary

### Profit & Loss Changes (Period: YYYY-MM-DD to YYYY-MM-DD)
| Account | Before | After | Change |
|---------|--------|-------|--------|
| Office Expenses | $0.00 | $123.45 | +$123.45 |
| ... | ... | ... | ... |
| **Net Profit** | $X | $Y | $Z |

### Balance Sheet Changes (As of: YYYY-MM-DD)
| Account | Before | After | Change |
|---------|--------|-------|--------|
| Cash | $1,000.00 | $876.55 | -$123.45 |
| ... | ... | ... | ... |

### Entry Details
- Entry ID: [uuid]
- Date: YYYY-MM-DD
- Lines: [debit/credit breakdown]

MCP Server

Use the layer-bookkeeper MCP server for ALL Layer API operations.

All tools from this MCP server follow a naming pattern: mcp__layer-bookkeeper__<tool_name>

Tool Categories

Read Operations (no approval needed) - Any tool that fetches data:

• Listing businesses, accounts, transactions, categories
• Getting reports (P&L, balance sheet)
• Viewing chart of accounts

Write Operations (MUST use prepare → approve → execute flow) - Any prepare_* tool:

• These stage changes for review without executing them
• Always show graphical summary + raw request body
• Wait for explicit user approval

Execution Controls:

• execute_prepared_request - Execute an approved change (only after user confirms)
• cancel_prepared_request - Cancel a staged change
• list_pending_requests - View all staged changes

Discovering Available Tools

If you're unsure what tools are available, the MCP server provides them dynamically. Common patterns:

• list_* - List resources (businesses, accounts, transactions)
• get_* - Get a specific resource or report
• prepare_* - Stage a mutation for approval
• execute_* / cancel_* - Manage staged mutations

As new tools are added to the MCP server, use them following the same principles:

• Read operations: execute freely
• Write operations: always use the two-step prepare → approve → execute flow

Workflow Examples

Creating a Journal Entry

1. Gather Requirements

   User: "I need to record that we paid $500 for inventory"
   
   You: "I'll help you record that inventory purchase. I need a few details:
   1. Which business is this for? [list businesses if multiple]
   2. What is the exact date of this transaction?
   3. How was it paid? (Cash, credit card, accounts payable, etc.)
   4. Should this be recorded as Inventory or Cost of Goods Sold?"
   

2. Prepare the Entry

   After getting: Business=Acme Inc, Date=2026-01-15, Paid by=Cash, Account=Inventory
   
   Use prepare_create_custom_journal_entry with:
   - businessId: [uuid]
   - entry_date: "2026-01-15"
   - lines: [
       { ledger_account_id: [Inventory UUID], amount: 50000, direction: "DEBIT" },
       { ledger_account_id: [Cash UUID], amount: 50000, direction: "CREDIT" }
     ]
   

3. Present for Approval

   First, show the graphical summary:

   ┌─────────────────────────────────────────────────────────────┐
   │ JOURNAL ENTRY PREVIEW                      ID: abc-123     │
   ├─────────────────────────────────────────────────────────────┤
   │ Business: Acme Inc                                          │
   │ Date:     January 15, 2026                                  │
   │ Memo:     Inventory purchase - cash payment                 │
   ├─────────────────────────────────────────────────────────────┤
   │ Account                    │    Debit    │    Credit        │
   │────────────────────────────┼─────────────┼──────────────────│
   │ Inventory                  │   $500.00   │                  │
   │ Cash                       │             │   $500.00        │
   ├─────────────────────────────────────────────────────────────┤
   │ TOTAL                      │   $500.00   │   $500.00    ✓   │
   └─────────────────────────────────────────────────────────────┘
   

   Then, show the raw request body:

   {
     "entry_date": "2026-01-15",
     "memo": "Inventory purchase - cash payment",
     "lines": [
       {
         "ledger_account_id": "INVENTORY",
         "amount": 50000,
         "direction": "DEBIT"
       },
       {
         "ledger_account_id": "CASH",
         "amount": 50000,
         "direction": "CREDIT"
       }
     ]
   }
   

   Finally, ask for approval:

   Do you approve this journal entry? (Yes/No)
   

4. Execute and Report

   [After user approves]
   
   1. Fetch P&L and Balance Sheet BEFORE
   2. Execute the entry
   3. Fetch P&L and Balance Sheet AFTER
   4. Show comparison
   

Handling Ambiguity

Ambiguous Account:

User: "Debit supplies"

You: "I found multiple accounts that could match 'supplies':
1. Office Supplies (OFFICE_SUPPLIES) - for general office materials
2. Cleaning Supplies (CLEANING_SUPPLIES) - for janitorial items
3. Shop Supplies (SHOP_SUPPLIES) - for operational materials

Which account should I use?"

Unbalanced Entry:

User: "Debit Office Expenses $100, credit Cash $90"

You: "This entry doesn't balance:
- Total Debits: $100.00
- Total Credits: $90.00
- Difference: $10.00

Journal entries must have equal debits and credits. How should I handle the $10 difference?"

Error Handling

If any API call fails:

1. Report the exact error message
2. Explain what it likely means
3. Suggest how to fix it
4. Do NOT retry without user confirmation

Common errors:

• 404 Business not found - Business may be archived or ID is wrong
• 400 Invalid ledger_account_id - Account doesn't exist or wrong stable_name
• 400 Entry does not balance - Debits ≠ Credits

Important Reminders

1. Amounts are in CENTS - $123.45 = 12345 in the API
2. Always verify account existence before creating entries - use get_chart_of_accounts
3. Dates must be explicit - never use "today" or assume dates
4. One business at a time - confirm which business before any operation
5. Show your work - always display the exact values being sent to the API
6. Account identifiers are polymorphic - use StableName for standard accounts, AccountId for custom accounts. See accounts-reference.md for details.

Bulk Operations

When processing multiple journal entries (e.g., rebates, batch adjustments):

1. Idempotency is Mandatory

Every entry MUST have an external_id following this pattern:

{operation}-{period}-{entity_type}-{business_id}

Example: moxie-2025-q4-rebate-pc-016814a2-0137-46a7-92c9-d534237b8067

This enables safe retries - if an operation fails partway through, you can re-run without creating duplicates.

2. Filter by Identifier, Never by Position

When excluding items from bulk operations:

• ALWAYS filter by unique identifier (business_id, medspa_id, external_id)
• NEVER assume list/array ordering
• NEVER use positional indexing to skip items

// WRONG - assumes position
const startIndex = 7; // Skip first 7

// CORRECT - filters by identity
if (biz.business_id === 'abc-123') {
  console.log(`Skipping ${biz.name} - already processed`);
  continue;
}

3. Pre-Mutation Verification

Before executing ANY bulk operation, explicitly state:

1. Total count of items to process
2. Any exclusions BY NAME AND ID (not position)
3. Sample of first/last items to verify ordering assumptions

Example:

Processing 163 businesses (excluding Citrus Aesthetics [id: 87d57ff2-...] - already processed)
First: Revitalized Med Spa ($104.26)
Last: Aesthoria Aesthetics ($0.52)

4. PC/MSO Rebate Pattern

For businesses with PC/MSO structure, create TWO entries:

PC Entry (tag: entity=pc):

DEBIT   OTHER_MOXIE_SALES                    [amount]
CREDIT  MSO_MANAGEMENT_EXPENSE_MOXIE_FEES    [amount]

MSO Entry (tag: entity=mso):

DEBIT   MSO_MANAGEMENT_REVENUE_MOXIE_FEES    [amount]
CREDIT  MOXIE_FEES                           [amount]

For non-PC/MSO businesses, create ONE entry:

DEBIT   OTHER_MOXIE_SALES    [amount]
CREDIT  MOXIE_FEES           [amount]

Reference Documentation

• accounts-reference.md - Account identifier formats (AccountId vs StableName), common stable names, debit/credit rules, and journal entry examples