@atomicmail/mcp 0.1.0 → 0.2.1

package/esm/mcp/src/docs-content.js

@@ -1,405 +0,0 @@
-// Static documentation strings served by the get_docs tool.
-// Kept in one file so future edits don't require touching tool wiring.
-export const TOPICS = {
-    overview: `\
-# AtomicMail — Overview
-
-AtomicMail is an email service provider (ESP) designed for AI agents. It
-gives you a programmable mailbox you can manage entirely over JMAP (JSON
-Meta Application Protocol) — no IMAP, no SMTP knowledge needed.
-
-## MCP Tools
-
-This MCP server exposes four tools:
-
-1. **register**     — Create a new account (PoW signup). Persists credentials
-                      to disk; returns the API key once.
-2. **jmap_session** — Fetch the JMAP session object to discover your
-                      accountId.
-3. **jmap_request** — Send any JMAP method-call batch. Auth is automatic.
-                      Accepts inline 'methodCalls' or a saved 'opsFile'.
-4. **get_docs**     — You're reading this! Pass a topic to drill in.
-
-## Typical Workflow
-
-1. If you don't have an API key, call \`register\` with a username.
-2. Call \`jmap_session\` to learn your accountId and INBOX id.
-3. Use \`jmap_request\` to read, send, and manage email.
-
-Available doc topics: overview, auth, jmap_cheatsheet, tools, installation,
-presets, troubleshooting.`,
-    installation: `\
-# AtomicMail MCP — Installation
-
-The MCP server ships as a single npm-published binary (built from Deno
-sources via dnt) and runs unchanged on Node, Bun, and Deno.
-
-## Quick start
-
-The simplest way to use it from any MCP host is via npx:
-
-\`\`\`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"
-      }
-    }
-  }
-}
-\`\`\`
-
-Replace \`npx\` with \`bunx\` for Bun, or use \`deno run -A npm:@atomicmail/mcp\`
-for Deno.
-
-## Cursor
-
-In \`~/.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
-
-In \`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 already use \`atomic-mail-signup\` from \`@atomic-mail/agent-skill\`,
-the MCP can pick up its credentials.json/session.jwt/capability.jwt with
-zero extra env vars beyond \`ATOMIC_MAIL_CREDENTIALS_DIR\`:
-
-\`\`\`json
-{
-  "mcpServers": {
-    "atomicmail": {
-      "command": "npx",
-      "args": ["-y", "@atomicmail/mcp"],
-      "env": {
-        "ATOMIC_MAIL_CREDENTIALS_DIR": "/Users/me/.atomicmail"
-      }
-    }
-  }
-}
-\`\`\`
-
-The MCP defaults the credential directory to \`~/.atomicmail/\` if no env
-var is set, so even \`{}\` may suffice on a machine where you've already
-run \`atomic-mail-signup\`.
-
-## From source (development)
-
-\`\`\`
-git clone https://github.com/atomic-mail/agentic-mail
-cd services/mcp-server-local
-
-# Run directly with Deno
-deno task start
-
-# Or build the npm package and run with Node
-deno task build:npm
-node npm/esm/main.js
-\`\`\`
-
-See README.md in the package root for more.`,
-    auth: `\
-# AtomicMail — Auth Flow
-
-Auth is fully automatic inside this MCP server. You don't need to do
-anything unless you're registering for the first time.
-
-## How it works internally
-
-1. **Challenge** — MCP server requests a challenge from the auth service.
-2. **Proof-of-Work** — MCP server computes a scrypt hash that satisfies the
-   difficulty requirement. ~64 attempts on average (< 1 second).
-3. **Session JWT** — Server validates the PoW and returns a session token
-   (valid for 4 hours). On signup, it also returns a one-time API key.
-4. **Capability JWT** — Before each JMAP call, the MCP server exchanges the
-   session JWT for a short-lived capability token (2 min TTL) that the API
-   service accepts.
-
-The MCP server decodes JWT \`exp\` claims and rotates session/capability
-JWTs as they approach expiry, persisting the new tokens to disk so a
-restarted process (or a concurrent atomic-mail-jmap CLI invocation) sees
-the latest values.
-
-## Credential files
-
-All three files live in the credential directory (default
-\`~/.atomicmail/\`, override with \`ATOMIC_MAIL_CREDENTIALS_DIR\`). They are
-written with mode 0600 so other local users cannot read them.
-
-  credentials.json   { apiKey, inboxId, authUrl, apiUrl, scryptSalt }
-  session.jwt        4-hour TTL
-  capability.jwt     2-minute TTL
-
-## Environment Variables
-
-| Variable                       | Required | Description                       |
-|--------------------------------|----------|-----------------------------------|
-| ATOMIC_MAIL_AUTH_URL           | Yes*     | Auth service URL                  |
-| ATOMIC_MAIL_API_URL            | Yes*     | API/JMAP service URL              |
-| ATOMIC_MAIL_SCRYPT_SALT        | No       | Optional PoW salt override (defaults match auth-service) |
-| ATOMIC_MAIL_API_KEY            | No       | Existing API key (skip signup)    |
-| ATOMIC_MAIL_CREDENTIALS_DIR    | No       | Override default credential dir   |
-
-* "Yes" means at least one source — env var OR credentials.json — must
-  provide authUrl and apiUrl. Env vars override credentials.json on a per-field
-  basis. PoW salt defaults to the built-in deployment constant when unset.`,
-    jmap_cheatsheet: `\
-# JMAP Cheatsheet for AtomicMail
-
-JMAP (RFC 8620 + RFC 8621) is a JSON-over-HTTP protocol for email. Every
-request is a batch of method calls. AtomicMail supports:
-
-## Capabilities (pass in "using")
-- urn:ietf:params:jmap:core
-- urn:ietf:params:jmap:mail
-- urn:ietf:params:jmap:submission
-
-## Common Method Calls
-
-### List mailboxes
-\`\`\`json
-["Mailbox/get", {"accountId": "ACCOUNT_ID"}, "m0"]
-\`\`\`
-
-### List identities (for sending)
-\`\`\`json
-["Identity/get", {"accountId": "ACCOUNT_ID"}, "i0"]
-\`\`\`
-
-### Query last 100 emails in INBOX (newest first)
-\`\`\`json
-["Email/query", {
-  "accountId": "ACCOUNT_ID",
-  "filter": {"inMailbox": "INBOX_ID"},
-  "sort": [{"property": "receivedAt", "isAscending": false}],
-  "limit": 100
-}, "q0"]
-\`\`\`
-
-### Fetch email details (back-reference from query)
-\`\`\`json
-["Email/get", {
-  "accountId": "ACCOUNT_ID",
-  "#ids": {"resultOf": "q0", "name": "Email/query", "path": "/ids"},
-  "properties": ["subject", "from", "to", "receivedAt", "bodyValues"],
-  "fetchAllBodyValues": true
-}, "g0"]
-\`\`\`
-
-### Send an email (create draft + submit, destroy on success)
-\`\`\`json
-["Email/set", {
-  "accountId": "ACCOUNT_ID",
-  "create": {
-    "draft": {
-      "mailboxIds": {"INBOX_ID": true},
-      "keywords": {"$draft": true},
-      "from": [{"email": "you@atomicmail.io"}],
-      "to": [{"email": "recipient@example.com"}],
-      "subject": "Hello",
-      "bodyValues": {"body": {"value": "Message body", "charset": "utf-8"}},
-      "textBody": [{"partId": "body", "type": "text/plain"}]
-    }
-  }
-}, "c0"],
-["EmailSubmission/set", {
-  "accountId": "ACCOUNT_ID",
-  "onSuccessDestroyEmail": ["#sub"],
-  "create": {
-    "sub": {
-      "emailId": "#draft",
-      "identityId": "IDENTITY_ID",
-      "envelope": {
-        "mailFrom": {"email": "you@atomicmail.io"},
-        "rcptTo": [{"email": "recipient@example.com"}]
-      }
-    }
-  }
-}, "c1"]
-\`\`\`
-
-## Tips
-
-- Always call \`jmap_session\` first to discover accountId and the INBOX id.
-- Back-references (\`#ids\`, \`#draft\`) chain calls in a single batch.
-- Add \`urn:ietf:params:jmap:submission\` to \`using\` when sending email.
-- Save reusable batches as preset files — see the \`presets\` topic.`,
-    tools: `\
-# AtomicMail MCP — Tool Reference
-
-## register
-**Input:**  { username: string }
-**Returns:** Account info + API key (also persisted to credentials.json).
-Creates a new account. Performs Proof-of-Work automatically. Refuses to
-run if an API key is already configured.
-
-## jmap_session
-**Input:**  (none)
-**Returns:** JMAP session JSON with accountId, capabilities, and URLs.
-Call this first to discover your accountId and mailbox structure.
-
-## jmap_request
-**Input:**  { using?: string[], methodCalls?: array, opsFile?: string }
-**Returns:** JMAP response JSON with methodResponses.
-Sends a batch of JMAP method calls. Auth is automatic.
-
-  • methodCalls — inline JMAP batch.
-  • opsFile     — path to a saved JSON preset (relative paths resolve
-                  against the credential directory).
-  • using       — capability URNs. Defaults to core + mail. Add
-                  "urn:ietf:params:jmap:submission" when sending.
-
-Exactly one of methodCalls or opsFile must be provided.
-
-## get_docs
-**Input:**  { topic?: string }
-**Returns:** Documentation text.
-Topics: overview, installation, auth, jmap_cheatsheet, tools, presets,
-troubleshooting.`,
-    presets: `\
-# AtomicMail MCP — JMAP Presets
-
-The \`opsFile\` parameter on \`jmap_request\` lets you save reusable JMAP
-batches as JSON files on disk, then reference them by path. This mirrors
-the \`atomic-mail-jmap --ops-file\` flag from the skill CLI, so the MCP
-server and the skill CLI both consume the same preset format from the
-same directory.
-
-## Where presets live
-
-Relative paths passed to \`opsFile\` resolve against the credential
-directory (default \`~/.atomicmail/\`, override with
-\`ATOMIC_MAIL_CREDENTIALS_DIR\`). Absolute paths are taken as-is.
-
-So \`opsFile: "fetch_last_100.json"\` reads from
-\`~/.atomicmail/fetch_last_100.json\`.
-
-## Preset file shape
-
-Two equivalent shapes are accepted:
-
-1. A bare \`methodCalls\` array:
-
-   \`\`\`json
-   [
-     ["Email/query", {
-       "accountId": "ACC",
-       "filter": {"inMailbox": "INBOX"},
-       "sort": [{"property": "receivedAt", "isAscending": false}],
-       "limit": 100
-     }, "q0"]
-   ]
-   \`\`\`
-
-2. A full envelope:
-
-   \`\`\`json
-   {
-     "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],
-     "methodCalls": [
-       ["Email/query", { "...": "..." }, "q0"]
-     ]
-   }
-   \`\`\`
-
-If the file already specifies \`using\`, that wins over the inline
-\`using\` parameter; otherwise the request defaults (\`core + mail\`) or
-the explicit \`using\` argument is used.
-
-## Suggested presets to keep
-
-- \`fetch_last_100.json\` — newest 100 emails in INBOX.
-- \`unread_inbox.json\`   — query \`{filter: {inMailbox: ..., notKeyword: "$seen"}}\`.
-- \`my_identities.json\`  — \`Identity/get\` for sending.
-- \`mailboxes.json\`      — \`Mailbox/get\` to keep a fresh map of folders.
-
-A typical agent workflow: bootstrap presets once via \`atomic-mail-signup\`
-+ a few file writes, then drive everything through \`opsFile\` + a small
-amount of inline parameter substitution.`,
-    troubleshooting: `\
-# AtomicMail MCP — Troubleshooting
-
-## "Missing required configuration: ATOMIC_MAIL_AUTH_URL, ..."
-
-The server could not resolve authUrl and apiUrl from either env vars or
-\`credentials.json\` in the credential directory.
-Either set the env vars in your MCP host config, or run
-\`atomic-mail-signup\` once to populate \`credentials.json\`.
-
-## "No API key configured — call the 'register' tool"
-
-The server started fine but no API key was found. Either:
-  - Call the \`register\` tool to create a new account, or
-  - Set \`ATOMIC_MAIL_API_KEY\` in your MCP env, or
-  - Place an existing \`credentials.json\` (from another machine, or
-    from \`atomic-mail-signup\`) into the credential directory.
-
-## "auth-service /api/v1/session returned 401"
-
-Usually means the API key is invalid for the configured auth service,
-or (if you set \`ATOMIC_MAIL_SCRYPT_SALT\`) the override does not match the
-server build. Verify authUrl and apiUrl match the deployment you signed up at.
-
-## "Capability JWT missing inboxId claim"
-
-The auth service returned a capability JWT without the inboxId claim. This
-indicates a server bug — please open an issue with the auth-service
-deployment version.
-
-## I changed the PoW salt override — what now?
-
-The PoW salt is normally fixed per server release. If you set
-\`ATOMIC_MAIL_SCRYPT_SALT\` or stored a custom \`scryptSalt\` in
-credentials.json, it must match the auth-service build you are talking to.
-
-## "Could not read opsFile '/path/to/x.json'"
-
-The opsFile path could not be opened. Relative paths resolve against the
-credential directory — for absolute control, pass an absolute path. The
-file must contain valid JSON (either a methodCalls array or a full
-envelope). See the \`presets\` topic.`,
-};
-export const TOPIC_LIST = Object.keys(TOPICS);
-export function getDocs(topic) {
-    if (!topic) {
-        return TOPICS["overview"];
-    }
-    const key = topic.toLowerCase().replace(/[\s-]/g, "_");
-    return (TOPICS[key] ??
-        `Unknown topic "${topic}". Available topics: ${TOPIC_LIST.join(", ")}`);
-}

