Add piggy bank management tools

[RadCod3]

Feature Request

Add MCP tools for managing Firefly III piggy banks, enabling users to track savings goals and manage piggy bank allocations through the LamPyrid server.

Motivation

Firefly III's piggy bank feature allows users to save money for specific goals (emergency fund, vacation, new car, etc.) by allocating funds from asset accounts. Currently, LamPyrid supports accounts, transactions, and budgets, but lacks piggy bank functionality.

Adding piggy bank tools would enable:

• Creating and managing savings goals
• Tracking progress towards financial targets
• Allocating funds to/from piggy banks
• Viewing piggy bank balances and status
• Automated savings workflows and analysis

This completes the core personal finance management capabilities of LamPyrid.

Proposed Implementation

New Tools

Implement the following MCP tools in a new tools/piggy_banks.py module:

1. list_piggy_banks

   • List all piggy banks with current balances
   • Optional filtering by account
   • Returns: name, target amount, current amount, percentage saved, linked account

2. get_piggy_bank

   • Get detailed information for a specific piggy bank
   • Parameters: piggy_bank_id
   • Returns: full piggy bank details including save history

3. create_piggy_bank

   • Create a new piggy bank/savings goal
   • Parameters: name, account_id, target_amount, start_date, target_date (optional), notes (optional)
   • Returns: created piggy bank details

4. update_piggy_bank

   • Update piggy bank details (name, target, dates, etc.)
   • Parameters: piggy_bank_id, updated fields
   • Returns: updated piggy bank details

5. delete_piggy_bank

   • Delete a piggy bank
   • Parameters: piggy_bank_id
   • Returns: success confirmation

6. add_to_piggy_bank

   • Add money to a piggy bank
   • Parameters: piggy_bank_id, amount, date (optional)
   • Returns: updated balance and transaction details

7. remove_from_piggy_bank

   • Remove money from a piggy bank
   • Parameters: piggy_bank_id, amount, date (optional)
   • Returns: updated balance and transaction details

Implementation Details

New Models in lampyrid_models.py:

• PiggyBank: Core piggy bank information
• PiggyBankWithBalance: Piggy bank with current savings and percentage
• CreatePiggyBankRequest: Request model for creation
• UpdatePiggyBankRequest: Request model for updates
• PiggyBankAllocationRequest: Request model for add/remove operations

New Client Methods in clients/firefly.py:

• list_piggy_banks(): GET /v1/piggy-banks
• get_piggy_bank(piggy_bank_id): GET /v1/piggy-banks/{id}
• create_piggy_bank(data): POST /v1/piggy-banks
• update_piggy_bank(piggy_bank_id, data): PUT /v1/piggy-banks/{id}
• delete_piggy_bank(piggy_bank_id): DELETE /v1/piggy-banks/{id}
• list_piggy_bank_events(piggy_bank_id): GET /v1/piggy-banks/{id}/events (for history)

Note: The Firefly III API handles money allocation through piggy bank events, not direct balance updates. The add/remove tools should use the events API.

Files to Create/Modify

1. src/lampyrid/tools/piggy_banks.py (NEW)

   • Create new tool module with all 7 tools
   • Follow existing tool patterns from accounts.py and transactions.py
   • Use proper tagging and documentation

2. src/lampyrid/tools/init.py

   • Add piggy bank server composition to compose_all_servers()

3. src/lampyrid/models/lampyrid_models.py

   • Add piggy bank models with proper field documentation

4. src/lampyrid/clients/firefly.py

   • Add piggy bank client methods

5. README.md

   • Document new piggy bank tools in the tools list

6. CLAUDE.md

   • Update tool counts and add piggy bank section

API Endpoints

Based on Firefly III OpenAPI spec (firefly-iii-6.4.14-v1.yaml):

• GET /v1/piggy-banks: List all piggy banks
• POST /v1/piggy-banks: Create piggy bank
• GET /v1/piggy-banks/{id}: Get piggy bank details
• PUT /v1/piggy-banks/{id}: Update piggy bank
• DELETE /v1/piggy-banks/{id}: Delete piggy bank
• GET /v1/accounts/{id}/piggy-banks: List piggy banks for account
• GET /v1/piggy-banks/{id}/events: List piggy bank events (money in/out)
• POST /v1/piggy-banks/{id}/events: Add event (money in/out)

Example Usage

# Create a piggy bank for emergency fund
piggy = await create_piggy_bank(
    name="Emergency Fund",
    account_id=1,
    target_amount=10000.00,
    notes="6 months of expenses"
)

# Add money to the piggy bank
await add_to_piggy_bank(
    piggy_bank_id=piggy.id,
    amount=500.00
)

# List all piggy banks to see progress
piggy_banks = await list_piggy_banks()

# Check specific piggy bank details
details = await get_piggy_bank(piggy_bank_id=1)

Benefits

• Completes core personal finance management feature set
• Enables savings goal tracking and automation
• Consistent API design with existing tools
• Full CRUD operations for flexibility
• Supports both manual and automated savings workflows

Implementation Notes

• Follow the existing modular tool organization pattern
• Ensure comprehensive error handling for all operations
• Add proper Pydantic validation for all models
• Include detailed docstrings and examples
• Tag tools appropriately for organization