[mforce]

A connected AI app can now submit a daily entry, and record feed use, water use, inventory purchases and expenses. Each action sits behind its own permission on the consent screen. Each one calls the REST route's own validator and handler, under that route's role policy.

Closes #1311
Closes #1313

Permissions

Consent permission	Scope	Tools	Roles
Read farm data	farm:read	the read tools (unchanged)	every role
Record daily entries	daily-entries:write	cluckwork_record_daily_entry (unchanged)	Owner, Manager, Worker
Submit daily entries	daily-entries:submit	cluckwork_submit_daily_entry	Owner, Manager, Worker
Record farm operations	operations:write	cluckwork_record_feed_usage, cluckwork_record_water_usage, cluckwork_record_inventory_purchase	Owner, Manager, Worker
Record expenses	expenses:write	cluckwork_record_expense	Owner, Manager

The scope names follow the existing <resource>:<verb> style. Submit shares the daily-entries resource with record because both act on the same record. A read tool requires exactly farm:read, and a write tool requires exactly one write scope. tools/list shows a tool only when the person's role and the token's scopes both allow it. The protected-resource metadata advertises all five scopes. The reasoning is in docs/decisions/1311-mcp-write-tools.md.

What changes for a farm

• Records take effect at once. Feed, water, purchases and expenses have no draft, as in the app. Every reply carries correctInApp, which names the screen and control where an Admin or Manager corrects the record. One example: "Feed records are never edited. An Admin or Manager corrects the stock with Correct stock on Inventory." Consent says these records count at once.
• Daily entries still start as a Draft. Only a person or the submit tool submits them. The submit tool takes the entry's id or a flock and date. It refuses an entry that is already submitted, with DailyEntry.NotDraft.
• No free text comes back. Notes, lot numbers and expense descriptions are accepted where REST accepts them, and are never returned.
• Audit. Feed use, water use and purchases now write an audit event (FeedUsage.Create, WaterUsage.Create, InventoryItem.Purchase), so each record names the person and the connected app. The REST routes write it too, because they share the handler. The Audit page's filters and labels gain the three actions in en, es and tl.
• Existing connections gain nothing silently. An app reconnects, and consent marks each new permission New. Claude Code asks for every advertised scope on reconnect, so it needs no setup change. I measured this with a throwaway config.

Reviewer guide

Start with these files:

• src/Cluckwork.Api/Mcp/McpWrite.cs: the MCP slice 6: write tool — record daily entry #809 claim, execute and publish protocol, moved out of the record tool. All six write tools use it. The record tool keeps its operation key, fingerprint and replay check.
• src/Cluckwork.Api/Mcp/DailyEntryTools.cs (submit), InventoryTools.cs (feed, water, purchase) and ExpenseTools.cs.
• McpNames.cs: items and expense categories match an active record exactly, ignoring case, or any record by id. A name shared by two farms is refused with both ids.
• web/src/auth/oauthScopes.ts: one table that drives both the consent screen and Connected apps.

The currency race (fixed in review). The expense and purchase tools convert a decimal using a currency read taken before the handler locks the account. If a currency change commits in between, the handler would stamp the new currency on the old figure. Each tool now compares the stored currency and precision and refuses with Money.CurrencyChanged. That failure rolls the whole record back through IdempotentUnit. The expense reply reports the stored amount.

Mechanical or guard files:

• tests/.../Architecture/Data/coupling-matrix.md is generated.
• RealModuleLedger.Adapters.cs gains two adapter rows.
• McpToolSurface.cs, McpToolSurfaceTests.cs and McpRouteParityTests.cs hold the scope rule and the reviewed reply-text list.
• tools/oauth/mutation-check.sh gains 16 rows. It also repairs 2 anchors: one my change moved, and rpc-429-as-problem, which was already stale on main.

Tests

• New McpWriteToolsTests (22 tests). They cover:
  • which write tools each scope and role lists;
  • submit by id and by flock and date;
  • a same-key retry that makes one set of lots;
  • each tool's audit row naming the app;
  • free text that is never echoed back;
  • a restricted Worker refused on another flock;
  • shared and inactive item names;
  • decimal precision;
  • two tools sharing one caller key (MCP slice 6: write tool — record daily entry #809 guard 20);
  • a controlled currency race for the expense and purchase tools.
• Local runs:
  • the MCP slice and the inventory, purchase, currency, simulation and expense slices together: 385 of 385;
  • OAuth, audit, history and related slices: 542 of 542, before the review fixes;
  • Application tests: 782 of 782;
  • web: 3887 of 3887.
• Mutations: I ran the 16 new rows and 4 existing rows whose code or anchor changed. All 20 were killed. The suite was green before and after each run, at 549 of 549 and then 551 of 551.
• The precache is 1529.79 KiB, against 1526.42 KiB on main and a ceiling of 1600 KiB.

Live run

I used the TypeScript MCP SDK client against an isolated stack behind TLS, with real consent and step-up.

1. Upgrade. An app connected with only Record daily entries, and its tools/list showed one tool. It then reconnected with the same client id. Consent marked Submit daily entries, Record farm operations and Record expenses New, and the five new tools appeared.
2. All five permissions. I recorded an entry and submitted it, which made 3 egg lots (94 Large, 3 Dirty, 2 Cracked). Then I recorded feed, water, a purchase and an expense. Each one appears on its screen in the app, and in the Audit log with "via Cluckwork live verifier".
3. Retry. Submitting again with the same key returned replayed: true with the same lot ids, and REST still shows one set of lots. A new key was refused with DailyEntry.NotDraft.
4. Roles. The restricted Worker's consent marks Record expenses "Not allowed for your role". Its expense call is refused. Feed and submit on an unassigned flock are refused as not found. Water on its assigned flock is recorded.

Screenshots follow in a comment.

[mforce]

Screenshots, at 1:1 from a stack rebuilt at ae160b3. The "before" frames come from main at 39228ed.

Consent, English. Before, an app asking for every scope saw two permissions. After, it sees five.

Reconnect. An app first allowed only Record daily entries asks again. The three new permissions are marked New.

Restricted Worker, with Details open. Record expenses is marked Not allowed for your role. The flock limit names daily entries, feed and water, and purchases are described as farm-wide.

Consent, Spanish.

Help, connected-app items, English and Spanish.