garmin-connect-mcp: Instructions file for Claude Code

Garmin Connect MCP Server - Project Instructions

Project Overview

This is an MCP (Model Context Protocol) server that provides integration with Garmin Connect. It enables access to health metrics, activities, and training data from Garmin devices through standardized MCP tools.

Tech Stack:

• TypeScript/Node.js (v20+)
• MCP SDK (@modelcontextprotocol/sdk)
• garmin-connect client library
• Vitest for testing
• tsup for bundling

Project Structure:

• src/ - Source code
• src/tools/ - MCP tool implementations
• src/types/ - TypeScript type definitions
• dist/ - Built output
• backlog/ - Task management using backlog.md CLI

Common Commands

# Development
pnpm dev              # Watch mode with auto-rebuild
pnpm build            # Build for production
pnpm start            # Run the built server

# Quality Checks
pnpm typecheck        # Run TypeScript type checking
pnpm lint             # Lint code
pnpm lint:fix         # Auto-fix linting issues

# Testing
pnpm test             # Run tests in watch mode
pnpm test:run         # Run tests once
pnpm test:coverage    # Generate coverage report

IMPORTANT: Always use pnpm, never npm or yarn.

Code Style Guidelines

• Use ES modules (import/export), not CommonJS
• Prefer functional programming patterns
• Use explicit types, avoid any
• Destructure imports when possible
• Use async/await over promises
• Follow existing naming conventions in the codebase

Example:

// ✅ Good
import { GarminConnect } from 'garmin-connect';
export async function fetchData(): Promise<Data> { ... }

// ❌ Bad
const GarminConnect = require('garmin-connect');
export function fetchData(): any { ... }

Testing Requirements

• New features require corresponding test files
• Use Vitest for unit tests
• Place tests in __tests__ directories or as *.test.ts files
• Mock external dependencies (Garmin API calls)
• Always run pnpm typecheck && pnpm test:run before committing

Task Management