Zulip MCP Server

Instructions

Implementation Reference

• src/server.ts:404-428 (handler)

  MCP handler function for 'send-message' tool: validates inputs (requires topic for streams, validates emails for direct), constructs params, calls ZulipClient.sendMessage, returns success/error in MCP format.

  server.tool(
    "send-message",
    "💬 SEND MESSAGE: Send a message to a Zulip stream (channel) or direct message to users. IMPORTANT: For streams use exact names from 'get-subscribed-streams'. For DMs use actual email addresses from 'search-users' tool (NOT display names). Always include 'topic' for stream messages.",
    SendMessageSchema.shape,
    async ({ type, to, content, topic }) => {
      try {
        if (type === 'stream' && !topic) {
          return createErrorResponse('Topic is required for stream messages. Think of it as a subject line for your message.');
        }
  
        if (type === 'direct') {
          const validation = validateEmailList(to);
          if (!validation.isValid) {
            return createErrorResponse(`Invalid email format for direct message recipients: ${to}. Use 'search-users' tool to find correct email addresses. Don't use display names.`);
          }
        }
  
        const messageParams = { type, to, content, ...(topic && { topic }) };
        const result = await zulipClient.sendMessage(messageParams);
        return createSuccessResponse(`Message sent successfully! Message ID: ${result.id}`);
      } catch (error) {
        return createErrorResponse(`Error sending message: ${error instanceof Error ? error.message : 'Unknown error'}`);
      }
    }
  );

• src/types.ts:113-119 (schema)

  Zod schema defining the input parameters for the send-message tool: type (stream/direct), to (stream name or emails), content, optional topic.

  export const SendMessageSchema = z.object({
    type: z.enum(["stream", "direct"]).describe("'stream' for channel messages, 'direct' for private messages"),
    to: z.string().describe("For streams: channel name (e.g., 'general'). For direct: comma-separated user emails (e.g., 'user@example.com' or 'user1@example.com,user2@example.com')"),
    content: z.string().describe("Message content using Zulip Markdown syntax. Support mentions (@**Name**), code blocks, links, etc."),
    topic: z.string().optional().describe("Topic name for stream messages (required for streams, max length varies by server)")
  });

• src/server.ts:404-428 (registration)

  Registers the 'send-message' tool with the MCP server using server.tool(), providing name, description, schema, and handler function.

  server.tool(
    "send-message",
    "💬 SEND MESSAGE: Send a message to a Zulip stream (channel) or direct message to users. IMPORTANT: For streams use exact names from 'get-subscribed-streams'. For DMs use actual email addresses from 'search-users' tool (NOT display names). Always include 'topic' for stream messages.",
    SendMessageSchema.shape,
    async ({ type, to, content, topic }) => {
      try {
        if (type === 'stream' && !topic) {
          return createErrorResponse('Topic is required for stream messages. Think of it as a subject line for your message.');
        }
  
        if (type === 'direct') {
          const validation = validateEmailList(to);
          if (!validation.isValid) {
            return createErrorResponse(`Invalid email format for direct message recipients: ${to}. Use 'search-users' tool to find correct email addresses. Don't use display names.`);
          }
        }
  
        const messageParams = { type, to, content, ...(topic && { topic }) };
        const result = await zulipClient.sendMessage(messageParams);
        return createSuccessResponse(`Message sent successfully! Message ID: ${result.id}`);
      } catch (error) {
        return createErrorResponse(`Error sending message: ${error instanceof Error ? error.message : 'Unknown error'}`);
      }
    }
  );

• src/zulip/client.ts:76-155 (helper)

  ZulipClient.sendMessage helper: constructs API payload for /messages endpoint, handles direct (array of emails) vs stream (name + topic), tries JSON then form-encoded request to Zulip API.

  async sendMessage(params: {
    type: 'stream' | 'direct';
    to: string;
    content: string;
    topic?: string;
  }): Promise<{ id: number }> {
    if (process.env.NODE_ENV === 'development') {
      debugLog('🔍 Debug - sendMessage called with:', JSON.stringify(params, null, 2));
    }
    
    // Use the type directly - newer API supports "direct" 
    const payload: any = {
      type: params.type,
      content: params.content
    };
  
    // Handle recipients based on message type
    if (params.type === 'direct') {
      // For direct messages, handle both single and multiple recipients
      const recipients = params.to.includes(',') 
        ? params.to.split(',').map(email => email.trim())
        : [params.to.trim()];
      
      // Try both formats to see which works
      payload.to = recipients;  // Array format first
      debugLog('🔍 Debug - Direct message recipients:', recipients);
    } else {
      // For stream messages, 'to' is the stream name
      payload.to = params.to;
      if (params.topic) {
        payload.topic = params.topic;
      }
    }
  
    debugLog('🔍 Debug - Final payload:', JSON.stringify(payload, null, 2));
  
    try {
      // Try JSON first (modern API)
      const response = await this.client.post('/messages', payload);
      debugLog('✅ Debug - Message sent successfully:', response.data);
      return response.data;
    } catch (jsonError) {
      debugLog('⚠️ Debug - JSON request failed, trying form-encoded...');
      if (jsonError instanceof Error) {
        debugLog('Error:', (jsonError as any).response?.data || jsonError.message);
      }
      
      // Fallback to form-encoded with different recipient format
      const formPayload = { ...payload };
      if (params.type === 'direct') {
        // Try JSON string format for recipients
        const recipients = params.to.includes(',') 
          ? params.to.split(',').map(email => email.trim())
          : [params.to.trim()];
        formPayload.to = JSON.stringify(recipients);
      }
      
      debugLog('🔍 Debug - Form payload:', JSON.stringify(formPayload, null, 2));
      
      const response = await this.client.post('/messages', formPayload, {
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
        },
        transformRequest: [(data) => {
          const params = new URLSearchParams();
          for (const key in data) {
            if (data[key] !== undefined) {
              params.append(key, String(data[key]));
            }
          }
          const formString = params.toString();
          debugLog('🔍 Debug - Form-encoded string:', formString);
          return formString;
        }]
      });
      
      debugLog('✅ Debug - Form-encoded message sent successfully:', response.data);
      return response.data;
    }
  }