MCP: proposed-transaction flow with in-app approval (approve / deny / edit & create) #1

Open
opened 2026-11-22 00:05:39 +05:30 by ayush · 0 comments
Owner

Summary

The MCP server (app/Mcp/Servers/AccountingServer.php) is currently 13 read-only tools + the accounting://schema resource — every tool carries #[IsReadOnly] and nothing mutates data. Add a write path with a human approval gate: an agent, given a dump of already-done transactions, proposes transactions in bulk; nothing enters the ledger until the user reviews and explicitly approves each one in the app.

Why the gate

An agent parsing a dump can hallucinate or misread entries — unreviewed writes would leave bogus transactions in the ledger that the user must hunt down and delete. The design goal is: zero ledger changes without a human click.

Proposed shape (suggestions, not a mandate)

  • New MCP tool(s), e.g. propose-transactions (batch-friendly: agent dumps N parsed transactions in one call). Writes proposals, never Transaction rows. Follow existing tool conventions (SerializesAccountingData, schema validation with helpful messages like the existing year_month.regex message).
  • Proposal storage — a transaction_proposals table: payload (JSON, the exact create-data the agent wants), source note (dump context / agent session id), status (pending / approved / denied / edited), timestamps, and the created-transaction FK once approved.
  • Approval UI — a review queue in the app showing each proposed transaction as it would appear (item, amount, date, type, envelope, payment method, person, splits…). Per proposal the user can:
    • Approve — create as proposed
    • Deny — discard; must leave zero ledger traces
    • Edit & create — tweak fields first, then create
  • On approval, funnel through TransactionService::create() (and update() for the edit path) so every domain rule is enforced identically to manual entry via TransactionForm: integer paise amounts (_paise fields, 1 INR = 100), date must fall within the selected month, enum values exact (status/origin/account_type), envelope balance checks, splits and reimbursements consistency.
  • accounting://schema resource updated to document the proposal lifecycle and the new tool so agents can self-serve the conventions.

Tests

Feature tests mirroring tests/Feature/Mcp/*ToolTest.php:

  • propose-transactions accepts a batch and creates pending proposals (no transactions)
  • invalid payloads are rejected per-proposal (partial success semantics — decide and document: all-or-nothing vs per-item validation results)
  • approve → transaction exists, matches payload, domain rules enforced
  • deny → transaction absent, proposal marked denied
  • edit & create → created transaction matches the edited fields
  • MCP server instruction text updated (it currently states "No tool mutates data" — that must be re-scoped to "no tool mutates ledger data directly; proposals only")

Context

  • Entry points today: routes/ai.php mounts Mcp::web('/mcp/accounting', AccountingServer::class) behind auth:sanctum
  • Existing tools live in app/Mcp/Tools/, tests in tests/Feature/Mcp/
  • Related: the UI review-queue surface is presentation for this feature; see the UI redesign issue for the look-and-feel constraints (no processing-logic changes)
## Summary The MCP server (`app/Mcp/Servers/AccountingServer.php`) is currently 13 read-only tools + the `accounting://schema` resource — every tool carries `#[IsReadOnly]` and nothing mutates data. Add a **write path with a human approval gate**: an agent, given a dump of already-done transactions, *proposes* transactions in bulk; nothing enters the ledger until the user reviews and explicitly approves each one in the app. ## Why the gate An agent parsing a dump can hallucinate or misread entries — unreviewed writes would leave bogus transactions in the ledger that the user must hunt down and delete. The design goal is: **zero ledger changes without a human click**. ## Proposed shape (suggestions, not a mandate) - **New MCP tool(s)**, e.g. `propose-transactions` (batch-friendly: agent dumps N parsed transactions in one call). Writes *proposals*, never `Transaction` rows. Follow existing tool conventions (`SerializesAccountingData`, schema validation with helpful messages like the existing `year_month.regex` message). - **Proposal storage** — a `transaction_proposals` table: payload (JSON, the exact create-data the agent wants), source note (dump context / agent session id), status (`pending` / `approved` / `denied` / `edited`), timestamps, and the created-transaction FK once approved. - **Approval UI** — a review queue in the app showing each proposed transaction as it would appear (item, amount, date, type, envelope, payment method, person, splits…). Per proposal the user can: - **Approve** — create as proposed - **Deny** — discard; must leave zero ledger traces - **Edit & create** — tweak fields first, then create - **On approval, funnel through `TransactionService::create()`** (and `update()` for the edit path) so every domain rule is enforced identically to manual entry via `TransactionForm`: integer paise amounts (`_paise` fields, 1 INR = 100), date must fall within the selected month, enum values exact (status/origin/account_type), envelope balance checks, splits and reimbursements consistency. - **`accounting://schema` resource** updated to document the proposal lifecycle and the new tool so agents can self-serve the conventions. ## Tests Feature tests mirroring `tests/Feature/Mcp/*ToolTest.php`: - `propose-transactions` accepts a batch and creates pending proposals (no transactions) - invalid payloads are rejected per-proposal (partial success semantics — decide and document: all-or-nothing vs per-item validation results) - approve → transaction exists, matches payload, domain rules enforced - deny → transaction absent, proposal marked denied - edit & create → created transaction matches the edited fields - MCP server instruction text updated (it currently states "No tool mutates data" — that must be re-scoped to "no tool mutates ledger data directly; proposals only") ## Context - Entry points today: `routes/ai.php` mounts `Mcp::web('/mcp/accounting', AccountingServer::class)` behind `auth:sanctum` - Existing tools live in `app/Mcp/Tools/`, tests in `tests/Feature/Mcp/` - Related: the UI review-queue surface is presentation for this feature; see the UI redesign issue for the look-and-feel constraints (no processing-logic changes)
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
ayush/accounting#1
No description provided.