@codespar/mcp-evolution-api 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,120 @@
+# @codespar/mcp-evolution-api
+
+> MCP server for **Evolution API** — self-hosted WhatsApp messaging API
+
+[![npm](https://img.shields.io/npm/v/@codespar/mcp-evolution-api)](https://www.npmjs.com/package/@codespar/mcp-evolution-api)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Quick Start
+
+### Claude Desktop
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "evolution-api": {
+      "command": "npx",
+      "args": ["-y", "@codespar/mcp-evolution-api"],
+      "env": {
+        "EVOLUTION_API_URL": "https://your-instance.example.com",
+        "EVOLUTION_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add evolution-api -- npx @codespar/mcp-evolution-api
+```
+
+### Cursor / VS Code
+
+Add to `.cursor/mcp.json` or `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "evolution-api": {
+      "command": "npx",
+      "args": ["-y", "@codespar/mcp-evolution-api"],
+      "env": {
+        "EVOLUTION_API_URL": "https://your-instance.example.com",
+        "EVOLUTION_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `send_text` | Send a text message via WhatsApp |
+| `send_image` | Send an image message via WhatsApp |
+| `send_document` | Send a document via WhatsApp |
+| `get_instances` | List all WhatsApp instances |
+| `create_instance` | Create a new WhatsApp instance |
+| `get_qrcode` | Get QR code for instance pairing |
+| `get_contacts` | Get contacts from an instance |
+| `send_poll` | Send a poll message via WhatsApp |
+| `get_messages` | Get messages from a chat |
+| `check_number` | Check if a phone number is registered on WhatsApp |
+
+## Authentication
+
+Evolution API uses an API key passed via the `apikey` header.
+
+## Sandbox / Testing
+
+Evolution API is self-hosted. Deploy your own instance using Docker for testing.
+
+### Get your credentials
+
+1. Go to [Evolution API Documentation](https://doc.evolution-api.com)
+2. Deploy your own instance (Docker recommended)
+3. Get the API key from your instance configuration
+4. Set the environment variables
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `EVOLUTION_API_URL` | Yes | Base URL of your Evolution API instance |
+| `EVOLUTION_API_KEY` | Yes | API key for authentication |
+
+## Roadmap
+
+### v0.2 (planned)
+- `create_group` — Create a WhatsApp group
+- `get_group_info` — Get group details and participants
+- `update_profile` — Update instance profile (name, photo, status)
+- `set_presence` — Set online/offline presence status
+- `get_chat_history` — Get full chat history with a contact
+
+### v0.3 (planned)
+- `bulk_send` — Send messages to multiple contacts
+- `template_messages` — Send WhatsApp Business template messages
+- `label_management` — Create, update, and assign labels to chats
+
+Want to contribute? [Open a PR](https://github.com/codespar/mcp-dev-brasil) or [request a tool](https://github.com/codespar/mcp-dev-brasil/issues).
+
+## Links
+
+- [Evolution API Documentation](https://doc.evolution-api.com)
+- [Evolution API GitHub](https://github.com/EvolutionAPI/evolution-api)
+- [MCP Dev Brasil](https://github.com/codespar/mcp-dev-brasil)
+- [Landing Page](https://codespar.dev/mcp)
+
+## Enterprise
+
+Need governance, budget limits, and audit trails for agent payments? [CodeSpar Enterprise](https://codespar.dev/enterprise) adds policy engine, payment routing, and compliance templates on top of these MCP servers.
+
+## License
+
+MIT

package/dist/index.js

@@ -13,6 +13,11 @@
  * - send_poll: Send a poll message
  * - get_messages: Get messages from a chat
  * - check_number: Check if a number is on WhatsApp
+ * - create_group: Create a WhatsApp group
+ * - get_group_info: Get group metadata and participants
+ * - update_profile: Update instance profile (name, picture, status)
+ * - set_presence: Set online/offline presence for an instance
+ * - get_chat_history: Get full chat history with pagination
  *
  * Environment:
  *   EVOLUTION_API_URL — Base URL of self-hosted Evolution API
@@ -20,6 +25,8 @@
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 const API_URL = process.env.EVOLUTION_API_URL || "";
 const API_KEY = process.env.EVOLUTION_API_KEY || "";
@@ -170,6 +177,78 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["instance", "numbers"],
             },
         },
+        {
+            name: "create_group",
+            description: "Create a WhatsApp group",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    instance: { type: "string", description: "Instance name" },
+                    subject: { type: "string", description: "Group name/subject" },
+                    participants: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Array of phone numbers to add (with country code)",
+                    },
+                    description: { type: "string", description: "Group description" },
+                },
+                required: ["instance", "subject", "participants"],
+            },
+        },
+        {
+            name: "get_group_info",
+            description: "Get group metadata, participants, and settings",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    instance: { type: "string", description: "Instance name" },
+                    groupJid: { type: "string", description: "Group JID (e.g. 120363000000000000@g.us)" },
+                },
+                required: ["instance", "groupJid"],
+            },
+        },
+        {
+            name: "update_profile",
+            description: "Update instance profile (name, status text, or picture)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    instance: { type: "string", description: "Instance name" },
+                    name: { type: "string", description: "New profile name" },
+                    status: { type: "string", description: "New status text" },
+                    picture: { type: "string", description: "URL of profile picture" },
+                },
+                required: ["instance"],
+            },
+        },
+        {
+            name: "set_presence",
+            description: "Set online/offline presence for an instance",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    instance: { type: "string", description: "Instance name" },
+                    presence: { type: "string", enum: ["available", "unavailable", "composing", "recording", "paused"], description: "Presence state" },
+                    number: { type: "string", description: "Target number (required for composing/recording)" },
+                },
+                required: ["instance", "presence"],
+            },
+        },
+        {
+            name: "get_chat_history",
+            description: "Get full chat history with pagination support",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    instance: { type: "string", description: "Instance name" },
+                    remoteJid: { type: "string", description: "Chat JID (e.g. 5511999999999@s.whatsapp.net)" },
+                    limit: { type: "number", description: "Number of messages (default 50)" },
+                    offset: { type: "number", description: "Pagination offset (message index)" },
+                    fromMe: { type: "boolean", description: "Filter only sent messages" },
+                },
+                required: ["instance", "remoteJid"],
+            },
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -200,6 +279,34 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case "check_number":
                 return { content: [{ type: "text", text: JSON.stringify(await evolutionRequest("POST", `/chat/whatsappNumbers/${args?.instance}`, { numbers: args?.numbers }), null, 2) }] };
+            case "create_group":
+                return { content: [{ type: "text", text: JSON.stringify(await evolutionRequest("POST", `/group/create/${args?.instance}`, { subject: args?.subject, participants: args?.participants, description: args?.description }), null, 2) }] };
+            case "get_group_info":
+                return { content: [{ type: "text", text: JSON.stringify(await evolutionRequest("GET", `/group/findGroupInfos/${args?.instance}?groupJid=${args?.groupJid}`), null, 2) }] };
+            case "update_profile": {
+                const profileData = {};
+                if (args?.name)
+                    profileData.name = args.name;
+                if (args?.status)
+                    profileData.status = args.status;
+                if (args?.picture)
+                    profileData.picture = args.picture;
+                return { content: [{ type: "text", text: JSON.stringify(await evolutionRequest("PUT", `/instance/updateProfile/${args?.instance}`, profileData), null, 2) }] };
+            }
+            case "set_presence":
+                return { content: [{ type: "text", text: JSON.stringify(await evolutionRequest("POST", `/chat/setPresence/${args?.instance}`, { presence: args?.presence, number: args?.number }), null, 2) }] };
+            case "get_chat_history": {
+                const body = {
+                    where: { key: { remoteJid: args?.remoteJid } },
+                };
+                if (args?.limit)
+                    body.limit = args.limit;
+                if (args?.offset)
+                    body.offset = args.offset;
+                if (args?.fromMe !== undefined)
+                    body.where = { ...body.where, key: { remoteJid: args?.remoteJid, fromMe: args.fromMe } };
+                return { content: [{ type: "text", text: JSON.stringify(await evolutionRequest("POST", `/chat/findMessages/${args?.instance}`, body), null, 2) }] };
+            }
             default:
                 return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
         }
