fastmail-cli 1.0.0

package/README.md

@@ -0,0 +1,127 @@
+# fastmail-cli
+
+OpenClaw plugin for Fastmail email, contacts, and calendar. Provides 36 agent tools backed by a persistent in-process MCP connection for token-efficient output (5-7x savings vs raw JSON).
+
+## Installation
+
+```bash
+openclaw plugins install fastmail-cli
+```
+
+## Prerequisites
+
+1. **Remote MCP Server**: Deploy the [fastmail-mcp-remote](https://github.com/omarshahine/fastmail-mcp-remote) Worker to Cloudflare.
+
+2. **Get a Bearer Token**: Authenticate via the CLI to obtain a token:
+
+   ```bash
+   alias fastmail="npx tsx ~/path/to/fastmail-mcp-remote/cli/main.ts"
+   fastmail auth --url https://your-worker.example.com --team myteam
+   ```
+
+   The token is saved to `~/.config/fastmail-cli/config.json`. Copy the `bearerToken` value for plugin configuration.
+
+## Configuration
+
+Both fields are **required** in your OpenClaw workspace config:
+
+| Key | Description |
+|-----|-------------|
+| `workerUrl` | URL of your deployed Fastmail MCP Worker |
+| `bearerToken` | Bearer token from `fastmail auth` (each user needs their own) |
+
+Each workspace can have different credentials, enabling multi-user setups on the same machine.
+
+## Tools
+
+### Email Read (11 tools, always available)
+
+- `fastmail_inbox` - Recent inbox emails
+- `fastmail_get_email` - Read a single email
+- `fastmail_search_emails` - Search with text and filters (sender, date, unread, etc.)
+- `fastmail_get_thread` - Conversation thread
+- `fastmail_list_mailboxes` - List mailboxes
+- `fastmail_get_mailbox_stats` - Mailbox statistics
+- `fastmail_get_account_summary` - Account overview
+- `fastmail_list_identities` - Sending identities
+- `fastmail_get_attachments` - Email attachments
+- `fastmail_download_attachment` - Download attachment
+- `fastmail_get_inbox_updates` - Incremental sync
+
+### Email Write (3 tools, optional)
+
+- `fastmail_send_email` - Send email
+- `fastmail_create_draft` - Create draft
+- `fastmail_reply_to_email` - Reply to email
+
+### Email Organize (6 tools, optional)
+
+- `fastmail_mark_read` - Mark as read
+- `fastmail_mark_unread` - Mark as unread
+- `fastmail_flag` - Flag (star)
+- `fastmail_unflag` - Unflag (unstar)
+- `fastmail_delete` - Delete (trash)
+- `fastmail_move` - Move to mailbox
+
+### Email Bulk (6 tools, optional)
+
+- `fastmail_bulk_read` - Bulk mark read
+- `fastmail_bulk_unread` - Bulk mark unread
+- `fastmail_bulk_flag` - Bulk flag
+- `fastmail_bulk_unflag` - Bulk unflag
+- `fastmail_bulk_delete` - Bulk delete
+- `fastmail_bulk_move` - Bulk move
+
+### Contacts (3 tools, always available)
+
+- `fastmail_list_contacts` - List contacts
+- `fastmail_get_contact` - Contact details
+- `fastmail_search_contacts` - Search contacts
+
+### Calendar (4 tools, 3 always + 1 optional)
+
+- `fastmail_list_calendars` - List calendars
+- `fastmail_list_events` - List events
+- `fastmail_get_event` - Event details
+- `fastmail_create_event` - Create event (optional)
+
+### Memos (3 tools, 1 always + 2 optional)
+
+- `fastmail_get_memo` - Get memo on email
+- `fastmail_create_memo` - Add memo (optional)
+- `fastmail_delete_memo` - Delete memo (optional)
+
+## Architecture
+
+```
+Agent -> OpenClaw Plugin -> MCP SDK (in-process) -> Remote Worker -> Fastmail JMAP API
+```
+
+The plugin maintains a persistent MCP connection per workspace:
+1. Registers OpenClaw tools with JSON Schema parameters
+2. On first tool call, connects to the remote Worker via MCP SDK with Bearer token auth
+3. All subsequent calls reuse the same connection (no per-call overhead)
+4. Responses are formatted in-process using compact text formatters
+
+One runtime dependency: `@modelcontextprotocol/sdk`.
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/omarshahine/fastmail-mcp-remote.git
+cd fastmail-mcp-remote/openclaw-plugin
+
+# Install dependencies
+npm install --legacy-peer-deps
+
+# Type check
+npx tsc --noEmit
+
+# Local test (symlink into OpenClaw extensions)
+ln -s $(pwd) ~/.openclaw/extensions/fastmail-cli
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,58 @@
+/**
+ * OpenClaw plugin entry point for Fastmail.
+ *
+ * Registers 36 agent tools that proxy to the remote Fastmail MCP Worker
+ * via a persistent in-process MCP SDK connection. Responses are formatted
+ * using compact text formatters for token efficiency.
+ *
+ * Credentials (workerUrl + bearerToken) come from plugin config,
+ * supporting multi-user setups where each workspace has its own token.
+ */
+
+import { FastmailMcpClient } from "./src/mcp-client.js";
+import { resolveCredentials } from "./src/auth.js";
+import { registerEmailTools } from "./src/tools/email.js";
+import { registerContactTools } from "./src/tools/contacts.js";
+import { registerCalendarTools } from "./src/tools/calendar.js";
+import { registerMemoTools } from "./src/tools/memo.js";
+
+/** Minimal typed interface for the OpenClaw plugin API. */
+export interface OpenClawApi {
+  registerTool(tool: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (_id: string, params: any) => Promise<{ content: Array<{ type: string; text: string }> }>;
+  }, opts?: { optional: boolean }): void;
+  config?: Record<string, unknown>;
+}
+
+export type GetClientFn = () => Promise<FastmailMcpClient>;
+
+/**
+ * Create a lazy client factory that connects on first tool call.
+ * One persistent connection per plugin instance (per workspace).
+ */
+function lazyClientFactory(pluginConfig: {
+  workerUrl?: string;
+  bearerToken?: string;
+}): GetClientFn {
+  let client: FastmailMcpClient | null = null;
+
+  return async () => {
+    if (client) return client;
+    const { url, token } = resolveCredentials(pluginConfig);
+    client = new FastmailMcpClient(url, token);
+    return client;
+  };
+}
+
+export default function register(api: OpenClawApi) {
+  const pluginConfig = (api.config || {}) as { workerUrl?: string; bearerToken?: string };
+  const getClient = lazyClientFactory(pluginConfig);
+
+  registerEmailTools(api, getClient);
+  registerContactTools(api, getClient);
+  registerCalendarTools(api, getClient);
+  registerMemoTools(api, getClient);
+}

