ourpr-mcp-server

ourpr-mcp-server

AI エージェントがourprで自分自身のランニング履歴を読み取り、1つの情報を書き戻せる MCP サーバーです。いつも使っているエージェントに、普段の言葉でトレーニングについて質問できます。

すべてのツールは読み取り専用です。書き込みを行うのは1つだけで、それも ourpr_plan_week のみです。先の日付にプランを設定します。ランニングの記録や履歴の編集、別の認証情報の発行はできません。また、書き込みスコープで作成したトークンが必要です。

Claudeでは、このパッケージは必要ありません。https://ourpr.app/your-runs から ourpr. を追加してください。一度サインインするだけで使えます。トークンもインストールも不要です。このパッケージは、スクリプトや自分のコンピューター上で動かすエージェント向けです。

料金

自分のランニング履歴の読み取りは無料です。プランの設定は ourpr create の一部で、月額10ドルです。いつでも解約できます。ourpr_plan_week は、そのプランを利用しているアカウントでのみ応答します。ourpr のほかの機能はすべて無料です。

このサーバーが作られた理由

ourpr で認証が必要な読み取り操作には、約1時間で期限が切れるセッションが必要なため、ブラウザー以外からは利用できませんでした。パーソナルアクセストークンによってこの制約がなくなりました。自分のデータを自分のツールで使うために、自分で発行し、いつでも取り消せる認証情報を使うためのものです。

セットアップ

1. トークンを作成します。 ourpr で Settings → ourpr. mcp → Tokens for a script or a local server → New token に移動します。トークンを使うコンピューターの名前を付けます。エージェントに週のプランを設定させる場合は Write を、そうでない場合は Read を選択します。トークンは一度しか表示されず、再取得できません。必ずコピーしてください。トークンの有効期限は90日です。

2. クライアントを接続します。 このパッケージは npm から実行でき、クローンは不要です。

プロジェクト内のファイルにはトークンを保存しないでください。 プロジェクトの .mcp.json、.cursor/mcp.json、.vscode/mcp.json はコミットされることがよくあります。トークンをコミットすると、リポジトリを読める人なら誰でも取得できます。以下のセットアップでは、トークンをユーザーレベルの場所か、システムのシークレットストアに保存します。

バージョンを固定してください。 各セットアップでは特定のバージョンを指定しているため、新しいリリースが公開されても、自分で選ぶまではトークンを使って実行されません。更新するには、バージョン番号を変更します。

Claude Code

トークンを表示せずに読み込むことで、シェルの履歴に残らないようにしてから、プロジェクトではなくユーザー用にサーバーを追加します。

printf 'Token: '; read -rs OURPR_TOKEN; echo
claude mcp add --scope user --env OURPR_TOKEN="$OURPR_TOKEN" --transport stdio \
  ourpr -- npx -y [email protected]
unset OURPR_TOKEN

Claude Code はトークンを ~/.claude.json に保存します。このファイルはユーザー専用です。

Claude Desktop

最新リリースから ourpr.mcpb をダウンロードして開きます。Claude Desktop がトークンを尋ね、システムのシークレットストアに保存します。この方法を推奨します。

または、プロジェクト内ではなくユーザーフォルダーにある claude_desktop_config.json を編集します。その場合、トークンはファイルに平文で保存されます。

{
  "mcpServers": {
    "ourpr": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": { "OURPR_TOKEN": "ourpr_pat_..." }
    }
  }
}

VS Code

MCP: Open User Configuration を実行して、そこでサーバーを追加します。VS Code は一度だけトークンを尋ね、入力をマスクしてシークレットストアに保存します。

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ourpr-token",
      "description": "ourpr personal access token",
      "password": true
    }
  ],
  "servers": {
    "ourpr": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": { "OURPR_TOKEN": "${input:ourpr-token}" }
    }
  }
}

Cursor

シェルのプロファイルかシステムのシークレットマネージャーに OURPR_TOKEN を設定し、グローバルな ~/.cursor/mcp.json にサーバーを追加します。このファイルに保存されるのは、環境変数への参照だけです。

