ourpr-mcp-server 0.2.0 → 0.4.0

package/README.md

@@ -1,10 +1,12 @@
 # ourpr-mcp-server
 
 An MCP server that lets an AI agent read **your own** running history from
-[ourpr](https://ourpr.app). Ask about your training in plain language, in
-whatever agent you already use.
+[ourpr](https://ourpr.app), and write one thing back. Ask about your
+training in plain language, in whatever agent you already use.
 
-Read only. It cannot change a run, plan a week, or issue another credential.
+Every tool reads. One tool writes, and only that one: `ourpr_plan_week` puts
+a plan on a day still ahead. It cannot log a run, edit history, or issue
+another credential, and it needs a token made with the write scope.
 
 ## Why it exists
 
@@ -15,40 +17,105 @@ credential you issued to yourself and can revoke.
 
 ## Setup
 
-**1. Make a token.** In ourpr, go to **Settings → Access tokens → New token**.
-Name it after the machine it will live on. Copy it — it is shown once and
-cannot be recovered. A token lasts 90 days.
+**1. Make a token.** In ourpr, go to
+**Profile → Settings → ourpr. mcp → New token**. Name it after the machine it
+will live on, and choose **Write** if you want the agent to plan your week;
+**Read** otherwise. Copy it — it is shown once and cannot be
+recovered. A token lasts 90 days.
 
 **2. Point a client at it.** The package runs from npm; nothing to clone.
 
+**Keep the token out of any file inside a project.** A project's `.mcp.json`,
+`.cursor/mcp.json` or `.vscode/mcp.json` is often committed, and a committed
+token can be read by anyone who can read the repository. Every setup below
+keeps the token in a user-level place or in your system's secret store.
+
+**Pin the version.** Each setup names an exact version, so a new release never
+runs with your token until you choose it. Change the number to update.
+
 ### Claude Code
 
+Read the token without echoing it, so it stays out of your shell history, then
+add the server for your user, not for a project:
+
 ```bash
-claude mcp add ourpr --env OURPR_TOKEN=ourpr_pat_... -- npx -y ourpr-mcp-server
+printf 'Token: '; read -rs OURPR_TOKEN; echo
+claude mcp add --scope user --env OURPR_TOKEN="$OURPR_TOKEN" --transport stdio \
+  ourpr -- npx -y ourpr-mcp-server@0.4.0
+unset OURPR_TOKEN
 ```
 
+Claude Code keeps it in `~/.claude.json`, which belongs to your user.
+
 ### Claude Desktop
 
 Download `ourpr.mcpb` from the latest release and open it. Claude Desktop asks
-for the token and stores it as a secret.
+for the token and keeps it in your system's secret store. This is the
+recommended way.
 
-Or edit `claude_desktop_config.json`:
+Or edit `claude_desktop_config.json`, which lives in your user folder, not in
+a project. The token is then plain text in that file:
 
 ```json
 {
   "mcpServers": {
     "ourpr": {
       "command": "npx",
-      "args": ["-y", "ourpr-mcp-server"],
+      "args": ["-y", "ourpr-mcp-server@0.4.0"],
       "env": { "OURPR_TOKEN": "ourpr_pat_..." }
     }
   }
 }
 ```
 
-### Cursor, VS Code
+### VS Code
+
+Run **MCP: Open User Configuration** and add the server there. VS Code asks
+for the token once, masks it, and keeps it in its secret store:
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "ourpr-token",
+      "description": "ourpr personal access token",
+      "password": true
+    }
+  ],
+  "servers": {
+    "ourpr": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "ourpr-mcp-server@0.4.0"],
+      "env": { "OURPR_TOKEN": "${input:ourpr-token}" }
+    }
+  }
+}
+```
+
+### Cursor
+
+Set `OURPR_TOKEN` in your shell profile or your system's secret manager, and
+add the server to the global `~/.cursor/mcp.json`. The file holds only a
+reference to the variable:
+
+```json
+{
+  "mcpServers": {
+    "ourpr": {
+      "command": "npx",
+      "args": ["-y", "ourpr-mcp-server@0.4.0"],
+      "env": { "OURPR_TOKEN": "${env:OURPR_TOKEN}" }
+    }
+  }
+}
+```
+
+### If a token leaks
 
-`.cursor/mcp.json` or `.vscode/mcp.json`, same shape as above.
+Revoke it in **Profile → Settings → ourpr. mcp**, then make a new one.
+Revocation is immediate.
 
 ### From source
 
@@ -58,6 +125,12 @@ cd ourpr-mcp-server
 npm install && npm run build && npm test
 ```
 
