pal-e-docs

Domain Model: gdocs-daily-mcp-remote

arch-domain-gdocs-daily-mcp-remote Architecture

architecture draft
Project

Domain Model: gdocs-daily-mcp-remote

Diagram

Components

Component Purpose Notes
GOOGLE_ACCOUNT The Google account whose Docs we read Lucas's personal account. Authenticated via OAuth 2.0 web flow.
GOOGLE_DOCS_FOLDER Optional folder scope for daily notes If daily notes live in a specific folder, we can scope searches. Otherwise we search by title across all Docs.
DAILY_NOTE A single daily note document Named MM-DD-YYYY. The Google Docs API returns structured JSON (paragraphs, lists, tables). We extract plain text for Claude.
OAUTH_SESSION Per-user OAuth token managed by mcp-remote-auth Encrypted in TokenStore on PVC. Refresh token survives pod restarts. Access token refreshed automatically.
MCP_TOOL The MCP tool exposed to Claude.ai Primary tool: <code>get_daily_note(date?)</code>. Defaults to today. Returns document content as text.

Key Decisions

  • Title-based lookup, not folder ID. Daily notes are found by searching for documents titled MM-DD-YYYY using the Google Drive API (files.list with q filter). This avoids hardcoding a folder ID and works even if notes move folders.
  • Read-only scope. We only need documents.readonly and drive.readonly (for search). No write operations — this is a consumption tool.
  • Plain text extraction. Google Docs API returns a deeply nested JSON structure (Body → Content → Paragraph → Elements → TextRun). We flatten to plain text with basic formatting preserved (headers, lists, bold). Claude doesn't need the raw JSON.
  • No inner MCP package. Unlike gmail-mcp-remote (which wraps gmail-mcp), we build the Google Docs integration directly in the remote server. The API surface is small enough (one tool) that a separate package would be over-engineering.
  • Date defaulting. When no date is provided, the tool uses the server's current date (UTC or configured timezone). This enables "what's on my note today?" without parameters.
  • arch-dataflow-gdocs-daily-mcp-remote — runtime flow from Claude.ai to Google Docs API
  • arch-deployment-gdocs-daily-mcp-remote — k8s deployment topology
  • story-gdocs-daily-mobile-daily-review — the user story this serves