get-timeline-posts

Retrieve your Bluesky home timeline, displaying posts from followed accounts in reverse chronological order. Specify the number of posts or hours to fetch for customizable results.

Instructions

Fetch your home timeline from Bluesky, which includes posts from all of the people you follow in reverse chronological order

Input Schema

TableJSON Schema

Name	Required	Description	Default
`count`	Yes	Number of posts to fetch or hours to look back
`type`	Yes	Whether count represents number of posts or hours to look back

Implementation Reference

src/index.ts:120-209 (handler)

The handler function for 'get-timeline-posts' tool. Fetches home timeline posts via agent.getTimeline with pagination, supports fetching by post count or hours back, filters accordingly, preprocesses posts using preprocessPosts, adds summary with formatSummaryText, and returns formatted text response.

async ({ count, type }) => {
  try {
    if (!agent) {
      return mcpErrorResponse("Not connected to Bluesky. Check your environment variables.");
    }

    const MAX_TOTAL_POSTS = 500; // Safety limit to prevent excessive API calls
    
    let allPosts: any[] = [];
    let nextCursor: string | undefined = undefined;
    let shouldContinueFetching = true;
    
    // Set up time-based or count-based fetching
    const useHoursLimit = type === "hours";
    const targetHours = count;
    const targetDate = new Date(Date.now() - targetHours * 60 * 60 * 1000);
    
    while (shouldContinueFetching && allPosts.length < MAX_TOTAL_POSTS) {
      // Calculate how many posts to fetch in this batch
      const batchLimit = 100;
      
      const response = await agent.getTimeline({ 
        limit: batchLimit,
        cursor: nextCursor
      });
      
      if (!response.success) {
        break;
      }
      
      const { feed, cursor } = response.data;
      
      // Filter posts based on time window if using hours limit
      let filteredFeed = feed;
      if (useHoursLimit) {
        filteredFeed = feed.filter(post => {
          const createdAt = post?.post?.record?.createdAt;
          if (!createdAt || typeof createdAt !== 'string') return false;
          const postDate = new Date(createdAt);
          return postDate >= targetDate;
        });
      }
      
      // Add the filtered posts to our collection
      allPosts = allPosts.concat(filteredFeed);
      
      // Update cursor for the next batch
      nextCursor = cursor;
      
      // Check if we should continue fetching based on the mode
      if (useHoursLimit) {
        // Check if we've reached posts older than our target date
        const oldestPost = feed[feed.length - 1];
        if (oldestPost?.post?.record?.createdAt && typeof oldestPost.post.record.createdAt === 'string') {
          const postDate = new Date(oldestPost.post.record.createdAt);
          if (postDate < targetDate) {
            shouldContinueFetching = false;
          }
        }
      } else {
        // If we're using count-based fetching, stop when we have enough posts
        shouldContinueFetching = allPosts.length < count;
      }
      
      // Stop if we don't have a cursor for the next page
      if (!cursor) {
        shouldContinueFetching = false;
      }
    }
    
    // If we're using count-based fetching, limit the posts to the requested count
    const finalPosts = !useHoursLimit
      ? allPosts.slice(0, count)
      : allPosts;
    
    if (finalPosts.length === 0) {
      return mcpSuccessResponse("Your timeline is empty.");
    }
    
    // Format the posts
    const timelineData = preprocessPosts(finalPosts);

    const summaryText = formatSummaryText(finalPosts.length, "timeline");
    
    return mcpSuccessResponse(`${summaryText}\n\n${timelineData}`);
    
  } catch (error) {
    return mcpErrorResponse(`Error fetching timeline: ${error instanceof Error ? error.message : String(error)}`);
  }
}

src/index.ts:116-119 (schema)

Input schema using Zod for the tool parameters: count (number between 1-500), type (enum: 'posts' or 'hours').

{
  count: z.number().min(1).max(500).describe("Number of posts to fetch or hours to look back"),
  type: z.enum(["posts", "hours"]).describe("Whether count represents number of posts or hours to look back")
},

src/index.ts:113-210 (registration)

Registration of the 'get-timeline-posts' tool on the MCP server, including name, description, input schema, and handler function.

server.tool(
  "get-timeline-posts",
  "Fetch your home timeline from Bluesky, which includes posts from all of the people you follow in reverse chronological order",
  {
    count: z.number().min(1).max(500).describe("Number of posts to fetch or hours to look back"),
    type: z.enum(["posts", "hours"]).describe("Whether count represents number of posts or hours to look back")
  },
  async ({ count, type }) => {
    try {
      if (!agent) {
        return mcpErrorResponse("Not connected to Bluesky. Check your environment variables.");
      }

      const MAX_TOTAL_POSTS = 500; // Safety limit to prevent excessive API calls
      
      let allPosts: any[] = [];
      let nextCursor: string | undefined = undefined;
      let shouldContinueFetching = true;
      
      // Set up time-based or count-based fetching
      const useHoursLimit = type === "hours";
      const targetHours = count;
      const targetDate = new Date(Date.now() - targetHours * 60 * 60 * 1000);
      
      while (shouldContinueFetching && allPosts.length < MAX_TOTAL_POSTS) {
        // Calculate how many posts to fetch in this batch
        const batchLimit = 100;
        
        const response = await agent.getTimeline({ 
          limit: batchLimit,
          cursor: nextCursor
        });
        
        if (!response.success) {
          break;
        }
        
        const { feed, cursor } = response.data;
        
        // Filter posts based on time window if using hours limit
        let filteredFeed = feed;
        if (useHoursLimit) {
          filteredFeed = feed.filter(post => {
            const createdAt = post?.post?.record?.createdAt;
            if (!createdAt || typeof createdAt !== 'string') return false;
            const postDate = new Date(createdAt);
            return postDate >= targetDate;
          });
        }
        
        // Add the filtered posts to our collection
        allPosts = allPosts.concat(filteredFeed);
        
        // Update cursor for the next batch
        nextCursor = cursor;
        
        // Check if we should continue fetching based on the mode
        if (useHoursLimit) {
          // Check if we've reached posts older than our target date
          const oldestPost = feed[feed.length - 1];
          if (oldestPost?.post?.record?.createdAt && typeof oldestPost.post.record.createdAt === 'string') {
            const postDate = new Date(oldestPost.post.record.createdAt);
            if (postDate < targetDate) {
              shouldContinueFetching = false;
            }
          }
        } else {
          // If we're using count-based fetching, stop when we have enough posts
          shouldContinueFetching = allPosts.length < count;
        }
        
        // Stop if we don't have a cursor for the next page
        if (!cursor) {
          shouldContinueFetching = false;
        }
      }
      
      // If we're using count-based fetching, limit the posts to the requested count
      const finalPosts = !useHoursLimit
        ? allPosts.slice(0, count)
        : allPosts;
      
      if (finalPosts.length === 0) {
        return mcpSuccessResponse("Your timeline is empty.");
      }
      
      // Format the posts
      const timelineData = preprocessPosts(finalPosts);

      const summaryText = formatSummaryText(finalPosts.length, "timeline");
      
      return mcpSuccessResponse(`${summaryText}\n\n${timelineData}`);
      
    } catch (error) {
      return mcpErrorResponse(`Error fetching timeline: ${error instanceof Error ? error.message : String(error)}`);
    }
  }
);

Bluesky MCP Server