finplan

FinPlan — Personal Finance Projection Engine

Future-focused projection engine accessed via MCP tools. Models current financial state and projects outcomes across scenarios, accounting for US tax law, goal priorities, and Monte Carlo uncertainty.

How to use FinPlan

All interaction is through MCP tools served at:

https://mcp.finplan.prethink.io/mcp

Do NOT call Python, import packages, or use the CLI. All capabilities are exposed as MCP tools.

MCP conventions

• Cold starts: The MCP server may sleep after inactivity. Call ping() as a lightweight warm-up before doing real work — it takes no parameters and returns server status, version, and auth state. If it fails, wait 5-10 seconds and retry. The /finplan:setup flow handles this automatically.
• Money inputs: Cents (integer). 10000000 = $100,000.00
• Money outputs: Both _cents and _dollars fields returned
• Displaying money: Money values from tools are in cents. Always reformat for display: divide by 100 and format as $X,XXX.XX (e.g., 10000000 → $100,000.00). Use the _dollars field when available for convenience, but the _cents field is the canonical value
• Rates/returns: Float decimals. 0.07 = 7%, 0.15 = 15%
• Percentages: Integer 0-100 for allocations. Float 0.0-1.0 for rates
• All tools return: success, summary/message, plus detailed fields

If MCP tools aren't available

If FinPlan tools don't appear in the deferred tools list (no mcp__claude_ai_FinPlan entries), the MCP connection failed to establish. Do NOT try to call MCP tools or curl the server directly — run /finplan:diagnose instead. It tests server reachability, authentication, and tool availability client-side and provides specific remediation steps.

File-Based Responses

Tools that produce large datasets always write full results to a file server and return URLs + compact inline summary. This keeps large arrays (timeseries, Chart.js specs, amortization schedules) out of the LLM context window.

# Example: 30-year projection
result = run_projection(
    initial_balance_cents=500_000_00,
    expected_annual_return=0.07,
    annual_volatility=0.15,
    time_horizon_months=360,
    monthly_contribution_cents=200_000,
)
# result["urls"]["data"] -> full time series JSON — NEVER read into context
# result["urls"]["schema"] -> data dictionary — read if you need to understand data structure
# result["summary"] -> key statistics (final balance percentiles) for immediate use

CRITICAL: NEVER load data files into context. This means:

• No Read tool on *_data.json files
• No WebFetch or fetch() on urls.data URLs
• No hardcoding data arrays extracted from tool responses as JS literals (e.g., const p50 = [100, 101, ...])

All three do the same thing: push hundreds of KB of time-series data through the context window, wasting tokens and producing brittle output. Instead:

• Use summary from the tool response for statistics, percentile values, and decision-making
• Use urls.schema or inline schemas in charts.md to understand data structure
• Use jq for targeted queries when you need specific values from data files
• Use the placeholder/inject pattern for any HTML that renders chart data (see charts.md)

Tools with file-based responses: run_projection, generate_mortgage_amortization_schedule, generate_projection_fan_chart, generate_account_breakdown_chart, generate_allocation_chart, generate_scenario_comparison_chart

See packages/file-tools.md for full details and the HTML embedding workflow.

Tool categories

When working with a specific area, read its detailed reference for tool names, parameters, and usage:

Category	What it does	Reference
Projections	Monte Carlo, closed-form, scenario comparison	packages/projection.md
Tax	Federal income tax, capital gains, after-tax projections	packages/tax.md
RMD	Required Minimum Distributions, IRS tables, penalties	packages/rmd.md
Accounts	Account types, allocations, ownership, creation	packages/accounts.md
Portfolio	Return assumptions, glide paths, characteristics	packages/portfolio.md
Goals	Financial goals, contribution calc, progress tracking	packages/goals.md
Social Security	Benefits, claiming strategies, spousal/survivor, PIA	packages/social-security.md
Mortgage	Monthly payments, amortization, P&I splits	packages/mortgage.md
Employer Match	401(k) matching formulas, vesting, calculations	packages/employer-match.md
Charts	Chart.js fan charts, account breakdowns, comparisons	packages/charts.md
File Tools	File-based responses, generate_data parameter	packages/file-tools.md
Profile & State	Person profiles, user state persistence	packages/state.md
Tool Search	Dynamic tool discovery, search across all tools	packages/tool-search.md
Reference Data	Static lookup tables: account types, enums, limits	packages/reference-data.md
System	Server ping, readiness check, auth verification	packages/system.md

