day-planner-mcp

An MCP App that renders an interactive day-planning dashboard directly inside Claude conversations — showing your calendar, inbox, and docs unified in one UI with live clock, expandable events, and one-click meeting prep.

Built as a reference implementation of the MCP Apps spec. Works with Claude Desktop and Claude.ai.

What this demonstrates

MCP Apps live inside a single parent MCP. When you need data from Calendar and Gmail and Drive, you can't simply compose three existing MCPs — each is isolated. The common workaround is hitting those APIs directly from the parent.

This implementation takes a different approach: the model itself as the composition layer. The MCP App provides the UI shell and initial data load. updateModelContext then injects structured day data into the conversation, enabling the model to orchestrate follow-up tool calls against whichever MCPs are available. The MCP App is the persistent UI surface; the model is the orchestration engine.

This maps to an insight from Jack Ivers' MCP Apps writeup: the composability gap (MCPs can't call each other) can be bridged by designing the model as the composition layer, with updateModelContext as the handoff mechanism for multi-step workflows.

Features

• Unified day view — calendar, inbox, and docs in a single dashboard
• Smart cross-referencing — emails and docs auto-matched to calendar events by attendee and keyword
• Expandable event cards — click any event to reveal related emails, docs, and meeting prep
• Priority inbox — important unread emails surfaced with Mark Done / Snooze actions
• Live clock — real-time, updates every second
• Bidirectional communication — UI actions fire back to the model via app.callServerTool()
• updateModelContext — structured day data injected into conversation context after load

Architecture

┌─────────────────────────────────────────────────────┐
│                    Claude (model)                   │
│                                                     │
│  1. User: "Show me my day"                          │
│  2. Model calls load_day_planner tool               │
│  3. MCP fetches Calendar + Gmail + Drive in parallel│
│  4. Cross-references data (emails/docs → meetings)  │
│  5. Returns tool result + MCP App HTML resource     │
│  6. Claude renders interactive dashboard in chat    │
│                                                     │
│  7. User clicks "Start Meeting Prep"                │
│  8. UI fires → model calls handle_action tool       │
│  9. Model gets guidance + calls Gmail/Drive MCPs    │
│  10. Model synthesizes meeting brief in chat        │
└─────────────────────────────────────────────────────┘

day-planner-mcp/
├── src/
│   ├── index.ts              # MCP server (stdio + HTTP transports)
│   ├── mcp-app.ts            # UI logic — App class, render, actions
│   ├── tools/
│   │   └── dayPlanner.ts     # registerAppTool + handle_action tool
│   ├── services/
│   │   └── mockData.ts       # Drop-in replacement for real MCP calls
│   └── types.ts              # Shared domain types
├── mcp-app.html              # UI entry point (bundled by Vite)
└── vite.config.ts            # Single-file bundle config

The MockDataService maps 1:1 to real MCP tool calls — each fetch* method is where you substitute a call to the Gmail MCP, Calendar MCP, or Drive MCP. The aggregation, cross-reference, UI, and action handling are unchanged.

Prerequisites

• Node.js 18+
• Claude Desktop or any MCP Apps-compatible host

Setup

git clone https://github.com/ryaker/day-planner-mcp
cd day-planner-mcp
npm install
npm run build

Connecting to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "day-planner": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/day-planner-mcp/src/index.ts"]
    }
  }
}

Restart Claude Desktop. Ask Claude: "Show me my day" or "Load the day planner".

Connecting to Claude.ai (web)

The web client requires HTTPS. Run the HTTP server and expose via tunnel:

# Terminal 1
TRANSPORT=http npm run serve

# Terminal 2
npx cloudflared tunnel --url http://localhost:3456

Add the generated URL as a custom connector in Claude Settings → Connectors (paid plan required).

Replacing mock data with real integrations

The mock service is a thin wrapper. In production, replace the parallel fetches in src/tools/dayPlanner.ts with real MCP calls, or let the model orchestrate them via updateModelContext:

// Mock (current)
const [events, emails, docs] = await Promise.all([
  svc.fetchCalendarEvents(date),
  svc.fetchEmailThreads(maxEmails),
  svc.fetchRecentDocs(maxDocs),
]);

// Production: model orchestrates calls to
// Google Calendar MCP, Gmail MCP, Drive MCP
// then passes results into the same DayPlannerData shape

Scripts

Command	Description
npm run build	Build UI (Vite) + compile server (tsc)
npm run build:ui	Build UI only → dist/mcp-app.html
npm run build:server	Compile TypeScript server only
npm run serve	Start server (stdio by default)
TRANSPORT=http npm run serve	Start HTTP server on port 3456

MCP Apps spec

Implements the official MCP Apps spec:

• registerAppTool — declares _meta.ui.resourceUri so hosts can preload the UI
• registerAppResource — serves bundled HTML at ui://day-planner/app.html
• App class from @modelcontextprotocol/ext-apps — postMessage bridge between iframe and host
• app.ontoolresult — receives initial tool result data when UI renders
• app.callServerTool() — fires user actions back to the server

Contributing

PRs welcome. Key areas:

• Real MCP integrations (Google Calendar, Gmail, Drive)
• Additional action types
• Mobile layout
• Theme variants

License

MIT