onenote-mcp

# onenote-mcp — Full LLM Reference

FastMCP 3.4 server for Microsoft OneNote via the Microsoft Graph API. Dual transport
(stdio + HTTP Streamable), Tauri/NSIS desktop wrapper, Vite React webapp.

## Quick facts

- Backend port: 10907 (REST `/api/*` + MCP `/mcp`)
- Webapp port: 10906 (Vite dev, proxies `/api` -> 10907)
- Auth: browser auth-code sign-in (primary) + device-code fallback; token persisted to repo-root token file, refresh cache enables silent re-auth
- Repo layout: `src/onenote_mcp/` (server, transport, models, activity log), `web_sota/` (React), `native/` (Tauri)

## Environment variables

| Var | Default | Purpose |
|-----|---------|---------|
| `GRAPH_ACCESS_TOKEN` | - | Microsoft Graph bearer token (fallback for the token file) |
| `MCP_TRANSPORT` | stdio | `stdio` / `http` / `sse` |
| `ONENOTE_HOST` | 127.0.0.1 | HTTP bind host |
| `ONENOTE_PORT` | 10907 | HTTP bind port |
| `ONENOTE_LOG_LEVEL` | info | uvicorn log level |
| `MCP_BRIDGE_URLS` | - | Comma-separated remote MCP URLs proxied via create_proxy |

## MCP tools (26) + prompts (1)

| Tool | Purpose |
|------|---------|
| `authenticate` | Sign in with Microsoft (device-code flow) |
| `onenote_save_access_token` | Persist a Graph token manually |
| `onenote_list_notebooks` | List all notebooks |
| `onenote_get_notebook` | Notebook details (name, URLs) |
| `onenote_list_sections` | Sections of a notebook |
| `onenote_list_pages` | Pages of a section |
| `onenote_get_page` | Page content as HTML or Markdown (`output_format`), with OneNote links; `include_ids` for element IDs |
| `onenote_create_page` | Create a page from HTML or Markdown (`content_format`); optional section_id |
| `onenote_append_page` | Append plain text or Markdown to a page |
| `onenote_update_page` | Replace/insert/prepend/append on one element of a page, or retitle it |
| `onenote_delete_page` | Permanently delete a page |
| `onenote_get_links` | Web and desktop-app links for a notebook, section or page |
| `onenote_create_notebook` | Create a notebook (Graph cannot rename/delete it later) |
| `onenote_create_section` | Create a section in a notebook |
| `onenote_create_section_group` | Create a section group in a notebook |
| `onenote_list_section_groups` | Section groups of a notebook |
| `onenote_search_pages` | Title-match search across notebooks (with notebook/section context); `mode="fulltext"` over the local FTS index |
| `onenote_index_start` | Build/refresh the local full-text index (background) |
| `onenote_index_status` | Index build progress and searchable page count |
| `onenote_get_notebook_toc` | Sections + pages overview |
| `onenote_recent` | Recently modified pages (domain inbox) |
| `onenote_export` | Back up notebooks to Markdown (background) |
| `onenote_export_status` | Backup progress and output dir |
| `show_notebooks_card` | Notebooks as an in-chat Prefab card |
| `onenote_help` | Tool list and usage notes |
| `shutdown_server` | Graceful server termination |

Prompt: `onenote_triage` - guided DISCOVER/RETRIEVE/MAP/CAPTURE triage.

## REST API (webapp surface)

- `GET /health` — liveness probe
- `GET /api/status` — version, uptime, tool count, Graph auth state
- `GET /api/capabilities` — feature flags + tool names
- `GET /api/v1/diagnostics` — tool list, system info (CUA-NSIS smoke)
- `GET /api/logs`, `DELETE /api/logs`, `GET /api/logs/stats`, `GET /api/logs/export` — activity ring buffer
- `POST /api/auth/device`, `GET /api/auth/poll`, `GET /api/auth/status` — device-code auth UI (fallback)
- `GET /api/auth/login`, `GET /api/auth/callback` — browser auth-code sign-in (primary)
- `GET /api/auth/debug` — auth diagnostics (no secrets)
- `GET /api/notebooks`, `GET /api/notebooks/{id}/toc` — notebook browser
- `GET /api/pages/{id}`, `POST /api/pages`, `GET /api/search?q=&mode=` — page content/creation/search (title or fulltext)
- `POST /api/index`, `GET /api/index/status` — FTS index build + progress
- `POST /api/export`, `GET /api/export/status` — Markdown backup + progress
- `GET /api/skills`, `GET /api/skills/{name}` — skills list + SKILL.md content
- `GET /api/fleet/apps` — Apps Hub registry (adjacent fleet webapps)
- `GET /api/llm/discover` — local LLM probe (Ollama :11434, LM Studio :1234, vLLM :8000; `providers[].models`)
- `GET /api/llm/providers` — provider registry (detected flags + models, no keys)
- `GET /api/llm/models?provider=` — model list for one provider
- `GET /api/llm/onboarding` — starter facts + recommended path
- `POST /api/llm/chat` — backend chat proxy (Ollama + OpenAI-compatible); the ONLY path Chat uses
- `POST /api/shutdown` — graceful shutdown (agent-requested)

## Architecture

`server.py` builds the FastMCP app with `custom_route` REST endpoints and registers tools.
The module exposes `http_app` (CORS-wrapped `app.http_app()`) as the uvicorn ASGI target —
never the raw FastMCP object. `transport.py` serves stdio/http/sse from the CLI. `run_server.py`
is the PyInstaller entry: serves `http_app` directly via `uvicorn.run` (no FastAPI shell).
`native/` bundles the backend exe as a Tauri resource (`.env.example` template only, never `.env`).

## Webapp pages

Dashboard (live KPIs), Notebooks (tree browser + page viewer + search + create), Tools (live
`/api/capabilities`), Status (live `/api/status`), Apps, Skills (`/api/skills` viewer),
Chat (backend `/api/llm/chat` proxy, personality selector, localStorage history), Logging
(ring buffer viewer), Help, Settings (auth + LLM provider).

## Troubleshooting

- `TypeError: 'FastMCP' object is not callable` — uvicorn was pointed at `server:app`;
  use `onenote_mcp.server:http_app`.
- Chat shows Ollama offline — start Ollama (port 11434) or check `/api/llm/discover`.
- Graph 401 — run `authenticate` again (token expired).