Skip to content

Scaffold production-ready TypeScript Strava MCP server with comprehensive tooling - #1

Merged
Stealinglight merged 7 commits into
mainfrom
copilot/scaffold-strava-mcp-server
Jan 17, 2026
Merged

Stealinglight merged 7 commits into
mainfrom
copilot/scaffold-strava-mcp-server

Conversation

Copilot AI commented Jan 13, 2026 •

Copy link
Copy Markdown
Contributor

Implements a complete MCP server for Strava API enabling AI assistants to manage activities, with focus on enriching auto-imported workouts from devices like Apple Watch.

Architecture

StravaClient (src/lib/strava-client.ts)

  • OAuth 2.0 with auto-refresh (5min buffer, thread-safe)
  • Generic request(method, endpoint, data, config) supporting any Strava endpoint
  • Environment-based credentials via Zod validation

Modular Tools (src/tools/)

  • Activities (5): get/create/update activities, zones. update_activity supports partial updates for enrichment workflow
  • Athlete (2): profile, stats (recent/YTD/all-time)
  • Streams (1): telemetry data (HR, pace, power, GPS, elevation, cadence, watts, temp, grade)
  • Clubs (1): member activities
  • Uploads (2): FIT/TCX/GPX file handling

Utilities (src/utils/)

  • Error formatting with HTTP status handling
  • Human-readable formatters (distance, duration, pace, elevation)

Configuration

// src/config/env.ts - Zod validation
const envSchema = z.object({
  STRAVA_CLIENT_ID: z.string().min(1),
  STRAVA_CLIENT_SECRET: z.string().min(1),
  STRAVA_REFRESH_TOKEN: z.string().min(1),
});

// src/lib/strava-client.ts - Generic request
async request<T>(method: string, endpoint: string, data?: any): Promise<T> {
  await this.ensureValidToken();
  return this.axiosInstance.request({ method, url: endpoint, data });
}

Documentation

  • agents.md (13.7KB): Performance Coach guide with enrichment patterns, tool usage, conversation flows
  • README.md: Setup, architecture, troubleshooting, Claude Desktop integration
  • QUICKSTART.md: 5-minute setup flow
  • get-token.js: Interactive OAuth helper

Key Design Decisions

  • Enrichment-first: get_activities supports date filtering to find recent workouts; update_activity accepts partial updates
  • Future-proof: Generic request method works with all current and future Strava endpoints
  • MCP logging: Uses stderr (console.error) for all logs since stdout is MCP protocol channel
  • NodeNext modules: ES modules with proper TypeScript resolution

Usage Example

// Find today's activities
const today = Math.floor(new Date().setHours(0, 0, 0, 0) / 1000);
const activities = await client.get('/athlete/activities', { 
  params: { after: today } 
});

// Enrich with context
await client.put(`/activities/${id}`, {
  name: 'Progressive Long Run - 10K',
  description: 'Perfect weather. Zone 2 easy pace, HR 135-145...'
});

// Analyze telemetry
const streams = await client.get(`/activities/${id}/streams`, {
  params: { keys: 'time,heartrate,velocity_smooth' }
});

Tech stack: TypeScript (NodeNext), @modelcontextprotocol/sdk, axios, zod, dotenv
Build: Zero compilation errors, ~1,900 LOC

Original prompt

Scaffold a TypeScript Strava MCP server (@modelcontextprotocol/sdk, axios). 1. Create StravaClient class with auto-refresh OAuth & a generic request method to support ALL endpoints dynamically. 2. Define Tools: update_activity (priority: enrich Apple Watch runs), create_activity, get_streams (telemetry). 3. Use modular structure: src/tools/. 4. Generate agents.md guiding Claude to act as a Performance Coach using these tools. 5. Include get-token.js for initial auth.


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copilot AI and others added 5 commits January 13, 2026 17:03
…ttern

Co-authored-by: Stealinglight <120747552+Stealinglight@users.noreply.github.com>
…ation

Co-authored-by: Stealinglight <120747552+Stealinglight@users.noreply.github.com>
Co-authored-by: Stealinglight <120747552+Stealinglight@users.noreply.github.com>
Co-authored-by: Stealinglight <120747552+Stealinglight@users.noreply.github.com>
Co-authored-by: Stealinglight <120747552+Stealinglight@users.noreply.github.com>
Copilot AI changed the title [WIP] Scaffold TypeScript Strava MCP server with tools Scaffold production-ready TypeScript Strava MCP server with comprehensive tooling Jan 13, 2026
Copilot AI requested a review from Stealinglight January 13, 2026 17:24
@Stealinglight
Stealinglight marked this pull request as ready for review January 15, 2026 03:20
@Stealinglight

Copy link
Copy Markdown
Owner

@claude Can you look into these merge conflicts and resolve them

@github-actions

Copy link
Copy Markdown

🤖 Claude Code Review

null


Automated review powered by Claude AI

@Stealinglight
Stealinglight merged commit ba6ac86 into main Jan 17, 2026
1 check passed
@Stealinglight
Stealinglight deleted the copilot/scaffold-strava-mcp-server branch January 17, 2026 03:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

⌂ 换网址