# Open Routine Protocol (ORP)

[![CI](https://github.com/neldroid/open-routine-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/neldroid/open-routine-protocol/actions/workflows/ci.yml)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Spec: 2026-09-16](https://img.shields.io/badge/spec-2026--09--16-informational.svg)](spec/2026-09-16/overview.md)

**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](DISCLAIMER.md).

---

## Contents

- [Why not just an app?](#why-not-just-an-app)
- [How it works](#how-it-works)
- [5-minute quickstart](#5-minute-quickstart)
- [The privacy promise](#the-privacy-promise)
- [Safety and the wellness disclaimer](#safety-and-the-wellness-disclaimer)
- [How ORP relates to OpenActive, schema.org, MCP and Open Wearables](#how-orp-relates-to-openactive-schemaorg-mcp-and-open-wearables)
- [Repository layout](#repository-layout)
- [Roadmap](#roadmap)
- [Contributing and governance](#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

```mermaid
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](spec/2026-09-16/mcp-tools.md).

## 5-minute quickstart

You need [uv](https://docs.astral.sh/uv/) and Python 3.12 or newer (uv can install Python for you).

```bash
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):

```bash
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`.

```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

```bash
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](examples/clients/claude-code.md).

### Other commands

```bash
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](https://openwearables.io) 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](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](spec/2026-09-16/safety.md). Read
[DISCLAIMER.md](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](https://openactive.io)** 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](https://openactive.io/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](https://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](https://modelcontextprotocol.io)** 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](https://openwearables.io)** 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](https://www.openstreetmap.org)** and **[Open Food Facts](https://world.openfoodfacts.org)**
  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](CONTRIBUTING.md) (including the RFC process), [GOVERNANCE.md](GOVERNANCE.md) and
the [Code of Conduct](CODE_OF_CONDUCT.md). Report vulnerabilities as described in
[SECURITY.md](SECURITY.md).

## License

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