package/esm/mcp/src/main.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-export {};
-//# sourceMappingURL=main.d.ts.map

package/esm/mcp/src/main.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/mcp/src/main.ts"],"names":[],"mappings":""}

package/esm/mcp/src/main.js

@@ -1,116 +0,0 @@
-#!/usr/bin/env node
-// AtomicMail MCP server — local stdio proxy with PoW auth and JMAP.
-//
-// Designed to be launched by an MCP-capable agent host (Cursor, Claude
-// Desktop, Continue, Cline, ...) as a child process and communicated with
-// over stdio.
-//
-// CONFIGURATION (priority order):
-//   1. credentials.json + session.jwt + capability.jwt in the credential
-//      directory (default: ~/.atomicmail/, override with the env var
-//      ATOMIC_MAIL_CREDENTIALS_DIR). This is the SAME on-disk layout
-//      produced by the atomic-mail-signup CLI from @atomic-mail/agent-skill.
-//   2. ATOMIC_MAIL_AUTH_URL / ATOMIC_MAIL_API_URL / ATOMIC_MAIL_API_KEY —
-//      overlay individual fields on top of (1). Optional: ATOMIC_MAIL_SCRYPT_SALT
-//      overrides the built-in PoW salt (normally unnecessary).
-//
-// If auth and API URLs cannot be resolved, the server fails fast on startup.
-//
-// See README.md for installation and MCP host configuration examples.
-import process from "node:process";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { AuthSession, resolveConfig } from "./auth-session.js";
-import { registerDocsTool } from "./tools/docs.js";
-import { registerJmapTool } from "./tools/jmap.js";
-import { registerRegisterTool } from "./tools/register.js";
-const VERSION = "0.1.0";
-const INSTRUCTIONS = `\
-AtomicMail MCP server — a programmable email inbox for AI agents.
-
-WORKFLOW
-  1. If you do not yet have an account, call the 'register' tool with a
-     desired username. It performs a Proof-of-Work signup and persists
-     credentials.json + session.jwt + capability.jwt into the credential
-     directory so future invocations skip this step.
-  2. Call 'jmap_session' to fetch your accountId, capabilities, and the
-     mailbox URL. Cache the accountId — every subsequent JMAP call needs it.
-  3. Call 'jmap_request' with one or more JMAP method calls. Auth (session
-     + capability JWT rotation) is fully automatic. You can either pass
-     'methodCalls' inline or 'opsFile' (a path to a saved JSON preset).
-  4. Call 'get_docs' for in-depth topic guides. Topics include:
-     overview, auth, jmap_cheatsheet, tools, installation, presets,
-     troubleshooting.
-
-CREDENTIAL FILES
-  Credentials live in ~/.atomicmail/ by default (override with
-  ATOMIC_MAIL_CREDENTIALS_DIR). The same files are produced by the
-  atomic-mail-signup CLI from @atomic-mail/agent-skill so you can mix and
-  match the two — e.g. bootstrap an account with the CLI, then point the
-  MCP at the same directory.
-
-    credentials.json   { apiKey, inboxId, authUrl, apiUrl, scryptSalt }
-    session.jwt        4-hour TTL, rotated automatically via PoW.
-    capability.jwt     2-minute TTL, rotated automatically via /capability.
-
-ENVIRONMENT VARIABLES
-  ATOMIC_MAIL_CREDENTIALS_DIR   override default credential directory
-  ATOMIC_MAIL_AUTH_URL          auth-service base URL
-  ATOMIC_MAIL_API_URL           api-service / JMAP base URL
-  ATOMIC_MAIL_SCRYPT_SALT       optional PoW salt override (defaults match auth-service)
-  ATOMIC_MAIL_API_KEY           existing API key (skip signup)
-
-SECURITY
-  credentials.json contains your apiKey — treat it like a password. Files
-  are written with mode 0600.
-
-For full reference call get_docs with the relevant topic.`;
-async function main() {
-    let config;
-    try {
-        config = await resolveConfig();
-    }
-    catch (err) {
-        console.error("AtomicMail MCP: configuration error:", err instanceof Error ? err.message : err);
-        process.exit(1);
-    }
-    console.error(`AtomicMail MCP v${VERSION}: credential dir '${config.credentialDir}' ` +
-        `(config source: ${config.source}).`);
-    if (config.apiKey) {
-        console.error(`AtomicMail MCP: API key found${config.inboxId ? ` (inbox ${config.inboxId})` : ""}.`);
-    }
-    else {
-        console.error("AtomicMail MCP: no API key configured — call the 'register' tool to create an account.");
-    }
-    const session = await AuthSession.create({
-        authUrl: config.authUrl,
-        apiUrl: config.apiUrl,
-        scryptSalt: config.scryptSalt,
-        apiKey: config.apiKey,
-        inboxId: config.inboxId,
-        credentialDir: config.credentialDir,
-        files: config.files,
-    });
-    const server = new McpServer({ name: "atomicmail", version: VERSION }, { instructions: INSTRUCTIONS });
-    registerRegisterTool(server, session);
-    registerJmapTool(server, session);
-    registerDocsTool(server);
-    const cleanup = () => {
-        session.destroy();
-    };
-    process.on("SIGINT", () => {
-        cleanup();
-        process.exit(0);
-    });
-    process.on("SIGTERM", () => {
-        cleanup();
-        process.exit(0);
-    });
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error("AtomicMail MCP: server running on stdio");
-}
-main().catch((err) => {
-    console.error("AtomicMail MCP: fatal error:", err);
-    process.exit(1);
-});