@@ -209,11 +316,46 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
 });
 async function main() {
-    if (!API_URL || !API_KEY) {
-        console.error("EVOLUTION_API_URL and EVOLUTION_API_KEY environment variables are required");
-        process.exit(1);
+    if (process.argv.includes("--http") || process.env.MCP_HTTP === "true") {
+        const { default: express } = await import("express");
+        const { randomUUID } = await import("node:crypto");
+        const app = express();
+        app.use(express.json());
+        const transports = new Map();
+        app.get("/health", (_req, res) => res.json({ status: "ok", sessions: transports.size }));
+        app.post("/mcp", async (req, res) => {
+            const sid = req.headers["mcp-session-id"];
+            if (sid && transports.has(sid)) {
+                await transports.get(sid).handleRequest(req, res, req.body);
+                return;
+            }
+            if (!sid && isInitializeRequest(req.body)) {
+                const t = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), onsessioninitialized: (id) => { transports.set(id, t); } });
+                t.onclose = () => { if (t.sessionId)
+                    transports.delete(t.sessionId); };
+                const s = new Server({ name: "mcp-evolution-api", version: "0.1.0" }, { capabilities: { tools: {} } });
+                server._requestHandlers.forEach((v, k) => s._requestHandlers.set(k, v));
+                server._notificationHandlers?.forEach((v, k) => s._notificationHandlers.set(k, v));
+                await s.connect(t);
+                await t.handleRequest(req, res, req.body);
+                return;
+            }
+            res.status(400).json({ jsonrpc: "2.0", error: { code: -32000, message: "Bad Request" }, id: null });
+        });
+        app.get("/mcp", async (req, res) => { const sid = req.headers["mcp-session-id"]; if (sid && transports.has(sid))
+            await transports.get(sid).handleRequest(req, res);
+        else
+            res.status(400).send("Invalid session"); });
+        app.delete("/mcp", async (req, res) => { const sid = req.headers["mcp-session-id"]; if (sid && transports.has(sid))
+            await transports.get(sid).handleRequest(req, res);
+        else
+            res.status(400).send("Invalid session"); });
+        const port = Number(process.env.MCP_PORT) || 3000;
+        app.listen(port, () => { console.error(`MCP HTTP server on http://localhost:${port}/mcp`); });
+    }
+    else {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
     }
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
 }
 main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codespar/mcp-evolution-api",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for Evolution API — WhatsApp messaging, instances, contacts",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,5 +25,6 @@
     "whatsapp",
     "messaging",
     "brazil"
