@deus-ai/channel-core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { MessageBuffer } from './message-buffer.js';
+export { registerCommonTools } from './server-base.js';
+export type { ChannelProvider, ChannelStatus, ChatInfo, IncomingMessage, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EACV,eAAe,EACf,aAAa,EACb,QAAQ,EACR,eAAe,GAChB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { MessageBuffer } from './message-buffer.js';
+export { registerCommonTools } from './server-base.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/message-buffer.d.ts

@@ -0,0 +1,20 @@
+import { IncomingMessage } from './types.js';
+/**
+ * Ring buffer for incoming messages.
+ * Supports cursor-based pagination for the get_new_messages polling tool.
+ */
+export declare class MessageBuffer {
+    private messages;
+    private nextCursor;
+    push(msg: IncomingMessage): void;
+    /**
+     * Get messages since the given cursor.
+     * Returns the messages and a new cursor for the next call.
+     */
+    getSince(cursor?: string): {
+        messages: IncomingMessage[];
+        cursor: string;
+    };
+    get size(): number;
+}
+//# sourceMappingURL=message-buffer.d.ts.map

package/dist/message-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-buffer.d.ts","sourceRoot":"","sources":["../src/message-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAI7C;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,UAAU,CAAK;IAEvB,IAAI,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAWhC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAc1E,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/message-buffer.js

@@ -0,0 +1,37 @@
+const MAX_BUFFER_SIZE = 1000;
+/**
+ * Ring buffer for incoming messages.
+ * Supports cursor-based pagination for the get_new_messages polling tool.
+ */
+export class MessageBuffer {
+    messages = [];
+    nextCursor = 0;
+    push(msg) {
+        this.messages.push(msg);
+        this.nextCursor++;
+        // Trim old messages to prevent unbounded growth
+        if (this.messages.length > MAX_BUFFER_SIZE) {
+            const excess = this.messages.length - MAX_BUFFER_SIZE;
+            this.messages.splice(0, excess);
+        }
+    }
+    /**
+     * Get messages since the given cursor.
+     * Returns the messages and a new cursor for the next call.
+     */
+    getSince(cursor) {
+        const from = cursor ? parseInt(cursor, 10) : 0;
+        // Calculate the offset into the current buffer
+        const bufferStart = this.nextCursor - this.messages.length;
+        const startIndex = Math.max(0, from - bufferStart);
+        const newMessages = this.messages.slice(startIndex);
+        return {
+            messages: newMessages,
+            cursor: String(this.nextCursor),
+        };
+    }
+    get size() {
+        return this.messages.length;
+    }
+}
+//# sourceMappingURL=message-buffer.js.map

package/dist/message-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-buffer.js","sourceRoot":"","sources":["../src/message-buffer.ts"],"names":[],"mappings":"AAEA,MAAM,eAAe,GAAG,IAAI,CAAC;AAE7B;;;GAGG;AACH,MAAM,OAAO,aAAa;IAChB,QAAQ,GAAsB,EAAE,CAAC;IACjC,UAAU,GAAG,CAAC,CAAC;IAEvB,IAAI,CAAC,GAAoB;QACvB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,UAAU,EAAE,CAAC;QAElB,gDAAgD;QAChD,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;YAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,eAAe,CAAC;YACtD,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,MAAe;QACtB,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAE/C,+CAA+C;QAC/C,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QAC3D,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,WAAW,CAAC,CAAC;QACnD,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAEpD,OAAO;YACL,QAAQ,EAAE,WAAW;YACrB,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC;SAChC,CAAC;IACJ,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC9B,CAAC;CACF"}

package/dist/server-base.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { MessageBuffer } from './message-buffer.js';
+import type { ChannelProvider } from './types.js';
+/**
+ * Register the common MCP tools that all channel servers share.
+ * Channel-specific tools (e.g., WhatsApp auth) are registered separately.
+ */
+export declare function registerCommonTools(server: McpServer, provider: ChannelProvider): MessageBuffer;
+//# sourceMappingURL=server-base.d.ts.map

package/dist/server-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-base.d.ts","sourceRoot":"","sources":["../src/server-base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,YAAY,CAAC;AAEnE;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,eAAe,GACxB,aAAa,CA2Hf"}

package/dist/server-base.js

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { MessageBuffer } from './message-buffer.js';
+/**
+ * Register the common MCP tools that all channel servers share.
+ * Channel-specific tools (e.g., WhatsApp auth) are registered separately.
+ */
+export function registerCommonTools(server, provider) {
+    const buffer = new MessageBuffer();
+    // Wire provider's message handler → buffer + MCP notification
+    provider.onMessage = (msg) => {
+        buffer.push(msg);
+        // Push to MCP client via logging notification (real-time path)
+        server.server.sendLoggingMessage({
+            level: 'info',
+            logger: 'incoming_message',
+            data: msg,
+        });
+    };
+    // ── Core messaging ──────────────────────────────────────────────────
+    server.tool('send_message', 'Send a message to a chat or group', { chat_id: z.string(), text: z.string() }, async (args) => {
+        if (!provider.isConnected() && provider.waitForReady) {
+            await Promise.race([
+                provider.waitForReady(),
+                new Promise((resolve) => setTimeout(resolve, 15_000)),
+            ]);
+        }
+        await provider.sendMessage(args.chat_id, args.text);
+        return { content: [{ type: 'text', text: 'Message sent.' }] };
+    });
+    server.tool('send_typing', 'Show or hide typing indicator', { chat_id: z.string(), is_typing: z.boolean() }, async (args) => {
+        if (provider.setTyping) {
+            await provider.setTyping(args.chat_id, args.is_typing);
+        }
+        return { content: [{ type: 'text', text: 'OK' }] };
+    });
+    // ── Status and discovery ────────────────────────────────────────────
+    server.tool('get_status', 'Get connection status and channel info', {}, async () => {
+        // If the provider is still connecting, wait briefly for it to be ready
+        if (!provider.isConnected() && provider.waitForReady) {
+            await Promise.race([
+                provider.waitForReady(),
+                new Promise((resolve) => setTimeout(resolve, 15_000)),
+            ]);
+        }
+        const status = provider.getStatus();
+        return {
+            content: [{ type: 'text', text: JSON.stringify(status) }],
+        };
+    });
+    server.tool('list_chats', 'List known chats and groups', {}, async () => {
+        const chats = provider.listChats ? await provider.listChats() : [];
+        return {
+            content: [{ type: 'text', text: JSON.stringify(chats) }],
+        };
+    });
+    server.tool('sync_groups', 'Refresh group and chat metadata from the platform', { force: z.boolean().optional() }, async () => {
+        if (!provider.isConnected() && provider.waitForReady) {
+            await Promise.race([
+                provider.waitForReady(),
+                new Promise((resolve) => setTimeout(resolve, 15_000)),
+            ]);
+        }
+        const groups = provider.syncGroups ? await provider.syncGroups() : [];
+        return {
+            content: [{ type: 'text', text: JSON.stringify(groups) }],
+        };
+    });
+    // ── Polling fallback ────────────────────────────────────────────────
+    server.tool('get_new_messages', 'Poll for incoming messages since the last call. Use the returned cursor for subsequent calls.', { since_cursor: z.string().optional() }, async (args) => {
+        const result = buffer.getSince(args.since_cursor);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result) }],
+        };
+    });
+    // ── Lifecycle ───────────────────────────────────────────────────────
+    server.tool('connect', 'Connect to the messaging platform', {}, async () => {
+        await provider.connect();
+        return { content: [{ type: 'text', text: 'Connected.' }] };
+    });
+    server.tool('disconnect', 'Disconnect from the messaging platform', {}, async () => {
+        await provider.disconnect();
+        return { content: [{ type: 'text', text: 'Disconnected.' }] };
+    });
+    return buffer;
+}
+//# sourceMappingURL=server-base.js.map

