Coachify

# Coachify — OKX.AI ASP

An Agent-to-MCP service that gives sleep-science-based, deterministic advice:
no LLM calls, no hallucination risk — every number comes from a documented
rule of thumb (caffeine half-life, melatonin onset window, sleep-cycle
length, circadian re-entrainment rate).

## Tools

| Tool | What it does |
|---|---|
| `wind_down_plan` | Bedtime-shift schedule + caffeine-clearance check + screen/light-dimming time |
| `nap_recommendation` | Nap length (0 / ~20 / ~90 min) + latest safe start time, based on sleep debt |
| `jetlag_plan` | Day-by-day light-exposure + melatonin-timing plan after time-zone travel |

## 1. Local setup

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## 2. Test locally over stdio (Claude Desktop / Claude Code / Cursor)

Run directly:

```bash
python3 server.py
```

Or register it with an MCP-capable client. For Claude Desktop, add to
`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sleep-circadian-coach": {
      "command": "python3",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}
```

Then in a chat, try: *"I usually go to bed at 1am but need to be up at 6:30am
for a new job — help me shift my schedule, my last coffee is at 3pm."*

## 3. Sanity-test the math directly (no MCP layer)

```bash
python3 -c "
from sleep_science import wind_down_plan
print(wind_down_plan(wake_time='06:00', current_bedtime='01:00',
                      target_bedtime='23:00', caffeine_last_dose='16:00'))
"
```

## 4. Run as a remote HTTP server (what you'll deploy)

```bash
cp .env.example .env   # fill in the OKX_X402_* values, see step 4b
TRANSPORT=http PORT=8000 python3 server.py
```

This serves the MCP **streamable-HTTP** transport at `http://<host>:<port>/`.
Deploy this to any **always-on** host — Render, Fly.io, Railway, or a small
VPS all work. It must NOT be a serverless/cold-start function (MCP session
state expects a persistent process), and the port must be publicly reachable
over HTTPS. A `Dockerfile` is included; most platforms will build/run it
automatically. Quick Render/Fly-style start command if you're not using the
Dockerfile:
```bash
pip install -r requirements.txt && TRANSPORT=http PORT=$PORT python3 server.py
```

### 4a. x402 payment compliance (required by OKX.AI review, even for free listings)

> Earlier guidance said "choose free pricing to skip x402" — OKX.AI's
> reviewer now requires every A2MCP service, free or paid, to speak
> x402 and return a proper `402` challenge to unauthenticated calls. The
> server now wires this in via the official `okxweb3-app-x402` SDK
> (`x402.http.middleware.fastapi.PaymentMiddlewareASGI`, mounted on the
> FastMCP streamable-HTTP ASGI app).

You need, from your own OKX account (nobody else can generate these for you):

- An API key/secret/passphrase from the [dev portal](https://web3.okx.com/onchainos/dev-portal)
- A payout wallet address (created during the Agentic Wallet / XLayer step
  below)

Put them in `.env` per `.env.example`. Keep `OKX_X402_PRICE` nominal
(e.g. `$0.00001`) to stay effectively free while still passing the
compliance check. `X402_ENABLED=false` disables payment gating entirely —
useful for local testing, but the deployed/submitted instance needs it
`true`.

## 5. List it on OKX.AI (hackathon submission steps)

1. Get an Agentic Wallet + on-chain agent identity via `okx.ai/tutorial` (this
   requires registering on XLayer — do this early, it's a separate step from
   writing code, and it's where you get the `OKX_X402_PAY_TO` address).
2. Deploy the HTTP endpoint (step 4) somewhere publicly reachable over HTTPS
   *before* registering — OKX.AI's review bot calls your `/` endpoint
   directly and will fail submission ("unable to reach service endpoint")
   if nothing is actually listening there yet.
3. Sanity-check reachability yourself first: `curl -i https://<your-host>/`
   should return an MCP-shaped response (or a `402` challenge once x402 is
   on), not a connection error/timeout.
4. Register your ASP through the `okx.ai/tutorial/asp` flow as an
   **Agent-to-MCP** service, pointing it at your `/` endpoint.
5. Manually verify before resubmitting: register as an OKX.AI user, then
   prompt "I would like to use the services of agent ID {your agent ID}"
   and confirm it responds.
6. Wait for OKX AI's internal review (~24h) — you'll get a result by email
   and in the agent conversation window.
7. Once live, post a ≤90-second demo on X with **#OKXAI**, showing an agent
   calling one of the three tools and returning a real plan.
8. Submit the Google form with your ASP details + X post link before
   **July 27, 2026, 23:59 UTC**.

## Notes / limitations

- All guidance is general wellness information based on population-level
  rules of thumb, not personalized medical advice — worth stating this
  explicitly in your ASP's listing description.
- Times are handled as plain 24h local "HH:MM" for the first two tools
  (single-timezone assumption). `jetlag_plan` is the one place true
  timezones (IANA names) are used, since that's where they matter.

Built Coachify, a deterministic (no-LLM) sleep-science coaching agent exposed as an MCP server with three tools — wind_down_plan (bedtime-shift schedule + caffeine-clearance check), nap_recommendation (optimal nap length and latest safe start time based on sleep debt), and jetlag_plan (day-by-day light-exposure and melatonin timing after time-zone travel). All outputs are based on documented rules of thumb (caffeine half-life, melatonin onset window, sleep-cycle length, circadian re-entrainment rate) rather than model-generated text, so there's no hallucination risk. The server runs over stdio for local MCP clients (Claude Desktop, Claude Code, Cursor) and over streamable-HTTP for remote deployment, with x402 payment-challenge compliance wired in via the okxweb3-app-x402 SDK per OKX.AI's ASP review requirement

N/A