mmm-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noriaki Horie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,346 @@
+# mmm-mcp-server
+
+Matryoshka Mind Map（マトリョシカ、マインドマップ／TODOアプリ）の自分のマップを、
+AIエージェントとの会話から直接読み書きできるようにするツールです。MCP
+（Model Context Protocol）という共通規格に対応したツールなので、Claude
+Desktop・Claude Codeに限らず、MCPに対応したAIエージェントであれば基本的に
+同じ手順で使えます（**動作確認はClaude Desktop / Claude Codeで実施**しています。
+他のクライアントでの登録方法はそれぞれのドキュメントを参照してください）。
+
+- 「今のマップ一覧を見せて」と話しかけるとマップ一覧を教えてくれる
+- 会話の中で考えた内容を、そのままマインドマップの階層構造として追加できる
+- 「〇〇のタスク終わったよ」と伝えるだけでTODOにチェックが付く
+- 長いメモやMarkdownをそのままマップに流し込める
+
+パソコンの中だけで動くツールで、常時起動しているサーバーはありません。使うときだけ
+起動し、あなた自身のログイン情報であなた自身のマップにアクセスします（開発者側は
+あなたのデータを見ることができません）。
+
+> **2026年9月30日より前にダウンロードした方へ**: アプリ側のデータ形式の切り替えに
+> 伴い、古い版ではマップへの書き込みが失敗するようになります。`mmm_mcp` フォルダで
+> `git pull && npm run build` を実行し、AIエージェントを再起動してください。
+
+> このページは、ある程度パソコン操作に慣れていない方でも迷わず進められるよう、
+> ターミナル（コマンドを打つ画面）の開き方から順に説明しています。
+>
+> **対応OS**: macOS・Windowsの両方で動作するはずです。Node.jsとgitだけで
+> 動くツールで、OS固有の機能には依存していません。ただし**実機での動作
+> 確認はmacOSでのみ行っています。** Windowsで試して気づいた点があれば、
+> このリポジトリのIssueで教えてください。手順のうち、操作方法がOSで
+> 異なる箇所（ターミナルの開き方・Node.jsのインストール）はmacOS/Windows
+> それぞれ記載しています。それ以外のコマンドはどちらのOSでも同じです。
+
+## 1. 事前に必要なもの
+
+- Matryoshka Mind Mapのアカウント（**匿名利用のみのアカウントは使えません。**
+  Google・Apple・メールアドレスのいずれかでログインできる状態にしてください。
+  アプリ内の「メールアドレスを連携」機能で後から連携することもできます）
+- MCPに対応したAIエージェント（Claude Desktop / Claude Codeで動作確認済み。
+  他のMCP対応クライアントでも基本的に使えるはずです）
+- Node.js（プログラムを動かすための土台。次の手順でインストールします）
+
+## 2. ターミナルを開く
+
+### macOSの場合
+
+1. キーボードで `command`キーを押しながら`スペース`キーを押す（Spotlight検索が開く）
+2. 「ターミナル」と入力する
+3. 一覧に出てきた「ターミナル」を左クリック、またはEnterキーを押す
+
+### Windowsの場合
+
+1. キーボードで `Windows`キーを押す（スタートメニューの検索が開く）
+2. 「PowerShell」と入力する
+3. 一覧に出てきた「Windows PowerShell」を左クリック、またはEnterキーを押す
+
+黒っぽい（または白い）ウィンドウが開けば準備完了です。以降の手順は、この
+ウィンドウに1行ずつコマンドを貼り付けてEnterキーを押していきます（コマンド
+自体はmacOS・Windowsで共通です）。
+
+## 3. Node.jsをインストールする
+
+すでにインストール済みか、次のコマンドで確認できます。
+
+```bash
+node --version
+```
+
+`v18` 以上のバージョン番号（例: `v20.11.0`）が表示されればインストール済みです。
+「command not found」のようなエラーが出た場合は、下記からインストーラーを
+ダウンロードしてください。
+
+https://nodejs.org/
+
+サイトを開くと大きなボタンが2つ出ます。**「LTS」と書かれている方**を左クリックして
+ダウンロードしてください（使っているOSに合わせて、macOSなら`.pkg`、Windowsなら
+`.msi`のインストーラーが自動でダウンロードされます）。ダウンロードしたファイルを
+ダブルクリックし、画面の指示に従って進めてください
+（macOSは「続ける」→「同意する」→「インストール」、Windowsは
+「Next」→「I accept...」→「Install」のように、案内される通りに次へ進めば
+インストールできます）。
+
+インストールが終わったら、ターミナルに戻ってもう一度確認します。
+
+```bash
+node --version
+```
+
+## 4. mmm-mcp-serverをダウンロードする
+
+```bash
+git clone https://github.com/nhorie-canal/mmm_mcp.git
+```
+
+コマンドの実行が終わったら、作られたフォルダに移動します。
+
+```bash
+cd mmm_mcp
+```
+
+## 5. セットアップする
+
+必要な部品を取り込みます（少し時間がかかります）。
+
+```bash
+npm install
+```
+
+続けて、使える状態にビルドします。
+
+```bash
+npm run build
+```
+
+## 6. ログインする
+
+Matryoshka Mind Mapアプリで普段どのログイン方法を使っているかに合わせて、
+次の3つから選んでください。**いずれの方法も、あなた自身が事前に何かを準備する
+必要はありません。**
+
+### Googleでログインしている場合
+
+```bash
+node dist/bin/login.js login --method google
+```
+
+ブラウザが自動で開くので、いつも使っているGoogleアカウントでログインします。
+
+### Appleでログインしている場合
+
+```bash
+node dist/bin/login.js login --method apple
+```
+
+こちらもブラウザが自動で開くので、Apple IDでログインします。
+
+### メールアドレスとパスワードでログインしている場合
+
+```bash
+node dist/bin/login.js login --method email
+```
+
+メールアドレスとパスワードを聞かれるので入力してください（パスワードは
+画面に表示されません）。
+
+> **「パスワードが違います」というエラーが出た場合**、実際にパスワードを
+> 間違えているとは限りません。そのアカウントがアプリ内でGoogle・Appleの
+> どちらかでログインしていて、そもそもメールアドレス＋パスワードでの
+> ログイン情報を持っていない場合も同じエラーになります。心当たりが
+> あれば、上の「Googleでログインしている場合」または「Appleでログイン
+> している場合」の手順を試してください。
+
+ログインに成功すると、以後は毎回ログインし直す必要はありません（ログイン情報は
+あなたのパソコンの中だけに、あなた以外読めない形で保存されます）。
+
+```bash
+node dist/bin/login.js status
+```
+
+でログイン状態を確認できます。ログアウトしたい場合は次のコマンドです。
+
+```bash
+node dist/bin/login.js logout
+```
+
+## 7. AIエージェントにMatryoshkaを教える
+
+ここでは動作確認済みのClaude Desktop / Claude Codeへの登録方法を示します。
+他のMCP対応クライアント（例: Codexなど）を使っている場合も、多くは同じように
+「サーバーを起動するコマンド」（`node <mmm_mcpのパス>/dist/src/server.js`）を
+そのクライアントのMCPサーバー設定に登録するだけで使えるはずです。具体的な
+登録方法はお使いのクライアントのドキュメントを確認してください。
+
+このステップで、あなたが今どこのフォルダにいるかによって次のコマンドの一部が
+変わります。次のコマンドで今いる場所（絶対パス）を確認してください。
+
+```bash
+pwd
+```
+
+表示された場所（例: `/Users/あなたの名前/mmm_mcp`）を、以下の
+`<mmm_mcpのパス>`の部分に置き換えて使います。
+
+### Claude Codeを使っている場合
+
+```bash
+claude mcp add mmm -- node <mmm_mcpのパス>/dist/src/server.js
+```
+
+### Claude Desktopを使っている場合
+
+Claude Desktopの設定ファイル（`claude_desktop_config.json`）を開き、
+`mcpServers`の中に次を追記します。
+
+```json
+{
+  "mcpServers": {
+    "mmm": {
+      "command": "node",
+      "args": ["<mmm_mcpのパス>/dist/src/server.js"]
+    }
+  }
+}
+```
+
+保存したらClaude Desktopを再起動してください。
+
+## 8. 使ってみる
+
+AIエージェントとの会話で、次のように話しかけてみてください。
+
+- 「Matryoshkaのマップ一覧を見せて」
+- 「〇〇マップに、××というタスクを追加して」
+- 「〇〇マップの、△△っていうタスク終わったよ」
+- 「このメモをMarkdownで貼るので〇〇マップに取り込んで」
+
+**マップの中身（要素の文字列）を初めて読むときだけ**、実際の中身を返す前に
+必ず本人の許可を求める仕組みになっています。中身に個人的な内容が含まれる
+可能性に配慮したものです。
+
+ツールは中身を返す代わりに、「ユーザー本人に直接確認してから`confirmed: true`
+を付けて呼び直せ」という指示だけを返します。実際に確認したかどうかをこちら側で
+検証する手段は無いベストエフォートの経路です。使っているAIエージェントが指示
+通りきちんと確認してくれるかは、そのエージェント次第になります。同じマップは、
+そのサーバーが起動している間（概ね1回の会話）は再確認されません。
+
+（以前はMCP標準の確認ダイアログ機能「elicitation」で強制する経路も
+併用していましたが、対応を広告していながら実際にはダイアログを出さない
+クライアントがあり、本人が一度も確認画面を見ないまま読み取れなくなる
+不具合があったため、2026-09-03に廃止し、上記の方式に一本化しました）
+
+## 書き方を安定させる
+
+AIエージェントに任せると楽な反面、そのままだと読みにくいマップになりがちです。
+次の文言を、AIエージェントが毎回読み込む指示ファイル（Claude Codeなら
+`~/.claude/CLAUDE.md`）に貼っておくと、書き方が安定します。
+
+```markdown
+## mmmへの書き方
+
+- 1つの要素は1行で読み切れる長さにする。説明を詰め込まない。
+  理由や補足を残したいときは、子要素として1段下に置く
+- URLは単独の要素にする。「資料はこちら https://...」のように
+  説明文と混ぜてはいけない。「資料」という要素を作り、その子に
+  URLだけを置く
+- やり忘れを防ぐための項目は時系列で並べる。「リリース直後」
+  「2週間後」「〇〇になったら」のように、いつやるかを項目名にする
+```
+
+それぞれの理由は次のとおりです。
+
+- **1行にする** … Matryoshkaは要素を入れ子で表示するので、1つが長いと
+  一覧性が落ちて、階層をたどる良さが消えてしまいます
+- **URLを混ぜない** … 説明文と同じ要素に入れるとアプリでリンクとして
+  扱われず、タップしても開けません
+- **時系列で並べる** … 作業の名前で並べるより、順に消していく形になるぶん、
+  抜けに気づきやすくなります
+
+## よくあるトラブル
+
+| 症状 | 原因・対処 |
+|---|---|
+| `node --version`が「command not found」になる | 手順3のNode.jsインストールがまだ。インストール後、ターミナルを一度閉じて開き直す |
+| ログイン時に「パスワードが違います」と出る | 手順6の補足を参照。Google/Appleでログインし直してみる |
+| 話しかけてもマップ操作をしてくれない | 手順7の登録が正しいか確認する。Claude Desktopは登録後に再起動が必要 |
+| マップの中身を教えてくれない・確認だけで止まる | 「読んでいいですか」の確認に「はい」と答えているか確認する |
+| 大きなマップをAIが読み込めない | 要素が数百を超えると`list_elements`の応答が大きくなり、一度に受け取れないことがある。AIエージェントによっては、いったんファイルに保存して必要な部分だけ読む形で対応する。頻繁に起きるならマップを分ける（最上位の要素を左スワイプすると、配下ごと独立したマップになる） |
+
+## 活用例（応用編）: フォルダ単位でタスクを自動記録する
+
+ここから先は**一つの使い方の例**です。全員にすすめる標準的な使い方という
+わけではなく、「こういう設定をすればこんなことができる」という可能性を
+示すものなので、自分に合わないと思えば無視してかまいません。
+
+**やりたいこと**: Claude Codeで作業しているフォルダ（プロジェクト）ごとに
+同名のマップを1つ対応させ、作業中に出てきたタスクをAIエージェントが確認なしで
+そのマップへリアルタイムに記録・更新していく。
+
+> ここで示す(2)の設定はClaude Codeの「グローバルCLAUDE.md」という、常に
+> 読み込ませる指示ファイルの仕組みを使った例です。他のAIエージェントでも、
+> 同じように「毎回読み込ませる指示」を設定できる機能があれば、同じ考え方を
+> 応用できるはずです。
+
+### 必要な設定
+
+**(1) mmmサーバーを全フォルダ共通で使えるように登録し直す**
+
+手順7でClaude Codeに登録するとき、そのままだと今いるフォルダでしか
+`mmm`ツールが使えません。どのフォルダで`claude`を起動しても使えるように
+するには、`--scope user`を付けて登録します。
+
+```bash
+claude mcp add mmm --scope user -- node <mmm_mcpのパス>/dist/src/server.js
+```
+
+**(2) グローバルのCLAUDE.md（`~/.claude/CLAUDE.md`）に運用ルールを書く**
+
+例えば次のような文言を追記します。
+
+```markdown
+## mmmでのタスク管理
+
+作業フォルダで発生したタスクは、mmm（Matryoshka Mind Map連携）に
+記録してリアルタイムで管理する。
+
+- 作業フォルダ名をそのままマップのタイトルとして扱う
+- list_mapsで同名のマップが既にあるか確認する。無ければ、
+  タイトルの確認を挟まずそのままcreate_map(title=フォルダ名,
+  isTodo=true)で作成してよい（この運用に限り事前確認は不要とする）
+- 既存タスクを把握するためlist_elementsを呼ぶと、そのマップを
+  そのプロセスで初めて読むときだけ確認が入る。それ以降は
+  auto_structure_thought/update_task_statusでリアルタイムに
+  追記・更新する
+```
+
+### 動きの理由
+
+- `create_map`はタイトルを直接引数で受け取るツールで、「呼ぶ前に会話で
+  確認を取る」というのはツールの説明文に書かれたAIエージェント向けの
+  推奨動作にすぎません。より具体的なCLAUDE.mdの指示を優先させることで、
+  確認なしの自動作成にできます
+- マップの中身を読む`list_elements`だけは、秘匿情報への配慮として
+  サーバー側で確認を強制しています（上の「使ってみる」節を参照）。
+  これはフォルダ単位の運用にしても変わらず、同じマップをその
+  プロセスで初めて読むときに1回だけ確認が入ります
+
+### 注意点
+
+- 全フォルダで自動的にマップが増えていくため、普段使っている厳選された
+  マインドマップの中に、作業ログ的なマップが混ざります。人によっては
+  雑多に感じるかもしれません。専用のアカウントを分ける、対象フォルダを
+  限定するなど、自分に合う形に調整してください
+- ここで示した`create_map`の確認省略は、あくまでこの運用を自分のCLAUDE.mdで
+  明示した場合の話です。何も設定しなければ、これまで通り会話内で確認を
+  取ってから作成されます
+
+## このツールについて
+
+- あなたのログイン情報（更新トークン）はあなたのパソコンの中
+  （macOSは`~/.config/mmm-mcp/credentials.json`、Windowsは
+  `C:\Users\<ユーザー名>\.config\mmm-mcp\credentials.json`）にのみ保存され、
+  他の場所には送信されません
+- マップの内容はあなたのFirebaseアカウントに直接読み書きされ、開発者を含む
+  第三者のサーバーを経由しません（Appleでログインする場合のみ、ログインの
+  最後の一手続きで署名専用の中継サーバーを経由しますが、あなたのマップの
+  中身は一切通りません）
+- 常時起動しているプロセスはなく、AIエージェントとの会話中だけ動作します

