Skip to main content
Glama

Open Routine Protocol (ORP)

CI License: Apache-2.0 Spec: 2026-09-16

ORP is an open protocol, plus a reference MCP server, that lets any AI assistant build a personal, location-aware routine combining exercise and eating. It works from your own profile, real places near you (gyms, parks with outdoor fitness equipment, pools, sports centres, restaurants) and, if you want, your wearable data. Your profile, plans and logs stay on your machine. ORP reuses open standards (OpenActive, schema.org, OpenStreetMap, MCP) and adds only what is missing: a portable profile, a plan format, a provider discovery manifest and an MCP tool contract. It is non-commercial, Apache-2.0 licensed, and for general wellness only.

⚠️ Wellness, not medicine. ORP does not diagnose, treat or take medical conditions into account. See DISCLAIMER.md.


Contents

Related MCP server: OSM Edit MCP Server

Why not just an app?

  • Your assistant already knows you. People plan their lives with AI assistants. A protocol lets any MCP-capable assistant (Claude, local models, others) plan routines, instead of locking the capability inside one app.

  • Data about places is scattered, and mostly open. Gyms publish sessions through OpenActive, OpenStreetMap maps outdoor fitness stations and restaurants, and Open Food Facts documents packaged food. An app would have to scrape or license all of that. A protocol lets providers publish once and be found by every assistant.

  • Plans should be portable. A profile or plan made with one tool should open in another. ORP documents are plain JSON with public schemas.

  • Safety and privacy belong in the standard. Readiness checks, intensity caps, attribution and "coarse location only" are protocol requirements, not features one app may or may not have.

  • Local-first is easier with a protocol. The server runs on your machine next to your data. Nobody needs to host your health information.

How it works

flowchart LR
    subgraph You["Your device"]
        P[(Profile<br/>plans · adherence log)]
        C[AI client<br/>Claude Desktop / Claude Code / …]
        S[ORP MCP server]
        C <-->|MCP tools · resources · prompts| S
        S <--> P
    end
    subgraph Open["Open data"]
        OSM[OpenStreetMap<br/>Nominatim · Overpass]
        OA[OpenActive<br/>RPDE feeds]
        OFF[Open Food Facts]
    end
    subgraph Prov["Providers"]
        G[Gym · sports centre<br/>/.well-known/orp.json]
        R[Restaurant<br/>schema.org Menu]
    end
    W[Open Wearables<br/>self-hosted, optional]
    S -->|coarse location + filters| OSM
    S -->|public feed pages| OA
    S -->|barcode / product name| OFF
    S -->|public manifests| G & R
    W -.->|aggregates| S

The language model composes the plan. The ORP server supplies data, validation and rules:

  1. profile_get / profile_update and the readiness gate (adult, disclaimer, generic screening);

  2. find_facilities, find_sessions, find_meals, food_lookup, geocode, wearable_summary;

  3. the model drafts a plan → plan_validate checks the schema and safety guardrails → the model fixes any errors → plan_save;

  4. log_adherence → adherence_summary → plan_suggest_adjustments proposes changes, which are saved only with your approval.

Full contract: spec/2026-09-16/mcp-tools.md.

5-minute quickstart

You need uv and Python 3.12 or newer (uv can install Python for you).

git clone https://github.com/neldroid/open-routine-protocol.git
cd open-routine-protocol
uv sync
uv run orp demo          # offline, end-to-end walkthrough; no network needed

Optionally create your profile from the terminal (or let the assistant do it in step 3):

uv run orp profile init --locale es-ES    # or --locale en

Claude Desktop

Add the server to your Claude Desktop configuration file. On macOS it is ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows, %APPDATA%\Claude\claude_desktop_config.json.

{
  "mcpServers": {
    "orp": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/open-routine-protocol", "orp", "serve"]
    }
  }
}

Restart Claude Desktop. Pick the create_weekly_plan prompt from the attachment menu, or just ask: "Make me a routine for next week with ORP. I live in Chamberí, Madrid."

Claude Code

claude mcp add orp -- uv run --directory /ABSOLUTE/PATH/TO/open-routine-protocol orp serve

Then run /mcp to confirm the connection, and use the /mcp__orp__create_weekly_plan prompt or ask in plain language. More options (wearables, HTTP transport) are in examples/clients/claude-code.md.

Other commands

