mcp-standardnotes CLAUDE.md

MCP Standard Notes

MCP (Model Context Protocol) server that lets Claude interact with a Standard Notes account (read, create, edit, delete notes and tags) while preserving Standard Notes' end-to-end encryption (E2EE).

What is implemented locally = only the Standard Notes protocol 004 framing (payload format 004:<nonce>:<ciphertext>:<aad>, root key derivation → masterKey/serverPassword, items_key wrap/unwrap). That's parsing/serialization of a documented public format, not new cryptography.

The @standardnotes/snjs package and the modular @standardnotes/{encryption,models,...} packages were ruled out: the monolith is deprecated (Node 16 only), and the modular packages have un-propagated breaking changes (ContentType removed from common) that make them unusable externally.

Stack

• Language: TypeScript (strict)
• Runtime: Node.js ≥ 20
• MCP SDK: @modelcontextprotocol/sdk
• Crypto: libsodium-wrappers-sumo (Argon2id + XChaCha20-Poly1305 IETF)
• HTTP: native fetch (Node 20+)
• MCP transport: stdio (local, no network exposure)

Commands

npm install            # Install dependencies
npm run build          # Compile TypeScript → dist/
npm run dev            # Watch mode (tsx)
npm run typecheck      # Type-check without emitting
npm test               # Run tests (vitest)
npm run lint           # ESLint

Structure

src/
  index.ts             # MCP stdio entry point
  server.ts            # McpServer + tool registration
  cli/login.ts         # `npm run login` — interactive prompt + keychain
  sn/
    client.ts          # Orchestration: login/session → HTTP + protocol
    crypto.ts          # libsodium wrapper (argon2id, xchacha20poly1305)
    protocol004.ts     # SN 004 framing: root key, items_key wrap, payload enc/dec
    http.ts            # fetch wrapper: /v1/login-params, /v1/login, /v1/items/sync
    session.ts         # Session persistence via keytar
    types.ts           # Note / NoteSummary / KeyParams types
  tools/notes.ts       # MCP handlers + zod schemas
  tools/tags.ts        # Tags + sync handlers + zod schemas
  security/
    redact.ts, logger.ts
.env.example