The same harvest problem as review_harvest, solved exactly rather than greedily

One command on the Portfolio lots and harvesting server, callable over MCP as optimize_harvest. Every result carries the method it used, the rule pack it was pinned to, what is still missing and whether coverage was complete, for a licensed professional to review.

What it needs, and why

Every input is checked before anything is calculated. subject_ref, document_ref, as_of, prices, idempotency_key and cash_target are required; the rest refine the answer.

Input	What it asks for	Why it matters	If you omit it
`subject_ref`	Account or household id you are entitled to read	The account or household the analysis is scoped to. Naming one is a request to read it, never a grant.	required
`document_ref`	Path to the normalized holdings export to analyse	Account metadata, lots and basis come from the export, and nothing resolves until one has been read.	required
`as_of`	Analysis date, YYYY-MM-DD	Holding periods and the 30-day wash-sale window are both measured from the analysis date.	required
`prices`	Price per share by security id, as decimal strings	A gain cannot be computed without a price per security, and no price is ever fetched or guessed here.	required
`idempotency_key`	Caller-chosen key	Repeating the key returns the first run instead of running again, so a retry cannot spend a gain budget twice.	required
`cash_target`	Cash to raise, as a decimal string	The objective is proceeds by a date. The gain budget is the constraint on reaching it, not the goal.	required
`withdrawal_account`	Account the cash is raised from	Cash is raised from a named account, which decides whose lots are sold and whose budget is spent.	optional
`gain_budget`	Cap on realized gains	A cap on realized gains is a decision rather than a default, and supplying one requires saying how it is measured.	optional
`netting_basis`	Whether the gain budget is measured net of losses or on gains alone one of `net_gains`, `gross_gains`	Gross and net readings of the same budget give different answers, so the server will not pick one for you.	optional
`period`	Tax period the budget applies to, e.g. "2026"	A budget belongs to a tax period, and gains already realized in that period consume the allowance.	optional
`planned_purchases`	Purchases already planned but not yet placed	A purchase a manager intends but has not placed can still create a wash sale, and only the caller knows about it.	optional

Requests it answers

“Can this harvest be proven the lowest-tax one?”
“Is there a selection that raises the cash for less tax?”

An agent with these skills loaded picks the command from phrasing like that, asks for whatever input is missing, and reports the figures with the method that produced them.

Run it

TAXAGENT_TENANT_ID=... TAXAGENT_PRINCIPAL_ID=... TAXAGENT_ACCOUNTS=... scripts/mcp_server.sh --server portfolio

The same command is exposed by taxagent-portfolio, so Claude, Claude Code, Codex, Cursor and any other MCP client can call it directly. Analysis only. No tool in this server places orders, modifies custodian records or files returns. Every result is scoped to the accounts this principal is entitled to read; an account named in an argument is a request, not a grant. Unknown basis blocks a lot rather than defaulting to zero.

Limits it inherits from taxagent-portfolio

Greedy selection; no optimality claim.
No multi-period or risk-aware objective.
Optimal means optimal over the lots, prices and constraints supplied, for the stated objective: reach the cash target, realize as little gain as possible, use as few trades as possible. It is not a statement about what the account should do.
Risk, tracking error, a client's view on a position and the reason a lot was bought are outside the model entirely.
Beyond 40 budget-consuming lots the search is not exhausted. The status degrades to feasible and a gap is reported; optimality is never claimed from a truncated search.
Account scope only. Running it once per account is not a household optimum.
Drift is the sum of absolute differences between current and target weight. The engine never sells more of a security than its overweight, so with chunky lots it under-trades rather than overshooting, and residual drift is expected and reported.
Buys are allocated across underweight securities in proportion to their shortfall. A purchase has no tax consequence, so there is nothing to optimise about which lot it becomes.
A buy is withheld when the security was sold at a loss inside the wash-sale window, which leaves that drift open until the window closes.
Requires advisor-supplied target weights. Inferring a target from the current holdings would make the portfolio its own benchmark.
Account scope only, and no view on transaction costs, market impact, tracking error or which account should hold which exposure.

The server, its other 8 commands and what it deliberately leaves alone are on the Portfolio lots and harvesting page.