# Waypost documentation

> Install Waypost, connect Proton Mail Bridge, Drive and Calendar, register the MCP server with Claude Code and other agents, use the CLI, and understand its write safeguards.

Project page: https://dbaney.com/projects/waypost/

## Install

Requires Node.js 22.14 or newer.

```sh
git clone https://github.com/baney75/waypost.git
cd waypost
npm ci --ignore-scripts
npm run build
node dist/cli.js init
node dist/cli.js tools
```

You can explore the CLI and prepare calendar files before connecting any service.

## Connect services

| Service | Connection | What works |
| --- | --- | --- |
| Mail | Proton Mail Bridge, or an authenticated read-only helper | Folders, labels, search, read messages and threads, save attachments, prepare drafts, optionally send. |
| Drive | Official Proton Drive CLI | List, inspect, download with a checksum check, optionally upload. |
| Calendar | ICS exports or refreshable Proton links | Read an agenda in local time; prepare import files. |

```sh
node dist/cli.js connect drive
node dist/cli.js connect calendar /absolute/path/to/calendar-export.ics
node dist/cli.js doctor
```

Drive opens Proton's own browser sign-in. Mail uses Bridge's certificate and generated credentials. `doctor` reports each service as `ready`, `not_configured` or `failed`.

Direct Bridge reads `WAYPOST_MAIL_USERNAME` and `WAYPOST_MAIL_PASSWORD` from the environment. Start your agent under a secret manager so those values never sit in a config file.

## Add to an agent

From the `waypost` folder, register it with Claude Code:

```sh
claude mcp add waypost --scope user -- node "$PWD/runtime/waypost.mjs" mcp
claude mcp list
```

For other clients, run `node dist/cli.js agent-config claude`, `cursor`, `codex` or `generic` and paste the result into the client's MCP settings. MCP uses standard input and output and opens no network listener.

## Tools

| Tool | What it does |
| --- | --- |
| `waypost_status` | Which services are set up and which writes are allowed. |
| `mail_mailboxes` | Folder and label names. |
| `mail_list` | Newest headers first, filtered by sender, recipient, subject, text, unseen or date. |
| `mail_read` | One message as text, with threading IDs and attachments. Never marks mail read. |
| `mail_thread` | Messages in the same conversation. |
| `mail_attachment` | Saves one attachment locally. |
| `mail_draft`, `mail_send` | Prepare an EML; sending is off by default and needs `confirm: true`. |
| `drive_list`, `drive_info`, `drive_download`, `drive_upload` | Drive under `/my-files`; uploads are off by default and need `confirm: true`. |
| `calendar_events`, `calendar_prepare` | Read events in a window; write an ICS file to import. |
| `pass_lookup` | Proton Pass item names and URLs only. |

Errors return `{ok:false, error:{code, message}}`, and the message says what to run or change.

## Use the CLI

```sh
waypost mail list --subject invoice --since 2026-09-01 --limit 20
waypost mail read --uid 123
waypost calendar agenda --days 7 --timezone America/New_York
waypost calendar prepare --summary "Project review" \
  --start 2026-10-05T09:00:00 --end 2026-10-05T09:30:00 \
  --timezone America/New_York --rrule "FREQ=WEEKLY;COUNT=4"
```

Install it on your PATH with `npm install -g .`, or use `node runtime/waypost.mjs` in place of `waypost`. `waypost tools` lists every input schema.

## Write safeguards

- Mail and Calendar are read-only by default.
- Mail sends and Drive uploads start disabled in config. When enabled, every call must still pass `confirm: true` (`--confirm` on the CLI).
- A send needs a prepared EML file and its exact SHA-256.
- There is no permanent-delete or public-sharing tool.
- Calendar imports must be saved and verified in Proton.

## Verify

```sh
npm run verify
```

Tests use synthetic data and drive the MCP server over stdio against a real IMAP server. Account-level checks need the configured official services.