WIP: docs(design): actions and MCP, the assistant does what the signed-in person may do #104

2026-11-11T23:06:10Z

james.maes commented

2026-11-11 23:06:10 +00:00

Draft design and work plan for owner review. Documentation only: no code changes, nothing implemented. Do not merge until the owner has decided the six items in section 11.1.

What this is

docs/actions-and-mcp.md designs three things, in delivery order:

Writes follow the person's permissions by default. Data access defaults are declared in code (READ_WRITE for tables, runnable for processes), an administrator's row can only restrict, and every write is confirmed on a card that shows the record and its values before and after.
New tools: run a process the person may run, create and edit saved reports and saved analyses, schedule delivery by email with the result in the body and as an attachment.
An MCP endpoint that serves the same tool registry as chat: read-only first, then writes as proposals the person approves in the application.

The binding rule throughout: the signed-in person is the permissions boundary. No tool, schedule or outside agent gets more than the person holds.

docs/DESIGN.md gets a one-line pointer under "Next phases".

Main choices

Question	Choice
Where defaults live	Code. A database row can only narrow.
Confirmation	Always. The policy switch that turns it off is retired.
What the card shows	The record, each field now and after, expiry, where the proposal came from. Re-read on confirmation; refused if the record changed.
Long process runs	Core's durable jobs, which core itself holds until the person starts them.
Report or analysis	Numbers by group: an analysis. The records themselves: a report. The assistant says which and why.
Scheduled runs	As the owner, through the service identity model core already has. First slice: analyses.
MCP transport	One spec'd `/qqq/v1` operation in this module, no SDK at runtime, the SDK's client as the test reference.
MCP channel	The `assistant` channel with an `mcp` detail, so every existing deny rule applies.
One tool surface	A registry used by chat and MCP, with a build test that they expose the same tools.
Health data over MCP	Refused, and unclassified data is refused too.

What a reviewer should look at

Section 11.1: six decisions for the owner, each with a recommendation.
Section 3.3: this withdraws two earlier owner decisions (optional confirmation and auto-confirm; the per-conversation write switch). Open draft #21 implements that switch and would be closed, not merged, if the owner confirms.
Section 6.4: core's saved-report email path makes the stored file public. The design does not use it and asks for a core fix before any application schedules reports.
Section 7.13: six things the MCP design depends on that are not yet proven. They are the first tests of the MCP work, before anything is built on them.
Section 13: where each statement about existing behaviour was read, and which were read by a researcher and not re-read.

Verification

No build or test was run for this pull request: it changes two Markdown files and no code.
Statements about existing behaviour were read in the code at the refs listed in section 0, except those marked (R) in section 13.
The repository's CI will run on this branch as on any push.

Not in this document

Details of any particular application that adopts this (its current pins, configuration and what blocks it) are deliberately left out of this public repository. They belong in that application's own repository.

This document was written with substantial AI assistance (see the commit trailers) and has not yet been reviewed by a person.

🤖 Generated with Claude Code

Draft design and work plan for owner review. **Documentation only: no code changes, nothing implemented.** Do not merge until the owner has decided the six items in section 11.1. ## What this is `docs/actions-and-mcp.md` designs three things, in delivery order: 1. **Writes follow the person's permissions by default.** Data access defaults are declared in code (READ_WRITE for tables, runnable for processes), an administrator's row can only restrict, and every write is confirmed on a card that shows the record and its values before and after. 2. **New tools:** run a process the person may run, create and edit saved reports and saved analyses, schedule delivery by email with the result in the body and as an attachment. 3. **An MCP endpoint** that serves the same tool registry as chat: read-only first, then writes as proposals the person approves in the application. The binding rule throughout: the signed-in person is the permissions boundary. No tool, schedule or outside agent gets more than the person holds. `docs/DESIGN.md` gets a one-line pointer under "Next phases". ## Main choices | Question | Choice | |---|---| | Where defaults live | Code. A database row can only narrow. | | Confirmation | Always. The policy switch that turns it off is retired. | | What the card shows | The record, each field now and after, expiry, where the proposal came from. Re-read on confirmation; refused if the record changed. | | Long process runs | Core's durable jobs, which core itself holds until the person starts them. | | Report or analysis | Numbers by group: an analysis. The records themselves: a report. The assistant says which and why. | | Scheduled runs | As the owner, through the service identity model core already has. First slice: analyses. | | MCP transport | One spec'd `/qqq/v1` operation in this module, no SDK at runtime, the SDK's client as the test reference. | | MCP channel | The `assistant` channel with an `mcp` detail, so every existing deny rule applies. | | One tool surface | A registry used by chat and MCP, with a build test that they expose the same tools. | | Health data over MCP | Refused, and unclassified data is refused too. | ## What a reviewer should look at - Section 11.1: six decisions for the owner, each with a recommendation. - Section 3.3: this withdraws two earlier owner decisions (optional confirmation and auto-confirm; the per-conversation write switch). Open draft #21 implements that switch and would be closed, not merged, if the owner confirms. - Section 6.4: core's saved-report email path makes the stored file public. The design does not use it and asks for a core fix before any application schedules reports. - Section 7.13: six things the MCP design depends on that are not yet proven. They are the first tests of the MCP work, before anything is built on them. - Section 13: where each statement about existing behaviour was read, and which were read by a researcher and not re-read. ## Verification - No build or test was run for this pull request: it changes two Markdown files and no code. - Statements about existing behaviour were read in the code at the refs listed in section 0, except those marked (R) in section 13. - The repository's CI will run on this branch as on any push. ## Not in this document Details of any particular application that adopts this (its current pins, configuration and what blocks it) are deliberately left out of this public repository. They belong in that application's own repository. This document was written with substantial AI assistance (see the commit trailers) and has not yet been reviewed by a person. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

james.maes added 2 commits 2026-11-11 23:06:11 +00:00

docs(design): actions and MCP, the assistant does what the signed-in person may do

maven / build (push) Successful in 5m31s

Details

build / maven (push) Successful in 5m31s

Details

798acd5541

Draft design and work plan for owner review. Nothing is implemented here.

- Writes follow the person's permissions by default: data access defaults
  declared in code, an administrator can only restrict, every write is
  confirmed on a card that shows the values before and after.
- New tools: run a process the person may run, create and edit saved
  reports and saved analyses, schedule delivery by email.
- An MCP endpoint that serves the same tool registry as chat: read-only
  first, then writes as proposals approved in the application.
- Test strategy, repositories and release order, risks, decisions for the
  owner, and work packages that can be built in parallel.

docs/DESIGN.md gets a pointer under "Next phases".

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

docs(design): name the open write-mode draft the design would replace

maven / build (push) Successful in 4m48s

Details

build / maven (push) Successful in 4m48s

Details

694309f528

The write-mode switch is not on develop but exists as an open draft
pull request (#21). Say so, and say what happens to it if the owner
confirms that every write is confirmed.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

james.maes referenced this pull request

2026-11-12 00:02:26 +00:00

refactor(tools): one tool registry (no behaviour change); build against QQQ 4.1.0-RC.32 #105

james.maes referenced this pull request

2026-11-12 19:18:50 +00:00

feat(access): writes follow the signed-in person; no answer without a spending limit; a fourth review of the tool boundary closed #109

All checks were successful

maven / build (push) Successful in 4m48s

Details

build / maven (push) Successful in 4m48s

Details

This branch is already included in the target branch. There is nothing to merge.