Bluesky MCP Server

Instructions

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)}`); } } );