Zulip MCP Server

Instructions

Implementation Reference

• src/server.ts:374-401 (handler)

  Handler function executes the 'get-started' tool: tests Zulip connection, fetches user's subscribed streams count and samples, checks recent activity, and returns formatted workspace overview with quick tips.

  async () => {
    try {
      const [streams, recentMessages] = await Promise.all([
        zulipClient.getSubscriptions().catch(() => ({ subscriptions: [] })),
        zulipClient.getMessages({ anchor: "newest", num_before: 3 }).catch(() => ({ messages: [] }))
      ]);
      
      const info = {
        status: "✅ Connected to Zulip",
        your_email: process.env.ZULIP_EMAIL,
        zulip_url: process.env.ZULIP_URL,
        streams_available: streams.subscriptions?.length || 0,
        sample_streams: streams.subscriptions?.slice(0, 5).map((s: any) => s.name) || [],
        recent_activity: recentMessages.messages?.length > 0,
        quick_tips: [
          "Use 'search-users' to find users before sending DMs",
          "Stream names are case-sensitive - use exact names from get-subscribed-streams",
          "Always include 'topic' when sending to streams",
          "For DMs, use actual email addresses (not display names)",
          "Note: 'streams' and 'channels' mean the same thing in Zulip"
        ]
      };
      
      return createSuccessResponse(JSON.stringify(info, null, 2));
    } catch (error) {
      return createErrorResponse(`Connection test failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
  }

• src/server.ts:370-402 (registration)

  Registration of the 'get-started' tool with server.tool(), including tool name, description, empty input schema ({}), and reference to the handler function.

  server.tool(
    "get-started",
    "🚀 START HERE: Test connection and get workspace overview. Use this first to verify everything is working and see available streams. Perfect for orientation and troubleshooting.",
    {},
    async () => {
      try {
        const [streams, recentMessages] = await Promise.all([
          zulipClient.getSubscriptions().catch(() => ({ subscriptions: [] })),
          zulipClient.getMessages({ anchor: "newest", num_before: 3 }).catch(() => ({ messages: [] }))
        ]);
        
        const info = {
          status: "✅ Connected to Zulip",
          your_email: process.env.ZULIP_EMAIL,
          zulip_url: process.env.ZULIP_URL,
          streams_available: streams.subscriptions?.length || 0,
          sample_streams: streams.subscriptions?.slice(0, 5).map((s: any) => s.name) || [],
          recent_activity: recentMessages.messages?.length > 0,
          quick_tips: [
            "Use 'search-users' to find users before sending DMs",
            "Stream names are case-sensitive - use exact names from get-subscribed-streams",
            "Always include 'topic' when sending to streams",
            "For DMs, use actual email addresses (not display names)",
            "Note: 'streams' and 'channels' mean the same thing in Zulip"
          ]
        };
        
        return createSuccessResponse(JSON.stringify(info, null, 2));
      } catch (error) {
        return createErrorResponse(`Connection test failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
      }
    }
  );

• src/server.ts:66-72 (helper)

  General helper function createSuccessResponse used by the get-started handler to format successful responses in MCP format.

  function createSuccessResponse(text: string) {
    return {
      content: [{
        type: "text" as const,
        text
      }]
    };

• src/server.ts:78-85 (helper)

  General helper function createErrorResponse used by the get-started handler to format error responses in MCP format.

  function createErrorResponse(message: string) {
    return {
      content: [{
        type: "text" as const,
        text: message
      }],
      isError: true
    };