Zulip MCP Server

Instructions

Implementation Reference

• index.ts:469-485 (handler)

  Handles the 'zulip_get_channel_history' tool call by validating arguments and delegating to ZulipClient.getMessages method.

  case "zulip_get_channel_history": {
    const args = request.params.arguments as unknown as GetChannelHistoryArgs;
    if (!args.channel_name || !args.topic) {
      throw new Error(
        "Missing required arguments: channel_name and topic"
      );
    }
    const response = await zulipClient.getMessages(
      args.channel_name,
      args.topic,
      args.limit,
      args.anchor
    );
    return {
      content: [{ type: "text", text: JSON.stringify(response) }],
    };
  }

• index.ts:156-183 (schema)

  Defines the tool's name, description, and input schema for validation.

  const getChannelHistoryTool: Tool = {
    name: "zulip_get_channel_history",
    description: "Get recent messages from a channel (stream) and topic",
    inputSchema: {
      type: "object",
      properties: {
        channel_name: {
          type: "string",
          description: "The name of the stream",
        },
        topic: {
          type: "string",
          description: "The topic name",
        },
        limit: {
          type: "number",
          description: "Number of messages to retrieve (default 20)",
          default: 20,
        },
        anchor: {
          type: "string",
          description: "Message ID to start from (default 'newest')",
          default: "newest",
        },
      },
      required: ["channel_name", "topic"],
    },
  };

• index.ts:538-548 (registration)

  Registers the tool by including it in the list returned by ListToolsRequest handler.

    tools: [
      listChannelsTool,
      postMessageTool,
      sendDirectMessageTool,
      addReactionTool,
      getChannelHistoryTool,
      getTopicsTool,
      subscribeToChannelTool,
      getUsersTool,
    ],
  };

• index.ts:306-334 (helper)

  Core implementation that retrieves messages from Zulip using the client, finding stream ID and constructing narrow parameters.

  async getMessages(streamName: string, topic: string, limit = 20, anchor = "newest") {
    try {
      // First, need to find the stream ID
      const streamsResponse = await this.getStreams(true, true, true);
      const stream = streamsResponse.streams.find((s: any) => s.name === streamName);
      
      if (!stream) {
        throw new Error(`Stream "${streamName}" not found`);
      }
      
      // Construct narrow to filter by stream and topic
      const narrow = [
        { operator: "stream", operand: streamName },
        { operator: "topic", operand: topic },
      ];
      
      const params = {
        narrow: JSON.stringify(narrow),
        num_before: Math.floor(limit / 2),
        num_after: Math.floor(limit / 2),
        anchor: anchor,
      };
      
      return await this.client.messages.retrieve(params);
    } catch (error) {
      console.error("Error getting messages:", error);
      throw error;
    }
  }