TimeTree-MCP: Instructions file for Claude Code

TimeTree MCP Project Guide

This is the shared project guide for people and AI coding assistants working in this repository. Keep it safe to commit: add only project-level guidance, never personal preferences, local machine paths, private credentials, copied calendar data, or session artifacts.

Project Purpose

TimeTree MCP is an unofficial Model Context Protocol (MCP) server for TimeTree. It connects MCP-compatible clients to TimeTree calendar data through TimeTree web APIs.

Important context:

• This project is not affiliated with, endorsed by, or supported by TimeTree.
• The API behavior is based on observed TimeTree web app behavior and may change without notice.
• package.json must keep "private": true unless maintainers explicitly decide to publish.
• Do not publish this package to npm or an MCP marketplace without maintainer approval.
• Distribution is limited to two channels: a git clone of main, and the Claude Desktop extension (.mcpb) attached to GitHub releases. See "Distribution" below.
• Treat upstream endpoints, cookies, CSRF tokens, and session identifiers as implementation details.

Current Capabilities

The server currently exposes tools for:

• Listing and creating calendars (creation does not invite members), and reading the signed-in user.
• Reading calendar events and updated events.
• Creating, updating, copying, and deleting events, including one occurrence (or it and later ones) of a recurring event.
• Managing event comments.
• Listing and managing memos.
• Reading and updating calendar labels.
• Reading calendar members, and reading and managing virtual members.
• Reading public holidays and recent calendar activity.

Write operations depend on TimeTree web authentication and CSRF handling. Keep error messages clear, but do not expose internal auth material.

Architecture Map

• src/index.ts - MCP server entry point and request routing.
• src/config/config.ts - TimeTree constants, API paths, and client metadata.
• src/client/auth.ts - Email/password authentication, CSRF extraction, and session state coordination.
• src/client/api.ts - TimeTree HTTP client operations, pagination, and domain-specific API methods.
• src/tools/ - MCP tool definitions, input/output shaping, annotations, and output schemas (shared pieces in shared-schemas.ts).
• src/utils/recurrence.ts - RRULE/EXDATE expansion and the series edits behind the occurrence tools.
• src/types/ - Zod schemas and shared TimeTree types.
• src/utils/http-client.ts - HTTP wrapper, headers, cookies, and CSRF token handling.
• src/utils/logger.ts - Structured logging and sensitive-data masking.
• src/utils/rate-limiter.ts - Token-bucket request throttling.
• src/utils/update-check.ts - Startup version check against main and the install-specific update notice.
• mcpb/manifest.json, mcpb/icon.png - Claude Desktop extension manifest and icon.
• scripts/build-mcpb.mjs - Bundles the server and all dependencies into one file and packs build/timetree-mcp-<version>.mcpb.
• scripts/mcpb-packer/ - The MCPB packer locked with its own package-lock.json, installed only when building the extension. It is kept out of the main package.json so its dev-only advisories do not fail the server's npm audit. Update it on purpose, not through the main lockfile.
• .github/workflows/release.yml - On a v* tag, tests, builds the .mcpb, and creates the GitHub release.
• docs/FEATURE_CANDIDATES.md - Observed TimeTree web features not exposed as tools yet, and why.
• docs/assets/ - Icon and GitHub social preview (SVG sources plus rendered PNGs), and the README demo GIFs (demo-en.gif, demo-ko.gif, demo-ja.gif).