@paperjot/mcp

Local MCP server that exposes your Paperjot vault to LLM tools (Claude Desktop, Claude Code, Cursor, anything that speaks the Model Context Protocol). The server runs entirely on your device — your decrypted content never leaves your machine. The cloud only ever sees ciphertext.

Install + pair (one time)

npx @paperjot/mcp login --serve \
  --firebase-config /path/to/firebase-web-config.json

This single command:

1. Generates a fresh X25519 keypair for this device.
2. Prints an 8-character pairing code (e.g. pj-AB12-CD34).
3. Open Paperjot in your browser → Settings → "MCP server" → "Pair new device". Type the code, give the device a label, confirm. The web client seals your identity keys to this device's pubkey and stores them in your account — only this device can unseal them.
4. CLI claims a one-time custom token and signs in as you.
5. Wraps the unsealed identity + the Firebase refresh token with a fresh device key. The wrapped blobs land in ~/.paperjot/<uid>/vault.enc and ~/.paperjot/<uid>/auth.enc (both 0600). The device key itself lives in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service).
6. Boots the MCP stdio server.

Subsequent runs

npx @paperjot/mcp serve

No re-pairing. The CLI loads the device key from your OS keychain, unwraps auth.enc, hands the refresh token back to the Firebase SDK, and the SDK gets a fresh ID token before any Firestore request goes out. If multiple accounts are paired on this machine, add --uid <uid>. To inspect what's paired locally:

npx @paperjot/mcp status

Configure your LLM tool

Point any MCP-compatible client at the paperjot-mcp bin. Example for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "paperjot": {
      "command": "npx",
      "args": ["@paperjot/mcp", "serve"]
    }
  }
}

Tools

The server advertises four read tools and a set of write + workbench tools.

Read

| Tool | Behavior | |---|---| | who_am_i | uid, email, project count, journal-access state. | | list_projects | Every project the user has access to. | | list_dir(path) | Virtual filesystem listing. See paths below. | | read_file(path) | Returns {content, etag, frontmatter} for the file. |

Write — tasks

| Tool | Behavior | |---|---| | create_task(project_slug, title, ...) | New task in the named project. | | update_task(task_id, ...) | Patches only the fields you pass. | | complete_task(task_id) | Sets status=done + stamps completedAt. | | reopen_task(task_id) | Reverts to open + clears completedAt. | | delete_task(task_id) | Hard-deletes. | | park_task / unpark_task / block_task | Flip into / out of started / blocked. | | commit_to_today / clear_from_today | Set / clear today as the due date. |

Write — notes

| Tool | Behavior | |---|---| | write_file(path, content, etag?) | Replaces a note or task file. | | edit_file(path, old_text, new_text, etag?) | Substring replace. | | create_file(path, content) | New task or note (path determines which). | | delete_file(path) | Hard-delete task; soft-archive note. |

Workbench

| Tool | Behavior | |---|---| | list_loops | Every parked + blocked task across all projects. Side effect: runs the auto-pull-to-Today rule. | | create_scratch(text) | Mints a scratch note in the Inbox. | | archive_scratch(note_id) | Soft-deletes a scratch note. | | sweep_stale_scratch(ttl_days?) | Archives every scratch older than the TTL (default 14d). | | promote_scratch(note_id, to_note? \| to_task_project_slug?) | Convert a scratch into a regular note or a task. | | append_to_session(task_id, markdown) | Appends a timestamped block to the task's session journal (creates one if missing). |

Filesystem paths

/                                               projects + _workbench/ (+ _journal/ if enabled)
/{projectSlug}                                  notes + _tasks/ + _sessions/
/{projectSlug}/{slug}-{shortId}.md              regular notes
/{projectSlug}/_tasks/{shortId}.md              open / started / blocked tasks
/{projectSlug}/_tasks/done/{shortId}.md         completed tasks
/{projectSlug}/_sessions/{shortId}.md           session journal notes
/_workbench/                                    cross-project tray
/_workbench/loops/{shortId}.md                  started + blocked tasks
/_workbench/today/{shortId}.md                  tasks due today
/_workbench/scratch/{shortId}.md                scratch notes
/_journal/                                      opt-in, read-only
/_journal/{YYYY-MM-DD}.md                       per-day Journal entries

shortId is the leading six chars of the file's stable id. It's stable across renames; the slug is decoration.

Security

• Trust boundary. The CLI process is a trusted client of your vault — same boundary as a browser tab. Anyone with shell access to your machine + the OS keychain entry has the same access as your unlocked Paperjot tab.
• At-rest wrap. The identity privkeys on disk are wrapped with a device key stored in your OS keychain. A leaked disk image alone isn't enough — you'd also need the keychain entry.
• Auto-lock. Idle for 30 minutes → identity buffers are wiped via sodium.memzero. Configurable with --idle-mins.
• Audit log. Every tool call writes a JSONL line to ~/.paperjot/<uid>/audit-YYYY-MM.log. No content — just {tool, outcome, target, ts}. Stays local; tail -f it yourself if you want a live view.
• Journal access is denied by default. Only the user can flip it to read-only from web Settings; there is no read-write toggle by design. Mutating verbs against the Journal project return journal_write_forbidden.
• --read-only flag suppresses every write tool at the transport level. Composes with journal access — --read-only does not grant Journal access on its own.