AimYear

AimYear MCP server

すでにお使いの AI エージェントの中で、目標達成をサポートします。 AimYear を Claude、Claude Code、ChatGPT、または任意の MCP クライアントに接続すると、エージェントが 1 年を通じて達成したい大きな目標を 1 つ管理し、その達成に向けて毎日 1 つの主要なステップを 計画し、作業中はタイマーを動かして、実際に完了した内容を記録します。主要なステップが 未完了のまま、気軽に取り組める作業を始めようとすると、先にステップを実行するよう促します。

一日中ものづくりをしていても、目標達成につながる作業、つまり販売、ユーザーとの対話、 公開をつい後回しにしてしまうインディー開発者やクリエイター向けに作られています。

• 無料： お使いのエージェントを通じて、デバイス数の制限なくサインインでき、目標、計画、 ルーティン、時間の記録、振り返りを利用できます。AimYear 側では AI を実行しないため、 AI の利用料金はかかりません。
• Pro（年額 $49 または月額 $8。近日公開予定のスマートフォンアプリを含む）：通知、 AimYear が作成する振り返り、AimYear 独自の AI コーチ、Google Calendar との同期。

ウェブサイト：aimyear.com · 設定ガイド：aimyear.com/connect.html · プライバシー：aimyear.com/privacy.html · お問い合わせ：[email protected]

接続（約 1 分）

エンドポイント：https://mcp.aimyear.com/mcp（Streamable HTTP、Google、Apple、またはメールで OAuth サインイン）。インストールは不要です。

• Claude（ウェブ、デスクトップ、モバイル）： 設定 → コネクタ → カスタムコネクタを追加 → エンドポイントを貼り付け → 接続し、サインインします。
• Claude Code： claude mcp add --transport http aimyear https://mcp.aimyear.com/mcp を実行し、 /mcp → aimyear → 認証します。
• ChatGPT（有料プラン、開発者モード）：設定 → アプリとコネクタ → 詳細設定 → 開発者モードをオンにします。次に、アプリとコネクタ → 作成を選択し、名前に AimYear、 URL に上記のエンドポイントを入力して、認証で OAuth を選び、作成してからサインインします。
• その他の MCP クライアント： エンドポイントを OAuth 対応のリモート（HTTP）サーバーとして追加します。

続けて、次のように伝えてください：「今年の目標を設定するのを手伝って」。エージェントは目標を 数えられる形にできているか確認し、段階的な道筋を作ります。その後は、「今日の計画を立てて」、 「タイマーを開始して」、「今週はどうだった？」 と伝えてください。

エージェントにこの方法を教えるスキルは、skills/aim/SKILL.md にあります。

データの取り扱い

サーバーは、エージェントがツールを通じて保存した内容（目標、道筋、計画、セッション、 それらの要約）を Google Cloud Firestore に保存します。会話はエージェントのプロバイダー側に 保存され、AimYear が受け取るのはツール呼び出しのみです。ログに保存されるのはツール名、 成功したかどうか、所要時間のみで、引数の値は保存されません。アカウントとデータを削除するには、 [email protected] までメールでご連絡ください。詳細：プライバシーポリシー。

ツール（43）

名前を見ればツールの機能がわかります。get_ は1つの項目を読み取り、list_ は複数の項目を読み取り、find_ は問題を探し、set_ はリスト全体を置き換え、add_ ／ edit_ ／ delete_ は1つの項目を変更します。

グループ	ツール
目標	get_goal, check_goal_draft, set_goal, record_progress, set_levers, set_projects
道筋	get_path, set_milestones, edit_milestone, add_steps, edit_step, delete_step, next_steps
週	get_commitments, set_commitments, get_capacity
日	get_planning_context, get_plan, set_plan, edit_plan_item, delete_plan_item, set_day_mode, get_routines, set_routines
タイマーとセッション	get_now, start_session, add_note, split_attention, stop_session, stop_timer, add_session, edit_session, delete_session, list_sessions, find_gaps
振り返り	summarize_day, summarize_week, find_leaks
設定とデバイス	get_settings, set_settings, add_device, list_devices, delete_device