package/dist/bin/login.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import * as readline from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { signInWithPassword, signInWithIdp, lookupAccountEmail, } from "../src/auth/firebaseAuthRest.js";
+import { saveCredentials, clearCredentials, loadCredentials, credentialsPath, } from "../src/auth/tokenStore.js";
+import { signInWithGoogleLoopback } from "../src/auth/googleLoopback.js";
+import { signInWithAppleLoopback } from "../src/auth/appleLoopback.js";
+import { exchangeAppleAuthorizationCode } from "../src/auth/appleTokenExchange.js";
+import { fetchAppleClientSecret } from "../src/auth/appleClientSecretRemote.js";
+// readlineに非表示入力(パスワード用)の機能が無いため、入力中だけ
+// stdoutへの書き込みを差し替えてエコーバックを抑える。
+function promptHidden(rl, promptText) {
+    const write = stdout.write.bind(stdout);
+    let hide = false;
+    stdout.write = ((chunk, ...args) => {
+        if (hide && typeof chunk === "string" && chunk !== promptText && !chunk.includes("\n")) {
+            return true;
+        }
+        // @ts-expect-error - Node標準のwriteシグネチャをそのまま委譲する
+        return write(chunk, ...args);
+    });
+    hide = true;
+    return rl.question(promptText).finally(() => {
+        hide = false;
+        stdout.write = write;
+        stdout.write("\n");
+    });
+}
+async function promptEmailPassword() {
+    const rl = readline.createInterface({ input: stdin, output: stdout, terminal: true });
+    const email = await rl.question("メールアドレス: ");
+    const password = await promptHidden(rl, "パスワード(入力は表示されません): ");
+    rl.close();
+    return { email: email.trim(), password };
+}
+function printUsage() {
+    console.log("使い方:");
+    console.log("  mmm-login login --method email   (メールアドレス+パスワードでサインイン)");
+    console.log("  mmm-login login --method google  (Googleアカウントでサインイン)");
+    console.log("  mmm-login login --method apple   (Appleアカウントでサインイン)");
+    console.log("  mmm-login logout                 (サインアウトしてローカルの認証情報を消す)");
+    console.log("  mmm-login status                 (サインイン状態を確認する)");
+}
+async function main() {
+    const [, , command, ...rest] = process.argv;
+    if (command === "logout") {
+        clearCredentials();
+        console.log("サインアウトしました。");
+        return;
+    }
+    if (command === "status") {
+        const creds = loadCredentials();
+        if (!creds) {
+            console.log("サインインしていません。");
+        }
+        else {
+            console.log(`サインイン中: ${creds.email ?? "(メールアドレス不明)"} (${creds.provider})`);
+            console.log(`保存先: ${credentialsPath()}`);
+        }
+        return;
+    }
+    if (command !== "login") {
+        printUsage();
+        process.exitCode = 1;
+        return;
+    }
+    const methodIndex = rest.indexOf("--method");
+    const method = methodIndex >= 0 ? rest[methodIndex + 1] : undefined;
+    if (method === "email") {
+        const { email, password } = await promptEmailPassword();
+        const result = await signInWithPassword(email, password);
+        saveCredentials({
+            uid: result.localId,
+            email: result.email,
+            refreshToken: result.refreshToken,
+            provider: "password",
+        });
+        console.log(`サインインしました: ${result.email ?? result.localId}`);
+    }
+    else if (method === "google") {
+        const idToken = await signInWithGoogleLoopback();
+        const result = await signInWithIdp("google.com", idToken);
+        const email = result.email ?? (await lookupAccountEmail(result.idToken));
+        saveCredentials({
+            uid: result.localId,
+            email,
+            refreshToken: result.refreshToken,
+            provider: "google.com",
+        });
+        console.log(`サインインしました: ${email ?? result.localId}`);
+    }
+    else if (method === "apple") {
+        // Cloud Functionの疎通確認を先に済ませ、失敗するならブラウザでの
+        // サインイン操作をさせる前に気付けるようにする。client_secretは
+        // 短命(5分)なので、ブラウザでの操作に時間がかかった場合に備えて
+        // 実際のトークン交換の直前にもう一度取り直す。
+        await fetchAppleClientSecret();
+        const code = await signInWithAppleLoopback();
+        const clientSecret = await fetchAppleClientSecret();
+        const appleIdToken = await exchangeAppleAuthorizationCode(code, clientSecret);
+        const result = await signInWithIdp("apple.com", appleIdToken);
+        const email = result.email ?? (await lookupAccountEmail(result.idToken));
+        saveCredentials({
+            uid: result.localId,
+            email,
+            refreshToken: result.refreshToken,
+            provider: "apple.com",
+        });
+        console.log(`サインインしました: ${email ?? result.localId}`);
+    }
+    else {
+        printUsage();
+        process.exitCode = 1;
+    }
+}
+main().catch((err) => {
+    console.error(`エラー: ${err instanceof Error ? err.message : String(err)}`);
+    process.exitCode = 1;
+});

