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, and one granted calendar-delete may remove an event. An event this tool created (the artist prefix on its id) goes in one call; any other event is shown first and removed only with a confirmation token. An install holding both may reschedule an event this tool created (a create then a delete), and may edit any event in place with edit_calendar_event, always behind a confirmation bound to the event's etag, with its pre-image recorded and nobody emailed. Invitations from others and whole recurring series are refused. Until 0013 the prefix kept the musician's events unreachable; now the confirmation is what protects them, and it is still only our code — Google's scope allows all of it. Read 0001 and 0013 before touching that path. Confirmation follows what a write can destroy: every write this tool can undo commits in one call, and a write that overwrites or removes the musician's own content keeps a preview and a token — edit_onenote_page, edit_calendar_event, and deleting an event this tool did not create. See 0009 before adding a preview back or taking the last one away.

An install granted onenote-create may create a new OneNote page. 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.

An install granted onenote-create-section may create a new, empty section in a notebook, under the same Notes.Create boundary: it cannot rename or delete one. Hosted users who already held onenote-create were given it by migration rather than asked again, which is a one-off for an invite-only deployment and not a precedent. See docs/decisions/0011-creating-sections.md.

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.