@atomicmail/mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @atomicmail/mcp
 
-AtomicMail MCP server — a local stdio Model Context Protocol server that gives
+Atomic Mail 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.
 
@@ -8,121 +8,64 @@ 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.
+It is the MCP companion to
+[`@atomicmail/agent-skill`](https://www.npmjs.com/package/@atomicmail/agent-skill)
+— a CLI with identical credential semantics. The MCP and the skill share the
+same on-disk layout (`credentials.json` + `session.jwt` + `capability.jwt`).
 
 ## 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`.  |
+| Tool           | Description                                                                                                                                               |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `register`     | PoW signup; persists credentials. Idempotent when username matches inbox.                                                                                 |
+| `jmap_request` | JMAP batch via `ops` or `ops_file`. Uppercase `$VAR_NAME` tokens are substituted (`$ACCOUNT_ID` / `$INBOX` from session; others via optional `vars` map). |
+| `help`         | Built-in docs (`topic` optional).                                                                                                                         |
 
 ## 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   |
+Your MCP host spawns this process; see configuration below.
 
-   \* "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`.
+## Defaults
 
-If neither source resolves `authUrl` and `apiUrl`, the server fails fast on
-startup with the missing fields listed.
+- auth endpoint: `https://auth.atomicmail.ai`
+- api endpoint: `https://api.atomicmail.ai`
+- credentials directory: `~/.atomicmail`
 
 ## Credential files
 
-All three live in the credential directory and are written with mode `0600`:
+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.
+- `credentials.json` — `{ apiKey, inboxId, authUrl, apiUrl, scryptSalt }`
+- `session.jwt` — 4h TTL, rotated via PoW
+- `capability.jwt` — 2m TTL, rotated before JMAP calls
 
-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.
+Use **`npx atomicmail register`** (from `@atomicmail/agent-skill`) against the
+same directory, or the MCP `register` tool.
 
 ## 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`:
+`~/.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"
-      }
+      "args": ["-y", "@atomicmail/mcp"]
     }
   }
 }
 ```
 
-### 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`:
+## Overriding defaults
 
 ```json
 {
@@ -131,102 +74,59 @@ repeated — the MCP reads URLs (and optional salt override) from `credentials.j
       "command": "npx",
       "args": ["-y", "@atomicmail/mcp"],
       "env": {
-        "ATOMIC_MAIL_CREDENTIALS_DIR": "/Users/me/.atomicmail"
+        "ATOMIC_MAIL_AUTH_URL": "https://custom-auth.example",
+        "ATOMIC_MAIL_API_URL": "https://custom-api.example",
+        "ATOMIC_MAIL_CREDENTIALS_DIR": "/Users/me/.atomicmail",
+        "ATOMIC_MAIL_SCRYPT_SALT": "hex-salt-override",
+        "ATOMIC_MAIL_API_KEY": "existing-api-key"
       }
     }
   }
 }
 ```
 
-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.
+1. `register` with a username (or rely on existing `credentials.json`).
+2. `jmap_request` with `ops` or `ops_file` (optional `vars` for `$TO`,
+   `$SUBJECT`, etc.).
+3. `help` when stuck.
 
-## JMAP presets (the `opsFile` parameter)
+## JMAP presets (`ops_file`)
 
-`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.
+Relative paths resolve against the credential directory. Example file
+`fetch_last_100.json` — then call `jmap_request` with
+`{ "ops_file": "fetch_last_100.json" }`.
 
-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.
+See `help` with topic `presets`.
 
 ## 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
+node npm/esm/mcp/src/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
+mcp/
+├── deno.json
+├── build_npm.ts
 ├── 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
+│   ├── main.ts
 │   └── tools/
 │       ├── register.ts
 │       ├── jmap.ts
-│       └── docs.ts
+│       └── help.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.
+Shared auth/JMAP logic lives in [`../lib/`](../lib/) (`AgentSession`, etc.).
 
 ## License
 

package/esm/lib/src/agent-auth-http.d.ts