+## Protocol
+
+The server speaks MCP `2026-07-28`, and it still answers a client that opens
+with the older `initialize` handshake. It is built on the official TypeScript
+SDK v2 (`@modelcontextprotocol/server`), and the tests run each version.
+
 ## Environment
 
 | | |
@@ -132,6 +205,67 @@ done that resembles a race you are training for.
 "What have I run that's like Boston — 26 miles, 800 feet of climb?"
 ```
 
+### `ourpr_training_blocks`
+
+Your goal race and its Block: race day, distance, goal time, the week of the
+Block today falls in, and the miles for each week so far. A week that has not
+begun shows no miles, not zero. Also the Blocks before your past races, each
+with its result, its weeks and its peak week.
+
+```
+"What week of my Dallas block am I in, and how is my mileage building?"
+"How does this block compare with the one before my last marathon?"
+```
+
+`past`: how many past Blocks, newest first. Three by default.
+
+### `ourpr_list_races`
+
+Every race ourpr finds in your history, tune-ups included, through the same
+detector the app's Blocks use. Each row carries the run id for
+`ourpr_get_run`. The answer also names the fastest result at 5K, 10K, half
+marathon and marathon.
+
+```
+"What is my half marathon PR?"
+"List every marathon I have run, with the times"
+```
+
+`distance`, `limit`.
+
+### `ourpr_list_plans`
+
+The plans already on your week between two dates, two weeks from today by
+default: the day, the name, the miles or time, the tag, your note, whether a
+run you logged fulfilled it, and whether ourpr create wrote it. An agent reads
+this before `ourpr_plan_week`, so a new plan does not land on a day that
+already holds one.
+
+```
+"What do I have planned for the next two weeks?"
+"Did I do the runs I planned last week?"
+```
+
+`start_date`, `end_date` (YYYY-MM-DD).
+
+### `ourpr_plan_week`
+
+The one write. One planned run, or a week of them, onto days still ahead.
+Each lands on the runner's week as a plan they can see, edit and remove; the
+day sheet says it came from ourpr create. It never logs a run.
+
+```
+"Put a 6 mile easy run on Tuesday and 14 long on Saturday"
+"Write me next week: three easy days, one workout, one long run"
+```
+
+`plans`, one to fourteen, each with `date` (YYYY-MM-DD, after today) and any
+of `miles`, `minutes`, `name`, `note`, `tag` (easy, workout, race), `is_long`.
+
+Needs a token made with the **Write** scope, and ourpr create on the account.
+A **Read** token, or an account without create, is refused before anything is
+written. Thirty plans a day.
+
 ## How the tool set was chosen
 
 By an evaluation, not by listing the API.
@@ -166,15 +300,19 @@ numbers the agent would only reduce anyway.
 
 ## Security
 
-The token grants read access to your own activity data and nothing else. It
-cannot write, cannot issue another token, cannot revoke your existing ones, and
-cannot widen its own scope.
+The token grants read access to your own runs, your goal race and your plans.
+On ourpr, every query a token makes is scoped to its owner by construction, and
+a test refuses a token route that could reach past it. A token made with the
+write scope, with ourpr create, may also put plans on your own week through
+one route, and nothing else. No token can log a run, issue another token, revoke
+your existing ones, or widen its own scope.
 
-Each token may make 60 reads a minute. ourpr answers 429 past that, with
-`RateLimit` and `Retry-After` headers, and the tool says how long to wait.
+Each token may make 60 reads a minute, and a runner may write 30 plans a day.
+ourpr answers 429 past either, with `RateLimit` and `Retry-After` headers, and
+the tool says how long to wait.
 
-Revoke any token at any time in **Settings → Access tokens**. Revocation is
-immediate and permanent — a revoked token can never be restored.
+Revoke any token at any time in **Profile → Settings → ourpr. mcp**.
+Revocation is immediate and permanent — a revoked token can never be restored.
 
 ### Tool results are untrusted content
 
@@ -241,6 +379,18 @@ bundle's entry point; `npx @anthropic-ai/mcpb pack` builds `ourpr.mcpb` for
 the release. `server.json` registers the package in the MCP Registry with
 `mcp-publisher publish`.
 
+Trusted publishing is the only way in. The package's npm settings require
+two-factor authentication and disallow tokens, so no stolen npm token can
+publish a version, and the OIDC workflow still can. `npm-shrinkwrap.json` ships
+in the package, so every install resolves the same dependency tree that the
+release tested. Run `npm install` and commit the shrinkwrap after any
+dependency change.
+
+A release changes the version in five places: `package.json`,
+`npm-shrinkwrap.json` (through `npm install`), `manifest.json`, `server.json`
+and the `McpServer` in `src/index.ts`. Every setup command in this README pins
+the version, and so does `AGENT_VERSION` in ourpr's `lib/agent-connect.ts`.
+
 ## License
 
 MIT

package/build/api.js

@@ -1,42 +1,12 @@
-// The ourpr API, as this server talks to it.
-//
-// AUTHENTICATION IS AN ENVIRONMENT VARIABLE, NOT A TOOL PARAMETER, and that is
-// a deliberate difference from revenuecat-charts-mcp, which takes `api_key` on
-// every call. RevenueCat issues one key per project and a person may hold
-// several, so asking per call is right there. An ourpr token belongs to ONE
-// runner and never changes between calls, so a parameter would put a live
-// credential into every tool call the agent makes — into its context, its
-// transcript, and any log of either. The env var keeps it out of all three.
-//
-// NOTHING THIS SERVER PRINTS MAY CARRY A CONFIGURED VALUE. `OURPR_TOKEN` is
-// never printed anywhere, and `OURPR_API_URL` is reduced to scheme and host
-// before it reaches an error — see `safeOrigin`. An error message travels into
-// the agent's context and its transcript, so printing there is publishing.
-//
-// NOTHING HERE MAY WRITE TO STDOUT. On a stdio server stdout IS the protocol
-// stream, and one stray `console.log` corrupts it. Diagnostics go to stderr.
+// The token is an environment variable, never a tool parameter, so no call carries it.
 import { cell } from "./safe.js";
 const TOKEN = process.env.OURPR_TOKEN ?? "";
 const BASE = (process.env.OURPR_API_URL ?? "https://ourpr.onrender.com/api").replace(/\/$/, "");
-// A bearer token over plain http travels in the clear. Warn once rather than
-// refuse: localhost is how this server runs against a dev backend.
+// A token over plain http travels in the clear; localhost is the dev backend.
 if (BASE.startsWith("http://") && !/^http:\/\/(localhost|127\.0\.0\.1)[:/]/.test(BASE)) {
     console.error("[ourpr-mcp-server] OURPR_API_URL is http, not https - the token is not encrypted in transit");
 }
-/**
- * The configured host, with everything else removed.
- *
- * NO ENVIRONMENT VALUE IS ECHOED WHOLE. An error goes straight into the
- * agent's context and its transcript, so anything printed there is published.
- * `OURPR_API_URL` is usually just a hostname — and it is a URL, so it CAN
- * carry `user:password@` before the host, which a self-hosted or staging
- * instance behind basic auth plausibly would. Dropping userinfo, path, query
- * and fragment leaves the one part that helps a person debug and none of the
- * part that must not travel.
- *
- * An unparseable value yields a placeholder rather than the raw string,
- * because "unparseable" is exactly the case where the string is unexpected.
- */
+/** The configured host only; userinfo, path and query never reach an error. */
 function safeOrigin() {
     try {
         const url = new URL(BASE);
@@ -46,19 +16,9 @@ function safeOrigin() {
         return "the configured host";
     }
 }
-/**
- * Why a request failed, WITHOUT the message.
- *
- * A Node fetch failure carries the full request URL in `cause`, and a timeout
- * message can too. The code — ECONNREFUSED, ENOTFOUND, TimeoutError — says
- * everything a person needs and carries nothing they did not choose to
- * publish.
- */
+/** The error code, never the message, which can carry the request URL. */
 function reason(err) {
-    // WALK THE CAUSE CHAIN. Node wraps a connection failure as
-    // `TypeError: fetch failed` with the useful code — ECONNREFUSED, ENOTFOUND —
-    // one or two levels down in `cause`. Reading only the top gave "TypeError",
-    // which tells a person nothing they can act on.
+    // Node puts the useful code one or two levels down in cause.
     let node = err;
     for (let depth = 0; node && depth < 4; depth++) {
         const code = node.code;
@@ -66,10 +26,7 @@ function reason(err) {
             return code;
         node = node.cause;
     }
-    // NO CODE — a URL that will not parse ("bad port") reaches here, and its
-    // MESSAGE is the only useful thing. Passed on ONLY when it cannot be
-    // carrying configured values: an "@" means userinfo, and the raw base or the
-    // token must never appear. Fails closed to the error name.
+    // A message passes only when it cannot carry a configured value.
     const deepest = deepestMessage(err);
     const safe = deepest &&
         !deepest.includes("@") &&
@@ -98,15 +55,18 @@ export class ApiError extends Error {
 function guidance(status, detail, retryAfterS) {
     if (status === 429) {
         const wait = /^\d+$/.test(retryAfterS ?? "") ? `${retryAfterS} seconds` : "a minute";
-        return `ourpr allows 60 reads a minute for each token. Wait ${wait}, then ask again.`;
+        return ("ourpr allows 60 reads a minute for each token and 30 plans a day. " +
+            `Wait ${wait}, then ask again.`);
     }
     if (status === 401) {
         return ("ourpr rejected the token. It may be revoked, expired (a token lasts 90 " +
             "days), or OURPR_TOKEN may be unset. Make a new one in ourpr under " +
-            "Settings, Access tokens.");
+            "Profile, Settings, ourpr. mcp.");
+    }
+    if (status === 403) {
+        return ("ourpr refused the write. The token needs the write scope, chosen when " +
+            "it is made, and ourpr create behind it.");
     }
-    if (status === 403)
-        return "That token can read only. This action needs a write scope.";
     if (status === 404)
         return "ourpr has no such run. Check the id against ourpr_list_runs.";
     if (status === 422)
@@ -115,33 +75,27 @@ function guidance(status, detail, retryAfterS) {
         return "ourpr had an error. Try again in a moment.";
     return detail || `ourpr answered ${status}.`;
 }
-/**
- * One line per call, on stderr.
- *
- * The 2026 guidance asks a server to log tool invocations, downstream calls,
- * errors and denials, so an operator can see what an agent did on their
- * behalf. THE PATH IS LOGGED AND THE TOKEN NEVER IS — a log that carries the
- * credential is a second copy of it, in a file nobody is guarding.
- */
+// The path is logged and the token never is.
 function audit(path, outcome, ms) {
     console.error(`[ourpr-mcp-server] ${outcome} ${path.split("?")[0]} ${ms}ms`);
 }
-export async function get(path) {
+async function request(method, path, payload) {
     const started = Date.now();
     if (!TOKEN) {
-        throw new ApiError("OURPR_TOKEN is not set. Create a token in ourpr under Settings, " +
-            "Access tokens, then put it in this server's environment.");
+        throw new ApiError("OURPR_TOKEN is not set. Create a token in ourpr under Profile, " +
+            "Settings, ourpr. mcp, then put it in this server's environment.");
     }
     let response;
     try {
         response = await fetch(`${BASE}${path}`, {
-            headers: { Authorization: `Bearer ${TOKEN}` },
+            method,
+            headers: {
+                Authorization: `Bearer ${TOKEN}`,
+                ...(payload === undefined ? {} : { "Content-Type": "application/json" }),
+            },
+            body: payload === undefined ? undefined : JSON.stringify(payload),
             signal: AbortSignal.timeout(60_000),
-            // DO NOT FOLLOW REDIRECTS WITH A CREDENTIAL ATTACHED. Node strips the
-            // Authorization header across origins, so this is belt rather than
-            // braces — but a redirect from ourpr's own host is not something this
-            // server should follow silently either, because the answer would then
-            // come from somewhere the operator did not configure.
+            // A request that carries the token never follows a redirect.
             redirect: "manual",
         });
     }
@@ -149,10 +103,7 @@ export async function get(path) {
         throw new ApiError(`Could not reach ourpr at ${safeOrigin()} (${reason(err)}). Check ` +
             "OURPR_API_URL and the network.");
     }
-    // OUTSIDE THE TRY, deliberately. Thrown inside it, this was caught by the
-    // network handler two lines up and re-reported as "could not reach ourpr" —
-    // an error that names the wrong cause is worse than the status code it
-    // replaced.
+    // Outside the try, so a redirect is not reported as a network failure.
     if (response.status >= 300 && response.status < 400) {
         audit(path, `${response.status}-redirect`, Date.now() - started);
         throw new ApiError("ourpr redirected the request, and this server does not follow " +
@@ -162,13 +113,11 @@ export async function get(path) {
     if (!response.ok) {
         let detail = "";
         try {
-            // CLEANED LIKE ANY OTHER REMOTE TEXT. Today `detail` is written by the
-            // backend, but a future backend change could derive it from runner
-            // text, and this is the one place it enters an error message.
+            // detail is remote text and is cleaned like any other.
             detail = cell((await response.json()).detail, 200);
         }
         catch {
-            // A non-JSON error body. The status still carries the meaning.
+            // The status carries the meaning without a body.
         }
         audit(path, `${response.status}`, Date.now() - started);
         throw new ApiError(guidance(response.status, detail, response.headers.get("retry-after") ?? undefined));
@@ -178,9 +127,7 @@ export async function get(path) {
         body = (await response.json());
     }
     catch {
-        // A 200 whose body is not JSON - a proxy page, a captive portal. The
-        // parse error's message can carry a fragment of that body, so the error
-        // is replaced rather than passed on.
+        // A non-JSON body can leak into the parse error, so the error is replaced.
         audit(path, "200-not-json", Date.now() - started);
         throw new ApiError(`ourpr at ${safeOrigin()} answered 200 with a body that is not JSON. ` +
             "Check OURPR_API_URL - it should be the API base, ending in /api.");
@@ -188,19 +135,11 @@ export async function get(path) {
     audit(path, "200", Date.now() - started);
     return body;
 }
-// ─── Units ──────────────────────────────────────────────────────────────────
-//
-// The API speaks metres and stores pace as a string, "7:43". An agent reads
-// miles and reasons about pace as text. Convert once, here, so no tool does it
-// twice and no two tools do it differently.
-/**
- * An id on its way into a URL path.
- *
- * Ids arrive from the agent, and an agent can be steered by text inside a
- * tool result. Unencoded, a crafted id could append query parameters or move
- * the request to a sibling path - fetch normalises "../" before sending.
- * Encoding makes the id one path segment and nothing more.
- */
+export const get = (path) => request("GET", path);
+/** The one write. The route it reaches needs the write scope and ourpr create. */
+export const post = (path, body) => request("POST", path, body);
+// Units: the API speaks metres and an agent reads miles. Convert once, here.
+/** Encoded, so a crafted id stays one path segment. */
 export const pathId = (value) => encodeURIComponent(value);
 export const METERS_PER_MILE = 1609.344;
 export const miles = (meters) => meters == null ? null : Math.round((meters / METERS_PER_MILE) * 100) / 100;
@@ -213,16 +152,41 @@ export function duration(seconds) {
     const m = Math.round((seconds % 3600) / 60);
     return h ? `${h}h ${m}m` : `${m}m`;
 }
+/** "3:05:12" or "21:40". A race result reads to the second. */
+export function clock(seconds) {
+    if (!seconds)
+        return null;
+    const whole = Math.round(seconds);
+    const h = Math.floor(whole / 3600);
+    const m = Math.floor((whole % 3600) / 60);
+    const s = String(whole % 60).padStart(2, "0");
+    return h ? `${h}:${String(m).padStart(2, "0")}:${s}` : `${m}:${s}`;
+}
 /** A day key, YYYY-MM-DD, out of whatever the API stored. */
 export const day = (iso) => (iso ?? "").slice(0, 10);
-/**
- * A calendar date to the Unix second the API wants.
- *
- * TOOLS TAKE DATES AND THE API TAKES TIMESTAMPS. An agent is asked "what did I
- * run in July", not "what did I run between 1751328000 and 1754006400", and
- * making it do that arithmetic is a step where it can quietly be wrong.
- * `end` pushes to the end of the day so a single-day window holds that day.
- */
+/** Today on this machine's calendar, which is the runner's own. */
+export function localDay(now) {
+    const m = String(now.getMonth() + 1).padStart(2, "0");
+    const d = String(now.getDate()).padStart(2, "0");
+    return `${now.getFullYear()}-${m}-${d}`;
+}
+// Day keys are walked as UTC dates, so a clock change never moves a day.
+const DAY_MS = 86_400_000;
+const dayMs = (key) => Date.parse(`${key}T00:00:00Z`);
+export function addDays(key, days) {
+    const ms = dayMs(key);
+    if (Number.isNaN(ms))
+        throw new ApiError(`"${key}" is not a date. Use YYYY-MM-DD.`);
+    return new Date(ms + days * DAY_MS).toISOString().slice(0, 10);
+}
+/** Which week of a Block `today` falls in, or 0 before week 1's Monday. */
+export function weekOf(start, weeks, today) {
+    const walked = Math.floor((dayMs(today) - dayMs(start)) / DAY_MS);
+    if (Number.isNaN(walked) || walked < 0)
+        return 0;
+    return Math.min(weeks, Math.floor(walked / 7) + 1);
+}
+/** A calendar date to a Unix second; "end" reaches the end of the day. */
 export function stamp(date, edge) {
     const time = edge === "start" ? "T00:00:00Z" : "T23:59:59Z";
     const ms = Date.parse(`${date}${time}`);