@atomicmail/mcp 0.1.0

package/README.md

@@ -0,0 +1,233 @@
+# @atomicmail/mcp
+
+AtomicMail MCP server — a local stdio Model Context Protocol server that gives
+an AI agent a programmable email inbox over JMAP, with automatic Proof-of-Work
+auth and capability-token rotation.
+
+The server is authored in TypeScript on Deno and built with
+[`dnt`](https://jsr.io/@deno/dnt) into a Node-compatible npm package, so the
+**same source** runs unchanged on Deno, Node, and Bun.
+
+It is the MCP companion to [`@atomic-mail/agent-skill`](../../skill/) — a
+CLI-first skill with identical credential semantics. The MCP and the skill share
+the same on-disk credential layout (`credentials.json` + `session.jwt` +
+`capability.jwt`), so you can mix and match the two freely.
+
+## Tools exposed
+
+| Tool           | Description                                                       |
+| -------------- | ----------------------------------------------------------------- |
+| `register`     | PoW signup. Persists credentials to disk; returns the API key.    |
+| `jmap_session` | `GET /.well-known/jmap` — discover accountId + mailbox URLs.      |
+| `jmap_request` | Send any JMAP method-call batch. Inline or via saved preset file. |
+| `get_docs`     | Built-in docs. Topics include `installation`, `presets`, `auth`.  |
+
+## Install
+
+The package is published to npm. Any of these work:
+
+```bash
+npx -y @atomicmail/mcp
+bunx @atomicmail/mcp
+deno run -A npm:@atomicmail/mcp/atomicmail-mcp
+```
+
+You don't typically run it directly — your MCP host (Cursor, Claude Desktop,
+...) will spawn it for you. See the configuration section below.
+
+## Configure (priority order)
+
+The server resolves configuration from two sources, with environment variables
+overriding individual fields from the file:
+
+1. **`credentials.json` in the credential directory.** The same file produced by
+   `atomic-mail-signup`. Default location: `~/.atomicmail/credentials.json`.
+   Override the directory with `ATOMIC_MAIL_CREDENTIALS_DIR`.
+2. **Environment variables.** Useful for hermetic MCP host configs:
+
+   | Variable                      | Required | Description                       |
+   | ----------------------------- | -------- | --------------------------------- |
+   | `ATOMIC_MAIL_AUTH_URL`        | Yes\*    | Auth service base URL             |
+   | `ATOMIC_MAIL_API_URL`         | Yes\*    | API service / JMAP base URL       |
+   | `ATOMIC_MAIL_SCRYPT_SALT`     | No       | Optional PoW salt override        |
+   | `ATOMIC_MAIL_API_KEY`         | No       | Existing API key (skips signup)   |
+   | `ATOMIC_MAIL_CREDENTIALS_DIR` | No       | Override default credential dir   |
+
+   \* "Yes" means at least one source must provide `authUrl` and `apiUrl`. If
+   `credentials.json` is present and complete, no env vars are required. PoW
+   salt defaults to the built-in value that matches `auth-service`.
+
+If neither source resolves `authUrl` and `apiUrl`, the server fails fast on
+startup with the missing fields listed.
+
+## Credential files
+
+All three live in the credential directory and are written with mode `0600`:
+
+- `credentials.json` — `{ apiKey, inboxId, authUrl, apiUrl, scryptSalt }`.
+  Long-lived. Treat as a secret — copying it to a new machine is enough to log
+  in.
+- `session.jwt` — 4-hour TTL, rotated automatically via PoW when near expiry.
+- `capability.jwt` — 2-minute TTL, rotated automatically before each JMAP
+  request when near expiry.
+
+Because the on-disk layout is identical to the
+[`@atomic-mail/agent-skill`](../../skill/) skill, you can:
+
+- Bootstrap once with `atomic-mail-signup`, then point the MCP at the same
+  directory.
+- Run `atomic-mail-jmap` from a shell while the MCP is also running — both will
+  see fresh JWTs as the other rotates them.
+
+## MCP host configuration examples
+
+### Cursor
+
+`~/.cursor/mcp.json` (or per-project `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "atomicmail": {
+      "command": "npx",
+      "args": ["-y", "@atomicmail/mcp"],
+      "env": {
+        "ATOMIC_MAIL_AUTH_URL": "https://auth.atomicmail.io",
+        "ATOMIC_MAIL_API_URL": "https://api.atomicmail.io"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+`claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "atomicmail": {
+      "command": "npx",
+      "args": ["-y", "@atomicmail/mcp"],
+      "env": {
+        "ATOMIC_MAIL_AUTH_URL": "https://auth.atomicmail.io",
+        "ATOMIC_MAIL_API_URL": "https://api.atomicmail.io"
+      }
+    }
+  }
+}
+```
+
+### Sharing credentials with the skill CLI
+
+If you've already run `atomic-mail-signup`, no auth-service URL needs to be
+repeated — the MCP reads URLs (and optional salt override) from `credentials.json`:
+
+```json
+{
+  "mcpServers": {
+    "atomicmail": {
+      "command": "npx",
+      "args": ["-y", "@atomicmail/mcp"],
+      "env": {
+        "ATOMIC_MAIL_CREDENTIALS_DIR": "/Users/me/.atomicmail"
+      }
+    }
+  }
+}
+```
+
+When you skip the env entirely (`{}`), the MCP defaults to `~/.atomicmail/`.
+
+## Typical agent workflow
+
+Once the MCP is wired in, an agent will:
+
+1. Call `register` (only on the first run, with no existing API key).
+2. Call `jmap_session` to discover the `accountId` and the INBOX id.
+3. Call `jmap_request` with whatever method calls it needs (inline) or reference
+   saved presets via `opsFile`.
+4. Call `get_docs` with topic `presets` or `jmap_cheatsheet` for ready-to-use
+   JMAP recipes.
+
+## JMAP presets (the `opsFile` parameter)
+
+`jmap_request` accepts either an inline `methodCalls` array or an `opsFile`
+path. Relative paths resolve against the credential directory, so common batches
+can be saved once and reused. This mirrors the skill's
+`atomic-mail-jmap --ops-file` behavior — both consume the same files.
+
+Example: drop `~/.atomicmail/fetch_last_100.json` containing
+
+```json
+[
+  [
+    "Email/query",
+    {
+      "accountId": "ACC",
+      "filter": { "inMailbox": "INBOX" },
+      "sort": [{ "property": "receivedAt", "isAscending": false }],
+      "limit": 100
+    },
+    "q0"
+  ]
+]
+```
+
+…then `jmap_request` with `{ "opsFile": "fetch_last_100.json" }`.
+
+See `get_docs presets` for the full preset format.
+
+## Develop
+
+The project is a Deno-first codebase. You'll need [Deno](https://deno.com/)
+installed.
+
+```bash
+# Run directly with Deno (live source, no build step)
+deno task start
+
+# Type-check
+deno task check
+
+# Format
+deno task fmt
+
+# Build the npm package via dnt
+deno task build:npm
+
+# Run the built artifact under Node
+node npm/esm/main.js
+```
+
+The dnt build emits to `./npm/`. The package's `bin` is `atomicmail-mcp`, mapped
+to `npm/esm/main.js`. After a build you can also `npm install` it locally and
+use the binary directly.
+
+### Project layout
+
+```
+services/mcp-server-local/
+├── deno.json          # Deno config + import map
+├── build_npm.ts       # dnt build script
+├── README.md
+├── src/
+│   ├── main.ts        # MCP server entry (stdio transport)
+│   ├── auth-session.ts# PoW + JWT rotation, with disk persistence
+│   ├── credentials.ts # File I/O: credentials.json, *.jwt
+│   ├── docs-content.ts# Static text served by the get_docs tool
+│   └── tools/
+│       ├── register.ts
+│       ├── jmap.ts
+│       └── docs.ts
+└── npm/               # dnt output (gitignored)
+```
+
+The auth-session and credentials files are kept in-step with their counterparts
+in [`skill/scripts/lib/`](../../skill/scripts/lib/) so both projects produce and
+consume identical credential files.
+
+## License
+
+MIT

package/esm/lib/src/consts.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Fixed proof-of-work scrypt salt. The auth-service passes this string (UTF-8
+ * bytes of the hex text, not decoded binary) to `scrypt` as the `salt`
+ * argument; all PoW clients must use the same value.
+ */
+export declare const DEFAULT_POW_SCRYPT_SALT_HEX = "0b980734412c292d6549110276b604ab1dea4883bd460d77d1b984adf8bca083";
+export declare const ONE_SEC_MS = 1000;
+export declare const ONE_MIN_MS: number;
+export declare const ONE_HOUR_MS: number;
+export declare const ONE_DAY_MS: number;
+export declare const ONE_MONTH_MS: number;
+export declare const ONE_YEAR_MS: number;
+//# sourceMappingURL=consts.d.ts.map

package/esm/lib/src/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../../../src/lib/src/consts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,qEAC4B,CAAC;AAErE,eAAO,MAAM,UAAU,OAAO,CAAC;AAC/B,eAAO,MAAM,UAAU,QAAkB,CAAC;AAC1C,eAAO,MAAM,WAAW,QAAkB,CAAC;AAC3C,eAAO,MAAM,UAAU,QAAmB,CAAC;AAC3C,eAAO,MAAM,YAAY,QAAkB,CAAC;AAC5C,eAAO,MAAM,WAAW,QAAmB,CAAC"}

package/esm/lib/src/consts.js

@@ -0,0 +1,12 @@
+/**
+ * Fixed proof-of-work scrypt salt. The auth-service passes this string (UTF-8
+ * bytes of the hex text, not decoded binary) to `scrypt` as the `salt`
+ * argument; all PoW clients must use the same value.
+ */
+export const DEFAULT_POW_SCRYPT_SALT_HEX = "0b980734412c292d6549110276b604ab1dea4883bd460d77d1b984adf8bca083";
+export const ONE_SEC_MS = 1000;
+export const ONE_MIN_MS = ONE_SEC_MS * 60;
+export const ONE_HOUR_MS = ONE_MIN_MS * 60;
+export const ONE_DAY_MS = ONE_HOUR_MS * 24;
+export const ONE_MONTH_MS = ONE_DAY_MS * 30;
+export const ONE_YEAR_MS = ONE_DAY_MS * 365;

package/esm/mcp/src/auth-session.d.ts

@@ -0,0 +1,88 @@
+import { type SkillFiles } from "./credentials.js";
+export declare const SESSION_TTL_MS: number;
+export declare const CAPABILITY_TTL_MS: number;
+export declare const SESSION_SAFETY_MARGIN_MS = 60000;
+export declare const CAPABILITY_SAFETY_MARGIN_MS = 20000;
+export interface JwtPayload {
+    exp?: number;
+    iat?: number;
+    jti?: string;
+    inboxId?: string;
+    [key: string]: unknown;
+}
+export declare function decodeJwtPayload<T = JwtPayload>(jwt: string): T;
+export declare function isJwtExpired(jwt: string, marginMs: number): boolean;
+export type ConfigSource = "credentials-file" | "env" | "mixed" | "incomplete";
+export interface ResolvedConfig {
+    authUrl: string;
+    apiUrl: string;
+    scryptSalt: string;
+    apiKey?: string;
+    inboxId?: string;
+    credentialDir: string;
+    files: SkillFiles;
+    source: ConfigSource;
+}
+/**
+ * Resolve credential directory from (in priority order):
+ *   1. ATOMIC_MAIL_CREDENTIALS_DIR env var
+ *   2. ~/.atomicmail/ (POSIX) or %USERPROFILE%/.atomicmail (Windows)
+ */
+export declare function resolveCredentialDir(): string;
+/**
+ * Resolve server configuration from:
+ *   1. credentials.json in the credential directory (if present and valid).
+ *   2. ATOMIC_MAIL_* environment variables (overlay on top of (1) so env
+ *      always wins on a per-field basis).
+ *
+ * The auth and api base URLs MUST be resolvable from at least one source.
+ * PoW scrypt salt defaults to the deployment constant when not set in env or
+ * credentials.json.
+ * The api key is optional; without it, the agent must call the register tool
+ * before any JMAP request.
+ */
+export declare function resolveConfig(): Promise<ResolvedConfig>;
+export interface AuthSessionConfig {
+    authUrl: string;
+    apiUrl: string;
+    scryptSalt: string;
+    apiKey?: string;
+    inboxId?: string;
+    credentialDir: string;
+    files: SkillFiles;
+}
+export declare class AuthSession {
+    private readonly authUrl;
+    readonly apiUrl: string;
+    private readonly scryptSalt;
+    private apiKey;
+    private inboxId;
+    readonly credentialDir: string;
+    readonly files: SkillFiles;
+    private sessionJWT;
+    private capabilityJWT;
+    constructor(cfg: AuthSessionConfig);
+    /** Construct a session and load any previously persisted JWTs from disk. */
+    static create(cfg: AuthSessionConfig): Promise<AuthSession>;
+    get hasApiKey(): boolean;
+    get currentInboxId(): string | undefined;
+    private loadFromDisk;
+    /**
+     * Full PoW signup. Persists credentials.json + session.jwt + capability.jwt
+     * to disk and updates in-memory state. Throws if an API key is already
+     * configured (refuse to clobber an existing account).
+     */
+    signup(username: string): Promise<{
+        apiKey: string;
+        inboxId: string;
+    }>;
+    /**
+     * Get a valid capability JWT, rotating session/capability tokens as needed.
+     * This is the primary method tool handlers call before every JMAP request.
+     */
+    getCapabilityToken(): Promise<string>;
+    private ensureSession;
+    /** Clean shutdown. No-op today; reserved for future cleanup. */
+    destroy(): void;
+}
+//# sourceMappingURL=auth-session.d.ts.map

package/esm/mcp/src/auth-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-session.d.ts","sourceRoot":"","sources":["../../../src/mcp/src/auth-session.ts"],"names":[],"mappings":"AAsBA,OAAO,EAGL,KAAK,UAAU,EAKhB,MAAM,kBAAkB,CAAC;AAO1B,eAAO,MAAM,cAAc,QAAqB,CAAC;AACjD,eAAO,MAAM,iBAAiB,QAAgB,CAAC;AAI/C,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAc/D;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQnE;AAgLD,MAAM,MAAM,YAAY,GACpB,kBAAkB,GAClB,KAAK,GACL,OAAO,GACP,YAAY,CAAC;AAEjB,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAW7C;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,cAAc,CAAC,CAqD7D;AAID,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAE3B,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,aAAa,CAAqB;gBAE9B,GAAG,EAAE,iBAAiB;IAUlC,4EAA4E;WAC/D,MAAM,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAMjE,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,cAAc,IAAI,MAAM,GAAG,SAAS,CAEvC;YAEa,YAAY;IAK1B;;;;OAIG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QACtC,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IA6CF;;;OAGG;IACG,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;YA8B7B,aAAa;IA0B3B,gEAAgE;IAChE,OAAO,IAAI,IAAI;CAGhB"}