For agents & their humans

Connect an AI to your library.

Writing Station keeps your research as plain markdown on your own disk — which means any agent that can run a command or speak MCP can file notes into it. Safely: every note is previewed and approved by you before it is written, tags come only from the vocabulary you manage in the app, and the router can only ever add files — never edit or delete.

Agents: fetch /ai.md for this page as plain markdown.

How it works

Three steps, every time — and you’re in charge the whole way.

1. You hand it something to keep. A quote, a thought, a book you’re reading, a paragraph you spoke out loud — whatever you want saved. Your assistant reads it and works out where it belongs in your library.
2. It checks with you first. Before saving anything, it tells you exactly what it’s about to do — something like “I’ll save this as a quote, tag it Quotes, and link it to Edwards and John 1:16. Look right?” If it’s not right, you say so and it tries again. Nothing is ever saved until you say yes.
3. It files it, and it’s there. Once you approve, the note lands in your library and shows up in Writing Station right away — sorted and searchable like everything else. It can only ever add notes; it can never change, move, or delete anything you already have.

What you need

• A Mac with Writing Station installed and a vault folder chosen (the router reads the vault location from the app’s own settings).
• The Writing Station toolkit — the app’s repository on that Mac — with node 22+ and pnpm (pnpm install once inside the repo).
• Optional: WS_VAULT=/path/to/vault to point the tools at a different vault than the app’s.

The CLI — ws-note

Run from the toolkit folder. Add --json to any command for machine-readable output. First, learn the vocabulary:

pnpm -s ws-note types     # the 5 note types + when to use each
pnpm -s ws-note tags      # the tag vocabulary (managed in the app — never invent)
pnpm -s ws-note people    # people already in the library ("Last, First")

Then the two-step filing:

pnpm -s ws-note propose --type snip \
  --title "Grace upon grace" \
  --tags "Quotes" \
  --people "Edwards, Jonathan" \
  --refs "John 1:16" \
  --source "Religious Affections" \
  --body "Of his fullness we have all received, grace for grace."

# → prints the destination, metadata, the exact markdown, and a token:
#   ── confirm with: ws-note commit a1b2c3d4e5 ──

pnpm -s ws-note commit a1b2c3d4e5   # ONLY after the human agrees

Body can also come from a file (--file note.md) or stdin. People are ;-separated (names contain commas). Unconfirmed proposals simply expire. ws-note proposals lists what’s pending.

The MCP server — writing-station-notes

The same engine, exposed as native tools for MCP clients (Claude Code, Claude Desktop, OpenClaw, anything that speaks MCP over stdio):

Claude Code — sessions started inside the toolkit repo get the server automatically (it ships a .mcp.json). From anywhere else:

claude mcp add writing-station-notes -- \
  npx tsx /path/to/writing-station-repo/tools/notewriter/mcp.mts

Claude Desktop / other clients — register a stdio server (in Desktop: claude_desktop_config.json):

{
  "mcpServers": {
    "writing-station-notes": {
      "command": "npx",
      "args": ["tsx", "/path/to/writing-station-repo/tools/notewriter/mcp.mts"]
    }
  }
}

The contract (read this, agents)

• Two steps, always. Propose, show the human the preview (destination, type, tags, people, refs), commit only on their explicit yes. If they hesitate, adjust and propose again — keep suggesting until agreement.
• Tags belong to the human. Choose only from list_tags. If nothing fits, file untagged and say so — the human adds tags in Writing Station → Settings → Tags, not you.
• People are canonical. Last, First — “Luther, Martin”, never “Martin Luther”. Check list_people first and reuse existing spellings; relay any near-duplicate warning.
• Five types, folder-decided: snip a captured quote · idea the human’s own thought · book a book record · person a bio hub that represents someone · general everything else. A note that merely mentions a person is not a person note.
• Scripture refs like John 1:1-5 or Romans 8 power the Bible filter; invalid ones are rejected.
• Add-only. Never overwrite, move, rename, or delete anything in the vault. Never write the vault’s sidecar files.

If something refuses

• “No vault found” — open Writing Station once and choose a vault, or set WS_VAULT.
• “Tag … is not in the vocabulary” — working as intended. Pick from the list, or the human adds the tag in the app first.
• “That proposal expired” — propose again so the human sees a current preview. Tokens live 30 minutes.

The library stays the human’s. The agent is a very careful librarian.