package/openclaw.plugin.json

@@ -0,0 +1,31 @@
+{
+  "id": "fastmail-cli",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["workerUrl", "bearerToken"],
+    "properties": {
+      "workerUrl": {
+        "type": "string",
+        "description": "Fastmail MCP Worker URL (e.g. https://fastmail-mcp.example.com)"
+      },
+      "bearerToken": {
+        "type": "string",
+        "description": "Bearer token from 'fastmail auth'. Each user needs their own token."
+      }
+    }
+  },
+  "uiHints": {
+    "workerUrl": {
+      "label": "Worker URL",
+      "placeholder": "https://fastmail-mcp.example.com"
+    },
+    "bearerToken": {
+      "label": "Bearer Token",
+      "placeholder": "Token from 'fastmail auth'"
+    }
+  },
+  "skills": [
+    "./skills"
+  ]
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "fastmail-cli",
+  "version": "1.0.0",
+  "description": "OpenClaw plugin for Fastmail email, contacts, and calendar",
+  "type": "module",
+  "files": [
+    "index.ts",
+    "src",
+    "skills",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "keywords": [
+    "openclaw",
+    "fastmail",
+    "email",
+    "mcp",
+    "agent-tools"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omarshahine/fastmail-mcp-remote.git",
+    "directory": "openclaw-plugin"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.8",
+    "typescript": "^5.9.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/skills/fastmail/SKILL.md

@@ -0,0 +1,136 @@
+# Fastmail Tools
+
+Token-efficient tools for Fastmail email, contacts, and calendar. Each tool connects to a remote Fastmail MCP Worker and returns compact text optimized for LLM token efficiency (5-7x savings vs raw JSON).
+
+## Authentication
+
+Tools require `workerUrl` and `bearerToken` to be configured in the OpenClaw workspace. Each user needs their own token from `fastmail auth`.
+
+## Available Tools
+
+### Email Reading (11 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `fastmail_inbox` | Get recent inbox emails (IDs, dates, senders, subjects, previews) |
+| `fastmail_get_email` | Read a single email (headers + body in markdown or HTML) |
+| `fastmail_search_emails` | Search emails by text, with optional filters: sender, recipient, date range, unread, attachments, mailbox |
+| `fastmail_get_thread` | Get all emails in a conversation thread |
+| `fastmail_list_mailboxes` | List all mailboxes with IDs and email counts |
+| `fastmail_get_mailbox_stats` | Get mailbox statistics (total, unread, threads) |
+| `fastmail_get_account_summary` | Account overview with counts |
+| `fastmail_list_identities` | List sending identities |
+| `fastmail_get_attachments` | List attachments for an email |
+| `fastmail_download_attachment` | Get download URL for an attachment |
+| `fastmail_get_inbox_updates` | Incremental sync: get changes since a state token |
+
+### Email Writing (3 optional tools)
+
+| Tool | Purpose |
+|------|---------|
+| `fastmail_send_email` | Send an email (text, HTML, or markdown body) |
+| `fastmail_create_draft` | Create an email draft |
+| `fastmail_reply_to_email` | Reply to an email (reply-all, send or draft) |
+
+### Email Organization (6 optional tools)
+
+| Tool | Purpose |
+|------|---------|
+| `fastmail_mark_read` | Mark email as read |
+| `fastmail_mark_unread` | Mark email as unread |
+| `fastmail_flag` | Flag (star) an email |
+| `fastmail_unflag` | Unflag (unstar) an email |
+| `fastmail_delete` | Delete an email (move to trash) |
+| `fastmail_move` | Move email to a different mailbox |
+
+### Bulk Operations (6 optional tools)
+
+| Tool | Purpose |
+|------|---------|
+| `fastmail_bulk_read` | Mark multiple emails as read |
+| `fastmail_bulk_unread` | Mark multiple emails as unread |
+| `fastmail_bulk_flag` | Flag multiple emails |
+| `fastmail_bulk_unflag` | Unflag multiple emails |
+| `fastmail_bulk_delete` | Delete multiple emails |
+| `fastmail_bulk_move` | Move multiple emails to a mailbox |
+
+### Contacts (3 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `fastmail_list_contacts` | List contacts with names, emails, phones |
+| `fastmail_get_contact` | Full contact details |
+| `fastmail_search_contacts` | Search contacts by name or email |
+
+### Calendar (4 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `fastmail_list_calendars` | List calendars with IDs |
+| `fastmail_list_events` | List events, optionally by calendar |
+| `fastmail_get_event` | Full event details |
+| `fastmail_create_event` | Create a calendar event (optional) |
+
+### Memos (3 tools)
+
+| Tool | Purpose |
+|------|---------|
+| `fastmail_get_memo` | Get the private memo on an email |
+| `fastmail_create_memo` | Add a private memo to an email (optional) |
+| `fastmail_delete_memo` | Delete a memo (optional) |
+
+## Output Format
+
+Tools return compact text optimized for LLM consumption. Email IDs appear first on each line for easy extraction.
+
+### Email List Example
+```
+# inbox (10)
+
+M1234abc  2026-02-19 10:30  *John Smith <john@example.com>
+  Re: Project Update -- Preview of the email content...
+
+M5678def  2026-02-19 09:15   Jane Doe <jane@example.com> [att]
+  Contract Review -- Please review the attached...
+```
+
+Indicators: `*` = unread, `!` = flagged, `[att]` = has attachments
+
+### Single Email Example
+```
+From: John Smith <john@example.com>
+To: me@example.com
+Date: 2026-02-19 10:30
+Subject: Re: Project Update
+ID: M1234abc | Thread: T5678
+
+[markdown body content]
+```
+
+## Common Workflows
+
+### Check inbox and read an email
+1. `fastmail_inbox` -- see list, note IDs
+2. `fastmail_get_email` with the ID -- read the email
+
+### Search, read, and reply
+1. `fastmail_search_emails` with query
+2. `fastmail_get_email` with the ID
+3. `fastmail_reply_to_email` with body and `send: true`
+
+### Triage inbox
+1. `fastmail_inbox` with limit 20
+2. `fastmail_bulk_read` for read emails
+3. `fastmail_delete` for unwanted emails
+4. `fastmail_move` to archive
+
+### Incremental sync
+1. `fastmail_get_inbox_updates` (no state token) -- returns current state + emails
+2. Save the `queryState` from the response
+3. `fastmail_get_inbox_updates` with `sinceQueryState` -- only changes since last check
+
+## Error Handling
+
+- **"Missing workerUrl/bearerToken"** -- Configure both in your OpenClaw workspace plugin settings
+- **"Token expired"** -- User needs to run `fastmail auth` and update the bearerToken in workspace config
+- **Connection errors** -- Check if the MCP worker is running

package/src/auth.ts

@@ -0,0 +1,27 @@
+/**
+ * Authentication for the Fastmail OpenClaw plugin.
+ *
+ * Credentials (workerUrl + bearerToken) are provided via plugin config,
+ * enabling multi-user setups where each workspace has its own token.
+ */
+
+export interface Credentials {
+  url: string;
+  token: string;
+}
+
+/**
+ * Resolve credentials from plugin config. Both fields are required.
+ */
+export function resolveCredentials(pluginConfig: {
+  workerUrl?: string;
+  bearerToken?: string;
+}): Credentials {
+  if (!pluginConfig.workerUrl) {
+    throw new Error("Missing workerUrl in plugin config");
+  }
+  if (!pluginConfig.bearerToken) {
+    throw new Error("Missing bearerToken in plugin config");
+  }
+  return { url: pluginConfig.workerUrl, token: pluginConfig.bearerToken };
+}