onenote-mcp: Instructions file for Claude Code

OneNote MCP server

A local, read-only MCP server over the OneNote desktop COM API. It runs as one user, on one machine, against the OneNote application that user already has open.

Hard rules

These are not style preferences. Each one was paid for.

1. Use comtypes. Never pywin32. OneNote's IDispatch cannot load its own type library, so every pywin32 call — late bound or InvokeTypes — fails with TYPE_E_LIBNOTREGISTERED, "Library not registered". comtypes calls the vtable directly and never asks OneNote to resolve a name. This is not a bitness problem. It was checked from 64-bit and 32-bit Python and fails identically in both. tests/test_guards.py enforces this.
2. Never touch the 2007 type library. OneNote.Application.12 and {F2A7EE29-8BF6-4A6D-83F1-098E366C709C} marshal successfully, which makes them look like a working alternative. Their GetPageContent takes three arguments against a four-argument vtable, and calling it kills the OneNote process. Only {0EA692EE-BB50-4E3C-AEF0-356D91732725} version 1.1.
3. Never read a page with piBinaryData or piAll. They inline every image as base64 and turn one ordinary page into 1.7 MB of XML. Read with piBasic, then fetch bytes per image with GetBinaryPageContent.
4. Never return raw page XML. About 90% of it is <one:OCRData>, one token with pixel coordinates per recognised word. A page whose visible text is 221 characters arrives as 83 KB. page.py renders; it does not forward.
5. No write path. No UpdatePageContent, no CreateNewPage, no DeleteHierarchy, no NavigateTo. Every tool is read_only_hint=True. A notebook stored on a SharePoint team site is shared, so a write there reaches everyone on that site. See "Before adding writes" below.
6. All COM calls go through the one thread in com.py. COM interface pointers belong to the apartment of the thread that created them. The single-worker executor is what keeps that true under async.
7. server.py must not raise while starting. A dead MCP server shows the user "Connection closed" and no reason. It also must not touch COM at start-up: connecting launches OneNote, which can take tens of seconds.
8. Never commit a real page. Captured page XML carries the note content itself, authorResolutionID attributes holding colleagues' O365 ids and mail addresses, ProjectWise paths, and live OneDrive share links that work. Git history is permanent, so scrubbing after the fact does not help. Every fixture is synthetic and comes from tools/make_fixtures.py. If a bug needs a real page to reproduce, keep that page outside the repository.