Draft: worker/mcp-proposals-a69e7b #3

Open
ayush wants to merge 8 commits from worker/mcp-proposals-a69e7b into main
Owner

Task spec:
Implement the MCP proposed-transaction flow with in-app approval (Forgejo
issue ayush/accounting#1) for this Laravel accounting app.

Background: the MCP server (app/Mcp/Servers/AccountingServer.php) currently
exposes 13 read-only tools plus the accounting://schema resource; every tool
carries #[IsReadOnly] and nothing mutates data. Add a write path gated on
human approval: 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 proposal in the app. Zero ledger
changes without a human click is the design goal.

Requirements:

  1. MCP tool propose-transactions (app/Mcp/Tools/ProposeTransactionsTool.php):

    • Batch-friendly: accepts N parsed transactions in one call.
    • Writes proposals only, never Transaction rows.
    • Follow existing tool conventions (SerializesAccountingData, schema
      validation with helpful messages like the existing year_month.regex
      message).
    • Decide and document (in the tool docblock) partial-success semantics:
      all-or-nothing vs per-item validation results.
  2. Proposal storage: transaction_proposals table with 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. Model + factory +
    migration, created via artisan make: commands.

  3. ProposalService with three outcomes:

    • approve: create the transaction exactly as proposed.
    • deny: discard; must leave zero ledger traces.
    • editAndCreate: apply field changes, then create.
      ALL transaction creation must funnel through TransactionService::create()
      (and update() where appropriate for the edit path) so domain rules are
      enforced identically to manual entry via TransactionForm: integer paise
      amounts (_paise fields, 1 INR = 100), date must fall within the selected
      month, exact enum values (status/origin/account_type), envelope balance
      checks, splits and reimbursements consistency.
  4. Approval UI: a Livewire review queue showing each proposed transaction
    as it would appear (item, amount, date, type, envelope, payment method,
    person, splits). Per proposal the user can Approve, Deny, or Edit &
    create. Follow existing Livewire component conventions in the repo.

  5. Update the accounting://schema resource to document the proposal
    lifecycle and the new tool so agents can self-serve the conventions.

  6. Update the MCP server instruction text: it currently states "No tool
    mutates data" — re-scope it to "no tool mutates ledger data directly;
    proposals only".

Tests (Pest, mirroring tests/Feature/Mcp/*ToolTest.php):

  • propose-transactions accepts a batch and creates pending proposals
    (no transactions created)
  • invalid payloads are rejected per-proposal
  • approve: transaction exists, matches payload, domain rules enforced
  • deny: transaction absent, proposal marked denied
  • edit & create: created transaction matches the edited fields
  • ProposalService coverage for all three outcomes

Working rules:

  • Read AGENTS.md at the repo root first and follow it; if .ai/rules exists,
    read its index and every rule file matching the paths you touch.
  • TDD: red-green-refactor; no stubs; tests before implementation.
  • Run composer install. Copy .env.example to .env; the test suite uses
    SQLite per phpunit.xml.
  • Run the narrowest test set while iterating (php artisan test --compact
    with a file path or --filter). Before finishing, run the full new test
    files plus the existing Mcp and Services suites, and
    vendor/bin/pint --dirty --format agent.
  • Do not change dependencies (composer.json / package.json). Do not push.
  • Commit all work on the work branch in accurate conventional commits. If
    any part cannot be completed, commit what works with its tests and state
    the remainder in your final message.

Acceptance:

  • propose-transactions tool creates pending proposals from a batch and creates zero Transaction rows
  • approving a proposal creates the transaction via TransactionService::create() matching the payload, with domain rules enforced
  • denying a proposal leaves zero ledger traces and marks the proposal denied
  • edit & create produces a transaction matching the edited fields
  • accounting://schema resource documents the proposal lifecycle and the new tool
  • MCP server instruction text re-scoped (no longer claims no tool mutates data)
  • all new tests pass and existing Mcp/Services suites stay green; pint clean on changed files
Task spec: Implement the MCP proposed-transaction flow with in-app approval (Forgejo issue ayush/accounting#1) for this Laravel accounting app. Background: the MCP server (app/Mcp/Servers/AccountingServer.php) currently exposes 13 read-only tools plus the accounting://schema resource; every tool carries #[IsReadOnly] and nothing mutates data. Add a write path gated on human approval: 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 proposal in the app. Zero ledger changes without a human click is the design goal. Requirements: 1. MCP tool propose-transactions (app/Mcp/Tools/ProposeTransactionsTool.php): - Batch-friendly: accepts N parsed transactions in one call. - Writes proposals only, never Transaction rows. - Follow existing tool conventions (SerializesAccountingData, schema validation with helpful messages like the existing year_month.regex message). - Decide and document (in the tool docblock) partial-success semantics: all-or-nothing vs per-item validation results. 2. Proposal storage: transaction_proposals table with 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. Model + factory + migration, created via artisan make: commands. 3. ProposalService with three outcomes: - approve: create the transaction exactly as proposed. - deny: discard; must leave zero ledger traces. - editAndCreate: apply field changes, then create. ALL transaction creation must funnel through TransactionService::create() (and update() where appropriate for the edit path) so domain rules are enforced identically to manual entry via TransactionForm: integer paise amounts (_paise fields, 1 INR = 100), date must fall within the selected month, exact enum values (status/origin/account_type), envelope balance checks, splits and reimbursements consistency. 4. Approval UI: a Livewire review queue showing each proposed transaction as it would appear (item, amount, date, type, envelope, payment method, person, splits). Per proposal the user can Approve, Deny, or Edit & create. Follow existing Livewire component conventions in the repo. 5. Update the accounting://schema resource to document the proposal lifecycle and the new tool so agents can self-serve the conventions. 6. Update the MCP server instruction text: it currently states "No tool mutates data" — re-scope it to "no tool mutates ledger data directly; proposals only". Tests (Pest, mirroring tests/Feature/Mcp/*ToolTest.php): - propose-transactions accepts a batch and creates pending proposals (no transactions created) - invalid payloads are rejected per-proposal - approve: transaction exists, matches payload, domain rules enforced - deny: transaction absent, proposal marked denied - edit & create: created transaction matches the edited fields - ProposalService coverage for all three outcomes Working rules: - Read AGENTS.md at the repo root first and follow it; if .ai/rules exists, read its index and every rule file matching the paths you touch. - TDD: red-green-refactor; no stubs; tests before implementation. - Run composer install. Copy .env.example to .env; the test suite uses SQLite per phpunit.xml. - Run the narrowest test set while iterating (php artisan test --compact with a file path or --filter). Before finishing, run the full new test files plus the existing Mcp and Services suites, and vendor/bin/pint --dirty --format agent. - Do not change dependencies (composer.json / package.json). Do not push. - Commit all work on the work branch in accurate conventional commits. If any part cannot be completed, commit what works with its tests and state the remainder in your final message. Acceptance: - propose-transactions tool creates pending proposals from a batch and creates zero Transaction rows - approving a proposal creates the transaction via TransactionService::create() matching the payload, with domain rules enforced - denying a proposal leaves zero ledger traces and marks the proposal denied - edit & create produces a transaction matching the edited fields - accounting://schema resource documents the proposal lifecycle and the new tool - MCP server instruction text re-scoped (no longer claims no tool mutates data) - all new tests pass and existing Mcp/Services suites stay green; pint clean on changed files
This pull request can be merged automatically.
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin worker/mcp-proposals-a69e7b:worker/mcp-proposals-a69e7b
git switch worker/mcp-proposals-a69e7b

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main
git merge --no-ff worker/mcp-proposals-a69e7b
git switch worker/mcp-proposals-a69e7b
git rebase main
git switch main
git merge --ff-only worker/mcp-proposals-a69e7b
git switch worker/mcp-proposals-a69e7b
git rebase main
git switch main
git merge --no-ff worker/mcp-proposals-a69e7b
git switch main
git merge --squash worker/mcp-proposals-a69e7b
git switch main
git merge --ff-only worker/mcp-proposals-a69e7b
git switch main
git merge worker/mcp-proposals-a69e7b
git push origin main
Sign in to join this conversation.
No reviewers
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!3
No description provided.