Skip to main content
Glama
ryaker

day-planner-mcp

by ryaker
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

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.

Related MCP server: PopUI

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

Available Tools

2 tools
handle_day_planner_actionHandle Day Planner ActionA

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

ParametersJSON Schema
NameRequiredDescriptionDefault
actionTypeYesThe type of action the user triggered in the UI
payloadYesAction-specific payload (e.g. threadId, eventId, hours)
currentDataJsonYesJSON-serialized DayPlannerData from the last load_day_planner call

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive mutation tool. The description adds useful context about the UI interaction context and specific action types, but doesn't disclose additional behavioral traits like side effects, authentication needs, rate limits, or what happens after processing each action type.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly structured with a clear purpose statement followed by a bulleted list of action types. Every sentence earns its place, there's zero waste, and the information is front-loaded with the most important context first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema, the description provides good context about what actions it handles but lacks information about return values, error conditions, or what constitutes successful processing. The annotations cover basic safety but additional behavioral context would be helpful given this is an interactive UI action processor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the schema already documents all three parameters thoroughly. The description adds value by explaining what 'actionType' values represent with concrete examples, but doesn't provide additional semantic context for 'payload' or 'currentDataJson' beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'processes an interactive action triggered by the user in the Day Planner UI' with specific action types listed. It distinguishes from the sibling tool 'load_day_planner' by focusing on action processing rather than data loading, providing a specific verb+resource+scope combination.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context about when to use this tool ('interactive action triggered by the user in the Day Planner UI') and implicitly references the sibling tool 'load_day_planner' through the 'currentDataJson' parameter. However, it doesn't explicitly state when NOT to use this tool or provide alternative tools for similar actions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

load_day_plannerLoad Day PlannerA

Opens an interactive day planning dashboard showing your calendar, emails, and docs.

The dashboard shows:

  • Today's calendar events (expandable to reveal related emails and docs)

  • Inbox emails prioritized by importance

  • Recent Drive documents surfaced by meeting context

  • Interactive buttons: expand events, mark emails handled, start meeting prep

Use this to give the user a holistic view of their day.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoDate to plan for in YYYY-MM-DD format. Defaults to today.
maxEmailsNoMax email threads to surface (default 10)
maxDocsNoMax recent Drive docs to surface (default 5)

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what the dashboard shows and interactive features, which adds useful context about the tool's behavior. However, it doesn't address important behavioral aspects like whether this is a read-only operation, if it requires specific permissions, or any rate limits. The description doesn't contradict annotations (none exist).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and well-structured with clear bullet points listing dashboard components. It's front-loaded with the core purpose. Some minor verbosity exists in the bullet descriptions, but overall it's efficient and each sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (interactive dashboard with multiple data sources), no annotations, and no output schema, the description does a reasonably complete job. It explains what the tool does, what the dashboard contains, and how to use it. However, it could be more complete by addressing the lack of output schema (what exactly gets returned) and providing more behavioral context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents all three parameters. The description doesn't add any parameter-specific information beyond what's in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Opens an interactive day planning dashboard showing your calendar, emails, and docs.' It uses specific verbs ('Opens', 'showing') and resources ('dashboard', 'calendar', 'emails', 'docs'), and distinguishes from the sibling tool 'handle_day_planner_action' by focusing on loading/displaying rather than handling actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: 'Use this to give the user a holistic view of their day.' It implies usage for day planning but doesn't explicitly state when NOT to use it or mention alternatives beyond the sibling tool, which is only referenced implicitly through differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv1.0.0
    • First observedhandle_day_planner_action
    • First observedload_day_planner
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0
Disambiguation5/5

The two tools have completely distinct purposes: one handles specific user actions in the Day Planner UI, while the other loads the entire interactive dashboard. There is no overlap or ambiguity between them, as they serve different functions in the user workflow.

Naming Consistency5/5

Both tools follow a consistent snake_case naming pattern with clear verb_noun structure: 'handle_day_planner_action' and 'load_day_planner'. The naming is predictable and readable, making it easy for an agent to understand their roles.

Tool Count2/5

With only 2 tools, the server feels too thin for its stated purpose of day planning, which involves calendar events, emails, documents, and interactive actions. A more comprehensive set would be expected to cover operations like creating events, managing tasks, or updating priorities, rather than just handling actions and loading a dashboard.

Completeness2/5

The tool surface is severely incomplete for day planning. While it covers loading a dashboard and handling some UI actions, it lacks core CRUD operations for managing calendar events, emails, or documents. There are significant gaps that would cause agent failures, such as no ability to create or modify events, send emails, or organize tasks beyond the provided actions.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • PopUI

    kelnishi
    A
    license
    Not graded
    quality
    C
    maintenance
    A companion desktop app enabling bi-directional interaction between Claude Desktop and visual UI elements, allowing Claude to display, read from, and write to interactive interfaces while processing user events and feedback.
    5
    8
    Apache 2.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ryaker/day-planner-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server