0.4.2では、難しいことを優先するチェックを追加しました。set_plan は、その日に難しいレバーに関する項目がない場合に警告し、add_steps ／ set_levers は、ステージの最初の難しいレバーのステップより前に準備を始める場合に警告します。サーバーの指示により、すべてのエージェントに同じルールが適用されます。

0.4.0では、ルーティンを追加しました。固定された曜日に繰り返す小さなステップです（「Redditで1人と話す」など）。サーバーが該当する各日の計画に追加するため、すべてのデバイスとエージェントで同じチェックを確認できます。get_now には未完了のルーティンが表示され、summarize_week ではその数が集計されます。

0.3.0では、ほとんどのツール名を変更し（0.2.xの名前は使えなくなりました）、編集ツールを追加しました。完了済みのセッション用のedit_session、delete_session、edit_milestone、delete_step、edit_plan_item、delete_plan_item、set_projects、およびタイムゾーンを扱うget_settings ／ set_settingsです。

プロトコルの詳細

ステートレスなStreamable HTTPで、POSTのみです。サインインにはPKCEと動的クライアント登録を使用するOAuth 2.1を使います。サインインページはAimYearアプリと同じFirebaseプロジェクトを使用するため、アプリと接続済みのすべてのAIで、1つのアカウントと履歴を共有します。ゲスト（匿名）アカウントは接続できません。各ツールは、サインインしている1人のユーザーとして動作します。docs/ACCESS.mdをご覧ください。

トークンがない場合、サーバーは自身の情報（initialize、tools/list、prompts/list、ping）を返します。それ以外のすべてのリクエストには、/.well-known/oauth-protected-resource/mcpを示すWWW-Authenticateヘッダーとともに401を返します。

アプリ向けの再試行に安全な書き込み（0.7）

サーバーが信頼できる唯一の情報源です。スマートフォンからは、タップ後かなり時間が経ってから、あるいは同じリクエストが2回届く場合があります。そのため、stop_session、start_session、add_session、add_note、add_steps、delete_session では、省略可能な op_id を受け取ります。これはアプリが初回の試行前に生成し、再試行のたびに再利用する ID です。書き込みは1回だけ適用され、再試行には最初の応答が返され、書き込みは行われません。適用済みの操作は users/{uid}/ops/{op_id}（tool、sessionId、result、at、expiresAt）に保存され、記録対象の変更と同じ Firestore トランザクションで書き込まれます。Firestore コンソールで、ops コレクションに expiresAt（30日）の TTL ポリシーを設定してください。

stop_session は end_at を、start_session は start_at（ISO 8601）を受け取ります。これにより、14:05にオフラインのキューへ追加され、16:40に届いた停止リクエストも、14:05の記録として扱われます。start_session はアプリ側で用意した session_id（存在しない場合にのみ作成）も受け取ります。op_id、end_at、または start_at を指定するリクエストでは、必ず session_id も指定してください。サーバーが再送リクエストの対象セッションを推測することはありません。これらを指定せず、エージェントが stop_session／delete_session を実行した場合は、そのエージェントの接続に紐づく実行中のセッションが1つだけあれば、そのセッションだけが対象になります。それ以外の場合は、実行中のセッションを ID とともに一覧表示します。

2台のデバイスから1つのセッションを停止できます。停止リクエストの到着順にかかわらず、結果は同じです。最も早い終了時刻が優先され（誰かが停止した時点で実行中ではなくなります）、他の結果より done が優先されます。最初の要約はそのまま保持され、後から届いた別の要約はメモに追加されます。すべての停止はセッションの stops[] に保存され、応答には applied: ended | shortened | recorded と示されます。

---

このファイルの残りは、サーバー自体を扱う人向けです。AimYear を使うだけなら必要ありません。

構成

