AI导哈

健身计划生成服务

Kiwi Fitness是一款基于模型上下文协议（MCP）的服务，为Kiwi Fitness ChatGPT应用生成个性化的单次健身计划。

  • by sumnerjj
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 sumnerjj/kiwi_mcp

使用说明

Kiwi Fitness MCP Server

Kiwi Fitness is a Model Context Protocol (MCP) server that generates customized single-session workout plans for the Kiwi Fitness ChatGPT app. The server exposes a single tool, generate-workout, which accepts user preferences (experience, goals, equipment, and limitations) and a list of six desired exercise names, then returns a structured plan ready for presentation inside ChatGPT.

Prerequisites

  • Node.js 18+
  • npm 9+

Getting Started

Install dependencies:

npm install

Build the TypeScript sources:

npm run build

Run the server over stdio (useful for local testing with the MCP CLI):

npx kiwi-fitness-mcp

You can also run it directly from TypeScript during development:

npm run dev

Integrating with ChatGPT

  1. Build the project (npm run build).

  2. Reference the compiled binary (dist/index.js) in your ChatGPT MCP configuration, for example:

    {
  "name": "kiwi-fitness",
  "command": "node",
  "args": ["/absolute/path/to/kiwi_mcp/dist/index.js"],
  "cwd": "/absolute/path/to/kiwi_mcp"
}

  3. Restart ChatGPT (or your MCP-compatible client) so it can pick up the new server.

  4. Use the generate-workout tool from the Kiwi Fitness app to create workouts. The MCP resources kiwi-equipment-options, kiwi-target-muscle-groups, and kiwi-popular-exercises expose the canonical strings the client can reference when composing requests.

HTTP Deployment

Set the environment variable MCP_TRANSPORT=http to expose the Streamable HTTP endpoint. The server listens on PORT (defaults to 8080) and provides:

  • GET /health – readiness + version probe.
  • POST /mcp – Streamable HTTP MCP endpoint compatible with ChatGPT Apps.

Example runtime command:

PORT=8080 MCP_TRANSPORT=http node dist/index.js

The Fly.io deployment included in this repo uses these environment variables automatically.

Tool Interface

The generate-workout tool accepts the following parameters:

Field Type Description
experienceLevel enum (beginner, intermediate, advanced) User's training background.
primaryGoal enum (strength, hypertrophy, endurance, weight_loss, general_fitness) Main training objective.
sessionsPerWeek number (1-7) Target training frequency.
sessionLengthMinutes number (20-120) Desired session duration.
availableEquipment string[] Free-form list describing equipment (e.g., "dumbbells", "resistance bands").
preferredEquipmentOptions string[] Canonical equipment strings (see kiwi-equipment-options) to prioritise when matching exercises.
targetMuscleGroups string[] Canonical muscle group strings (see kiwi-target-muscle-groups) to emphasise across the plan.
preferredFocusAreas array of enums (full_body, upper_body, lower_body, core, conditioning, mobility) Optional emphasis areas to distribute across the week.
injuriesOrLimitations string[] Movements or body parts to protect.
workoutLocation enum (gym, home, outdoor) Primary training environment.
additionalPreferences string[] Any extra flavor notes (e.g., likes kettlebells, needs quiet sessions).
requestedExerciseNames string[] (minimum 6) Required. Provide the six exercise names the session must include. Use canonical catalog strings so the server can resolve them accurately.

The tool returns both Markdown and structured JSON describing the workout schedule, including warm-ups, primary blocks, optional finishers, cooldowns, and coaching guidance.

Example Invocation Payload

{
  "experienceLevel": "intermediate",
  "primaryGoal": "strength",
  "sessionsPerWeek": 4,
  "sessionLengthMinutes": 55,
  "availableEquipment": ["dumbbells", "kettlebells", "pull-up bar"],
  "preferredEquipmentOptions": ["Dumbbell"],
  "targetMuscleGroups": ["Gluteus Maximus", "Latissimus Dorsi and Teres Major"],
  "preferredFocusAreas": ["upper_body", "lower_body", "conditioning", "mobility"],
  "injuriesOrLimitations": ["left knee irritation"],
  "workoutLocation": "home",
  "additionalPreferences": ["enjoys kettlebell complexes"],
  "requestedExerciseNames": [
    "Goblet Squat",
    "Romanian Deadlift",
    "Dumbbell Bench Press",
    "Bent-over Row",
    "Arnold Press",
    "Hollow Body Hold"
  ]
}

Development Notes

  • The server uses the @modelcontextprotocol/sdk TypeScript SDK and communicates over stdio.
  • Zod schemas validate both input and structured output for safety and predictable tool usage.
  • Update exerciseLibrary in src/index.ts to tweak exercise selection logic or add modality-specific equipment.
  • Run npm run build before distributing or linking the server into ChatGPT.

Debugging Fuzzy Matches

You can inspect the catalog’s fuzzy-search results from the command line:

npm run build
npm run search -- "dumbbell hip thrust"

Use --limit, --goal, --focus, --equipment, or --target to experiment with filters. Pass --show-canon to list the canonical equipment and muscle-group strings exposed through the MCP resources.

Versioning & Caching

ChatGPT caches widget templates and resource payloads aggressively. Whenever you ship a breaking change to the workout HTML (or any resource the client downloads), register it under a new URI—for example, bump ui://kiwi/workout-plan-v1.html to …v2.html and update the corresponding tool metadata in the same deploy. Apply the same pattern to canonical data resources (equipment, muscle groups, etc.) by publishing …v2.json, then referencing the new URIs in your instructions. This keeps old sessions functioning while guaranteeing that fresh conversations load the latest assets instead of stale cached versions.

License

MIT

相关 MCP