Open Routine Protocol (ORP)

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

• Why not just an app?
• How it works
• 5-minute quickstart
• The privacy promise
• Safety and the wellness disclaimer
• How ORP relates to OpenActive, schema.org, MCP and Open Wearables
• Repository layout
• Roadmap
• Contributing and governance

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

Loading

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.