-  ]
+  ],
+  "mcpName": "io.github.codespar/mcp-evolution-api"
 }

package/server.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.codespar/mcp-evolution-api",
+  "description": "MCP server for Evolution API — WhatsApp messaging, instances, contacts",
+  "repository": {
+    "url": "https://github.com/codespar/mcp-dev-brasil",
+    "source": "github",
+    "subfolder": "packages/communication/evolution-api"
+  },
+  "version": "0.1.2",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@codespar/mcp-evolution-api",
+      "version": "0.1.2",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "EVOLUTION_API_KEY",
+          "description": "API key for evolution-api",
+          "isRequired": true,
+          "format": "string",
+          "isSecret": true
+        }
+      ]
+    }
+  ]
+}

package/src/__tests__/index.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+let listToolsHandler: Function;
+let callToolHandler: Function;
+
+vi.mock("@modelcontextprotocol/sdk/server/index.js", () => {
+  class FakeServer {
+    constructor() {}
+    setRequestHandler(schema: any, handler: Function) {
+      if (JSON.stringify(schema).includes("tools/list")) listToolsHandler = handler;
+      if (JSON.stringify(schema).includes("tools/call")) callToolHandler = handler;
+    }
+    connect() { return Promise.resolve(); }
+  }
+  return { Server: FakeServer };
+});
+
+vi.mock("@modelcontextprotocol/sdk/server/stdio.js", () => ({ StdioServerTransport: class {} }));
+
+process.env.EVOLUTION_API_URL = "https://evo.example.com";
+process.env.EVOLUTION_API_KEY = "test-key";
+
+const mockFetch = vi.fn();
+global.fetch = mockFetch as any;
+
+beforeEach(async () => {
+  vi.resetModules();
+  listToolsHandler = undefined as any;
+  callToolHandler = undefined as any;
+  mockFetch.mockReset();
+  global.fetch = mockFetch as any;
+  await import("../index.js");
+});
+
+describe("mcp-evolution-api", () => {
+  it("should register 15 tools", async () => {
+    const result = await listToolsHandler();
+    expect(result.tools).toHaveLength(15);
+  });
+
+  it("should call correct API endpoint for send_text", async () => {
+    mockFetch.mockResolvedValueOnce({ ok: true, json: () => Promise.resolve({ key: { id: "msg1" } }) });
+
+    await callToolHandler({
+      params: { name: "send_text", arguments: { instance: "mybot", number: "5511999999999", text: "Hello" } },
+    });
+
+    const [url, opts] = mockFetch.mock.calls[0];
+    expect(url).toContain("/message/sendText/mybot");
+    expect(opts.method).toBe("POST");
+    expect(opts.headers.apikey).toBe("test-key");
+  });
+});

