day-planner-mcp

Instructions

Implementation Reference

• src/tools/dayPlanner.ts:92-157 (handler)

  Main handler implementation for 'handle_day_planner_action' tool. Uses server.registerTool() with an async handler function (lines 109-156) that processes user actions from the Day Planner UI. Implements a switch statement handling action types: 'mark_email_handled', 'start_meeting_prep', 'snooze_email', and 'open_doc'. Returns JSON with actionType, payload, and guidance text.

    server.registerTool(
      'handle_day_planner_action',
      {
        title: 'Handle Day Planner Action',
        description: `Processes an interactive action triggered by the user in the Day Planner UI.
  
  Action types:
    - mark_email_handled: User marked an email thread as done
    - start_meeting_prep: User wants prep help for a meeting
    - snooze_email: Snooze an email for N hours
    - open_doc: User opened a Drive document`,
        inputSchema: HandleActionSchema.shape,
        annotations: {
          readOnlyHint: false,
          destructiveHint: false,
        },
      },
      async ({ actionType, payload, currentDataJson }) => {
        const data = JSON.parse(currentDataJson) as DayPlannerData;
        let guidance = '';
  
        switch (actionType) {
          case 'mark_email_handled': {
            const thread = data.emails.find(e => e.id === payload.threadId);
            guidance = thread
              ? `User marked "${thread.subject}" as handled. You can call Gmail MCP to mark thread ${payload.threadId} as read.`
              : 'Thread not found.';
            break;
          }
          case 'start_meeting_prep': {
            const event = data.events.find(e => e.id === payload.eventId);
            if (event) {
              const relatedEmails = data.eventEmailMap[event.id] ?? [];
              const relatedDocs   = data.eventDocMap[event.id]   ?? [];
              guidance = `Meeting prep for "${event.title}" at ${new Date(event.startTime).toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })}.
  
  Attendees: ${event.attendeeNames.join(', ')}
  Related emails: ${relatedEmails.map(e => e.subject).join('; ') || 'none'}
  Related docs: ${relatedDocs.map(d => d.title).join('; ') || 'none'}
  
  Recommended: fetch full thread content from Gmail MCP and doc summaries from Drive MCP, then synthesize a meeting brief.`;
            } else {
              guidance = 'Event not found.';
            }
            break;
          }
          case 'snooze_email': {
            const thread = data.emails.find(e => e.id === payload.threadId);
            guidance = thread
              ? `User snoozed "${thread.subject}" for ${payload.hours} hours.`
              : 'Thread not found.';
            break;
          }
          case 'open_doc': {
            guidance = `User opened "${payload.title}". Fetch doc content from Drive MCP if user asks about it.`;
            break;
          }
          default:
            guidance = `Unknown action: ${actionType}`;
        }
  
        return {
          content: [{ type: 'text' as const, text: JSON.stringify({ actionType, payload, guidance }) }],
        };
      },
    );

• src/tools/dayPlanner.ts:23-30 (schema)

  Input schema definition for 'handle_day_planner_action' using Zod. Defines HandleActionSchema with three fields: actionType (enum of 4 action types), payload (record of strings), and currentDataJson (string containing serialized DayPlannerData).

  const HandleActionSchema = z.object({
    actionType: z.enum(['mark_email_handled', 'start_meeting_prep', 'snooze_email', 'open_doc'])
      .describe('The type of action the user triggered in the UI'),
    payload: z.record(z.string())
      .describe('Action-specific payload (e.g. threadId, eventId, hours)'),
    currentDataJson: z.string()
      .describe('JSON-serialized DayPlannerData from the last load_day_planner call'),
  });

• src/index.ts:36-37 (registration)

  Tool registration point where registerDayPlannerTools(server) is called, which registers both 'load_day_planner' and 'handle_day_planner_action' tools to the MCP server instance.

  // Register day planner tools (load_day_planner + handle_day_planner_action)
  registerDayPlannerTools(server);

• src/mcp-app.ts:72-73 (helper)

  UI-side invocation of 'handle_day_planner_action' tool. The frontend calls app.callServerTool() with the tool name and arguments including actionType, payload, and currentDataJson, enabling user interactions from the Day Planner UI to trigger server-side actions.

  await app.callServerTool({
    name: 'handle_day_planner_action',