mastodon_get_timeline

Instructions

Implementation Reference

• src/mastodon_tool.ts:168-205 (handler)

  The handler function that implements the core logic of the 'mastodon_get_timeline' tool: processes parameters, fetches timeline data via MastodonClient methods, formats the response as a text list of posts, and returns it in MCP content format.

  async (params: TimelineParams) => {
    const timelineParams = {
      limit: params.limit,
      max_id: params.max_id,
      since_id: params.since_id,
    };
  
    let posts;
    switch (params.timeline_type) {
      case "home":
        posts = await client.getHomeTimeline(timelineParams);
        break;
      case "public":
        posts = await client.getPublicTimeline(timelineParams);
        break;
      case "local":
        posts = await client.getLocalTimeline(timelineParams);
        break;
      default:
        throw new Error(`Unknown timeline type: ${params.timeline_type}`);
    }
  
    const summary = `Found ${posts.length} posts from ${params.timeline_type} timeline`;
    const postsList = posts.map((post, index) => {
      const reblogInfo = post.reblog ? ` (reblogged from @${post.reblog.account.acct})` : "";
      const mediaInfo = post.media_attachments.length > 0 ? ` [${post.media_attachments.length} media]` : "";
      return `${index + 1}. @${post.account.acct}${reblogInfo}: ${post.content.replace(/<[^>]*>/g, '').substring(0, 100)}...${mediaInfo}\n   Posted: ${new Date(post.created_at).toLocaleString()}\n   URL: ${post.url}`;
    }).join('\n\n');
  
    return {
      content: [
        {
          type: "text",
          text: `${summary}\n\n${postsList}`,
        },
      ],
    };
  }

• src/mastodon_tool.ts:36-56 (schema)

  Zod schema defining the input parameters for the mastodon_get_timeline tool: timeline_type (home/public/local), limit (1-40), max_id, since_id.

  const TimelineSchema = z.object({
    timeline_type: z
      .enum(["home", "public", "local"])
      .describe("Type of timeline to fetch")
      .default("home"),
    limit: z
      .number()
      .min(1)
      .max(40)
      .describe("Number of posts to fetch (1-40)")
      .default(20)
      .optional(),
    max_id: z
      .string()
      .describe("Get posts older than this ID")
      .optional(),
    since_id: z
      .string()
      .describe("Get posts newer than this ID")
      .optional(),
  });

• src/mastodon_tool.ts:164-206 (registration)

  MCP server tool registration for 'mastodon_get_timeline', including name, description, input schema reference, and inline handler function.

  server.tool(
    "mastodon_get_timeline",
    "Fetch posts from Mastodon timelines (home, public, or local)",
    TimelineSchema.shape,
    async (params: TimelineParams) => {
      const timelineParams = {
        limit: params.limit,
        max_id: params.max_id,
        since_id: params.since_id,
      };
  
      let posts;
      switch (params.timeline_type) {
        case "home":
          posts = await client.getHomeTimeline(timelineParams);
          break;
        case "public":
          posts = await client.getPublicTimeline(timelineParams);
          break;
        case "local":
          posts = await client.getLocalTimeline(timelineParams);
          break;
        default:
          throw new Error(`Unknown timeline type: ${params.timeline_type}`);
      }
  
      const summary = `Found ${posts.length} posts from ${params.timeline_type} timeline`;
      const postsList = posts.map((post, index) => {
        const reblogInfo = post.reblog ? ` (reblogged from @${post.reblog.account.acct})` : "";
        const mediaInfo = post.media_attachments.length > 0 ? ` [${post.media_attachments.length} media]` : "";
        return `${index + 1}. @${post.account.acct}${reblogInfo}: ${post.content.replace(/<[^>]*>/g, '').substring(0, 100)}...${mediaInfo}\n   Posted: ${new Date(post.created_at).toLocaleString()}\n   URL: ${post.url}`;
      }).join('\n\n');
  
      return {
        content: [
          {
            type: "text",
            text: `${summary}\n\n${postsList}`,
          },
        ],
      };
    }
  );

• src/api.ts:128-143 (helper)

  Supporting helper methods in MastodonClient class: getHomeTimeline, getPublicTimeline, and getLocalTimeline, which perform the actual API requests to fetch timeline data used by the tool handler.

  // Timeline methods
  async getHomeTimeline(params: TimelineParams = {}): Promise<MastodonStatus[]> {
    const queryParams = this.buildQueryParams(params);
    return this.request<MastodonStatus[]>(`/api/v1/timelines/home${queryParams}`);
  }
  
  async getPublicTimeline(params: TimelineParams = {}): Promise<MastodonStatus[]> {
    const queryParams = this.buildQueryParams(params);
    return this.request<MastodonStatus[]>(`/api/v1/timelines/public${queryParams}`);
  }
  
  async getLocalTimeline(params: TimelineParams = {}): Promise<MastodonStatus[]> {
    const localParams = { ...params, local: true };
    const queryParams = this.buildQueryParams(localParams);
    return this.request<MastodonStatus[]>(`/api/v1/timelines/public${queryParams}`);
  }