package/src/index.ts

@@ -14,6 +14,11 @@
  * - send_poll: Send a poll message
  * - get_messages: Get messages from a chat
  * - check_number: Check if a number is on WhatsApp
+ * - create_group: Create a WhatsApp group
+ * - get_group_info: Get group metadata and participants
+ * - update_profile: Update instance profile (name, picture, status)
+ * - set_presence: Set online/offline presence for an instance
+ * - get_chat_history: Get full chat history with pagination
  *
  * Environment:
  *   EVOLUTION_API_URL — Base URL of self-hosted Evolution API
@@ -22,6 +27,8 @@
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
@@ -182,6 +189,78 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["instance", "numbers"],
       },
     },
+    {
+      name: "create_group",
+      description: "Create a WhatsApp group",
+      inputSchema: {
+        type: "object",
+        properties: {
+          instance: { type: "string", description: "Instance name" },
+          subject: { type: "string", description: "Group name/subject" },
+          participants: {
+            type: "array",
+            items: { type: "string" },
+            description: "Array of phone numbers to add (with country code)",
+          },
+          description: { type: "string", description: "Group description" },
+        },
+        required: ["instance", "subject", "participants"],
+      },
+    },
+    {
+      name: "get_group_info",
+      description: "Get group metadata, participants, and settings",
+      inputSchema: {
+        type: "object",
+        properties: {
+          instance: { type: "string", description: "Instance name" },
+          groupJid: { type: "string", description: "Group JID (e.g. 120363000000000000@g.us)" },
+        },
+        required: ["instance", "groupJid"],
+      },
+    },
+    {
+      name: "update_profile",
+      description: "Update instance profile (name, status text, or picture)",
+      inputSchema: {
+        type: "object",
+        properties: {
+          instance: { type: "string", description: "Instance name" },
+          name: { type: "string", description: "New profile name" },
+          status: { type: "string", description: "New status text" },
+          picture: { type: "string", description: "URL of profile picture" },
+        },
+        required: ["instance"],
+      },
+    },
+    {
+      name: "set_presence",
+      description: "Set online/offline presence for an instance",
+      inputSchema: {
+        type: "object",
+        properties: {
+          instance: { type: "string", description: "Instance name" },
+          presence: { type: "string", enum: ["available", "unavailable", "composing", "recording", "paused"], description: "Presence state" },
+          number: { type: "string", description: "Target number (required for composing/recording)" },
+        },
+        required: ["instance", "presence"],
+      },
+    },
+    {
+      name: "get_chat_history",
+      description: "Get full chat history with pagination support",
+      inputSchema: {
+        type: "object",
+        properties: {
+          instance: { type: "string", description: "Instance name" },
+          remoteJid: { type: "string", description: "Chat JID (e.g. 5511999999999@s.whatsapp.net)" },
+          limit: { type: "number", description: "Number of messages (default 50)" },
+          offset: { type: "number", description: "Pagination offset (message index)" },
+          fromMe: { type: "boolean", description: "Filter only sent messages" },
+        },
+        required: ["instance", "remoteJid"],
+      },
+    },
   ],
 }));
 
@@ -213,6 +292,28 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
       case "check_number":
         return { content: [{ type: "text", text: JSON.stringify(await evolutionRequest("POST", `/chat/whatsappNumbers/${args?.instance}`, { numbers: args?.numbers }), null, 2) }] };
