rescuetime-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

RescueTime MCP Server — a Model Context Protocol server providing AI assistants access to RescueTime productivity data. Built with FastMCP, functype (IO, Option, Either, Try), and Zod.

Key patterns: functype IO<never, Error, T> for lazy composable API effects with IO.gen do-notation, Option<T> for singleton client, Try for safe formatting, .runOrThrow() at tool boundaries.

Development Commands

pnpm validate        # Main command: format + lint + typecheck + test + build
pnpm test            # Run tests once
pnpm test:watch      # Run tests in watch mode
pnpm build           # Production build (outputs to dist/)
pnpm inspect         # Build + launch MCP Inspector for interactive testing
pnpm start           # Build + run CLI
pnpm serve           # Build + run as Node process

Running a Single Test

pnpm test -- --testNamePattern="pattern"
pnpm test -- test/specific.spec.ts

Architecture

src/
  index.ts                        # FastMCP server setup, tool registration
  bin.ts                          # CLI entry point (stdio transport)
  types.ts                        # All domain types (readonly, immutable)
  errors.ts                       # Sealed error union types (_kind discriminator)
  client/
    rescuetime-client.ts          # Singleton client, IO-based API methods
  tools/
    index.ts                      # Barrel export
    analytics-tools.ts            # get_activity_data, get_daily_summary, get_productivity_score
    focus-tools.ts                # start_focus_session, end_focus_session, get_focus_sessions
    highlight-tools.ts            # get_highlights, post_highlight
    offline-tools.ts              # log_offline_time
  utils/
    formatters.ts                 # Markdown output formatters

Key Patterns

• Client singleton: Option<RescueTimeClient> with initializeClient() / getClient()
• API calls: Return IO<never, Error, T> via IO.tryPromise() + IO.fromEither() — lazy until .run()
• Tool boundary: IO.gen(function* () { ... }).runOrThrow() — do-notation with no explicit throws
• Client unwrap: getClient().toEither(err) → IO.fromEither() — stays in the IO pipeline
• Error types: Sealed union AppError = ApiError | ConfigError | RateLimitError with _kind
• Formatting: Array-join pattern with .map() for functional style