# 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](https://modelcontextprotocol.io/extensions/apps/overview). 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](https://www.jackivers.me/p/mcp-apps): 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

```bash
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):

```json
{
  "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:

```bash
# Terminal 1
TRANSPORT=http npm run serve

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

Add the generated URL as a [custom connector](https://support.anthropic.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) 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`:

```typescript
// 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](https://modelcontextprotocol.io/extensions/apps/overview):

- `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