ファイル	内容
src/http.ts	Express アプリです。MCP エンドポイント、OAuth ルート、メニューバーのエンドポイントを提供します。
src/access.ts	すべての MCP メソッド、ツール、ルートを、理由とともに public／auth／admin に分類したテーブルです。すべてのアクセス制御でこれを参照します。
src/oauth.ts	Firestore における OAuth ストレージ（コードとトークンは SHA-256 ハッシュとして保存）と、サインイン／同意ページです。プロトコル自体は MCP SDK の mcpAuthRouter を使います。
src/calllog.ts	MCP 呼び出しごとに1行の構造化ログを記録します。メソッド、ツール、成功の有無、エラーコード、レイテンシ、ユーザー、クライアントが含まれます。引数の値は記録しません。
src/tools.ts	ツールの登録、注釈（読み取り専用／破壊的／冪等）、サーバーへの指示です。
src/service.ts、src/domain/	ルールです。目標の評価基準、分類、注意、プラン、セッションを扱います。
src/surface.ts	surface.lock.json の基になるサーフェスフィンガープリントです。
.githooks/pre-commit	src/access.ts から docs/ACCESS.md を再生成し、コミットのたびにステージします。これにより、コミットされるテーブルがずれることを防ぎます（npm ci は prepare スクリプトを通じて core.hooksPath をここに設定します。古いファイルが残っている場合は test/access.test.ts でも引き続き失敗します）。

データは Firestore の users/{uid}/aim/{goal,path,profile}、users/{uid}/days、 users/{uid}/sessions、users/{uid}/blocks、users/{uid}/ops（適用済みの op_id。expiresAt に TTL を設定）に保存されます。OAuth データは oauth_clients、oauth_requests、oauth_codes、oauth_tokens に保存されます。リマインダーは pending_notifications に保存され、プッシュの前にトランザクションによる削除で取得済みにします。

ローカルで実行する

npm install && npm run build
# stdio, one person:
claude mcp add --scope user aimyear -e AIMYEAR_UID=<firebase uid> -- node $PWD/dist/index.js
# HTTP:
AIMYEAR_TOKENS="sometoken=<uid>" PORT=8787 node dist/index.js --http

認証情報：Firebase 管理者サービスアカウントを ~/.aimyear/service-account.json に配置してください（または AIMYEAR_SERVICE_ACCOUNT=<path> を指定します。どちらもない場合は Application Default Credentials を使います）。

環境変数：AIMYEAR_UID（stdio）、AIMYEAR_TOKENS（HTTP。Claude Code スクリプト、メニューバーアプリ、スケジューラー向けの静的な token=uid ペア）、AIMYEAR_BASE_URL（公開 URL。OAuth 発行者）、AIMYEAR_ALLOWED_ORIGINS（追加のブラウザーオリジン）、AIMYEAR_WORKPLACE、AIMYEAR_TZ。

テスト

npm test                  # access table guard, anonymous gate and batch smuggling, OAuth discovery,
                          # annotations, Origin, version negotiation, surface lock, domain rules
npm run test:conformance  # a client's path through the real HTTP entry point: initialize and
                          # tools/list without a token, then every tool with a throwaway user
                          # in the real Firestore; cleans up
CONFORMANCE_URL=https://mcp.aimyear.com/mcp npm run test:conformance   # read-only tools, live
npm run test:oauth        # register → consent → real Firebase ID token → code → token (PKCE) →
                          # tool call → refresh rotation, plus every refusal; cleans up
npx tsx test/smoke.ts     # the service end to end against Firestore

ツールを追加する場合は、src/access.ts にエントリを追加してください（追加しないと npm test が失敗します）。npm run access-doc を実行し、src/version.ts のバージョンを上げてから、npm run surface-lock を実行してください。

ホステッド（Cloud Run）

gcloud run deploy aimyear-mcp --source . --project aimyear-app --region us-central1 --quiet

サービスの環境変数：AIMYEAR_TOKENS、AIMYEAR_TZ、AIMYEAR_PROJECT、 AIMYEAR_BASE_URL=https://mcp.aimyear.com。mcp.aimyear.com は Cloud Run のドメインマッピング （Route 53 で ghs.googlehosted.com を参照する CNAME）で、Firebase Auth の承認済みドメインに含まれています。 ヘルスチェック：/health。旧 URL https://<service>/c/<token>/mcp も引き続き利用できます。

呼び出し分析：scripts/mcp-calls.sh [1d] を実行すると、ツールごとの呼び出し数と、 ユーザーおよびクライアントごとの呼び出しシーケンスが表示されます。

ライセンス

FSL-1.1-MIT：このサーバーの閲覧、実行、セルフホスト、変更はできますが、競合する商用サービスとして提供することはできません。各リリースは公開から2年後に MIT ライセンスになります。ホステッドサービスは https://mcp.aimyear.com/mcp にあります。