@@ -0,0 +1,26 @@
+export declare function fetchChallenge(authUrl: string): Promise<{
+    challengeJWT: string;
+    challenge: string;
+    difficulty: number;
+}>;
+export interface SessionResponse {
+    sessionJWT: string;
+    apiKey?: string;
+}
+export declare function exchangeSession(authUrl: string, body: {
+    challengeJWT: string;
+    powHex: string;
+    nonce: string;
+    apiKey?: string;
+    username?: string;
+}): Promise<SessionResponse>;
+export declare function fetchCapability(authUrl: string, sessionJWT: string): Promise<string>;
+export interface PerformPoWInput {
+    authUrl: string;
+    scryptSalt: string;
+    apiKey?: string;
+    username?: string;
+    onPowProgress?: (nonce: bigint) => void;
+}
+export declare function performPoWAndSession(input: PerformPoWInput): Promise<SessionResponse>;
+//# sourceMappingURL=agent-auth-http.d.ts.map

package/esm/lib/src/agent-auth-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-auth-http.d.ts","sourceRoot":"","sources":["../../../src/lib/src/agent-auth-http.ts"],"names":[],"mappings":"AAoCA,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CAqBD;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,eAAe,CAAC,CAS1B;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,eAAe,CAAC,CAgB1B"}

package/esm/lib/src/agent-auth-http.js

@@ -0,0 +1,76 @@
+// auth-service HTTP: challenge → session → capability.
+import { decodeJwtPayload } from "./agent-jwt.js";
+import { solvePow } from "./agent-pow.js";
+async function postJson(url, body, headers = {}) {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...(body ? { "Content-Type": "application/json" } : {}),
+            ...headers,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    const path = (() => {
+        try {
+            return new URL(url).pathname;
+        }
+        catch {
+            return url;
+        }
+    })();
+    if (!res.ok) {
+        throw new Error(`auth-service ${path} returned ${res.status}: ${text}`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`auth-service ${path} returned non-JSON body: ${text}`);
+    }
+}
+export async function fetchChallenge(authUrl) {
+    const data = await postJson(`${authUrl}/api/v1/challenge`, undefined);
+    if (typeof data.challengeJWT !== "string") {
+        throw new Error("Challenge response missing challengeJWT.");
+    }
+    const payload = decodeJwtPayload(data.challengeJWT);
+    if (typeof payload.jti !== "string" ||
+        typeof payload.difficulty !== "number") {
+        throw new Error("Challenge JWT payload malformed (missing jti or difficulty).");
+    }
+    return {
+        challengeJWT: data.challengeJWT,
+        challenge: payload.jti,
+        difficulty: payload.difficulty,
+    };
+}
+export async function exchangeSession(authUrl, body) {
+    const data = await postJson(`${authUrl}/api/v1/session`, { ...body });
+    if (typeof data.sessionJWT !== "string") {
+        throw new Error("Session response missing sessionJWT.");
+    }
+    return {
+        sessionJWT: data.sessionJWT,
+        apiKey: typeof data.apiKey === "string" ? data.apiKey : undefined,
+    };
+}
+export async function fetchCapability(authUrl, sessionJWT) {
+    const data = await postJson(`${authUrl}/api/v1/capability`, undefined, { Authorization: `Bearer ${sessionJWT}` });
+    if (typeof data.capabilityJWT !== "string") {
+        throw new Error("Capability response missing capabilityJWT.");
+    }
+    return data.capabilityJWT;
+}
+export async function performPoWAndSession(input) {
+    const { authUrl, scryptSalt } = input;
+    const { challengeJWT, challenge, difficulty } = await fetchChallenge(authUrl);
+    const { powHex, nonce } = await solvePow(challenge, difficulty, scryptSalt, input.onPowProgress);
+    return exchangeSession(authUrl, {
+        challengeJWT,
+        powHex,
+        nonce,
+        apiKey: input.apiKey,
+        username: input.username,
+    });
+}

package/esm/{mcp/src/credentials.d.ts → lib/src/agent-credentials-store.d.ts}

