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); }