uv run orp validate examples/plans/*.json     # validate ORP documents (type auto-detected)
uv run orp serve --http --port 8765           # streamable HTTP on 127.0.0.1 (no auth: local only)

Configuration

Variable

Purpose

ORP_HOME

Where the profile, plans and log live (default: platform config dir, e.g. ~/.config/orp)

ORP_CACHE_DIR

Public-data HTTP cache (default: platform cache dir)

ORP_OPENACTIVE_FEEDS

Comma-separated OpenActive RPDE feed URLs (also $ORP_HOME/openactive-feeds.json)

ORP_OPEN_WEARABLES_URL, ORP_OPEN_WEARABLES_API_KEY, ORP_OPEN_WEARABLES_USER_ID

Your own Open Wearables instance (optional)

ORP_OVERPASS_URL, ORP_NOMINATIM_URL, ORP_OPENFOODFACTS_URL

Use other instances (recommended for heavy use)

ORP provider manifests are discovered through a local registry, $ORP_HOME/providers.json: {"providers": ["https://gym.example.org"]}.

The privacy promise

  • Your profile, plans and logs never leave your machine through ORP. They are plain JSON files with owner-only permissions under ORP_HOME, and you can export or delete them at any time.

  • Outbound requests carry only coarse location (≤ 3 decimals, about 110 m), a radius and activity or diet filters. This is a protocol requirement, enforced by tests that inspect every outgoing request.

  • Wearables are opt-in, read-only, aggregates only, from an instance you host. They are never cached.

  • No telemetry, analytics or crash reporting.

  • Remember that your AI client sends tool results to its model provider under its own terms.

Details, a data-flow diagram and GDPR notes are in spec/2026-09-16/privacy.md.

Safety and the wellness disclaimer

ORP is a general wellness tool. It is not a medical device and not medical advice.

  • Plans are generated only for adults who have acknowledged the disclaimer.

  • A generic readiness screening (inspired by established questionnaires, not a copy of any) switches plans to low intensity and recommends consulting a professional when any answer suggests caution.

  • plan_validate enforces documented guardrails: intensity caps for beginners, at most 6 consecutive workout days, limits on week-over-week load increases, and no aggressive energy deficits. Guidance is portion-based by default; numbers appear only if you opt in.

  • Every plan tells you to stop and seek urgent help on chest pain, fainting or similar warning signs.

Thresholds and their sources are in spec/2026-09-16/safety.md. Read DISCLAIMER.md.

How ORP relates to OpenActive, schema.org, MCP and Open Wearables

ORP is a complementary layer. It exists because these projects already did the hard work, and it tries hard not to duplicate any of it.

  • OpenActive publishes open opportunity data for physical activity: sessions, facility slots and the Activity List vocabulary, over RPDE feeds. ORP consumes those feeds as they are, uses the Activity List for preferences, and points provider manifests at existing RPDE feeds instead of inventing a session format. Booking will build on the Open Booking API. Thank you to the OpenActive community and to publishers such as Everyone Active, whose CC BY 4.0 data is used in our tests.

  • schema.org already describes restaurants, menus, nutrition, diets, organisations and opening hours. ORP provider manifests and menus are plain schema.org JSON-LD.

  • Model Context Protocol is how assistants use tools. ORP is a set of MCP tools, resources and prompts with a normative contract, so any MCP client can use any ORP server.

  • Open Wearables unifies wearable data behind a self-hosted API. ORP reads aggregates from it, with the user's opt-in, instead of integrating each device.

  • OpenStreetMap and Open Food Facts provide the places and packaged-food data (ODbL). ORP follows their usage policies (identifying User-Agent, rate limits, caching) and always carries attribution into plans.

What ORP adds is the agentic glue: a portable profile, a plan document with safety semantics, a discovery manifest, and a tool contract. If a future version of any of these projects covers part of that, ORP should adopt it.

Repository layout

spec/2026-09-16/        normative spec (RFC 2119) and JSON Schemas (source of truth)
spec/rfcs/              RFC template and accepted RFCs
examples/               personas (Madrid, Valencia, London), valid plans, providers, client configs
src/orp/                reference implementation: MCP server, adapters, safety, CLI, demo
tests/                  offline test suite (recorded fixtures, respx, in-memory MCP client)

Roadmap

  • Booking through the OpenActive Open Booking API (links only today).

  • Spanish municipal sports centre adapters, and more OpenActive-style open data outside the UK.

  • Weather-aware alternatives (for example with an open weather API).

  • An orp.json generator page for small providers.

  • Client SDKs, starting with Kotlin/JVM.

  • Honour provider Cache-Control, and support full RPDE feed replication with background harvesting.

  • More opening_hours syntax, more languages, accessibility-aware venue filtering.

  • Spec: a conformance test kit for third-party ORP servers.

Contributing and governance

Contributions are very welcome: code, adapters, translations, and especially spec reviews. Read CONTRIBUTING.md (including the RFC process), GOVERNANCE.md and the Code of Conduct. Report vulnerabilities as described in SECURITY.md.

License

Apache License 2.0 for both the specification and the code. See LICENSE. Data in src/orp/demo/fixtures/ keeps its original licences (ODbL, CC BY 4.0), as listed in its README.

Available Tools

16 tools
adherence_summaryB
Read-only

7- and 28-day adherence metrics for the current plan.

Inputs: as_of. Returns: as_of, plan_id, counts_7d, counts_28d, +3 more

estimate_energyA
Read-only

Opt-in energy ESTIMATES: Mifflin-St Jeor resting energy and Compendium MET values. Refuses unless the profile enables show_energy_estimates. Never a prescription.

Inputs: workouts, include_resting. Returns: method, citation, estimate, workouts, +3 more

find_facilitiesA
Read-only

Gyms, sports centres, outdoor fitness stations, pools, tracks and parks from OpenStreetMap. Defaults to the profile home area and travel radius. Sends only coarse coordinates.

Inputs: lat, lon, kinds, limit, +1 more. Returns: center, sources, radius_m, facilities

find_mealsC
Read-only

Places to eat that fit the diet, from OpenStreetMap and ORP provider menus.

Inputs: lat, lon, limit, cuisine, +2 more. Returns: notes, center, places, sources, +2 more

find_sessionsB
Read-only

Classes and bookable facility slots from ORP provider manifests and OpenActive feeds.

Inputs: lat, lon, limit, activity, +1 more. Returns: feeds, notes, center, sources, +2 more

food_lookupA
Read-only

Packaged-food information from Open Food Facts, by barcode or by name.

Inputs: limit, query, barcode. Returns: notes, sources, products

geocodeA
Read-only

Turn a place label into coarse coordinates (Nominatim). Sends only the label.

Inputs: query (required), locale. Returns: lat, lon, label, sources

log_adherenceC

Append an entry to the adherence log (append-only).

Inputs: status (required), plan_item_id (required), note, timestamp, +1 more. Returns: entry

plan_get_currentA
Read-only

Return the current plan, or null.

Inputs: no named parameters. Returns: plan

plan_saveA

Validate again and store the plan as the current plan. Refuses invalid plans.

Inputs: plan (required). Returns: plan_id, saved_at, validation

plan_suggest_adjustmentsA
Read-only

Evaluate the current plan's adjustment_rules against adherence and wearable aggregates. Returns a proposal (JSON Patch + proposed plan). Never changes the stored plan: ask the user for approval, then call plan_save.

Inputs: as_of, use_wearables. Returns: as_of, notes, changes, metrics, +4 more

plan_validateB
Read-only

Validate a plan against the schema, the readiness gate and the safety guardrails.

Inputs: plan (required), compare_with_current. Returns: valid, errors, summary, warnings

profile_getA
Read-only

Read the local ORP profile and the readiness gate status.

Inputs: no named parameters. Returns: profile, readiness

profile_updateA

Create or patch the local profile. Never include diagnoses, medications or conditions.

Inputs: patch (required). Returns: profile, warnings, readiness

readiness_questionsB
Read-only

Generic pre-activity screening items, the wellness disclaimer and the red-flag notice.

Inputs: locale. Returns: items, locale, disclaimer, further_reading, +1 more

wearable_summaryA
Read-only

Aggregated sleep, resting heart rate, steps and workouts from the user's own Open Wearables instance. Opt-in; returns aggregates only.

Inputs: days. Returns: days, period, steps_avg, steps_avg_7d, +7 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 16 tools

    Disambiguation4/5

    Each tool targets a distinct resource or action: profile get/update, facility/session/meal discovery, plan lifecycle, and adherence logging/summary. Minor overlap exists between plan_validate and plan_save (save re-validates) and between profile_get and readiness_questions, but the descriptions clarify the boundaries.

    Naming Consistency3/5

    Most names follow a verb_noun pattern (find_facilities, estimate_energy, plan_save), but several are noun phrases (readiness_questions, wearable_summary, adherence_summary), one is a single verb (geocode), and food_lookup reverses the verb/object order. The snake_case convention is consistent, but the semantic pattern is mixed.

    Tool Count4/5

    16 tools is slightly above the ideal 3-15 range, but the domain spans profile management, discovery, nutrition, wearables, plans, and adherence, and each tool has a distinct purpose. No tools feel redundant.

    Completeness3/5

    Core workflows are covered: profile get/update, plan validate/save/get, adherence log/summary, and location/nutrition discovery. Obvious gaps include no plan delete/history, no retrieval of raw adherence entries, and no booking action for discoverable sessions or facilities.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive AI-powered fitness tracking application that enables AI tools to interact intelligently with user fitness data, providing personalized workout plans, nutrition tracking, and progress analysis through natural language.
      15
      MIT
    • A
      license
      B
      quality
      A
      maintenance
      Enables AI assistants to search, validate, and edit OpenStreetMap data through natural language commands and built-in safety protections. It supports discovery of nearby amenities, geographic data exploration, and secure map editing via OAuth authentication.
      36
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A universal fitness intelligence layer for AI assistants like Claude, ChatGPT, and Copilot, enabling user profiles, workout/diet plans, calendar scheduling, and gamification via MCP and REST APIs.
      9,324 npm
      MIT