Profile & State¶
Create and update operations.
Persistence (save/load) is handled client-side via /finplan:read-state and /finplan:save-state slash commands, not by the MCP server.
manage_state¶
Manage user state: create and modify financial profiles.
| Parameter | Type | Default | Description |
|---|---|---|---|
action |
string | required | Action to perform: 'create' - create new state from person info, 'update_account' - add or update account in state, 'update_goal' - add or update goal in state, 'update_person' - update (edit) person info in state, 'set_spouse' - set or replace the primary person's spouse, 'clear_spouse' - remove the primary person's spouse, 'update_income_stream' - add or update income stream in state, 'update_expense' - add or update expense in state, 'remove_account' - remove an account by account_id, 'remove_goal' - remove a goal by goal_id, 'remove_income_stream' - remove an income stream by income_stream_id, 'remove_expense' - remove an expense by expense_id |
state_json |
object | null | Current UserState as JSON dictionary. Required for: update_account, update_goal, update_person, set_spouse, clear_spouse, update_income_stream, update_expense, remove_account, remove_goal, remove_income_stream, remove_expense. |
person_json |
object | null | Person profile as JSON dict with fields: date_of_birth (YYYY-MM-DD), employment_status, annual_pretax_income_cents, marital_status, zipcode. Can also include number_of_dependents (int) which will be converted to dependents list. Optionally pia_cents_today_dollars (int) and pia_source, which must be supplied together: the Social Security benefit at full retirement age, in today's dollars, and where it came from (ssa_statement, estimated, user_input, from_earnings_record). estimate_social_security_pia_from_earnings_record returns both, as pia_cents_today_dollars and source — note its key is 'source', not 'pia_source'. Required for: create. Required for: update_person. |
spouse_json |
object | null | Spouse profile as JSON dict with the same fields as a person: date_of_birth (YYYY-MM-DD), employment_status, annual_pretax_income_cents, marital_status, zipcode, and the optional pia_cents_today_dollars / pia_source pair described under person_json — a spouse has their own PIA, which is what spousal and survivor benefits are computed against. Unlike person_json, this payload fully REPLACES the stored spouse, so one that omits the PIA pair drops it; when editing a saved spouse, carry the existing pia_cents_today_dollars and pia_source forward or they are silently lost. Omitting id keeps the existing spouse's id (or mints one for a first spouse); pass an explicit id to swap in a different person. The primary person must be married. Required for: set_spouse. |
account_json |
object | null | Account to add/update (from create_account result). Required for: update_account. |
goal_json |
object | null | Goal to add/update (from create_goal result). Required for: update_goal. |
income_stream_json |
object | null | Income stream to add/update (from create_income_stream result). Required for: update_income_stream. The payload fully REPLACES the stored item, so one that omits price_level is read as a newly authored REAL item; when editing a saved item, carry its existing price_level forward or its frame silently changes. |
expense_json |
object | null | Expense to add/update (from create_expense result). Required for: update_expense. The payload fully REPLACES the stored item, so one that omits price_level is read as a newly authored REAL item; when editing a saved item, carry its existing price_level forward or its frame silently changes. |
account_id |
string | null | account_id of the account to remove. Required for: remove_account. |
goal_id |
string | null | id of the goal to remove. Required for: remove_goal. |
income_stream_id |
string | null | id of the income stream to remove. Required for: remove_income_stream. |
expense_id |
string | null | id of the expense to remove. Required for: remove_expense. |
return_full_state |
bool | false |
When False (default), every mutating action (all actions except 'create') returns only the changed section plus a 'state_hash' instead of echoing the whole document back — apply the 'changed' item to the state_json you passed in to rebuild it. Set True to receive the full UserState inline (for callers that do not keep their own copy). Ignored by 'create', which always returns the full document. |
migrate_state¶
Upgrade a state document to the current schema and return it as a download.
| Parameter | Type | Default | Description |
|---|---|---|---|
state_json |
object | required | A finplan_state document to upgrade to the current schema. May be unstamped or stale; it is validated and re-stamped on the way through. |
Returns {success, urls, summary} on success (the migrated document lives at urls.data; summary carries kind, schema_hash, migrated, schema_drift, warnings), or an error envelope with structured errors when the document cannot validate.