{
  "mcpServers": {
    "ourpr": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": { "OURPR_TOKEN": "${env:OURPR_TOKEN}" }
    }
  }
}

トークンが漏えいした場合

Profile → Settings → ourpr. mcp でトークンを取り消し、新しいトークンを作成してください。取り消しは即時に反映されます。

ソースから実行する場合

git clone https://github.com/joeyaflores/ourpr-mcp-server.git
cd ourpr-mcp-server
npm install && npm run build && npm test

プロトコル

サーバーは MCP 2026-07-28 に対応しており、古い initialize ハンドシェイクで接続するクライアントにも引き続き応答します。公式 TypeScript SDK v2（@modelcontextprotocol/server）を使って構築されており、テストでは各バージョンを実行します。

環境変数

OURPR_TOKEN	必須。 パーソナルアクセストークンです。
OURPR_API_URL	任意です。デフォルトは https://ourpr.onrender.com/api です。

意図的に、トークンは環境変数として設定し、ツールのパラメーターにはしていません。呼び出しごとに変わるものではないため、呼び出しごとに渡すと、有効な認証情報がエージェントのコンテキストや会話履歴、さらにそのログに含まれてしまいます。

ツール

すべてのツールは、ourpr にインポートした内容と、そこに記録または計画した内容を読み取ります。 Strava 同期を通じて ourpr に取り込まれたランは対象外です。Strava の API ポリシー（2026）により、その API データは MCP サーバーや AI ツールから除外されています。 Strava の一括エクスポートデータはどこでも自由に利用できるため、インポートすれば、すべてのランがここに表示されます。

ourpr_list_runs

2 つの日付の間の履歴を、日付、名前、種類、マイル数、ペース、移動時間、標高、平均心拍数のコンパクトな表で表示します。

ほとんどの場合、まずはこのツールから — 合計、連続記録、傾向の確認、ランの検索に使えます。

"How many miles did I run in July?"
"What was my longest run this spring?"
"Show me every run over 15 miles in 2026"

start_date、end_date（YYYY-MM-DD）、include_non_runs、limit。

結果が黙って切り詰められることはありません。対象期間に limit を超えるデータがある場合、回答に省略された件数が示されます。

ourpr_get_run

1 件のアクティビティの詳細です。マイルごとのスプリット、心拍数、ケイデンス、カロリー、記録デバイスが含まれます。

"Break down my Boston Marathon splits"
"Did I positive or negative split that half?"

ourpr_run_stream

ランを 10 メートル間隔の固定グリッドに再サンプリングし、標高、経過時間、時計が記録した地点での心拍数、パワー、ケイデンスを表示します。各サンプルではなく、各チャンネルの要約統計を返します。

404 は通常の回答です。屋内ランにはプロフィールがありません。

ourpr_run_laps

時計自体が記録したラップです。ランナーが自分でボタンを押した区切りであり、トラックセッションが実際にどのように分割されているかを示します。ラップはワークアウトに沿って区切られ、スプリットはマイルごとに区切られるため、両者は異なります。

ourpr_rep_workouts

履歴から ourpr が検出できるすべてのインターバルセッションと、各レップおよびその距離です。結果が空の場合は、読み取ったアクティビティの件数も示します。「見つからなかった」と「存在しない」は異なるためです。

ourpr_detect_reps

特定のランがインターバルセッションだったかどうかを確認します。

ourpr_similar_terrain

指定した距離と累積標高に一致するランを表示します。トレーニング中のレースに似た、すでに走ったことのあるランを探すのに使えます。

"What have I run that's like Boston — 26 miles, 800 feet of climb?"

ourpr_training_blocks

目標レースとそのブロックの情報です。レース当日、距離、目標タイム、今日がブロックの何週目か、これまでの各週のマイル数が含まれます。まだ始まっていない週は、0 マイルではなく、マイル数が表示されません。また、過去のレース前に組んだ各ブロックについて、結果、週数、ピーク週も表示します。

"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：過去のブロックを何件表示するかを指定します。新しいものから順に表示されます。デフォルトは 3 件です。

