Timeline MCP Server

Instructions

Implementation Reference

• timeline-fastmcp.ts:138-270 (handler)

  The execute function implementing the core logic for adding a scheduled event: validates input, finds or creates track, creates media directory and info.json, prepares and inserts event data into database, returns event details.
  execute: async (params) => { console.error('[Timeline MCP] Add scheduled event called with params:', JSON.stringify(params, null, 2)); const db = await getDb(); try { // Validate params const validatedParams = addScheduledEventParams.parse(params); console.error('[Timeline MCP] Validated params:', JSON.stringify(validatedParams, null, 2)); // Find or create track let track = await db.select().from(tracks) .where(and(eq(tracks.name, validatedParams.trackName), eq(tracks.type, 'planned'))) .limit(1); if (track.length === 0) { const maxOrder = await db.select({ maxOrder: tracks.order }) .from(tracks) .orderBy(desc(tracks.order)) .limit(1); const newOrder = (maxOrder[0]?.maxOrder || 0) + 1; const trackId = uuidv4(); const postyAccountId = await getDefaultPostyAccountId(); await db.insert(tracks).values({ id: trackId, postyAccountId, name: validatedParams.trackName, type: 'planned', order: newOrder }); const [newTrack] = await db.select().from(tracks).where(eq(tracks.id, trackId)); track = [newTrack]; } // Generate event ID first const eventId = uuidv4(); // Create media folder path const mediaPath = await createMediaPath(validatedParams.trackName, validatedParams.eventName); // Create the actual folder on disk const workspacePath = getWorkspacePath(); const fullMediaPath = path.join(workspacePath, mediaPath); console.error('[Timeline MCP] Creating media folder:', fullMediaPath); try { await fs.mkdir(fullMediaPath, { recursive: true }); // Create an info.json file with event metadata const infoFile = path.join(fullMediaPath, 'info.json'); const info = { eventId: eventId, eventName: validatedParams.eventName, trackId: track[0].id, createdAt: new Date().toISOString() }; await fs.writeFile(infoFile, JSON.stringify(info, null, 2)); console.error('[Timeline MCP] Media folder created successfully with info.json'); } catch (error) { console.error('[Timeline MCP] Error creating media folder:', error); // Continue even if folder creation fails } // Create event const scheduledTime = new Date(validatedParams.scheduledTime); const generationTime = calculateGenerationTime(scheduledTime); const postyAccountId = await getDefaultPostyAccountId(); const eventData = prepareEventForDb({ id: eventId, postyAccountId, trackId: track[0].id, name: validatedParams.eventName, platform: validatedParams.platform, scheduledTime: scheduledTime, generationTime: generationTime, prompt: validatedParams.prompt, // Store prompt string directly agent: validatedParams.agent, eventType: 'scheduled', mediaPath: mediaPath, mcpTools: JSON.stringify(validatedParams.mcpTools), approvalVia: validatedParams.approvalVia, metadata: JSON.stringify(validatedParams.metadata || {}), // Platform-specific metadata contentGenerated: false, approved: false, posted: false }); await db.insert(events).values(eventData); const [newEvent] = await db.select().from(events).where(eq(events.id, eventId)); const response = { success: true, event: { id: newEvent.id, trackId: newEvent.trackId, name: newEvent.name, scheduledTime: newEvent.scheduledTime, generationTime: newEvent.generationTime, mediaPath: newEvent.mediaPath, platform: newEvent.platform, metadata: newEvent.metadata ? JSON.parse(newEvent.metadata) : undefined } }; // Log event creation console.log('[MCP Timeline] Event created:', newEvent.id, newEvent.name); return JSON.stringify(response, null, 2); } catch (error) { console.error('[Timeline MCP] Error in add_scheduled_event:', error); if (error instanceof z.ZodError) { return JSON.stringify({ success: false, error: 'Validation error', details: error.errors }, null, 2); } return JSON.stringify({ success: false, error: error instanceof Error ? error.message : 'Unknown error occurred', stack: error instanceof Error ? error.stack : undefined }, null, 2); } }
• timeline-fastmcp.ts:120-130 (schema)

  Zod schema defining the input parameters for the timeline_add_scheduled_event tool, including validation rules for trackName, eventName, prompt, scheduledTime, platform, agent, etc.
  const addScheduledEventParams = z.object({ trackName: z.string().min(1, 'Track name cannot be empty').max(100, 'Track name too long'), eventName: z.string().min(1, 'Event name cannot be empty').max(200, 'Event name too long'), prompt: z.string().min(1, 'Prompt cannot be empty').max(5000, 'Prompt too long'), scheduledTime: isoDateTimeSchema, platform: platformSchema.default('x'), agent: agentSchema.optional().default('claude-sonnet-4-5-20250929'), approvalVia: z.string().optional().default('manual'), mcpTools: z.array(z.string()).optional().default(['timeline', 'fal', 'sqlite', 'playwright']), metadata: z.record(z.any()).optional().describe('Platform-specific metadata (e.g., { targetSubreddit: "subredditname" } for Reddit posts)') });
• timeline-fastmcp.ts:134-271 (registration)

  Registration of the timeline_add_scheduled_event tool with FastMCP using mcp.addTool(), including name, description, parameters schema, and execute handler.
  mcp.addTool({ name: 'timeline_add_scheduled_event', description: 'Add a scheduled event to a track. IMPORTANT: 1) Use the terminal MCP tool to get the current date/time (execute_command("date")) before scheduling events to ensure correct dates. 2) ALWAYS use timeline_list_tracks first to check existing tracks - if a track with a similar name or purpose already exists, use that instead of creating a new one. If unsure whether an existing track matches your needs, ask the user for clarification before proceeding.', parameters: addScheduledEventParams, execute: async (params) => { console.error('[Timeline MCP] Add scheduled event called with params:', JSON.stringify(params, null, 2)); const db = await getDb(); try { // Validate params const validatedParams = addScheduledEventParams.parse(params); console.error('[Timeline MCP] Validated params:', JSON.stringify(validatedParams, null, 2)); // Find or create track let track = await db.select().from(tracks) .where(and(eq(tracks.name, validatedParams.trackName), eq(tracks.type, 'planned'))) .limit(1); if (track.length === 0) { const maxOrder = await db.select({ maxOrder: tracks.order }) .from(tracks) .orderBy(desc(tracks.order)) .limit(1); const newOrder = (maxOrder[0]?.maxOrder || 0) + 1; const trackId = uuidv4(); const postyAccountId = await getDefaultPostyAccountId(); await db.insert(tracks).values({ id: trackId, postyAccountId, name: validatedParams.trackName, type: 'planned', order: newOrder }); const [newTrack] = await db.select().from(tracks).where(eq(tracks.id, trackId)); track = [newTrack]; } // Generate event ID first const eventId = uuidv4(); // Create media folder path const mediaPath = await createMediaPath(validatedParams.trackName, validatedParams.eventName); // Create the actual folder on disk const workspacePath = getWorkspacePath(); const fullMediaPath = path.join(workspacePath, mediaPath); console.error('[Timeline MCP] Creating media folder:', fullMediaPath); try { await fs.mkdir(fullMediaPath, { recursive: true }); // Create an info.json file with event metadata const infoFile = path.join(fullMediaPath, 'info.json'); const info = { eventId: eventId, eventName: validatedParams.eventName, trackId: track[0].id, createdAt: new Date().toISOString() }; await fs.writeFile(infoFile, JSON.stringify(info, null, 2)); console.error('[Timeline MCP] Media folder created successfully with info.json'); } catch (error) { console.error('[Timeline MCP] Error creating media folder:', error); // Continue even if folder creation fails } // Create event const scheduledTime = new Date(validatedParams.scheduledTime); const generationTime = calculateGenerationTime(scheduledTime); const postyAccountId = await getDefaultPostyAccountId(); const eventData = prepareEventForDb({ id: eventId, postyAccountId, trackId: track[0].id, name: validatedParams.eventName, platform: validatedParams.platform, scheduledTime: scheduledTime, generationTime: generationTime, prompt: validatedParams.prompt, // Store prompt string directly agent: validatedParams.agent, eventType: 'scheduled', mediaPath: mediaPath, mcpTools: JSON.stringify(validatedParams.mcpTools), approvalVia: validatedParams.approvalVia, metadata: JSON.stringify(validatedParams.metadata || {}), // Platform-specific metadata contentGenerated: false, approved: false, posted: false }); await db.insert(events).values(eventData); const [newEvent] = await db.select().from(events).where(eq(events.id, eventId)); const response = { success: true, event: { id: newEvent.id, trackId: newEvent.trackId, name: newEvent.name, scheduledTime: newEvent.scheduledTime, generationTime: newEvent.generationTime, mediaPath: newEvent.mediaPath, platform: newEvent.platform, metadata: newEvent.metadata ? JSON.parse(newEvent.metadata) : undefined } }; // Log event creation console.log('[MCP Timeline] Event created:', newEvent.id, newEvent.name); return JSON.stringify(response, null, 2); } catch (error) { console.error('[Timeline MCP] Error in add_scheduled_event:', error); if (error instanceof z.ZodError) { return JSON.stringify({ success: false, error: 'Validation error', details: error.errors }, null, 2); } return JSON.stringify({ success: false, error: error instanceof Error ? error.message : 'Unknown error occurred', stack: error instanceof Error ? error.stack : undefined }, null, 2); } } });