@atomicmail/mcp 0.1.0 → 0.2.0

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/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) }],
-    }));
-}