artist-mcp: Instructions file for Claude Code

artist-mcp

An npm-published MCP server that reads a user's OneNote notes, signing in to Microsoft and Google on the user's own machine, plus a small web app for sign-in and the install instructions.

Scope, what shipped, and the open gaps are docs/scope.md. Read it before starting work. It is the source of truth for scope and for what is actually done — a ticked box means done and verified, and blocked items say why. Update it as you go rather than at the end.

Scope is deliberately narrow. The workflow layer is defined in apps/mcp/agent-pack: one OneNote page is one working unit, Markdown roles and project types are loaded at runtime, and every result stays in chat.

If you find yourself adding writes, sends, or synchronization, stop. That rule stands, with four exceptions, and none of them is a precedent.

An install granted --allow-writes calendar-create may create a single Google Calendar event, previewed and confirmed, and one granted calendar-delete may remove an event that this tool itself created, identified by the artist prefix on its id. An install holding both may also reschedule one, which is those two writes in one confirmed step — a create then a delete, never a PATCH, because the event id is a hash of the event's own contents. An event the musician made is unreachable, and that prefix check is the only thing making delete safe to offer. Read docs/decisions/0001-opt-in-calendar-writes.md before touching that path — it says what was decided, what it cost, and what would reverse it.

An install granted onenote-create may create a new OneNote page, previewed and confirmed. That capability alone cannot edit or delete any page, including one it created, and that is not a rule this repository keeps — the scope is Notes.Create, which cannot express an edit or a delete, verified as a 403 on both against a page the token had just created itself. This is the inverse of the calendar situation, where no insert-only scope exists and the boundary had to become our code. Read docs/decisions/0003-onenote-writes.md before touching that path.

Editing is a separate grant, and it shipped. Notes.ReadWrite would hand back edit and delete over every page and put the boundary in our code again — but it was not the only door. An install granted onenote-edit holds Notes.ReadWrite.CreatedByApp, which Microsoft enforces against this app's own pages, verified as 401 on a page the musician wrote, and under it an element-level replace is both surgical and recoverable from a pre-image captured before every write — no capture, no write. docs/decisions/0004-onenote-page-maintenance.md was built and verified end to end on 2026-08-31, and that live run is what found its last two defects; nothing else did. 0006 extends it to tables, which is where a filled-in page actually keeps its content: OneNote supports no update to a row or a cell, so the unit is the whole table, written as markup and previewed as rows. That widens what one confirmed change can destroy, and it amends policy:patch's smallest-fragment rule rather than quietly breaking it — read it before touching either. Deleting stays out.

Message sending and synchronization remain out, and the reasoning is in the records rather than restated here.

Sources are read-only apart from those grants, and deliberately few. OneNote holds the working unit; Gmail and Google Calendar are supporting evidence only — they corroborate or fill gaps in a page and are never themselves a working unit. That asymmetry is the whole reason further sources did not dissolve the one-page-one-unit rule that every role and playbook depends on. Each new source means re-deciding it, not repeating it: Google Tasks was considered and left out, because a task list is a rival system of record for the work itself rather than evidence about it.