package/dist/src/auth/appleClientSecretRemote.js

@@ -0,0 +1,29 @@
+import { APPLE_CLIENT_SECRET_FUNCTION_URL } from "../firebaseConfig.js";
+/**
+ * Sign in with Appleのclient_secret(JWT)を、Cloud Function経由で取得する。
+ * 秘密鍵はこのFunction側だけが持ち、全ユーザーのCLIが共有で呼び出す
+ * (client_secretはアプリ自身を認証するものであり、ユーザーごとに
+ * 異なるものではないため)。
+ */
+export async function fetchAppleClientSecret() {
+    let res;
+    try {
+        res = await fetch(APPLE_CLIENT_SECRET_FUNCTION_URL);
+    }
+    catch (err) {
+        throw new Error(`client_secretの発行元(${APPLE_CLIENT_SECRET_FUNCTION_URL})に接続できませんでした: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const text = await res.text();
+    let data;
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        data = { error: text };
+    }
+    if (!res.ok || typeof data.client_secret !== "string") {
+        const message = data.error ?? `HTTP ${res.status}`;
+        throw new Error(`client_secretの取得に失敗しました: ${message}`);
+    }
+    return data.client_secret;
+}

package/dist/src/auth/appleLoopback.js

@@ -0,0 +1,75 @@
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import open from "open";
+import { APPLE_SERVICES_ID, APPLE_RELAY_URL, APPLE_LOOPBACK_PORT } from "../firebaseConfig.js";
+const AUTHORIZE_ENDPOINT = "https://appleid.apple.com/auth/authorize";
+function base64url(buffer) {
+    return buffer.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/**
+ * Appleは(Googleと違って)localhostへのredirect_uriを許可しないため、
+ * Firebase Hosting上の中継ページ(web/mcp-apple-relay.html)を経由して
+ * このプロセスに認可コードを引き渡してもらう。中継ページのURLは
+ * 固定でなければならず、そこにポート番号を含められないため、
+ * ここでは毎回固定ポート(APPLE_LOOPBACK_PORT)でローカルサーバーを立てる。
+ */
+export async function signInWithAppleLoopback() {
+    const state = base64url(randomBytes(16));
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            try {
+                const url = new URL(req.url ?? "/", `http://127.0.0.1:${APPLE_LOOPBACK_PORT}`);
+                if (url.pathname !== "/callback") {
+                    res.writeHead(404).end();
+                    return;
+                }
+                const returnedState = url.searchParams.get("state");
+                const code = url.searchParams.get("code");
+                const error = url.searchParams.get("error");
+                if (error) {
+                    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                    res.end("<p>サインインがキャンセルされました。このタブは閉じて構いません。</p>");
+                    server.close();
+                    reject(new Error(`Apple認証が拒否されました: ${error}`));
+                    return;
+                }
+                if (returnedState !== state || !code) {
+                    // stateが一致しない・codeが無いリクエストは、favicon取得等の無関係な
+                    // アクセスの可能性もあるため、応答だけしてサーバーは閉じずに待ち続ける。
+                    res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                    res.end("<p>不正なリクエストです。このタブは閉じて構いません。</p>");
+                    return;
+                }
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end("<p>Appleサインインが完了しました。このタブは閉じてターミナルに戻ってください。</p>");
+                server.close();
+                resolve(code);
+            }
+            catch (err) {
+                res.writeHead(500).end("internal error");
+                server.close();
+                reject(err);
+            }
+        });
+        server.listen(APPLE_LOOPBACK_PORT, "127.0.0.1", () => {
+            const authUrl = new URL(AUTHORIZE_ENDPOINT);
+            authUrl.searchParams.set("client_id", APPLE_SERVICES_ID);
+            authUrl.searchParams.set("redirect_uri", APPLE_RELAY_URL);
+            authUrl.searchParams.set("response_type", "code");
+            authUrl.searchParams.set("response_mode", "query");
+            authUrl.searchParams.set("state", state);
+            console.log("ブラウザでAppleのサインイン画面を開きます…");
+            open(authUrl.toString()).catch(() => {
+                console.log(`自動で開けなかった場合は次のURLを開いてください:\n${authUrl.toString()}`);
+            });
+        });
+        server.on("error", (err) => {
+            if (err.code === "EADDRINUSE") {
+                reject(new Error(`ポート${APPLE_LOOPBACK_PORT}が使用中です。他のプロセスを終了してから再試行してください。`));
+            }
+            else {
+                reject(err);
+            }
+        });
+    });
+}

package/dist/src/auth/appleTokenExchange.js

@@ -0,0 +1,29 @@
+import { APPLE_SERVICES_ID, APPLE_RELAY_URL } from "../firebaseConfig.js";
+const APPLE_TOKEN_ENDPOINT = "https://appleid.apple.com/auth/token";
+/** Appleの認可コードをid_tokenに交換する(トークンエンドポイントへのサーバー間通信)。 */
+export async function exchangeAppleAuthorizationCode(code, clientSecret) {
+    const res = await fetch(APPLE_TOKEN_ENDPOINT, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            client_id: APPLE_SERVICES_ID,
+            client_secret: clientSecret,
+            redirect_uri: APPLE_RELAY_URL,
+        }),
+    });
+    const text = await res.text();
+    let data;
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        data = { error: text };
+    }
+    if (!res.ok || typeof data.id_token !== "string") {
+        const message = data.error_description ?? data.error ?? `HTTP ${res.status}`;
+        throw new Error(`Appleトークン交換に失敗しました: ${message}`);
+    }
+    return data.id_token;
+}