+      case "create_group":
+        return { content: [{ type: "text", text: JSON.stringify(await evolutionRequest("POST", `/group/create/${args?.instance}`, { subject: args?.subject, participants: args?.participants, description: args?.description }), null, 2) }] };
+      case "get_group_info":
+        return { content: [{ type: "text", text: JSON.stringify(await evolutionRequest("GET", `/group/findGroupInfos/${args?.instance}?groupJid=${args?.groupJid}`), null, 2) }] };
+      case "update_profile": {
+        const profileData: Record<string, unknown> = {};
+        if (args?.name) profileData.name = args.name;
+        if (args?.status) profileData.status = args.status;
+        if (args?.picture) profileData.picture = args.picture;
+        return { content: [{ type: "text", text: JSON.stringify(await evolutionRequest("PUT", `/instance/updateProfile/${args?.instance}`, profileData), null, 2) }] };
+      }
+      case "set_presence":
+        return { content: [{ type: "text", text: JSON.stringify(await evolutionRequest("POST", `/chat/setPresence/${args?.instance}`, { presence: args?.presence, number: args?.number }), null, 2) }] };
+      case "get_chat_history": {
+        const body: Record<string, unknown> = {
+          where: { key: { remoteJid: args?.remoteJid } },
+        };
+        if (args?.limit) body.limit = args.limit;
+        if (args?.offset) body.offset = args.offset;
+        if (args?.fromMe !== undefined) body.where = { ...(body.where as Record<string, unknown>), key: { remoteJid: args?.remoteJid, fromMe: args.fromMe } };
+        return { content: [{ type: "text", text: JSON.stringify(await evolutionRequest("POST", `/chat/findMessages/${args?.instance}`, body), null, 2) }] };
+      }
       default:
         return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
     }
@@ -222,12 +323,32 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 
 async function main() {
-  if (!API_URL || !API_KEY) {
-    console.error("EVOLUTION_API_URL and EVOLUTION_API_KEY environment variables are required");
-    process.exit(1);
+  if (process.argv.includes("--http") || process.env.MCP_HTTP === "true") {
+    const { default: express } = await import("express");
+    const { randomUUID } = await import("node:crypto");
+    const app = express();
+    app.use(express.json());
+    const transports = new Map<string, StreamableHTTPServerTransport>();
+    app.get("/health", (_req: any, res: any) => res.json({ status: "ok", sessions: transports.size }));
+    app.post("/mcp", async (req: any, res: any) => {
+      const sid = req.headers["mcp-session-id"] as string | undefined;
+      if (sid && transports.has(sid)) { await transports.get(sid)!.handleRequest(req, res, req.body); return; }
+      if (!sid && isInitializeRequest(req.body)) {
+        const t = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), onsessioninitialized: (id) => { transports.set(id, t); } });
+        t.onclose = () => { if (t.sessionId) transports.delete(t.sessionId); };
+        const s = new Server({ name: "mcp-evolution-api", version: "0.1.0" }, { capabilities: { tools: {} } }); (server as any)._requestHandlers.forEach((v: any, k: any) => (s as any)._requestHandlers.set(k, v)); (server as any)._notificationHandlers?.forEach((v: any, k: any) => (s as any)._notificationHandlers.set(k, v)); await s.connect(t);
+        await t.handleRequest(req, res, req.body); return;
+      }
+      res.status(400).json({ jsonrpc: "2.0", error: { code: -32000, message: "Bad Request" }, id: null });
+    });
+    app.get("/mcp", async (req: any, res: any) => { const sid = req.headers["mcp-session-id"] as string; if (sid && transports.has(sid)) await transports.get(sid)!.handleRequest(req, res); else res.status(400).send("Invalid session"); });
+    app.delete("/mcp", async (req: any, res: any) => { const sid = req.headers["mcp-session-id"] as string; if (sid && transports.has(sid)) await transports.get(sid)!.handleRequest(req, res); else res.status(400).send("Invalid session"); });
+    const port = Number(process.env.MCP_PORT) || 3000;
+    app.listen(port, () => { console.error(`MCP HTTP server on http://localhost:${port}/mcp`); });
+  } else {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
   }
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
 }
 
 main().catch(console.error);

package/tsconfig.json

@@ -6,6 +6,7 @@
     "outDir": "./dist",
     "rootDir": "./src",
     "strict": true,
+    "skipLibCheck": true,
     "esModuleInterop": true,
     "declaration": true
   },