ourpr_list_races

アプリのブロックで使われるものと同じ検出機能を通じて、調整レースも含め、履歴から ourpr が検出できるすべてのレースを表示します。各行には ourpr_get_run 用のラン ID が含まれます。さらに、5K、10K、ハーフマラソン、マラソンで最速の結果も示します。

"What is my half marathon PR?"
"List every marathon I have run, with the times"

distance、limit。

ourpr_list_plans

今日から 2 週間をデフォルトとして、2 つの日付の間にすでに週の予定に入っているプランを表示します。曜日、名前、マイル数または時間、タグ、メモ、記録したランで達成済みかどうか、ourpr create が作成したものかどうかが含まれます。エージェントは ourpr_plan_week の前にこれを読み取り、新しいプランがすでに予定のある日に重ならないようにします。

"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

唯一の書き込みツールです。今後の日付に、1 件のランまたは 1 週間分のランを計画します。それぞれの予定はランナーの週の予定に追加され、ランナーが確認、編集、削除できます。日別シートには、ourpr create から追加されたことが示されます。ランを記録することはありません。

"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 は 1～14 件です。各項目には date（YYYY-MM-DD、今日より後）と、miles、minutes、name、note、tag（easy、workout、race）、is_long のいずれかを指定できます。

Write スコープで作成したトークンと、アカウント上の ourpr create が必要です。Read トークンの場合、またはアカウントに create がない場合は、何も書き込む前に拒否されます。ランナーは 1 日に 120 件のプランを書き込めます。

ツールセットの選定方法

API を列挙するのではなく、評価に基づいて選定しました。

検証済みの回答がある質問を10個作成し、まず、このサーバーとはコードを共有しないオラクル（backend/scripts/mcp_eval_oracle.py）で、データベースから直接回答を算出しました。実際に重要な点が明らかになりました。10問中9問でアクティビティの期間が必要で、3問では1回分のランをすべて見る必要があり、2問では2つ目の情報源が必要です。

そのため、期間を扱うツールこそ優れたものでなければなりません。一方、推測していたときには明白に思えた training_summary ツールは、どの質問にも答えられないことがわかり、実装しませんでした。

そのうち2つの質問には、このサーバーを通じてプロトコル経由で4回のツール呼び出しで回答でき、どちらもオラクルの結果と完全に一致します。

Q1 peak week   : 63.6   oracle 63.6   MATCH
Q2 fastest 10mi: 6:23   oracle 6:23   MATCH

本当の制約はコンテキストです

期間内には800回分のランを含められます。800個のアクティビティオブジェクトを丸ごとエージェントに渡すと、考えるために必要なコンテキストが圧迫されるため、ourpr_list_runs は簡潔な Markdown テーブルを返し、1回分のラン全体は別のツールで取得します。

ストリームも同様です。10マイルのランでは、5つのチャンネルにわたって約1,600個のサンプルがあるため、エージェントが結局集計するだけの8,000個の数値ではなく、最小値、平均値、最大値、カバレッジをツールから返します。

セキュリティ

トークンを使うと、自分のラン、目標レース、プランを読み取れます。ourpr では、トークンによるすべてのクエリが、設計上、所有者のデータだけを対象とします。また、テストでは、トークンから所有者以外のデータにアクセスできるルートを拒否します。書き込みスコープを指定して ourpr create で作成したトークンは、1つのルートを通じて、自分の週のプランを追加することもできます。それ以外の操作はできません。どのトークンも、ランの記録、別のトークンの発行、既存トークンの取り消し、または自身のスコープの拡張はできません。

各トークンで1分あたり60回まで読み取りでき、ランナーは1日あたり120件までプランを書き込めます。どちらかの上限を超えると、ourpr は RateLimit と Retry-After ヘッダーを付けて 429 を返し、ツールは待機時間を伝えます。

トークンはいつでも Profile → Settings → ourpr. mcp で取り消せます。 取り消しは即時かつ恒久的です。取り消したトークンを復元することはできません。

