bn-telegram-mcp-server 0.0.1

package/README.md

@@ -0,0 +1,1031 @@
+# Telegram MCP Server Tools
+
+---
+
+## Quick Reference Table
+
+| Tool | Description | Key Input | Key Output |
+|------|-------------|-----------|------------|
+| `getMe` | Current user info | *none* | `{id, name, status}` |
+| `getChat` | Get/list chats | `chat?`, `limit?` | `{id, title, type}` or `{chats[], summary}` |
+| `getMessages` | Get messages (history/specific/search) | `chat?`, `mode`, `query?` | `{messages[], total_count}` |
+| `getMessageContext` | Get surrounding messages for context | `chat`, `mode`, `message_id?`, `query?` | `{contexts[], summary}` |
+| `sendMessage` | Send/forward messages | `chat`, `action`, `text?` | `{id, content, date}` |
+| `getUser` | User profile | `user` (name/ID) | `{id, name, status}` |
+| `getContacts` | List/search contacts | `query?`, `limit?` | `{contacts[], total_count}` |
+| `getFile` | Get file metadata | `file_id` | `{id, size, remote_id}` |
+| `getGroup` | Group info (basic/super) | `group`, `type?` | `{id, name, member_count}` |
+| `getChatMembers` | Chat members with filters | `chat`, `filter?` | `{members[], total_count}` |
+
+---
+
+## 1. getMe
+
+**Description:** Get information about the current Telegram user (the authenticated user). Returns name, username, phone, status, and profile info.
+
+### Input Schema
+```json
+{
+  "type": "object",
+  "properties": {}
+}
+```
+*No parameters required.*
+
+### Output Schema
+```typescript
+{
+  id: number;           // User's numeric ID
+  name: string;         // Full name (e.g., "John Doe")
+  username?: string;    // @username if set
+  phone?: string;       // Phone number if visible
+  status: string;       // Online status (e.g., "online", "last seen 2 hours ago")
+  is_contact: boolean;
+  is_premium: boolean;
+  is_verified: boolean;
+}
+```
+
+### Use Cases
+
+**Use Case 1: Check authenticated user**
+```bash
+# Input
+{}
+
+# Output
+{
+  "id": 111222333,
+  "name": "John Doe",
+  "phone": "+1234567890",
+  "status": "online",
+  "is_contact": false,
+  "is_premium": false,
+  "is_verified": false
+}
+```
+
+**Use Case 2: Verify connection status**
+```bash
+# Call getMe to verify the Telegram session is active
+# If successful, returns user info; if failed, session needs re-authentication
+```
+
+---
+
+## 2. getChat
+
+**Description:** Get chat information - either a specific chat or list all chats. When `chat` is provided, returns single chat details. When `chat` is omitted, returns list of all chats.
+
+### Input Schema
+```json
+{
+  "type": "object",
+  "properties": {
+    "chat": {
+      "type": ["number", "string"],
+      "description": "Optional: Chat identifier (name/title or numeric ID). If omitted, lists all chats."
+    },
+    "chat_list": {
+      "type": "string",
+      "enum": ["main", "archive"],
+      "description": "Which chat list to retrieve (default: main)"
+    },
+    "limit": {
+      "type": "number",
+      "description": "Maximum chats when listing (default: 100, max: 4000)"
+    }
+  }
+}
+```
+
+### Output Schema (Single Chat)
+```typescript
+{
+  id: number;
+  title: string;
+  type: string;          // "private", "group", "supergroup", "channel"
+  unread_count: number;
+  last_message?: {
+    preview: string;
+    sender: string;
+    date: string;
+    date_relative: string;
+  };
+  is_pinned: boolean;
+  is_muted: boolean;
+}
+```
+
+### Output Schema (List Chats)
+```typescript
+{
+  chats: Array<{
+    id: number;
+    title: string;
+    type: string;
+    unread_count: number;
+    last_message?: { preview, sender, date, date_relative };
+    is_pinned: boolean;
+    is_muted: boolean;
+  }>;
+  total_count: number;
+  summary: string;        // e.g., "15 chats loaded, 3 unread messages"
+}
+```
+
+### Use Cases
+
+**Use Case 1: List all chats**
+```bash
+# Input
+{"limit": 10}
+
+# Output
+{
+  "chats": [
+    {
+      "id": 555666777,
+      "title": "John Doe",
+      "type": "private",
+      "unread_count": 0,
+      "last_message": {
+        "preview": "Test message",
+        "sender": "User 111222333",
+        "date": "2025-12-04T08:41:54.000Z",
+        "date_relative": "4 hours ago"
+      }
+    }
+  ],
+  "total_count": 15,
+  "summary": "10 chats loaded, 0 unread messages"
+}
+```
+
+**Use Case 2: Get specific chat by name**
+```bash
+# Input
+{"chat": "John Doe"}
+
+# Output
+{
+  "id": 555666777,
+  "title": "John Doe",
+  "type": "private",
+  "unread_count": 0,
+  "is_pinned": false,
+  "is_muted": false
+}
+```
+
+**Use Case 3: Get archived chats**
+```bash
+# Input
+{"chat_list": "archive", "limit": 50}
+```
+
+---
+
+## 3. getMessages
+
+**Description:** Get messages from a chat using different modes: paginated history, specific message IDs, or text search. Supports both chat-specific and global search.
+
+### Input Schema
+```json
+{
+  "type": "object",
+  "properties": {
+    "chat": {
+      "type": ["number", "string"],
+      "description": "Chat identifier. Required for 'history'/'specific' modes, optional for 'search'"
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["history", "specific", "search"],
+      "description": "Mode: 'history' (default), 'specific', or 'search'"
+    },
+    "from_message_id": {
+      "type": "number",
+      "description": "(history/chat search mode) Start from this message ID (0 for latest)"
+    },
+    "offset": {
+      "type": "number",
+      "description": "(history mode) Numeric pagination offset"
+    },
+    "limit": {
+      "type": "number",
+      "description": "Max messages to return (default: 50, max: 100)"
+    },
+    "only_local": {
+      "type": "boolean",
+      "description": "(history mode) Only return cached messages"
+    },
+    "message_ids": {
+      "type": "array",
+      "items": { "type": "number" },
+      "description": "(specific mode) Array of message IDs to retrieve"
+    },
+    "query": {
+      "type": "string",
+      "description": "(search mode) Search query text"
+    },
+    "next_offset": {
+      "type": "string",
+      "description": "(search mode) Cursor for pagination - pass the next_offset from previous response"
+    }
+  }
+}
+```
+
+### Output Schema (History/Search)
+```typescript
+{
+  messages: Array<{
+    id: number;
+    chat_id: number;
+    sender: string;
+    sender_id: number;
+    content: string;
+    content_type: string;    // "Text", "Photo", "Video", etc.
+    date: string;
+    date_relative: string;
+    is_outgoing: boolean;
+    is_pinned: boolean;
+    file_id?: number;
+  }>;
+  total_count: number;
+  chat_title?: string;       // (history mode)
+  search_query?: string;     // (search mode)
+  next_offset?: string;      // (search mode) For pagination
+}
+```
+
+### Use Cases
+
+**Use Case 1: Get chat history**
+```bash
+# Input
+{"chat": "John Doe", "mode": "history", "limit": 5}
+
+# Output
+{
+  "messages": [
+    {
+      "id": 14680064,
+      "chat_id": 555666777,
+      "sender": "User 111222333",
+      "content": "Test message from script",
+      "content_type": "Text",
+      "date": "2025-12-04T08:41:54.000Z",
+      "date_relative": "4 hours ago",
+      "is_outgoing": true
+    }
+  ],
+  "total_count": 1,
+  "chat_title": "John Doe"
+}
+```
+
+**Use Case 2: Get specific messages by IDs**
+```bash
+# Input
+{"chat": "John Doe", "mode": "specific", "message_ids": [9437184, 9437185]}
+
+# Output
+{
+  "messages": [...],
+  "count": 2,
+  "chat_title": "John Doe"
+}
+```
+
+**Use Case 3: Search messages globally**
+```bash
+# Input
+{"mode": "search", "query": "meeting", "limit": 10}
+
+# Output
+{
+  "messages": [...],
+  "total_count": 5,
+  "search_query": "meeting"
+}
+```
+
+**Use Case 4: Search in specific chat**
+```bash
+# Input
+{"chat": "Project Team", "mode": "search", "query": "deadline"}
+```
+
+**Use Case 5: Search with pagination**
+```bash
+# First request
+{"mode": "search", "query": "meeting", "limit": 10}
+
+# Response includes next_offset
+{
+  "messages": [...],
+  "total_count": 50,
+  "next_offset": "abc123xyz",
+  "search_query": "meeting"
+}
+
+# Next page - pass the next_offset from previous response
+{"mode": "search", "query": "meeting", "limit": 10, "next_offset": "abc123xyz"}
+```
+
+---
+
+## 4. getMessageContext
+
+**Description:** Get surrounding messages for context around a specific message or search results. Returns messages before and after the target to understand the full conversation flow. Useful when you need to understand the context of a particular message.
+
+### Input Schema
+```json
+{
+  "type": "object",
+  "properties": {
+    "chat": {
+      "type": ["number", "string"],
+      "description": "Chat identifier. Required for 'message_id' mode, optional for 'search' mode (global search if omitted)"
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["message_id", "search"],
+      "description": "Mode: 'message_id' (default) or 'search'"
+    },
+    "message_id": {
+      "type": "number",
+      "description": "(message_id mode) The message ID to get context around"
+    },
+    "query": {
+      "type": "string",
+      "description": "(search mode) Search query to find messages"
+    },
+    "search_limit": {
+      "type": "number",
+      "description": "(search mode) Max search results to get context for (default: 5, max: 20)"
+    },
+    "context_count": {
+      "type": "number",
+      "description": "Messages to fetch before AND after target (default: 5, max: 50)"
+    }
+  }
+}
+```
+
+### Output Schema
+```typescript
+{
+  contexts: Array<{
+    messages: Array<{            // Single chronological array (easier for LLMs)
+      id: number;
+      chat_id: number;
+      sender: string;
+      content: string;
+      content_type: string;
+      date: string;
+      date_relative: string;
+      is_target: boolean;        // true for the target message
+    }>;
+    target_message_id: number;   // ID of the target message
+    context_count: number;
+    chat_id: number;
+    chat_title?: string;
+  }>;
+  total_matches: number;
+  search_query?: string;         // Only present in search mode
+  summary: string;               // Human-readable summary
+}
+```
+
+### Use Cases
+
+**Use Case 1: Get context around a specific message**
+```bash
+# Input
+{"chat": "Project Team", "mode": "message_id", "message_id": 12345, "context_count": 3}
+
+# Output - Single chronological array with is_target flag
+{
+  "contexts": [
+    {
+      "messages": [
+        {"id": 12342, "content": "Good morning everyone", "is_target": false, ...},
+        {"id": 12343, "content": "Hi team", "is_target": false, ...},
+        {"id": 12344, "content": "Ready for the standup?", "is_target": false, ...},
+        {"id": 12345, "content": "Let's discuss the deadline", "is_target": true, ...},
+        {"id": 12346, "content": "Sure, what about Friday?", "is_target": false, ...},
+        {"id": 12347, "content": "Friday works for me", "is_target": false, ...},
+        {"id": 12348, "content": "Let's set it for 3pm", "is_target": false, ...}
+      ],
+      "target_message_id": 12345,
+      "context_count": 3,
+      "chat_title": "Project Team"
+    }
+  ],
+  "total_matches": 1,
+  "summary": "Showing context for 1 message(s) (7 total messages)"
+}
+```
+
+**Use Case 2: Search and get context for each match**
+```bash
+# Input
+{"chat": "Project Team", "mode": "search", "query": "deadline", "search_limit": 3, "context_count": 2}
+
+# Output
+{
+  "contexts": [
+    {
+      "messages": [
+        {"id": 12343, "content": "Hi team", "is_target": false, ...},
+        {"id": 12344, "content": "Ready for the standup?", "is_target": false, ...},
+        {"id": 12345, "content": "Let's discuss the deadline", "is_target": true, ...},
+        {"id": 12346, "content": "Sure, what about Friday?", "is_target": false, ...},
+        {"id": 12347, "content": "Friday works for me", "is_target": false, ...}
+      ],
+      "target_message_id": 12345,
+      "chat_title": "Project Team"
+    },
+    {
+      "messages": [
+        {"id": 9874, "content": "Any updates?", "is_target": false, ...},
+        {"id": 9875, "content": "Yes, checking now", "is_target": false, ...},
+        {"id": 9876, "content": "The deadline is next week", "is_target": true, ...},
+        {"id": 9877, "content": "Got it, thanks", "is_target": false, ...},
+        {"id": 9878, "content": "I'll prepare the report", "is_target": false, ...}
+      ],
+      "target_message_id": 9876,
+      "chat_title": "Project Team"
+    }
+  ],
+  "total_matches": 5,
+  "search_query": "deadline",
+  "summary": "Found 5 match(es) for \"deadline\", showing context for 2 result(s) (10 total messages)"
+}
+```
+
+**Use Case 3: Global search with context**
+```bash
+# Input - search across all chats
+{"mode": "search", "query": "urgent", "search_limit": 5, "context_count": 3}
+
+# Output - results may come from different chats
+{
+  "contexts": [
+    {
+      "messages": [
+        {"id": 553, "content": "Please review", "is_target": false, ...},
+        {"id": 554, "content": "Will do", "is_target": false, ...},
+        {"id": 555, "content": "This is urgent!", "is_target": true, ...},
+        {"id": 556, "content": "On it now", "is_target": false, ...}
+      ],
+      "target_message_id": 555,
+      "chat_id": 1111111,
+      "chat_title": "Work Group"
+    },
+    {
+      "messages": [
+        {"id": 775, "content": "Schedule update", "is_target": false, ...},
+        {"id": 776, "content": "What time?", "is_target": false, ...},
+        {"id": 777, "content": "Urgent meeting tomorrow", "is_target": true, ...},
+        {"id": 778, "content": "I'll be there", "is_target": false, ...}
+      ],
+      "target_message_id": 777,
+      "chat_id": 2222222,
+      "chat_title": "Project Team"
+    }
+  ],
+  "total_matches": 12,
+  "search_query": "urgent",
+  "summary": "Found 12 match(es) for \"urgent\", showing context for 2 result(s) (8 total messages)"
+}
+```
+
+---
+
+## 5. sendMessage
+
+**Description:** Send or forward messages to a chat. Use `action="send"` to compose new messages, or `action="forward"` to forward existing messages from another chat.
+
+### Input Schema
+```json
+{
+  "type": "object",
+  "properties": {
+    "chat": {
+      "type": ["number", "string"],
+      "description": "Target chat: name/title or numeric ID"
+    },
+    "action": {
+      "type": "string",
+      "enum": ["send", "forward"],
+      "description": "Action type (default: 'send')"
+    },
+    "text": {
+      "type": "string",
+      "description": "(send action) Text content of the message"
+    },
+    "reply_to_message_id": {
+      "type": "number",
+      "description": "(send action) ID of message to reply to"
+    },
+    "from_chat": {
+      "type": ["number", "string"],
+      "description": "(forward action) Source chat to forward from"
+    },
+    "message_ids": {
+      "type": "array",
+      "items": { "type": "number" },
+      "description": "(forward action) Message IDs to forward"
+    },
+    "send_copy": {
+      "type": "boolean",
+      "description": "(forward action) Send copies without forwarding header"
+    },
+    "remove_caption": {
+      "type": "boolean",
+      "description": "(forward action) Remove media captions"
+    }
+  },
+  "required": ["chat"]
+}
+```
+
+### Output Schema (Send)
+```typescript
+{
+  id: number;
+  chat_id: number;
+  sender: string;
+  content: string;
+  content_type: string;
+  date: string;
+  date_relative: string;
+  is_outgoing: true;
+  is_pinned: boolean;
+}
+```
+
+### Output Schema (Forward)
+```typescript
+{
+  forwarded: Array<{
+    id: number;
+    chat_id: number;
+    sender: string;
+    content: string;
+    date: string;
+    is_outgoing: boolean;
+  }>;
+  count: number;
+}
+```
+
+### Use Cases
+
+**Use Case 1: Send a new message**
+```bash
+# Input
+{"chat": "John Doe", "text": "Hello from MCP!"}
+
+# Output
+{
+  "id": 14680065,
+  "chat_id": 555666777,
+  "sender": "User 111222333",
+  "content": "Hello from MCP!",
+  "content_type": "Text",
+  "date": "2025-12-04T12:45:00.000Z",
+  "date_relative": "just now",
+  "is_outgoing": true
+}
+```
+
+**Use Case 2: Reply to a message**
+```bash
+# Input
+{"chat": "Project Team", "text": "I agree!", "reply_to_message_id": 12345}
+```
+
+**Use Case 3: Forward messages**
+```bash
+# Input
+{
+  "chat": "John Doe",
+  "action": "forward",
+  "from_chat": "Project Team",
+  "message_ids": [100, 101, 102]
+}
+
+# Output
+{
+  "forwarded": [...],
+  "count": 3
+}
+```
+
+**Use Case 4: Forward as copy (no "Forwarded from" header)**
+```bash
+# Input
+{
+  "chat": "John Doe",
+  "action": "forward",
+  "from_chat": "Project Team",
+  "message_ids": [100],
+  "send_copy": true
+}
+```
+
+---
+
+## 6. getUser
+
+**Description:** Get information about a Telegram user. You can use their name, @username, or numeric user ID.
+
+### Input Schema
+```json
+{
+  "type": "object",
+  "properties": {
+    "user": {
+      "type": ["number", "string"],
+      "description": "User identifier: name, @username, or numeric ID"
+    }
+  },
+  "required": ["user"]
+}
+```
+
+### Output Schema
+```typescript
+{
+  id: number;
+  name: string;
+  username?: string;
+  phone?: string;
+  status: string;        // "online", "last seen 2 hours ago", etc.
+  is_contact: boolean;
+  is_premium: boolean;
+  is_verified: boolean;
+}
+```
+
+### Use Cases
+
+**Use Case 1: Get user by numeric ID**
+```bash
+# Input
+{"user": 555666777}
+
+# Output
+{
+  "id": 555666777,
+  "name": "John Doe",
+  "phone": "+1234567890",
+  "status": "last seen 2 hours ago",
+  "is_contact": true,
+  "is_premium": false,
+  "is_verified": false
+}
+```
+
+**Use Case 2: Get user by username**
+```bash
+# Input
+{"user": "@johndoe"}
+```
+
+---
+
+## 7. getContacts
+
+**Description:** Get contacts - either list all contacts or search by name/username. When `query` is provided, searches contacts; otherwise returns all contacts.
+
+### Input Schema
+```json
+{
+  "type": "object",
+  "properties": {
+    "query": {
+      "type": "string",
+      "description": "Optional: Search query to filter contacts"
+    },
+    "limit": {
+      "type": "number",
+      "description": "Max results when searching (default: 50, max: 200)"
+    }
+  }
+}
+```
+
+### Output Schema
+```typescript
+{
+  contacts: Array<{
+    id: number;
+    name: string;
+    username?: string;
+    phone?: string;
+    status: string;
+  }>;
+  total_count: number;
+  query?: string;         // Only present when searching
+}
+```
+
+### Use Cases
+
+**Use Case 1: List all contacts**
+```bash
+# Input
+{}
+
+# Output
+{
+  "contacts": [
+    {
+      "id": 555666777,
+      "name": "John Doe",
+      "phone": "+1234567890",
+      "status": "last seen 2 hours ago"
+    },
+    {
+      "id": 123456789,
+      "name": "John Doe",
+      "username": "johndoe",
+      "status": "online"
+    }
+  ],
+  "total_count": 2
+}
+```
+
+**Use Case 2: Search contacts**
+```bash
+# Input
+{"query": "John", "limit": 10}
+
+# Output
+{
+  "contacts": [
+    {
+      "id": 555666777,
+      "name": "John Doe",
+      "phone": "+1234567890",
+      "status": "last seen 2 hours ago"
+    }
+  ],
+  "total_count": 1,
+  "query": "John"
+}
+```
+
+---
+
+## 8. getFile
+
+**Description:** Get file metadata (size, remote ID). Note: Download is not supported in stateless mode since session files are cleaned up after each request.
+
+### Input Schema
+```json
+{
+  "type": "object",
+  "properties": {
+    "file_id": {
+      "type": "number",
+      "description": "Identifier of the file to get metadata for"
+    }
+  },
+  "required": ["file_id"]
+}
+```
+
+### Output Schema
+```typescript
+{
+  id: number;
+  size: string;              // Human-readable (e.g., "1.5 MB")
+  size_bytes: number;
+  remote_id?: string;        // Remote file identifier
+}
+```
+
+### Use Cases
+
+**Use Case 1: Get file metadata**
+```bash
+# Input
+{"file_id": 33}
+
+# Output
+{
+  "id": 33,
+  "size": "1.00 MB",
+  "size_bytes": 1024000,
+  "remote_id": "AgACAgEAAxk..."
+}
+```
+
+**Use Case 2: Get file info from a message**
+```bash
+# First, get messages to find a file_id
+{"chat": "John Doe", "mode": "history", "limit": 5}
+# Response includes file_id in messages with media
+
+# Then get file metadata
+{"file_id": 45}
+```
+
+---
+
+## 9. getGroup
+
+**Description:** Get information about a group (basic group, supergroup, or channel). Use `type="auto"` to detect automatically, or specify `type="supergroup"` or `type="basic_group"` explicitly.
+
+### Input Schema
+```json
+{
+  "type": "object",
+  "properties": {
+    "group": {
+      "type": ["number", "string"],
+      "description": "Group identifier: name or numeric ID"
+    },
+    "type": {
+      "type": "string",
+      "enum": ["auto", "supergroup", "basic_group"],
+      "description": "Group type (default: 'auto')"
+    }
+  },
+  "required": ["group"]
+}
+```
+
+### Output Schema
+```typescript
+{
+  id: number;
+  name: string;
+  type: "basic_group" | "supergroup" | "channel";
+  member_count: number;
+  is_verified?: boolean;    // supergroups only
+  is_scam?: boolean;        // supergroups only
+  join_date?: string;
+}
+```
+
+### Use Cases
+
+**Use Case 1: Get group with auto-detection**
+```bash
+# Input
+{"group": "Project Team"}
+
+# Output
+{
+  "id": 1234567890,
+  "name": "Project Team",
+  "type": "supergroup",
+  "member_count": 15,
+  "is_verified": false,
+  "is_scam": false
+}
+```
+
+**Use Case 2: Get basic group explicitly**
+```bash
+# Input
+{"group": "Family Group", "type": "basic_group"}
+
+# Output
+{
+  "id": 9876543210,
+  "name": "Family Group",
+  "type": "basic_group",
+  "member_count": 5
+}
+```
+
+**Use Case 3: Get supergroup by ID**
+```bash
+# Input
+{"group": 1234567890, "type": "supergroup"}
+```
+
+---
+
+## 10. getChatMembers
+
+**Description:** Get members of a chat with filtering options. Supports filtering by role (administrators, banned, bots) or searching by name.
+
+### Input Schema
+```json
+{
+  "type": "object",
+  "properties": {
+    "chat": {
+      "type": ["number", "string"],
+      "description": "Chat identifier: name/title or numeric ID"
+    },
+    "filter": {
+      "type": "string",
+      "enum": ["recent", "administrators", "banned", "bots", "search"],
+      "description": "Filter type (default: 'recent')"
+    },
+    "query": {
+      "type": "string",
+      "description": "Search query (for 'search' and 'banned' filters)"
+    },
+    "offset": {
+      "type": "number",
+      "description": "Pagination offset"
+    },
+    "limit": {
+      "type": "number",
+      "description": "Max members to return (default: 200, max: 200)"
+    }
+  },
+  "required": ["chat"]
+}
+```
+
+### Output Schema
+```typescript
+{
+  members: Array<{
+    user_id: number;
+    name: string;
+    username?: string;
+    status: string;
+    role: string;           // "owner", "administrator", "member", etc.
+    joined_date?: string;
+  }>;
+  total_count: number;
+  chat_title?: string;
+}
+```
+
+### Use Cases
+
+**Use Case 1: Get recent members**
+```bash
+# Input
+{"chat": "Project Team", "limit": 10}
+
+# Output
+{
+  "members": [
+    {
+      "user_id": 111222333,
+      "name": "John Doe",
+      "status": "member",
+      "role": "creator"
+    },
+    {
+      "user_id": 123456789,
+      "name": "John Doe",
+      "username": "johndoe",
+      "status": "member",
+      "role": "member"
+    }
+  ],
+  "total_count": 15,
+  "chat_title": "Project Team"
+}
+```
+
+**Use Case 2: Get only administrators**
+```bash
+# Input
+{"chat": "Project Team", "filter": "administrators"}
+
+# Output
+{
+  "members": [
+    {
+      "user_id": 111222333,
+      "name": "John Doe",
+      "status": "administrator",
+      "role": "owner"
+    }
+  ],
+  "total_count": 1,
+  "chat_title": "Project Team"
+}
+```
+
+**Use Case 3: Search members by name**
+```bash
+# Input
+{"chat": "Project Team", "filter": "search", "query": "john"}
+```
+
+**Use Case 4: Get bot members**
+```bash
+# Input
+{"chat": "Project Team", "filter": "bots"}
+```
+