AtlatestRepositorybureau

bureau / treeCLAUDE.md

Read it rendered

1# Bureau
2
3Bureau is an MCP server for Fastmail email and calendar, built with Sigil.
4
5## Project Structure
6
7```
8bureau/
9├── package.sgl # Package definition
10├── dev-redirects.sgl # Points deps at local sigil checkout
11├── .env # Credentials (gitignored)
12├── src/bureau/
13│ ├── main.sgl # Entry point: MCP server setup and run
14│ ├── config.sgl # Env var credential reading
15│ ├── connection.sgl # Lazy JMAP/CalDAV client caching
16│ ├── email.sgl # Email tool handlers
17│ ├── calendar.sgl # Calendar tool handlers
18│ └── format.sgl # Output formatting + ISO 8601 parsing
19└── test/test-bureau.sgl # Unit tests
20```
22## Dependencies
24Bureau depends on these Sigil packages:
25- **sigil-mcp** — MCP server framework
26- **sigil-jmap** — JMAP email client (Fastmail, etc.)
27- **sigil-caldav** — CalDAV calendar client
28- **sigil-run**, **sigil-stdlib**, **sigil-tls**, **sigil-http** — transitive deps declared explicitly
30## Building
32Always build with `--redirects` to use the local Sigil checkout:
34```bash
35/path/to/sigil/build/dev/bin/sigil build --redirects dev-redirects.sgl
36```
38The dev config produces a bundled binary at `build/dev/bin/bureau`.
40If you get stale cache errors (empty `.a` files, corrupt `.sgb`), clear the cache:
41```bash
42rm -rf ~/.cache/sigil/store
43```
45## Credentials
47Bureau needs a `.env` file (gitignored) with three variables:
49```
51BUREAU_FASTMAIL_API_TOKEN=fmu1-...
52BUREAU_FASTMAIL_APP_PASSWORD=fmu1-...
53```
55- **BUREAU_FASTMAIL_USERNAME** — Fastmail email address (used as CalDAV username)
56- **BUREAU_FASTMAIL_API_TOKEN** — Fastmail API token for JMAP email access (`Authorization: Bearer <token>`)
57- **BUREAU_FASTMAIL_APP_PASSWORD** — Fastmail app password for CalDAV calendar access (HTTP Basic auth)
59These must be separate credentials — an API token (Settings → API tokens) for
60JMAP and an app password (Settings → App passwords) for CalDAV.
62## Testing MCP Tools
64Test tools by piping JSON-RPC messages to the bureau binary:
66```bash
67source .env && echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}
68{"jsonrpc":"2.0","method":"notifications/initialized"}
69{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"bureau/mailboxes","arguments":{}}}' | timeout 30 ./build/dev/bin/bureau serve 2>&1
70```
72To extract just the tool response text:
73```bash
74... | grep -o '"text":"[^"]*"'
75```
77## Fastmail-Specific Notes
79- **JMAP session URL**: Use `https://api.fastmail.com/jmap/session` directly. The `.well-known/jmap` URL returns a redirect that sigil-http doesn't follow.
80- **CalDAV namespace**: Must use `urn:ietf:params:xml:ns:caldav` (the short form `urn:ietf:params:caldav` causes 403 on REPORT requests).
81- **CalDAV discovery**: Fastmail doesn't support `calendar-home-set` on the principal URL. The client falls back to replacing `/principals/` with `/calendars/` in the principal path.
82- **JMAP onSuccessUpdateEmail**: Fastmail rejects `#draft` back-reference keys in `onSuccessUpdateEmail`. The send flow uses a separate `Email/set` call to move to Sent after submission.
83- **JSON null values**: JSON null is truthy in Sigil. Always guard with `(string? x)` before calling string operations on values that might be null.
85## MCP Tools
87### Email
88- `bureau/mailboxes` — List mailboxes with counts
89- `bureau/email-search` — Search emails with filters
90- `bureau/email-read` — Read full email by ID
91- `bureau/email-send` — Send email (use `identity` param for sender address)
92- `bureau/email-reply` — Reply with threading
93- `bureau/email-move` — Move to mailbox
94- `bureau/email-archive` — Archive email
95- `bureau/email-trash` — Trash single email
96- `bureau/email-trash-batch` — Trash multiple emails (comma-separated IDs)
97- `bureau/email-flag` — Flag/unflag
98- `bureau/email-mark-read` — Mark read/unread
100### Calendar
101- `bureau/calendars` — List calendars
102- `bureau/events` — Query events in date range
103- `bureau/event-details` — Full event details
104- `bureau/event-create` — Create event
105- `bureau/event-update` — Update event
106- `bureau/event-delete` — Delete event
107- `bureau/free-slots` — Find free time slots
109### Utility
110- `bureau/identities` — Sending identities
111- `bureau/status` — Connection health check