package/dist/server-base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-base.js","sourceRoot":"","sources":["../src/server-base.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,63 @@
+/** Normalized incoming message from any channel. */
+export interface IncomingMessage {
+    id: string;
+    chat_id: string;
+    sender: string;
+    sender_name: string;
+    content: string;
+    timestamp: string;
+    is_from_me?: boolean;
+    is_group?: boolean;
+    chat_name?: string;
+    /** Channel-specific metadata (e.g., reply context, media info). */
+    metadata?: Record<string, unknown>;
+}
+/** Connection status returned by get_status. */
+export interface ChannelStatus {
+    connected: boolean;
+    channel: string;
+    identity?: string;
+    uptime_seconds?: number;
+}
+/** Chat/group info returned by list_chats. */
+export interface ChatInfo {
+    id: string;
+    name: string;
+    is_group: boolean;
+}
+/**
+ * Interface that each channel implementation must provide.
+ * The base server wraps this in MCP tools.
+ */
+export interface ChannelProvider {
+    /** Channel name (e.g., 'whatsapp', 'telegram'). */
+    readonly name: string;
+    /** Connect to the messaging platform. */
+    connect(): Promise<void>;
+    /** Disconnect from the messaging platform. */
+    disconnect(): Promise<void>;
+    /** Whether the channel is currently connected. */
+    isConnected(): boolean;
+    /** Send a text message to a chat. */
+    sendMessage(chatId: string, text: string): Promise<void>;
+    /** Get current connection status. */
+    getStatus(): ChannelStatus;
+    /** Show/hide typing indicator. Optional — not all platforms support it. */
+    setTyping?(chatId: string, isTyping: boolean): Promise<void>;
+    /** List known chats/groups. Optional — not all platforms support listing. */
+    listChats?(): Promise<ChatInfo[]>;
+    /** Refresh group/chat metadata from the platform. */
+    syncGroups?(): Promise<ChatInfo[]>;
+    /**
+     * Wait for the channel to be ready (connected).
+     * Optional — if not implemented, tools assume the channel is ready immediately.
+     * Should resolve when connected, or reject/timeout if connection fails.
+     */
+    waitForReady?(): Promise<void>;
+    /**
+     * Called by the base server to inject the message handler.
+     * The channel calls this function whenever a new message arrives.
+     */
+    onMessage: (msg: IncomingMessage) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,8CAA8C;AAC9C,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,yCAAyC;IACzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB,8CAA8C;IAC9C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B,kDAAkD;IAClD,WAAW,IAAI,OAAO,CAAC;IAEvB,qCAAqC;IACrC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzD,qCAAqC;IACrC,SAAS,IAAI,aAAa,CAAC;IAE3B,2EAA2E;IAC3E,SAAS,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7D,6EAA6E;IAC7E,SAAS,CAAC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAElC,qDAAqD;IACrD,UAAU,CAAC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEnC;;;;OAIG;IACH,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/B;;;OAGG;IACH,SAAS,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAC;CAC3C"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@deus-ai/channel-core",
+  "version": "1.0.0",
+  "description": "Shared types and base server logic for Deus MCP channel servers",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { MessageBuffer } from './message-buffer.js';
+export { registerCommonTools } from './server-base.js';
+export type {
+  ChannelProvider,
+  ChannelStatus,
+  ChatInfo,
+  IncomingMessage,
+} from './types.js';

package/src/message-buffer.ts

@@ -0,0 +1,45 @@
+import { IncomingMessage } from './types.js';
+
+const MAX_BUFFER_SIZE = 1000;
+
+/**
+ * Ring buffer for incoming messages.
+ * Supports cursor-based pagination for the get_new_messages polling tool.
+ */
+export class MessageBuffer {
+  private messages: IncomingMessage[] = [];
+  private nextCursor = 0;
+
+  push(msg: IncomingMessage): void {
+    this.messages.push(msg);
+    this.nextCursor++;
+
+    // Trim old messages to prevent unbounded growth
+    if (this.messages.length > MAX_BUFFER_SIZE) {
+      const excess = this.messages.length - MAX_BUFFER_SIZE;
+      this.messages.splice(0, excess);
+    }
+  }
+
+  /**
+   * Get messages since the given cursor.
+   * Returns the messages and a new cursor for the next call.
+   */
+  getSince(cursor?: string): { messages: IncomingMessage[]; cursor: string } {
+    const from = cursor ? parseInt(cursor, 10) : 0;
+
+    // Calculate the offset into the current buffer
+    const bufferStart = this.nextCursor - this.messages.length;
+    const startIndex = Math.max(0, from - bufferStart);
+    const newMessages = this.messages.slice(startIndex);
+
+    return {
+      messages: newMessages,
+      cursor: String(this.nextCursor),
+    };
+  }
+
+  get size(): number {
+    return this.messages.length;
+  }
+}

package/src/server-base.ts

@@ -0,0 +1,137 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+import { MessageBuffer } from './message-buffer.js';
+import type { ChannelProvider, IncomingMessage } from './types.js';
+
+/**
+ * Register the common MCP tools that all channel servers share.
+ * Channel-specific tools (e.g., WhatsApp auth) are registered separately.
+ */
+export function registerCommonTools(
+  server: McpServer,
+  provider: ChannelProvider,
+): MessageBuffer {
+  const buffer = new MessageBuffer();
+
+  // Wire provider's message handler → buffer + MCP notification
+  provider.onMessage = (msg: IncomingMessage) => {
+    buffer.push(msg);
+
+    // Push to MCP client via logging notification (real-time path)
+    server.server.sendLoggingMessage({
+      level: 'info',
+      logger: 'incoming_message',
+      data: msg,
+    });
+  };
+
+  // ── Core messaging ──────────────────────────────────────────────────
+
+  server.tool(
+    'send_message',
+    'Send a message to a chat or group',
+    { chat_id: z.string(), text: z.string() },
+    async (args) => {
+      if (!provider.isConnected() && provider.waitForReady) {
+        await Promise.race([
+          provider.waitForReady(),
+          new Promise((resolve) => setTimeout(resolve, 15_000)),
+        ]);
+      }
+      await provider.sendMessage(args.chat_id, args.text);
+      return { content: [{ type: 'text' as const, text: 'Message sent.' }] };
+    },
+  );
+
+  server.tool(
+    'send_typing',
+    'Show or hide typing indicator',
+    { chat_id: z.string(), is_typing: z.boolean() },
+    async (args) => {
+      if (provider.setTyping) {
+        await provider.setTyping(args.chat_id, args.is_typing);
+      }
+      return { content: [{ type: 'text' as const, text: 'OK' }] };
+    },
+  );
+
+  // ── Status and discovery ────────────────────────────────────────────
+
+  server.tool(
+    'get_status',
+    'Get connection status and channel info',
+    {},
+    async () => {
+      // If the provider is still connecting, wait briefly for it to be ready
+      if (!provider.isConnected() && provider.waitForReady) {
+        await Promise.race([
+          provider.waitForReady(),
+          new Promise((resolve) => setTimeout(resolve, 15_000)),
+        ]);
+      }
+      const status = provider.getStatus();
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(status) }],
+      };
+    },
+  );
+
+  server.tool('list_chats', 'List known chats and groups', {}, async () => {
+    const chats = provider.listChats ? await provider.listChats() : [];
+    return {
+      content: [{ type: 'text' as const, text: JSON.stringify(chats) }],
+    };
+  });
+
+  server.tool(
+    'sync_groups',
+    'Refresh group and chat metadata from the platform',
+    { force: z.boolean().optional() },
+    async () => {
+      if (!provider.isConnected() && provider.waitForReady) {
+        await Promise.race([
+          provider.waitForReady(),
+          new Promise((resolve) => setTimeout(resolve, 15_000)),
+        ]);
+      }
+      const groups = provider.syncGroups ? await provider.syncGroups() : [];
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(groups) }],
+      };
+    },
+  );
+
+  // ── Polling fallback ────────────────────────────────────────────────
+
+  server.tool(
+    'get_new_messages',
+    'Poll for incoming messages since the last call. Use the returned cursor for subsequent calls.',
+    { since_cursor: z.string().optional() },
+    async (args) => {
+      const result = buffer.getSince(args.since_cursor);
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(result) }],
+      };
+    },
+  );
+
+  // ── Lifecycle ───────────────────────────────────────────────────────
+
+  server.tool('connect', 'Connect to the messaging platform', {}, async () => {
+    await provider.connect();
+    return { content: [{ type: 'text' as const, text: 'Connected.' }] };
+  });
+
+  server.tool(
+    'disconnect',
+    'Disconnect from the messaging platform',
+    {},
+    async () => {
+      await provider.disconnect();
+      return { content: [{ type: 'text' as const, text: 'Disconnected.' }] };
+    },
+  );
+
+  return buffer;
+}

