Zulip MCP Server

Instructions

Implementation Reference

• src/server.ts:607-618 (handler)

  MCP tool handler function for 'upload-file' that receives parameters, calls ZulipClient.uploadFile, and formats success/error responses.

  async ({ filename, content, content_type }) => {
    try {
      const result = await zulipClient.uploadFile(filename, content, content_type);
      return createSuccessResponse(JSON.stringify({
        success: true,
        uri: result.uri,
        message: `File uploaded successfully! Use this URI in messages: ${result.uri}`
      }, null, 2));
    } catch (error) {
      return createErrorResponse(`Error uploading file: ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
  }

• src/server.ts:603-619 (registration)

  Registration of the 'upload-file' MCP tool including name, description, schema, and handler function.

  server.tool(
    "upload-file",
    "Upload a file or image to Zulip.",
    UploadFileSchema.shape,
    async ({ filename, content, content_type }) => {
      try {
        const result = await zulipClient.uploadFile(filename, content, content_type);
        return createSuccessResponse(JSON.stringify({
          success: true,
          uri: result.uri,
          message: `File uploaded successfully! Use this URI in messages: ${result.uri}`
        }, null, 2));
      } catch (error) {
        return createErrorResponse(`Error uploading file: ${error instanceof Error ? error.message : 'Unknown error'}`);
      }
    }
  );

• src/types.ts:128-132 (schema)

  Zod input schema defining parameters for the upload-file tool: filename, base64 content, optional content_type.

  export const UploadFileSchema = z.object({
    filename: z.string().describe("Name of the file including extension (e.g., 'document.pdf', 'image.png')"),
    content: z.string().describe("Base64 encoded file content"),
    content_type: z.string().optional().describe("MIME type (e.g., 'image/png', 'application/pdf'). Auto-detected if not provided")
  });

• src/zulip/client.ts:233-247 (helper)

  Core implementation in ZulipClient that converts base64 to buffer, creates FormData, and uploads to Zulip /user_uploads API endpoint.

  async uploadFile(filename: string, content: string, contentType?: string): Promise<{ uri: string }> {
    // Convert base64 to buffer
    const buffer = Buffer.from(content, 'base64');
    
    const formData = new FormData();
    const blob = new Blob([buffer], { type: contentType });
    formData.append('file', blob, filename);
  
    const response = await this.client.post('/user_uploads', formData, {
      headers: {
        'Content-Type': 'multipart/form-data'
      }
    });
    return response.data;
  }