State Persistence Guidelines

CRITICAL: User state must be persisted whenever information changes. Persistence is handled client-side via slash commands, not by the MCP server.

Client-side commands

These commands are bundled with the FinPlan plugin and available automatically after installation. See SETUP.md for installation instructions.

• /read-state — Read state from local JSON file using targeted jq queries (minimal token usage). Supports: /read-state, /read-state person, /read-state accounts, /read-state goals, /read-state account <id>, /read-state goal <id>.
• /save-state — Write the current state JSON to the local file system. Call after every state mutation.
• /projection-dashboard — Generate a self-contained HTML dashboard with goal-oriented Monte Carlo projections and interactive Chart.js charts.
• /profile — View and update the user's personal financial profile (age, income, employment, marital status, dependents).
• /accounts — View and manage financial accounts (balances, allocations, add/update accounts).
• /goals — View and manage financial goals with guided setup for common goal types (emergency fund, retirement, education, home, major purchase).
• /setup — Guided interview to create a complete financial profile, accounts, and goals from scratch.
• /checkup — Review an existing plan for life changes, update profile/accounts/goals, and identify gaps or new goals.

When to save state

Call /finplan:save-state immediately after ANY of these events:

• Creating a new user state
• Adding a new account to the state
• Adding a new goal to the state
• Updating person information (income, employment status, etc.)
• Modifying any account or goal details
• Any time the user provides new financial information

How to maintain state

1. Load state at session start — Use /finplan:read-state to load existing state from local file
2. Use state integration tools — Use manage_state(action="update_account") and manage_state(action="update_goal") to integrate created objects
3. Save after every change — Call /finplan:save-state immediately after each modification. Don't batch saves.
4. Use a consistent file path — Default: ./finplan_state.json

Common mistake to avoid

❌ Wrong: Create accounts and goals but never add them to state or save

state = manage_state(action="create", ...)   # Creates state
create_account(...)         # Creates account but it's lost!
create_goal(...)            # Creates goal but it's lost!
# User's accounts and goals are never persisted

✅ Correct: Use integration tools and save after each change

state = manage_state(action="create", ...)
/finplan:save-state

account = create_account(...)
state = manage_state(action="update_account", state_json=state, account_json=account["account"])
/finplan:save-state

goal = create_goal(...)
state = manage_state(action="update_goal", state_json=state, goal_json=goal["goal"])
/finplan:save-state

Recommended workflows

Quick projection: Use run_projection for fast analytical projections with percentile outputs. This is the recommended default.

New user setup: Run /finplan:setup for a guided interview that creates the profile, adds accounts, and sets up goals.

Full planning session:

1. /finplan:read-state to load existing state (or skip if starting fresh)
2. manage_state(action="create") → /finplan:save-state
3. For each account: create_account → manage_state(action="update_account") → /finplan:save-state
4. For each goal: create_goal → manage_state(action="update_goal") → /finplan:save-state
5. calculate_portfolio_characteristics for return/volatility assumptions
6. run_projection for projections
7. generate_projection_fan_chart to visualize results

Periodic review: Run /finplan:checkup to review the plan for life changes, update values, and identify new goals.

Quick updates: Use /finplan:profile, /finplan:accounts, or /finplan:goals to view or update individual sections.

Social Security analysis:

1. estimate_social_security_pia_from_salary to estimate PIA
2. estimate_social_security_benefits_all_ages to compare claiming ages
3. estimate_social_security_breakeven_age for claiming strategy
4. calculate_social_security_lifetime_benefits for total benefit comparison