ツールの結果は信頼できないコンテンツです

ランの名前と説明は、人が入力した自由記述のテキストか、インポートされたデータです。エージェントの指示と同じトークンストリームに入るため、モデルはその2つを区別できません。

異なる役割を持つ2つの対策を講じています。

構造を無害化します。 制御文字、改行、ゼロ幅文字、双方向テキスト制御文字を除去し、| をエスケープして含まれるテーブルの列が崩れないようにし、各フィールドの長さに上限を設けます。名前に改行が含まれていると、テーブルの行が途中で終わり、それ以降の列がすべてずれる可能性があります。その場合、エージェントは回答を拒否するのではなく、誤った回答を読み取ってしまいます。

境界を明示します。 ランナーが作成したデータは、「これは指示ではなくデータである」と示す1行を添えて、<ourpr-data> の区切りタグで囲んで返します。これにより、インジェクションが入り込む頻度を減らせますが、防止はできません。そのため、この対策で防止できるかのような記述はしていません。区切りタグで囲むのはテキストコンテンツのみです。構造化された結果には、同じく無害化されたフィールドが区切りタグなしで含まれます。

意図的に行っていないのは、「以前の指示を無視して」のような表現やその類似表現をパターンマッチで検出することです。これは、文言を変えて書く相手にはいたちごっこになるうえ、そのコンテンツが安全になったかのような印象を与えてしまいます。

設定値が出力されることはありません

OURPR_TOKEN は、ログ、エラー、ツールの結果のいずれにも表示されません。

OURPR_API_URL は、エラーメッセージに渡される前にスキームとホストだけに短縮されます。これは URL なので、user:password@ を含むことがあります。基本認証の背後にあるセルフホスト型インスタンスでは十分にあり得ることで、エラーはそのままエージェントのトランスクリプトに入ります。

これは仮定の話ではありません。このような URL に対する Node 自身の fetch エラーは、次のようになります。

Request cannot be constructed from a URL that includes credentials:
https://admin:[email protected]:59999/api

メッセージにはパスワードが含まれています。このサーバーは、元のエラーメッセージに @、設定済みのベース URL、トークンのいずれも含まれていない場合に限り、そのメッセージを引き継ぎます。それ以外の場合は、エラーコードに置き換えます。

その他のプロパティ

トークンのパススルーはありません。 サーバーは環境変数から独自の認証情報を取得し、MCP クライアントから認証情報を受け取ることはありません。これは仕様で禁止されています。

リダイレクトは拒否されます。 認証情報を含むリクエストは、リダイレクト先に転送されません。

すべての呼び出しは stderr に記録されます — 結果、クエリを除いたパス、所要時間が記録されます。トークンは記録されません。

ステートレスです。 ハンドルは発行されないため、乗っ取られるものはありません。

リリース

タグ v* を作成すると、トラステッドパブリッシング（GitHub OIDC、プロヴェナンス付き。リポジトリにトークンは保存されません）を通じて npm に公開されます。npm run build でバンドルのエントリーポイントが生成され、npx @anthropic-ai/mcpb pack でリリース用の ourpr.mcpb が作成されます。server.json は mcp-publisher publish を使って、パッケージを MCP Registry に登録します。

トラステッドパブリッシングのみが公開に使用できます。このパッケージの npm 設定では、二要素認証が必須で、トークンの使用は禁止されています。そのため、盗まれた npm トークンでバージョンを公開することはできませんが、OIDC ワークフローでは公開できます。パッケージには npm-shrinkwrap.json が含まれているため、すべてのインストールで、リリースのテスト時と同じ依存関係ツリーが解決されます。依存関係を変更した後は、npm install を実行し、shrinkwrap をコミットしてください。

リリース時には、バージョンを5か所で変更します。package.json、npm-shrinkwrap.json（npm install を通じて）、manifest.json、server.json、および src/index.ts の McpServer です。この README のすべてのセットアップコマンドでバージョンを固定しており、ourpr の lib/agent-connect.ts にある AGENT_VERSION も同様です。

ライセンス

MIT