package/src/types.ts

@@ -0,0 +1,75 @@
+/** Normalized incoming message from any channel. */
+export interface IncomingMessage {
+  id: string;
+  chat_id: string;
+  sender: string;
+  sender_name: string;
+  content: string;
+  timestamp: string;
+  is_from_me?: boolean;
+  is_group?: boolean;
+  chat_name?: string;
+  /** Channel-specific metadata (e.g., reply context, media info). */
+  metadata?: Record<string, unknown>;
+}
+
+/** Connection status returned by get_status. */
+export interface ChannelStatus {
+  connected: boolean;
+  channel: string;
+  identity?: string;
+  uptime_seconds?: number;
+}
+
+/** Chat/group info returned by list_chats. */
+export interface ChatInfo {
+  id: string;
+  name: string;
+  is_group: boolean;
+}
+
+/**
+ * Interface that each channel implementation must provide.
+ * The base server wraps this in MCP tools.
+ */
+export interface ChannelProvider {
+  /** Channel name (e.g., 'whatsapp', 'telegram'). */
+  readonly name: string;
+
+  /** Connect to the messaging platform. */
+  connect(): Promise<void>;
+
+  /** Disconnect from the messaging platform. */
+  disconnect(): Promise<void>;
+
+  /** Whether the channel is currently connected. */
+  isConnected(): boolean;
+
+  /** Send a text message to a chat. */
+  sendMessage(chatId: string, text: string): Promise<void>;
+
+  /** Get current connection status. */
+  getStatus(): ChannelStatus;
+
+  /** Show/hide typing indicator. Optional — not all platforms support it. */
+  setTyping?(chatId: string, isTyping: boolean): Promise<void>;
+
+  /** List known chats/groups. Optional — not all platforms support listing. */
+  listChats?(): Promise<ChatInfo[]>;
+
+  /** Refresh group/chat metadata from the platform. */
+  syncGroups?(): Promise<ChatInfo[]>;
+
+  /**
+   * Wait for the channel to be ready (connected).
+   * Optional — if not implemented, tools assume the channel is ready immediately.
+   * Should resolve when connected, or reject/timeout if connection fails.
+   */
+  waitForReady?(): Promise<void>;
+
+  /**
+   * Called by the base server to inject the message handler.
+   * The channel calls this function whenever a new message arrives.
+   */
+  onMessage: (msg: IncomingMessage) => void;
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}