Zulip MCP Server

Instructions

Implementation Reference

• src/server.ts:826-849 (handler)

  The asynchronous handler function that implements the core logic for the 'update-status' tool. It processes input parameters, filters out undefined values using filterUndefined helper, calls the ZulipClient.updateStatus method, and returns formatted MCP success or error responses.

  async ({ status_text, away, emoji_name, emoji_code, reaction_type }) => {
    try {
      console.error('🔍 SERVER DEBUG - Raw parameters received:', { status_text, away, emoji_name, emoji_code, reaction_type });
      
      const updateParams = filterUndefined({
        status_text,
        away,
        emoji_name,
        emoji_code,
        reaction_type
      });
      
      console.error('🔍 SERVER DEBUG - After filterUndefined:', updateParams);
      
      if (Object.keys(updateParams).length === 0) {
        return createErrorResponse('At least one parameter must be provided to update status');
      }
      
      await zulipClient.updateStatus(updateParams);
      return createSuccessResponse(`Status updated successfully!${status_text ? ` Message: "${status_text}"` : ''}${away !== undefined ? ` Away: ${away}` : ''}`);
    } catch (error) {
      return createErrorResponse(`Error updating status: ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
  }

• src/server.ts:822-850 (registration)

  Registers the 'update-status' tool with the MCP server using server.tool(), providing the tool name, description, input schema (UpdateStatusSchema.shape), and the handler function.

  server.tool(
    "update-status", 
    "Update user status message with emoji and availability. Examples: Unicode emoji (emoji_name: 'coffee', emoji_code: '2615'), custom org emoji (reaction_type: 'realm_emoji'), or Zulip special emoji (reaction_type: 'zulip_extra_emoji').",
    UpdateStatusSchema.shape,
    async ({ status_text, away, emoji_name, emoji_code, reaction_type }) => {
      try {
        console.error('🔍 SERVER DEBUG - Raw parameters received:', { status_text, away, emoji_name, emoji_code, reaction_type });
        
        const updateParams = filterUndefined({
          status_text,
          away,
          emoji_name,
          emoji_code,
          reaction_type
        });
        
        console.error('🔍 SERVER DEBUG - After filterUndefined:', updateParams);
        
        if (Object.keys(updateParams).length === 0) {
          return createErrorResponse('At least one parameter must be provided to update status');
        }
        
        await zulipClient.updateStatus(updateParams);
        return createSuccessResponse(`Status updated successfully!${status_text ? ` Message: "${status_text}"` : ''}${away !== undefined ? ` Away: ${away}` : ''}`);
      } catch (error) {
        return createErrorResponse(`Error updating status: ${error instanceof Error ? error.message : 'Unknown error'}`);
      }
    }
  );

• src/types.ts:161-167 (schema)

  Zod schema defining the input validation and structure for the 'update-status' tool parameters, including descriptions for MCP tool documentation.

  export const UpdateStatusSchema = z.object({
    status_text: z.string().max(60).optional().describe("Status message text (max 60 chars, empty string clears status)"),
    away: z.boolean().optional().describe("Set away status (deprecated in Zulip 6.0, will be removed)"),
    emoji_name: z.string().optional().describe("Emoji name: for unicode use short name (e.g., 'coffee', 'airplane'), for realm_emoji use custom name, for zulip_extra use special names like 'zulip'"),
    emoji_code: z.string().optional().describe("Emoji identifier: for unicode_emoji use codepoint (e.g., '2615' for coffee), for realm_emoji use custom emoji ID, for zulip_extra use emoji ID"),
    reaction_type: z.enum(["unicode_emoji", "realm_emoji", "zulip_extra_emoji"]).optional().describe("Emoji type: 'unicode_emoji' for standard emojis (default), 'realm_emoji' for organization custom emojis, 'zulip_extra_emoji' for special Zulip emojis")
  });

• src/zulip/client.ts:398-440 (helper)

  ZulipClient.updateStatus helper method that handles the actual Zulip API call to POST /users/me/status with form-encoded parameters, including filtering logic and debug logging.

  async updateStatus(params: {
    status_text?: string;
    away?: boolean;
    emoji_name?: string;
    emoji_code?: string;
    reaction_type?: string;
  }): Promise<void> {
    // Filter out undefined values and empty strings
    const filteredParams: any = {};
    if (params.status_text !== undefined && params.status_text !== null) {
      filteredParams.status_text = params.status_text;
    }
    if (params.away !== undefined) {filteredParams.away = params.away;}
    if (params.emoji_name !== undefined && params.emoji_name !== '') {
      filteredParams.emoji_name = params.emoji_name;
    }
    if (params.emoji_code !== undefined && params.emoji_code !== '') {
      filteredParams.emoji_code = params.emoji_code;
    }
    if (params.reaction_type !== undefined && params.reaction_type !== '') {
      filteredParams.reaction_type = params.reaction_type;
    }
    
    debugLog('🔍 Debug - updateStatus filtered params:', JSON.stringify(filteredParams, null, 2));
    
    // Zulip expects form-encoded data for this endpoint
    const response = await this.client.post('/users/me/status', filteredParams, {
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      transformRequest: [(data) => {
        const params = new URLSearchParams();
        Object.keys(data).forEach(key => {
          params.append(key, data[key]);
        });
        const formString = params.toString();
        debugLog('🔍 Debug - Form-encoded status update:', formString);
        return formString;
      }]
    });
    
    debugLog('✅ Debug - Status updated successfully:', response.data);
  }