package/esm/mcp/src/tools/docs.d.ts

@@ -1,3 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
-export declare function registerDocsTool(server: McpServer): void;
-//# sourceMappingURL=docs.d.ts.map

package/esm/mcp/src/tools/docs.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../../src/mcp/src/tools/docs.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAGtE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA2BxD"}

package/esm/mcp/src/tools/docs.js

@@ -1,22 +0,0 @@
-import { z } from "zod";
-import { getDocs, TOPIC_LIST } from "../docs-content.js";
-export function registerDocsTool(server) {
-    server.registerTool("get_docs", {
-        title: "AtomicMail documentation",
-        description: `Get documentation about AtomicMail and this MCP server. ` +
-            `Available topics: ${TOPIC_LIST.join(", ")}. ` +
-            `Call with no topic for the overview.`,
-        inputSchema: z.object({
-            topic: z
-                .string()
-                .optional()
-                .describe(`Documentation topic. One of: ${TOPIC_LIST.join(", ")}. Omit for overview.`),
-        }),
-        annotations: {
-            readOnlyHint: true,
-            idempotentHint: true,
-        },
-    }, ({ topic }) => ({
-        content: [{ type: "text", text: getDocs(topic) }],
-    }));
-}

package/esm/mcp/src/tools/jmap.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"jmap.d.ts","sourceRoot":"","sources":["../../../../src/mcp/src/tools/jmap.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAEtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA2CtD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,WAAW,GACnB,IAAI,CAyMN"}