@@ -13,8 +13,9 @@ export interface SkillFiles {
 export declare function defaultFilesFromOutDir(outDir: string): SkillFiles;
 export declare function writeCredentials(path: string, creds: Credentials): Promise<void>;
 export declare function readCredentials(path: string): Promise<Credentials>;
-/** Like readCredentials, but returns undefined when the file does not exist. */
 export declare function tryReadCredentials(path: string): Promise<Credentials | undefined>;
 export declare function writeJwtFile(path: string, jwt: string): Promise<void>;
 export declare function tryReadJwtFile(path: string): Promise<string | undefined>;
-//# sourceMappingURL=credentials.d.ts.map
+/** Best-effort removal of credential artifacts (ignore missing files). */
+export declare function unlinkCredentialArtifacts(files: SkillFiles): Promise<void>;
+//# sourceMappingURL=agent-credentials-store.d.ts.map

package/esm/lib/src/agent-credentials-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-credentials-store.d.ts","sourceRoot":"","sources":["../../../src/lib/src/agent-credentials-store.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAOjE;AAMD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAiCxE;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAOlC;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3E;AAED,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B;AAED,0EAA0E;AAC1E,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/esm/{mcp/src/credentials.js → lib/src/agent-credentials-store.js}

@@ -1,17 +1,6 @@
-// Credential file I/O. Three files form a complete credential set:
-//   credentials.json  — long-lived: apiKey, inboxId, server URLs, PoW salt.
-//   session.jwt       — short-lived (~4h): rotates via /session + PoW.
-//   capability.jwt    — short-lived (~2min): rotates via /capability.
-//
-// Files are written with mode 0600 so other local users cannot read them.
-//
-// This file mirrors skill/scripts/lib/credentials.ts so that the MCP server
-// reads and writes the same on-disk layout as the atomic-mail-signup /
-// atomic-mail-jmap CLIs from the @atomic-mail/agent-skill skill. The two
-// are interchangeable: you can run the skill CLI to bootstrap credentials
-// and the MCP server will pick them up automatically (see resolveConfig
-// in auth-session.ts).
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+// Credential file I/O shared by MCP and AgentSkill.
+// Three files: credentials.json, session.jwt, capability.jwt (mode 0600).
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 export function defaultFilesFromOutDir(outDir) {
     const base = resolve(outDir);
@@ -35,7 +24,7 @@ export async function readCredentials(path) {
     }
     catch (err) {
         throw new Error(`Could not read credentials file '${path}': ${err.message}. ` +
-            "Did you run signup first?");
+            "Did you run register first?");
     }
     let obj;
     try {
@@ -58,7 +47,6 @@ export async function readCredentials(path) {
     }
     return obj;
 }
-/** Like readCredentials, but returns undefined when the file does not exist. */
 export async function tryReadCredentials(path) {
     try {
         await readFile(path, "utf-8");
@@ -81,3 +69,18 @@ export async function tryReadJwtFile(path) {
         return undefined;
     }
 }
+/** Best-effort removal of credential artifacts (ignore missing files). */
+export async function unlinkCredentialArtifacts(files) {
+    for (const p of [
+        files.credentialsFile,
+        files.sessionFile,
+        files.capabilityFile,
+    ]) {
+        try {
+            await unlink(p);
+        }
+        catch {
+            // ignore
+        }
+    }
+}

package/esm/lib/src/agent-help-content.d.ts

@@ -0,0 +1,4 @@
+export declare const HELP_TOPICS: Record<string, string>;
+export declare const HELP_TOPIC_LIST: string[];
+export declare function getHelp(topic?: string): string;
+//# sourceMappingURL=agent-help-content.d.ts.map

package/esm/lib/src/agent-help-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-help-content.d.ts","sourceRoot":"","sources":["../../../src/lib/src/agent-help-content.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAuO9C,CAAC;AAEF,eAAO,MAAM,eAAe,UAA2B,CAAC;AAExD,wBAAgB,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAW9C"}