mcp-toggl AGENTS.md

AGENTS.md

This file provides guidance to coding agents (Claude Code, Cursor, Codex, etc.) when working with this repository. It is the single source of truth; CLAUDE.md imports it via @AGENTS.md.

Project Overview

MCP Toggl is an MCP (Model Context Protocol) server for Toggl Track time tracking. It lets AI assistants read time entries, start/stop timers, generate daily/weekly/project/workspace reports, list workspaces/projects/clients, and inspect the Toggl Desktop activity timeline — translating MCP tool calls into Toggl Track API v9 requests over stdio.

Core purpose:

• Translate MCP tool calls into Toggl Track API requests
• Provide reporting (daily, weekly, per-project, per-workspace hour summaries)
• Cache workspace/project/client/tag metadata to cut API calls and avoid rate limits

This is a single-package TypeScript project (ES modules, Node 20.19+/22.12+). It runs as a stdio MCP server; there are no hooks, queues, or background services.

Build & Development

# Install dependencies
npm install

# Development with hot-reload (tsx watch on src/index.ts)
npm run dev

# Build TypeScript to dist/ (removes dist first, then tsc; postbuild chmod +x dist/index.js)
npm run build

# Start the built server (stdio mode)
npm start

# Run tests (Vitest, single run — no watch)
npm test

# Tests with coverage (v8)
npm run test:coverage

# Lint (ESLint over src/ and tests/)
npm run lint

# Format (Prettier over src/**/*.ts)
npm run format

# First-time local setup helper (creates .env from .env.example, installs, builds)
npm run setup

The test runner is Vitest (vitest run). There is no separate integration-test suite — npm test runs the full suite and needs no Toggl credentials: HTTP is mocked (node-fetch is vi.mock-ed in tests/toggl-api.test.ts), so tests never hit the live API. npm run build does rm -rf dist && tsc, and a postbuild step marks dist/index.js executable so the mcp-toggl bin works.