@atomicmail/mcp 0.1.0 → 0.2.1

package/esm/lib/network/auth-client.js

@@ -0,0 +1,188 @@
+// auth-client
+//
+// Thin HTTP client for services/auth-service. Encapsulates the full PoW
+// challenge → session → capability flow so callers (integration tests, the
+// future agent skill, etc.) don't have to reimplement scrypt grinding.
+//
+// The PoW digest is scrypt-based and uses the SAME salt the auth-service
+// uses on the verify path (see services/auth-service/src/crypto.ts). The
+// client must therefore be configured with that salt — there is no public
+// hash function here, the salt is part of the protocol.
+import { scrypt } from "node:crypto";
+import { DEFAULT_POW_SCRYPT_SALT_HEX } from "../core/consts.js";
+// Mirror services/auth-service/src/crypto.ts exactly. Changing any of these
+// constants on either side breaks PoW interop.
+const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1 };
+const POW_HASH_BYTES = 64;
+/** Thrown for any non-2xx HTTP response or malformed payload. */
+export class AuthClientError extends Error {
+    status;
+    bodyText;
+    constructor(status, bodyText, message) {
+        super(message);
+        this.name = "AuthClientError";
+        this.status = status;
+        this.bodyText = bodyText;
+    }
+}
+export class AuthClient {
+    baseUrl;
+    scryptSaltHex;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.scryptSaltHex = options.scryptSaltHex ?? DEFAULT_POW_SCRYPT_SALT_HEX;
+    }
+    /**
+     * Register a new inbox under `username`. Returns the freshly minted API key
+     * (the server only ever returns it once — the caller MUST persist it) and
+     * a session JWT.
+     */
+    async signup(username) {
+        const { challengeJWT, challenge, difficulty } = await this.fetchChallenge();
+        const { powHex, nonce } = await this.solvePoW(challenge, difficulty);
+        const data = await this.postSession({
+            challengeJWT,
+            powHex,
+            nonce: nonce.toString(),
+            username,
+        });
+        if (typeof data.apiKey !== "string" ||
+            typeof data.sessionJWT !== "string") {
+            throw new AuthClientError(200, JSON.stringify(data), "Signup response missing apiKey or sessionJWT.");
+        }
+        return { apiKey: data.apiKey, sessionJWT: data.sessionJWT };
+    }
+    /** Exchange an existing API key for a fresh session JWT. */
+    async login(apiKey) {
+        const { challengeJWT, challenge, difficulty } = await this.fetchChallenge();
+        const { powHex, nonce } = await this.solvePoW(challenge, difficulty);
+        const data = await this.postSession({
+            challengeJWT,
+            powHex,
+            nonce: nonce.toString(),
+            apiKey,
+        });
+        if (typeof data.sessionJWT !== "string") {
+            throw new AuthClientError(200, JSON.stringify(data), "Login response missing sessionJWT.");
+        }
+        return { sessionJWT: data.sessionJWT };
+    }
+    /**
+     * Exchange a session JWT for a short-lived capability JWT (audience:
+     * api-service).
+     */
+    async renew(sessionJWT) {
+        const res = await fetch(`${this.baseUrl}/api/v1/capability`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${sessionJWT}` },
+        });
+        const data = await this.parseJsonOrThrow(res, "capability");
+        if (typeof data.capabilityJWT !== "string") {
+            throw new AuthClientError(res.status, JSON.stringify(data), "Capability response missing capabilityJWT.");
+        }
+        return { capabilityJWT: data.capabilityJWT };
+    }
+    async fetchChallenge() {
+        const res = await fetch(`${this.baseUrl}/api/v1/challenge`, {
+            method: "POST",
+        });
+        const data = await this.parseJsonOrThrow(res, "challenge");
+        if (typeof data.challengeJWT !== "string") {
+            throw new AuthClientError(res.status, JSON.stringify(data), "Challenge response missing challengeJWT.");
+        }
+        const payload = decodeJwtPayload(data.challengeJWT);
+        if (typeof payload.jti !== "string" ||
+            typeof payload.difficulty !== "number") {
+            throw new AuthClientError(res.status, data.challengeJWT, "Challenge JWT payload is malformed (missing jti or difficulty).");
+        }
+        return {
+            challengeJWT: data.challengeJWT,
+            challenge: payload.jti,
+            difficulty: payload.difficulty,
+        };
+    }
+    async postSession(body) {
+        const res = await fetch(`${this.baseUrl}/api/v1/session`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        return await this.parseJsonOrThrow(res, "session");
+    }
+    async parseJsonOrThrow(res, endpoint) {
+        const text = await res.text();
+        if (!res.ok) {
+            throw new AuthClientError(res.status, text, `auth-service ${endpoint} returned ${res.status}: ${text}`);
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new AuthClientError(res.status, text, `auth-service ${endpoint} returned non-JSON body.`);
+        }
+    }
+    /**
+     * Brute-force a PoW nonce. Mirrors `generatePow` in
+     * services/auth-service/src/crypto.ts: scrypt(`${challenge}:${nonce}`, salt,
+     * 64) until `difficulty` leading bits of the digest are zero.
+     *
+     * Expected work at the server's POW_DIFFICULTY=6 is ~2^6 = 64 attempts; well
+     * within the challenge JWT's 3-minute TTL.
+     */
+    async solvePoW(challenge, difficulty) {
+        let nonce = 0n;
+        while (true) {
+            const digest = await scryptHash(`${challenge}:${nonce}`, this.scryptSaltHex);
+            if (hasLeadingZeroBits(digest, difficulty)) {
+                return { powHex: bytesToHex(digest), nonce };
+            }
+            nonce++;
+        }
+    }
+}
+function scryptHash(data, salt) {
+    const bytes = new TextEncoder().encode(data);
+    return new Promise((resolve, reject) => {
+        scrypt(bytes, salt, POW_HASH_BYTES, SCRYPT_PARAMS, (err, derived) => {
+            if (err)
+                return reject(err);
+            resolve(new Uint8Array(derived));
+        });
+    });
+}
+function hasLeadingZeroBits(hash, bits) {
+    if (bits > hash.length * 8)
+        return false;
+    const fullBytes = Math.floor(bits / 8);
+    const remainingBits = bits % 8;
+    for (let i = 0; i < fullBytes; i++) {
+        if (hash[i] !== 0)
+            return false;
+    }
+    if (remainingBits > 0) {
+        const mask = (0xff << (8 - remainingBits)) & 0xff;
+        if ((hash[fullBytes] & mask) !== 0)
+            return false;
+    }
+    return true;
+}
+function bytesToHex(bytes) {
+    let hex = "";
+    for (let i = 0; i < bytes.length; i++) {
+        hex += bytes[i].toString(16).padStart(2, "0");
+    }
+    return hex;
+}
+function decodeJwtPayload(jwt) {
+    const parts = jwt.split(".");
+    if (parts.length < 2) {
+        throw new Error("Malformed JWT: expected at least 2 dot-separated segments.");
+    }
+    const payloadB64Url = parts[1];
+    const padLen = (4 - (payloadB64Url.length % 4)) % 4;
+    const base64 = payloadB64Url
+        .replace(/-/g, "+")
+        .replace(/_/g, "/")
+        .padEnd(payloadB64Url.length + padLen, "=");
+    return JSON.parse(atob(base64));
+}

package/esm/mcp/main.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "../_dnt.polyfills.js";
+//# sourceMappingURL=main.d.ts.map

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

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

package/esm/mcp/main.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// AtomicMail MCP server — stdio, PoW auth, JMAP (register / jmap_request / help).
+//
+// CONFIGURATION: credentials.json + session.jwt + capability.jwt in the
+// credential directory (default ~/.atomicmail/, override ATOMIC_MAIL_CREDENTIALS_DIR),
+// merged with ATOMIC_MAIL_AUTH_URL / ATOMIC_MAIL_API_URL / ATOMIC_MAIL_API_KEY.
+import "../_dnt.polyfills.js";
+import process from "node:process";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { AgentSession, resolveAgentConfigFromEnv } from "../lib/mod.js";
+import { registerHelpTool } from "./tools/help.js";
+import { registerJmapTool } from "./tools/jmap.js";
+import { registerRegisterTool } from "./tools/register.js";
+const VERSION = "0.1.0";
+const INSTRUCTIONS = `\
+Atomic Mail MCP — programmable inbox for AI agents.
+
+WORKFLOW
+  1. Call register with a desired username (PoW signup; credentials on disk).
+  2. Call jmap_request with JMAP method calls (inline ops JSON or ops_file preset).
+     $VAR_NAME tokens: $ACCOUNT_ID / $INBOX from session; pass others in vars.
+  3. Call help for full documentation (JMAP cheatsheet, presets, troubleshooting).
+
+CREDENTIAL DIRECTORY
+  Default ~/.atomicmail/ (override ATOMIC_MAIL_CREDENTIALS_DIR). Same files as
+  the @atomicmail/agent-skill CLI: credentials.json, session.jwt, capability.jwt.
+
+ENVIRONMENT
+  ATOMIC_MAIL_CREDENTIALS_DIR  credential directory
+  ATOMIC_MAIL_AUTH_URL         auth-service base URL
+  ATOMIC_MAIL_API_URL          JMAP / API base URL
+  ATOMIC_MAIL_SCRYPT_SALT      optional PoW salt override
+  ATOMIC_MAIL_API_KEY          optional existing API key
+
+SECURITY
+  credentials.json contains your apiKey — treat it as a secret (mode 0600).`;
+async function main() {
+    let config;
+    try {
+        config = await resolveAgentConfigFromEnv();
+    }
+    catch (err) {
+        console.error("Atomic Mail MCP: configuration error:", err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+    console.error(`Atomic Mail MCP v${VERSION}: credential dir '${config.credentialDir}' ` +
+        `(config source: ${config.source}).`);
+    if (config.apiKey) {
+        console.error(`Atomic Mail MCP: API key configured${config.inboxId ? ` (inbox ${config.inboxId})` : ""}.`);
+    }
+    else {
+        console.error("Atomic Mail MCP: no API key — call register to create an account.");
+    }
+    const session = await AgentSession.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);
+    registerHelpTool(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("Atomic Mail MCP: server running on stdio");
+}
+main().catch((err) => {
+    console.error("Atomic Mail MCP: fatal error:", err);
+    process.exit(1);
+});

package/esm/mcp/tools/help.d.ts

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

package/esm/mcp/tools/help.d.ts.map

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

package/esm/mcp/tools/help.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { getHelp, HELP_TOPIC_LIST } from "../../lib/mod.js";
+export function registerHelpTool(server) {
+    server.registerTool("help", {
+        title: "Atomic Mail documentation",
+        description: "Return in-depth documentation: JMAP cheatsheet, presets, auth flow, " +
+            "troubleshooting. Optional topic. Topics: " +
+            HELP_TOPIC_LIST.join(", ") + ".",
+        inputSchema: z.object({
+            topic: z
+                .string()
+                .optional()
+                .describe(`Topic (e.g. ${HELP_TOPIC_LIST.slice(0, 4).join(", ")}, ...). Omit for overview.`),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+    }, ({ topic }) => ({
+        content: [{ type: "text", text: getHelp(topic) }],
+    }));
+}

package/esm/mcp/{src/tools → tools}/jmap.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
-import type { AuthSession } from "../auth-session.js";
-export declare function registerJmapTool(server: McpServer, session: AuthSession): void;
+import { type AgentSession } from "../../lib/mod.js";
+export declare function registerJmapTool(server: McpServer, session: AgentSession): void;
 //# sourceMappingURL=jmap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jmap.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/jmap.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAEtE,OAAO,EACL,KAAK,YAAY,EAIlB,MAAM,kBAAkB,CAAC;AAE1B,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,YAAY,GACpB,IAAI,CAmIN"}

package/esm/mcp/tools/jmap.js

@@ -0,0 +1,115 @@
+import { z } from "zod";
+import { DEFAULT_JMAP_USING, readOpsFile, runJmapRequest, } from "../../lib/mod.js";
+export function registerJmapTool(server, session) {
+    server.registerTool("jmap_request", {
+        title: "Send a JMAP request",
+        description: "Send a JMAP method-call batch. Auth and JWT rotation are automatic. " +
+            "Provide exactly one of: `ops` (JSON string — methodCalls array or full " +
+            "envelope) or `ops_file` (preset path; relative paths resolve against " +
+            "the credential directory). Tokens `$VAR_NAME` (uppercase `$FOO_BAR`) in " +
+            "either input are replaced: `$ACCOUNT_ID` and `$INBOX` come from the JMAP " +
+            "session; pass other names via `vars`.",
+        inputSchema: z.object({
+            using: z
+                .array(z.string())
+                .default([...DEFAULT_JMAP_USING])
+                .describe("JMAP capability URNs when `ops` omits `using`. Ignored if the " +
+                "JSON body already sets `using`."),
+            ops: z
+                .string()
+                .optional()
+                .describe("Inline JSON: methodCalls array or { using, methodCalls }. " +
+                "Mutually exclusive with ops_file."),
+            ops_file: z
+                .string()
+                .optional()
+                .describe("Path to a preset JSON file. Mutually exclusive with ops."),
+            vars: z
+                .record(z.string().regex(/^[A-Z][A-Z0-9_]*$/), z.string())
+                .optional()
+                .describe("Map of placeholder names (no `$`) to string values, e.g. " +
+                '{ "TO": "a@b.com", "SUBJECT": "Hi" } for `$TO` and `$SUBJECT` in ' +
+                "ops or ops_file. Overrides session values for `ACCOUNT_ID` / `INBOX` if set."),
+        }),
+    }, async ({ using, ops, ops_file, vars }) => {
+        try {
+            if (ops && ops_file) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "ops and ops_file are mutually exclusive — provide one.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            if (!ops && !ops_file) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Provide either ops or ops_file.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            let raw;
+            let sourceLabel;
+            if (ops_file) {
+                try {
+                    raw = await readOpsFile(session.credentialDir, ops_file);
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Could not read ops_file: ${err.message}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                sourceLabel = `ops_file '${ops_file}'`;
+            }
+            else {
+                raw = ops;
+                sourceLabel = "ops";
+            }
+            const { ok, status, bodyText } = await runJmapRequest({
+                session,
+                opsJson: raw,
+                defaultUsing: using,
+                sourceLabel,
+                vars,
+            });
+            if (!ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `JMAP request failed (HTTP ${status}): ${bodyText}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return {
+                content: [{ type: "text", text: bodyText }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `JMAP request error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/esm/mcp/{src/tools → tools}/register.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
-import type { AuthSession } from "../auth-session.js";
-export declare function registerRegisterTool(server: McpServer, session: AuthSession): void;
+import type { AgentSession } from "../../lib/mod.js";
+export declare function registerRegisterTool(server: McpServer, session: AgentSession): void;
 //# sourceMappingURL=register.d.ts.map

package/esm/mcp/tools/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/register.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAEtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,YAAY,GACpB,IAAI,CAiDN"}

package/esm/mcp/tools/register.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+export function registerRegisterTool(server, session) {
+    server.registerTool("register", {
+        title: "Register an Atomic Mail inbox",
+        description: "Proof-of-work signup; persists credentials. Idempotent when the same " +
+            "username matches the inbox already stored. A different username " +
+            "replaces credentials and creates a new inbox. Returns JSON with " +
+            "inbox, accountId, and apiKey on first signup only.",
+        inputSchema: z.object({
+            username: z
+                .string()
+                .min(1)
+                .describe("Desired username (local-part of your @atomicmail.ai address)."),
+        }),
+        annotations: {
+            idempotentHint: true,
+            destructiveHint: false,
+        },
+    }, async ({ username }) => {
+        try {
+            const result = await session.register(username);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Registration failed: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@atomicmail/mcp",
-  "version": "0.1.0",
-  "description": "AtomicMail MCP server — local stdio proxy with PoW auth and JMAP, for AI agents.",
+  "version": "0.2.1",
+  "description": "Atomic Mail MCP server — local stdio proxy with PoW auth and JMAP, for AI agents.",
   "keywords": [
     "atomic-mail",
     "atomicmail",
@@ -16,15 +16,15 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/atomic-mail/agentic-mail.git"
+    "url": "git+https://github.com/atomic-mail/agentic-clients.git"
   },
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/atomic-mail/agentic-mail/issues"
+    "url": "https://github.com/atomic-mail/agentic-clients/issues"
   },
   "scripts": {},
   "bin": {
-    "atomicmail-mcp": "./esm/mcp/src/main.js"
+    "atomicmail-mcp": "./esm/mcp/main.js"
   },
   "engines": {
     "node": ">=20"

package/presets/list_inbox.json

@@ -0,0 +1,39 @@
+{
+  "using": [
+    "urn:ietf:params:jmap:core",
+    "urn:ietf:params:jmap:mail"
+  ],
+  "methodCalls": [
+    [
+      "Email/query",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "filter": { "inMailbox": "$INBOX" },
+        "sort": [{ "property": "receivedAt", "isAscending": false }],
+        "limit": "$COUNT"
+      },
+      "q0"
+    ],
+    [
+      "Email/get",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "#ids": {
+          "resultOf": "q0",
+          "name": "Email/query",
+          "path": "/ids"
+        },
+        "properties": [
+          "id",
+          "threadId",
+          "receivedAt",
+          "from",
+          "to",
+          "subject",
+          "preview"
+        ]
+      },
+      "g0"
+    ]
+  ]
+}

package/presets/reply.json

@@ -0,0 +1,75 @@
+{
+  "using": [
+    "urn:ietf:params:jmap:core",
+    "urn:ietf:params:jmap:mail",
+    "urn:ietf:params:jmap:submission"
+  ],
+  "methodCalls": [
+    [
+      "Email/get",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "ids": ["$MAIL_ID"],
+        "properties": [
+          "id",
+          "threadId",
+          "from",
+          "replyTo",
+          "subject",
+          "messageId"
+        ]
+      },
+      "g0"
+    ],
+    [
+      "Email/set",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "create": {
+          "d1": {
+            "from": [{ "email": "$INBOX" }],
+            "#to": {
+              "resultOf": "g0",
+              "name": "Email/get",
+              "path": "/list/0/replyTo"
+            },
+            "#subject": {
+              "resultOf": "g0",
+              "name": "Email/get",
+              "path": "/list/0/subject"
+            },
+            "#inReplyTo": {
+              "resultOf": "g0",
+              "name": "Email/get",
+              "path": "/list/0/messageId"
+            },
+            "textBody": [{ "partId": "b", "type": "text/plain" }],
+            "bodyValues": { "b": { "value": "$BODY" } },
+            "keywords": { "$draft": true }
+          }
+        }
+      },
+      "c0"
+    ],
+    [
+      "EmailSubmission/set",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "create": {
+          "s1": {
+            "emailId": "#d1",
+            "envelope": {
+              "mailFrom": { "email": "$INBOX" },
+              "#rcptTo": {
+                "resultOf": "g0",
+                "name": "Email/get",
+                "path": "/list/0/replyTo"
+              }
+            }
+          }
+        }
+      },
+      "c1"
+    ]
+  ]
+}