@agenticmail/mcp 0.7.0 → 0.7.2

package/README.md

@@ -10,7 +10,7 @@ When connected, your AI agent can send emails and texts, check inboxes, reply to
 npm install -g @agenticmail/mcp
 ```
 
-**Requirements:** Node.js 20+, AgenticMail API server running
+**Requirements:** Node.js 22+, AgenticMail API server running
 
 ---
 
@@ -35,7 +35,7 @@ Add to your MCP client configuration (e.g., `.mcp.json` or project settings):
       "command": "npx",
       "args": ["agenticmail-mcp"],
       "env": {
-        "AGENTICMAIL_API_URL": "http://127.0.0.1:3100",
+        "AGENTICMAIL_API_URL": "http://127.0.0.1:3829",
         "AGENTICMAIL_API_KEY": "ak_your_agent_key"
       }
     }
@@ -56,7 +56,7 @@ For desktop AI applications, add to your MCP configuration file. Example paths:
       "command": "npx",
       "args": ["agenticmail-mcp"],
       "env": {
-        "AGENTICMAIL_API_URL": "http://127.0.0.1:3100",
+        "AGENTICMAIL_API_URL": "http://127.0.0.1:3829",
         "AGENTICMAIL_API_KEY": "ak_your_agent_key"
       }
     }
@@ -68,9 +68,27 @@ For desktop AI applications, add to your MCP configuration file. Example paths:
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `AGENTICMAIL_API_URL` | Yes | AgenticMail API server URL (e.g., `http://127.0.0.1:3100`) |
-| `AGENTICMAIL_API_KEY` | Yes | Agent API key (`ak_...`). Determines which agent this MCP server acts as. |
-| `AGENTICMAIL_MASTER_KEY` | No | Master key (`mk_...`). Required for admin operations (create/delete agents, approve emails, gateway config). |
+| `AGENTICMAIL_API_URL` | Yes | AgenticMail API server URL. Default port is **`3829`** (changed from `3100` in `@agenticmail/mcp@0.7.x` to avoid common dev-tool conflicts). Example: `http://127.0.0.1:3829`. |
+| `AGENTICMAIL_API_KEY` | Yes¹ | Agent API key (`ak_...`). Determines the default identity this MCP server acts as when a tool call doesn't pass `_account`. |
+| `AGENTICMAIL_MASTER_KEY` | No | Master key (`mk_...`). Required for admin operations (create/delete agents, approve emails, gateway config). **Also enables on-demand `_account` resolution** — any tool call passing `_account: "<name>"` will lazily fetch that agent's API key via the master key the first time it sees the name, so freshly-`create_account`'d agents become addressable without restarting the MCP server. |
+| `AGENTICMAIL_ACCOUNT_KEYS_JSON` | No | JSON map of `{"<agentName>": "<apiKey>"}` for per-call identity switching. When the caller passes `_account: "Fola"` (etc.), the server authenticates AS that agent for the duration of the call. Populated automatically by `agenticmail claudecode install` for the Claude Code integration. |
+
+¹ Either `AGENTICMAIL_API_KEY` OR `AGENTICMAIL_MASTER_KEY` (or `AGENTICMAIL_ACCOUNT_KEYS_JSON`) must be set, but you don't strictly need all three.
+
+### Per-call identity switching (`_account`)
+
+Every tool's input schema accepts an optional `_account: "<name>"` parameter. When passed, the server resolves that name to an apiKey (from `AGENTICMAIL_ACCOUNT_KEYS_JSON`, then falling back to a live master-keyed lookup of `/accounts`) and runs the call as that agent. Without `_account`, the call uses `AGENTICMAIL_API_KEY` as the default identity.
+
+This is what powers the [`@agenticmail/claudecode`](https://www.npmjs.com/package/@agenticmail/claudecode) integration: one MCP server process, many AgenticMail identities. A Claude Code subagent that "is" Fola passes `_account: "Fola"` on every call and ends up reading Fola's real inbox, sending mail from `fola@localhost`, and so on.
+
+### Meta-tools for cheap discovery (`request_tools` + `invoke`)
+
+To keep host context windows small, only ~10 of the 62 tools are pre-declared in a typical subagent's `tools:` whitelist. The other ~50 stay reachable through two always-on meta-tools:
+
+- **`request_tools({ query?, sets? })`** — Returns a text catalogue of the unloaded tools, grouped by set (`mail_extras`, `mail_compose`, `sms`, `account_admin`, …). Optional substring filter or set-name filter.
+- **`invoke({ tool, args, _account? })`** — Dispatches to any of the 62 tools by name. The agent uses `request_tools` to discover, `invoke` to call.
+
+Token impact: a typical subagent spawn loads ~3K tokens of tool schemas instead of ~15K. The cost is one extra round trip for uncommon operations (discover → invoke), which is almost always a worthwhile trade.
 
 ---
 

package/dist/index.js

@@ -22878,7 +22878,7 @@ var toolDefinitions = [
   },
   {
     name: "create_account",
-    description: "Create a new agent email account (requires master API key)",
+    description: 'Create a new AgenticMail agent (email account + identity + API key + persona derived from role/metadata). Requires master API key. After creation: address them at `<name>@localhost`, delegate work via `call_agent({ target: "<name>", task: ... })`, or hand off via `send_email` / `message_agent`. The new agent acts as themselves \u2014 you never need to (and must not) roleplay them inside your host\'s native sub-agent tool.',
     inputSchema: {
       type: "object",
       properties: {
@@ -22999,7 +22999,7 @@ var toolDefinitions = [
   },
   {
     name: "list_agents",
-    description: "List all AI agents in the system with their email addresses and roles. Use this to discover which agents you can communicate with via message_agent.",
+    description: "List all AI agents in the system with their email addresses and roles. Use this to discover which agents you can call via call_agent (sync RPC) or email via send_email / message_agent (async). DO NOT spawn one of your host's native sub-agents and roleplay AS these agents \u2014 each one is a real identity with its own mailbox; just address them through AgenticMail and let them work as themselves.",
     inputSchema: {
       type: "object",
       properties: {}
@@ -23007,7 +23007,7 @@ var toolDefinitions = [
   },
   {
     name: "message_agent",
-    description: "Send a message to another AI agent by name. The message is delivered to their email inbox. Use list_agents first to see available agents. This is the primary way for agents to coordinate and share information with each other.",
+    description: "Async fire-and-forget: deliver a message to another AI agent's inbox. They will process it on their own schedule (immediately if a dispatcher is attached, later otherwise) and may reply by email. Use this for non-blocking handoffs. Prefer `call_agent` when you need a structured reply back. Both flows let the target agent do the work AS THEMSELVES \u2014 never roleplay them inside your own host.",
     inputSchema: {
       type: "object",
       properties: {
@@ -23248,7 +23248,7 @@ var toolDefinitions = [
   },
   {
     name: "call_agent",
-    description: "Synchronous RPC: assign a task to another agent, notify them via email (wakes wait_for_email), and wait for the result. Times out after specified duration.",
+    description: `Synchronous RPC to delegate work to another AgenticMail agent. Pipeline: the task is queued in AgenticMail, the target agent processes it AS THEMSELVES (under their real identity, mailbox, persona, and audit trail), and the structured result returns into your call. THIS IS HOW MULTI-AGENT COORDINATION IS SUPPOSED TO WORK from any MCP host. Do not, instead, spawn one of your host's native sub-agents and tell it to "act as <target>" \u2014 that produces output under your identity, never touches the target's inbox, and skips their persona. Times out after the specified duration (default 180s, max 300s).`,
     inputSchema: {
       type: "object",
       properties: {
@@ -24902,12 +24902,74 @@ function jsonSchemaToZod(schema, topLevel = false) {
   }
   return schema.description ? result.describe(schema.description) : result;
 }
+var SERVER_INSTRUCTIONS = [
+  "\u{1F380} AgenticMail \u2014 multi-agent email + SMS infrastructure.",
+  "",
+  "AgenticMail agents are NOT prompts you wrap around your host's native",
+  "sub-agent tool. Each AgenticMail agent is a persistent identity with its",
+  "own inbox, API key, persona, and audit trail. Address other agents through",
+  "AgenticMail's own primitives below \u2014 never roleplay them inside your host.",
+  "",
+  "How to coordinate work between agents \u2014 the right way:",
+  "",
+  "1. List or create the agents you need (`list_agents`, `create_account`).",
+  "2. Send them work using ONE of:",
+  "     \u2022 `call_agent({ target, task, payload?, timeout? })` \u2014 SYNCHRONOUS RPC.",
+  "         Fires a structured task at the target agent and waits for their",
+  "         result. The target processes the task as themselves (under their",
+  "         own identity and mailbox) and the structured result returns into",
+  "         your call. Use this when you need an answer back.",
+  '     \u2022 `send_email({ to: "<name>@localhost", ... })` or',
+  "       `message_agent({ agent, subject, text })` \u2014 ASYNCHRONOUS.",
+  "         Mail lands in their inbox; they process it on their own schedule",
+  "         and may reply by email. Use this for fire-and-forget handoffs.",
+  "3. Read replies with `list_inbox` + `read_email`, or `search_emails`.",
+  "",
+  "What NOT to do (regardless of host \u2014 Claude Code, ChatGPT, Cursor, Grok, \u2026):",
+  "",
+  "\u2717 Do NOT spawn a native sub-agent / sub-task / parallel-thinking tool of",
+  '  your host and instruct it to "act as Lyra" / "write as Orion". That',
+  "  produces output under YOUR identity, never reaches the named agent's",
+  "  inbox, and bypasses their persona, signatures, outbound guard, and",
+  "  audit trail. The real agent has not actually thought anything.",
+  "\u2717 Do NOT compose an agent's reply yourself in the host session and then",
+  "  `send_email` it on their behalf. Let `call_agent` (or an email handoff)",
+  "  produce the reply from the real agent.",
+  '\u2717 Do NOT pass `_account: "<other-agent>"` to act AS another agent. That',
+  "  falsifies the From: header. Use `call_agent` to delegate instead.",
+  "",
+  "How the wake-up actually happens (host-dependent \u2014 best-effort):",
+  "  - With the Claude Code integration installed, a dispatcher daemon",
+  "    auto-wakes the target agent as a Claude Code subagent when mail",
+  "    arrives or `call_agent` fires.",
+  "  - With other MCP hosts (no dispatcher), `send_email` / `message_agent`",
+  "    still deliver the mail; a human or another scheduled process picks",
+  "    it up later. `call_agent` will still queue the task and return its",
+  "    result once any worker (yourself, a cron, another agent) processes",
+  "    it \u2014 see `check_tasks` / `claim_task` / `submit_result`.",
+  "  Either way, the RIGHT primitives from your side are the same:",
+  "  call_agent / send_email / message_agent. Never roleplay.",
+  "",
+  "Identity & `_account`:",
+  '  Every tool call accepts an optional `_account: "<your-agent-name>"` to',
+  "  scope the call to a specific agent. From the HOST session, omit it to",
+  "  use bridge identity, or pass it to read/write a specific agent's",
+  "  mailbox directly. From inside an agent's own context, ALWAYS pass",
+  '  `_account: "<self>"`.',
+  "",
+  "Tool surface: ~62 tools across email, SMS, contacts, drafts, templates,",
+  "rules, tags, search, scheduling, RPC. Only ~10 are pre-loaded; the rest",
+  "are reachable via `request_tools` (discover) + `invoke` (call)."
+].join("\n");
 function createMcpServer() {
-  const server = new McpServer({
-    name: "\u{1F380} AgenticMail",
-    version: "0.2.27",
-    description: "\u{1F380} AgenticMail \u2014 Email infrastructure for AI agents. By Ope Olatunji (https://github.com/agenticmail/agenticmail)"
-  });
+  const server = new McpServer(
+    {
+      name: "\u{1F380} AgenticMail",
+      version: "0.2.29",
+      description: "\u{1F380} AgenticMail \u2014 Email infrastructure for AI agents. By Ope Olatunji (https://github.com/agenticmail/agenticmail)"
+    },
+    { instructions: SERVER_INSTRUCTIONS }
+  );
   const ACCOUNT_PROP = {
     type: "string",
     description: 'Optional. Override identity for THIS call: pass the AgenticMail agent name (e.g. "Fola") to authenticate as that agent. Requires AGENTICMAIL_ACCOUNT_KEYS_JSON to contain a matching key. Omit to use the default identity (AGENTICMAIL_API_KEY).'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/mcp",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "mcpName": "io.github.agenticmail/mcp",
   "description": "MCP server for AgenticMail — give any AI client real email and SMS capabilities",
   "type": "module",