# Ryot MCP Starter

A local/private MCP server for a self-hosted Ryot instance, focused on workouts/routines, body measurements, movies, shows, and games.

## Project layout

```text
src/
  index.ts              # MCP bootstrap only
  ryot.ts               # GraphQL client + live schema helpers
  schemas.ts            # Shared zod schemas/enums
  common.ts             # Shared helpers
  discovery-tools.ts    # Schema/debug/discovery tools
  workout-tools.ts      # Fitness, measurements, routine tools
  media-tools.ts        # Movies, shows, games, collections, progress tools
  media-convenience-tools.ts # Search-and-act, next-episode, collections, raw review helpers
```

## Configure Cursor/Claude

```json
{
  "mcpServers": {
    "ryot": {
      "command": "node",
      "args": ["/absolute/path/to/ryot-mcp-starter/dist/index.js"],
      "env": {
        "RYOT_BASE_URL": "https://ryot.shivansh.top",
        "RYOT_AUTH_HEADER": "Bearer YOUR_RYOT_API_TOKEN",
        "RYOT_COOKIE": "",
        "RYOT_USER_ID": "",
        "RYOT_MOVIE_WATCHLIST_COLLECTION": "Movie Watchlist",
        "RYOT_SHOW_WATCHLIST_COLLECTION": "Show Watchlist",
        "RYOT_GAME_BACKLOG_COLLECTION": "Game Backlog",
        "RYOT_WALKING_EXERCISE_ID": "",
        "RYOT_SIT_TO_STAND_EXERCISE_ID": "",
        "RYOT_WALL_PUSHUP_EXERCISE_ID": ""
      }
    }
  }
}
```

`RYOT_AUTH_HEADER` should contain the exact working Authorization value. For Ryot integration tokens this is usually `Bearer <token>`.

`RYOT_USER_ID` is only needed for collection tools such as adding a movie to watchlist or a game to backlog.

## Build

```bash
npm install
npm run build
```

Restart Cursor/Claude after every rebuild.

## Tools

### Core/debug

- `ryot_health_check`
- `ryot_graphql`
- `ryot_schema_search`
- `ryot_find_candidate_operations`
- `ryot_workout_discovery`
- `ryot_media_discovery`
- `ryot_game_discovery`

### Fitness/routines

- `ryot_search_exercises`
- `ryot_list_recent_workouts`
- `ryot_list_workout_templates`
- `ryot_get_workout_details`
- `ryot_get_workout_template_details`
- `ryot_log_workout`
- `ryot_create_workout_template`
- `ryot_log_body_measurement`
- `ryot_log_walk`
- `ryot_log_bodyweight_set`
- `ryot_log_minimum_workout`
- `ryot_create_minimum_routine_template`
- `ryot_start_today_routine`
- `ryot_log_weight`
- `ryot_log_waist`
- `ryot_list_measurements`
- `ryot_log_minimum_day`
- `ryot_log_recovery_day`
- `ryot_get_weekly_workout_summary`

### General media

- `ryot_search_media`
- `ryot_get_metadata_details`
- `ryot_get_user_metadata_details`
- `ryot_mark_media_progress`
- `ryot_create_collection`
- `ryot_add_to_collection`
- `ryot_list_collections`
- `ryot_collection_contents`
- `ryot_user_metadata_list`
- `ryot_create_default_collections`
- `ryot_create_or_update_review`
- `ryot_delete_review`

### Movies

- `ryot_search_movie`
- `ryot_get_movie_status`
- `ryot_mark_movie_in_progress`
- `ryot_mark_movie_watched`
- `ryot_add_movie_to_watchlist`
- `ryot_search_and_mark_movie_watched`
- `ryot_search_and_add_movie_to_watchlist`

### Shows

- `ryot_search_show`
- `ryot_get_show_status`
- `ryot_mark_show_in_progress`
- `ryot_mark_show_episode_started`
- `ryot_mark_show_episode_watched`
- `ryot_add_show_to_watchlist`
- `ryot_search_and_add_show_to_watchlist`
- `ryot_search_and_mark_show_episode_watched`
- `ryot_get_next_show_episode`
- `ryot_mark_next_show_episode_watched`

### Games

- `ryot_search_game`
- `ryot_get_game_status`
- `ryot_mark_game_started`
- `ryot_mark_game_completed`
- `ryot_mark_game_dropped`
- `ryot_mark_game_on_hold`
- `ryot_update_game_progress_percent`
- `ryot_add_game_to_backlog`
- `ryot_search_and_start_game`
- `ryot_search_and_update_game_progress`
- `ryot_search_and_mark_game_completed`
- `ryot_search_and_add_game_to_backlog`

## Notes

Ryot list/search endpoints often return a cached response object rather than full objects directly. This MCP uses live schema introspection to build valid GraphQL selections for object return types, so it should return whatever scalar/cached fields your Ryot version exposes without hard-coding wrapper field names.

For workout logging/templates, Ryot requires internal `exerciseId` values. Use `ryot_search_exercises` first, then pass those IDs to `ryot_log_workout` or set default exercise IDs in env vars.

### Duration units (important for agents)

Ryot uses **different units** on different fields. Getting this wrong makes a 5-minute walk show as 300 minutes.

| Field                                   | Unit        | Example                                 |
| --------------------------------------- | ----------- | --------------------------------------- |
| `exercises[].sets[].statistic.duration` | **minutes** | 5-min walk → `5` (not `300`)            |
| `workout.duration`                      | **seconds** | 7-min workout → `420`                   |
| `exercises[].sets[].restTime`           | **seconds** | 90-sec rest → `90`                      |
| `walkingMinutes` / `minutes` tool args  | **minutes** | Human input; helpers convert internally |

Run `ryot_workout_discovery` to see `durationUnits` in the response. Never multiply set duration by 60.

The high-level routine shortcuts can read default exercise IDs from env vars:

- `RYOT_WALKING_EXERCISE_ID`
- `RYOT_SIT_TO_STAND_EXERCISE_ID`
- `RYOT_WALL_PUSHUP_EXERCISE_ID`

The collection shortcut tools can read default collection names from env vars:

- `RYOT_MOVIE_WATCHLIST_COLLECTION`
- `RYOT_SHOW_WATCHLIST_COLLECTION`
- `RYOT_GAME_BACKLOG_COLLECTION`

The `ryot_search_and_*` tools are best-effort wrappers: if Ryot returns only a cached search ID and no metadata ID, they return the search response so you can pick the result and call the ID-based tool.

Review tools are intentionally raw until the exact `CreateOrUpdateReviewInput` for your Ryot version is confirmed with schema discovery.

Keep this MCP private/local. The generic `ryot_graphql` tool can run arbitrary queries/mutations against your Ryot account.