mmm-mcp-server 0.1.0

package/dist/src/domain/moveElement.js

@@ -0,0 +1,93 @@
+import { buildInsertChildWrite, buildReorderChildWrite, buildRemoveChildrenWrite } from "./levels.js";
+import { mergeWritesByPath } from "../firestore/restClient.js";
+/**
+ * 要素1件(配下ごと)を新しい場所へ移動するための書き込みを組み立てる。
+ * tools/moveElement.tsから切り出した純粋寄りの関数(client.getDocumentだけ呼ぶ)。
+ * 呼び出し側で自己参照・循環などのバリデーションを済ませ、[elementId]が
+ * [existingBodies]に存在することを保証しておくこと。
+ */
+export async function buildMoveElementWrites(client, bodiesPath, levelsPath, existingBodies, elementId, newParentElementId, afterElementId) {
+    const byId = new Map(existingBodies.map((b) => [b.id, b]));
+    const body = byId.get(elementId);
+    if (!body) {
+        throw new Error(`elementId(${elementId})がこのマップに見つかりません。`);
+    }
+    const writes = [];
+    // 1) 元の場所の連結リストを繋ぎ直す
+    if (body.prev !== null) {
+        writes.push({
+            path: `${bodiesPath}/${body.prev}`,
+            fields: { next: body.next },
+            requireUpdateTime: byId.get(body.prev)?.updateTime,
+        });
+    }
+    else if (body.parent !== null) {
+        writes.push({
+            path: `${bodiesPath}/${body.parent}`,
+            fields: { child: body.next },
+            requireUpdateTime: byId.get(body.parent)?.updateTime,
+        });
+    }
+    if (body.next !== null) {
+        writes.push({
+            path: `${bodiesPath}/${body.next}`,
+            fields: { prev: body.prev },
+            requireUpdateTime: byId.get(body.next)?.updateTime,
+        });
+    }
+    // 2) 新しい場所へ挿入する位置を求める(afterElementIdが実際にnewParentElementId
+    //    の子でなければ、見つからない扱い=末尾として無視する)。
+    const newSiblingsExcludingSelf = existingBodies.filter((b) => b.parent === newParentElementId && b.id !== elementId);
+    const afterBody = afterElementId !== null
+        ? newSiblingsExcludingSelf.find((b) => b.id === afterElementId) ?? null
+        : null;
+    const newPrevId = afterElementId === null ? null : afterBody?.id ?? null;
+    const newNextId = newPrevId === null
+        ? newSiblingsExcludingSelf.find((b) => b.prev === null)?.id ?? null
+        : newSiblingsExcludingSelf.find((b) => b.prev === newPrevId)?.id ?? null;
+    writes.push({
+        path: `${bodiesPath}/${elementId}`,
+        fields: { parent: newParentElementId, prev: newPrevId, next: newNextId },
+        requireUpdateTime: body.updateTime,
+    });
+    if (newPrevId !== null) {
+        writes.push({
+            path: `${bodiesPath}/${newPrevId}`,
+            fields: { next: elementId },
+            requireUpdateTime: byId.get(newPrevId)?.updateTime,
+        });
+    }
+    else if (newParentElementId !== null) {
+        writes.push({
+            path: `${bodiesPath}/${newParentElementId}`,
+            fields: { child: elementId },
+            requireUpdateTime: byId.get(newParentElementId)?.updateTime,
+        });
+    }
+    if (newNextId !== null) {
+        writes.push({
+            path: `${bodiesPath}/${newNextId}`,
+            fields: { prev: elementId },
+            requireUpdateTime: byId.get(newNextId)?.updateTime,
+        });
+    }
+    // 3) levels側: 元の親から取り除き、新しい親へ挿入する
+    const oldLevelId = body.parent ?? "root";
+    const newLevelId = newParentElementId ?? "root";
+    const entry = { id: elementId, detail: body.detail, done: body.done };
+    if (oldLevelId === newLevelId) {
+        // **同じ親の中での並べ替えは1つの書き込みにまとめること。**
+        // remove用とinsert用を別々に作ると、どちらも「元のchildren」を
+        // 読んでから組み立てるため、同じドキュメントへの書き込みが2つでき、
+        // 後勝ちのinsert側だけが残る。insert側は対象がまだ入ったままの配列に
+        // もう1つ足したものなので、要素が重複する(実データで踏んだ)。
+        writes.push(await buildReorderChildWrite(client, levelsPath, oldLevelId, entry, newPrevId));
+    }
+    else {
+        const removeWrite = await buildRemoveChildrenWrite(client, levelsPath, oldLevelId, [elementId]);
+        if (removeWrite)
+            writes.push(removeWrite);
+        writes.push(await buildInsertChildWrite(client, levelsPath, newLevelId, entry, newPrevId));
+    }
+    return mergeWritesByPath(writes);
+}

package/dist/src/firebaseConfig.js

@@ -0,0 +1,36 @@
+// lib/main.dartのFirebaseOptions(Web版)と同じ値。
+// Web用のAPIキーだが、Identity Toolkit REST APIの呼び出しには
+// プラットフォームを問わず同じキーを使える。
+export const FIREBASE_API_KEY = "AIzaSyCp1EMDbIcYHJXtkZiUYJH0yo_4U366WqQ";
+export const FIREBASE_PROJECT_ID = "matryoshkamap";
+export const FIREBASE_AUTH_DOMAIN = "matryoshkamap.firebaseapp.com";
+// Googleログイン(ローカルループバック方式)用の共有OAuthクライアント
+// (種類:デスクトップアプリ)。インストール型アプリのクライアントシークレットは
+// Google自身がconfidentialとして扱わない設計のため(gcloud CLI等と同じ)、
+// 全ユーザーのCLIで共有してよい。ユーザーごとにGoogle Cloud Consoleで
+// 作り直す必要は無い。
+export const GOOGLE_OAUTH_CLIENT_ID = "1020142389980-s55ds6qtude3v5e5piqpmuh24u5ktf4u.apps.googleusercontent.com";
+export const GOOGLE_OAUTH_CLIENT_SECRET = "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";
+// Sign in with AppleのServices ID(Web/Android用、Bundle IDと別)。
+// アプリ本体が使っているものと同じServices IDを、MCPのCLIも再利用する
+// (Return URLに中継ページのURLを追加登録するだけでよい)。
+export const APPLE_SERVICES_ID = "jp.spheres.mm.signin";
+// client_secret(JWT)発行用のCloud Function(functions/src/index.ts)。
+// Sign in with Appleの秘密鍵(.p8)はアプリを識別するためのものであり、
+// ユーザーごとに異なるものではないため、鍵自体を各ユーザーに配る代わりに、
+// 署名専用のこのエンドポイントを全ユーザーのCLIから共有で呼び出す。
+export const APPLE_CLIENT_SECRET_FUNCTION_URL = "https://asia-northeast1-matryoshkamap.cloudfunctions.net/appleClientSecret";
+// Apple中継ページの本番URL。web/mcp-apple-relay.html をビルド・デプロイした先。
+// このURLをApple Developer PortalのServices ID設定のReturn URLに
+// 追加登録する必要がある。
+//
+// ドメインは.web.appではなく.firebaseappを使うこと。Appleの
+// Return URL登録は「Domains and Subdomains」への事前登録も必要で、
+// アプリ本体のApple連携(Return URL:
+// https://matryoshkamap.firebaseapp.com/__/auth/handler)により
+// matryoshkamap.firebaseappは既に登録済みのため、新規のドメイン登録なしで
+// Return URLの追加だけで済む。.web.appは別ドメイン扱いになり
+// invalid_request(Invalid web redirect url)になることを実機で確認済み。
+export const APPLE_RELAY_URL = "https://matryoshkamap.firebaseapp.com/mcp-apple-relay.html";
+// web/mcp-apple-relay.html のLOOPBACK_PORTと必ず一致させること。
+export const APPLE_LOOPBACK_PORT = 51004;

package/dist/src/firestore/restClient.js

@@ -0,0 +1,267 @@
+import { FIREBASE_PROJECT_ID } from "../firebaseConfig.js";
+import { decodeFields, encodeFields, encodeValue, lastPathSegment, } from "./valueCodec.js";
+const BASE_URL = `https://firestore.googleapis.com/v1/projects/${FIREBASE_PROJECT_ID}/databases/(default)/documents`;
+export class FirestoreError extends Error {
+    status;
+    raw;
+    constructor(message, status, raw) {
+        super(message);
+        this.status = status;
+        this.raw = raw;
+        this.name = "FirestoreError";
+    }
+}
+function encodePath(path) {
+    return path
+        .split("/")
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+/** レスポンスがJSONでない(障害時のHTMLエラーページ等)場合でも例外にせず読む。 */
+async function parseJsonResponse(res) {
+    const text = await res.text();
+    try {
+        return text ? JSON.parse(text) : {};
+    }
+    catch {
+        return { error: { message: text || `HTTP ${res.status}` } };
+    }
+}
+/** Firestoreの1コミット(:commit)に含められる書き込み件数の上限(500)より余裕を持たせた値。 */
+const COMMIT_CHUNK_SIZE = 400;
+/**
+ * 同じドキュメントを指す書き込みを1件にまとめる。
+ *
+ * **1回のcommitに同じpathの書き込みを2つ以上積んではいけない。** Firestoreは
+ * エラーにせず順に適用するため、後の書き込みが前の書き込みを打ち消す。
+ * 実データで2度踏んだ(move_elementで要素が重複、delete_elementsで存在しない
+ * IDを指すポインタが残る)。writesを返す直前に必ずこれを通すこと。
+ *
+ * deleteが1つでもあればdeleteが勝つ(消すドキュメントへの部分更新は無意味)。
+ * fields同士はマージし、requireUpdateTimeは最初に読み取った値を残す。
+ */
+export function mergeWritesByPath(writes) {
+    const byPath = new Map();
+    const order = [];
+    for (const write of writes) {
+        const prev = byPath.get(write.path);
+        if (!prev) {
+            byPath.set(write.path, { ...write });
+            order.push(write.path);
+            continue;
+        }
+        if (write.delete || prev.delete) {
+            byPath.set(write.path, { path: write.path, delete: true });
+            continue;
+        }
+        if (write.arrayUnion || prev.arrayUnion) {
+            // 配列追記と通常の更新は混ぜられない。後から積んだ方を採る。
+            byPath.set(write.path, { ...write });
+            continue;
+        }
+        byPath.set(write.path, {
+            path: write.path,
+            fields: { ...(prev.fields ?? {}), ...(write.fields ?? {}) },
+            requireUpdateTime: prev.requireUpdateTime ?? write.requireUpdateTime,
+            requireMissing: prev.requireMissing ?? write.requireMissing,
+        });
+    }
+    return order.map((path) => byPath.get(path));
+}
+export class FirestoreRestClient {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    async headers() {
+        const idToken = await this.session.getValidIdToken();
+        return {
+            Authorization: `Bearer ${idToken}`,
+            "Content-Type": "application/json",
+        };
+    }
+    async getDocument(path) {
+        const res = await fetch(`${BASE_URL}/${encodePath(path)}`, {
+            headers: await this.headers(),
+        });
+        if (res.status === 404)
+            return null;
+        const data = await parseJsonResponse(res);
+        if (!res.ok) {
+            throw new FirestoreError(data?.error?.message ?? `HTTP ${res.status}`, res.status, data);
+        }
+        return {
+            id: lastPathSegment(data.name),
+            data: decodeFields(data.fields ?? {}),
+            updateTime: data.updateTime,
+        };
+    }
+    /**
+     * [operation]を実行し、返された[FirestoreWrite]をコミットする。[operation]
+     * が返す書き込みに[FirestoreWrite.requireUpdateTime]が含まれ、コミット時点で
+     * 対象ドキュメントが読み取り後に他から変更されていた場合(FAILED_PRECONDITION)、
+     * [operation]の読み取りからやり直して最大[maxAttempts]回リトライする。
+     *
+     * Firestoreの明示的なトランザクション(:beginTransaction)はFirebase Authの
+     * IDトークンではIAM権限が無く403になるため使えない(2026-09-09に実アカウントで
+     * 確認)。代わりにcurrentDocument.updateTimeによる楽観的ロックで
+     * read-modify-write競合を検出する。
+     */
+    async runOptimistic(operation, maxAttempts = 5) {
+        let lastError;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const writes = await operation();
+            try {
+                await this.commitWrites(writes);
+                return;
+            }
+            catch (e) {
+                lastError = e;
+                const raw = e instanceof FirestoreError ? e.raw : undefined;
+                const isPreconditionFailed = raw?.error?.status === "FAILED_PRECONDITION";
+                if (!isPreconditionFailed) {
+                    throw e;
+                }
+                // 読み取り後に他の書き込みが割り込んだ。少し待って
+                // 最初から(読み取りも含めて)やり直す。
+                await new Promise((resolve) => setTimeout(resolve, 50 * (attempt + 1)));
+            }
+        }
+        throw lastError instanceof Error
+            ? lastError
+            : new Error("runOptimistic: リトライ上限に達した");
+    }
+    /** コレクション配下の全ドキュメントを取得する(ページングを自動で辿る)。 */
+    async listDocuments(collectionPath) {
+        const results = [];
+        let pageToken;
+        do {
+            const url = new URL(`${BASE_URL}/${encodePath(collectionPath)}`);
+            url.searchParams.set("pageSize", "300");
+            if (pageToken)
+                url.searchParams.set("pageToken", pageToken);
+            const res = await fetch(url, { headers: await this.headers() });
+            const data = await parseJsonResponse(res);
+            if (!res.ok) {
+                throw new FirestoreError(data?.error?.message ?? `HTTP ${res.status}`, res.status, data);
+            }
+            for (const doc of data.documents ?? []) {
+                results.push({
+                    id: lastPathSegment(doc.name),
+                    data: decodeFields(doc.fields ?? {}),
+                    updateTime: doc.updateTime,
+                });
+            }
+            pageToken = data.nextPageToken;
+        } while (pageToken);
+        return results;
+    }
+    /** サーバー採番のIDで新規ドキュメントを作る。 */
+    async createDocument(collectionPath, fields) {
+        const res = await fetch(`${BASE_URL}/${encodePath(collectionPath)}`, {
+            method: "POST",
+            headers: await this.headers(),
+            body: JSON.stringify({ fields: encodeFields(fields) }),
+        });
+        const data = await parseJsonResponse(res);
+        if (!res.ok) {
+            throw new FirestoreError(data?.error?.message ?? `HTTP ${res.status}`, res.status, data);
+        }
+        return { id: lastPathSegment(data.name), data: decodeFields(data.fields ?? {}) };
+    }
+    /** 指定パスに、全フィールドを置き換える形で書き込む(無ければ作成)。 */
+    async setDocument(docPath, fields) {
+        const res = await fetch(`${BASE_URL}/${encodePath(docPath)}`, {
+            method: "PATCH",
+            headers: await this.headers(),
+            body: JSON.stringify({ fields: encodeFields(fields) }),
+        });
+        if (!res.ok) {
+            const data = await parseJsonResponse(res);
+            throw new FirestoreError(data?.error?.message ?? `HTTP ${res.status}`, res.status, data);
+        }
+    }
+    /** 指定したフィールドだけを部分更新する。 */
+    async updateDocument(docPath, fields) {
+        const mask = Object.keys(fields).map((key) => `updateMask.fieldPaths=${encodeURIComponent(key)}`);
+        const url = `${BASE_URL}/${encodePath(docPath)}?${mask.join("&")}`;
+        const res = await fetch(url, {
+            method: "PATCH",
+            headers: await this.headers(),
+            body: JSON.stringify({ fields: encodeFields(fields) }),
+        });
+        if (!res.ok) {
+            const data = await parseJsonResponse(res);
+            throw new FirestoreError(data?.error?.message ?? `HTTP ${res.status}`, res.status, data);
+        }
+    }
+    async deleteDocument(docPath) {
+        const res = await fetch(`${BASE_URL}/${encodePath(docPath)}`, {
+            method: "DELETE",
+            headers: await this.headers(),
+        });
+        if (!res.ok && res.status !== 404) {
+            const data = await parseJsonResponse(res);
+            throw new FirestoreError(data?.error?.message ?? `HTTP ${res.status}`, res.status, data);
+        }
+    }
+    /**
+     * 複数ドキュメントへの部分更新・削除をまとめて行う。
+     * マインドマップの連結リスト(prev/next/parent/child)を書き換える操作は
+     * 一部だけ成功すると整合性が壊れるため、必ずこれを使う。
+     *
+     * Firestoreの:commitは1リクエストあたり最大500件の書き込みまでしか
+     * 受け付けないため、それを超える場合は複数回のコミットに分割する
+     * (分割した場合、コミット単位はそれぞれ独立したトランザクションになる)。
+     */
+    async commitWrites(writes) {
+        for (let i = 0; i < writes.length; i += COMMIT_CHUNK_SIZE) {
+            await this.commitChunk(writes.slice(i, i + COMMIT_CHUNK_SIZE));
+        }
+    }
+    async commitChunk(writes) {
+        if (writes.length === 0)
+            return;
+        const body = {
+            writes: writes.map((w) => {
+                const name = `projects/${FIREBASE_PROJECT_ID}/databases/(default)/documents/${w.path}`;
+                const currentDocument = w.requireUpdateTime
+                    ? { currentDocument: { updateTime: w.requireUpdateTime } }
+                    : w.requireMissing
+                        ? { currentDocument: { exists: false } }
+                        : {};
+                if (w.delete) {
+                    return { delete: name, ...currentDocument };
+                }
+                if (w.arrayUnion) {
+                    return {
+                        transform: {
+                            document: name,
+                            fieldTransforms: [
+                                {
+                                    fieldPath: w.arrayUnion.field,
+                                    appendMissingElements: { values: w.arrayUnion.values.map(encodeValue) },
+                                },
+                            ],
+                        },
+                    };
+                }
+                const fields = w.fields ?? {};
+                return {
+                    update: { name, fields: encodeFields(fields) },
+                    updateMask: { fieldPaths: Object.keys(fields) },
+                    ...currentDocument,
+                };
+            }),
+        };
+        const res = await fetch(`${BASE_URL}:commit`, {
+            method: "POST",
+            headers: await this.headers(),
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const data = await parseJsonResponse(res);
+            throw new FirestoreError(data?.error?.message ?? `HTTP ${res.status}`, res.status, data);
+        }
+    }
+}

package/dist/src/firestore/valueCodec.js

@@ -0,0 +1,65 @@
+// Firestore REST API (https://firestore.googleapis.com/v1/...) の
+// 型付きValue表現と、JSのプレーンな値との相互変換。
+export function encodeValue(value) {
+    if (value === null || value === undefined) {
+        return { nullValue: null };
+    }
+    if (typeof value === "boolean") {
+        return { booleanValue: value };
+    }
+    if (typeof value === "number") {
+        return Number.isInteger(value)
+            ? { integerValue: String(value) }
+            : { doubleValue: value };
+    }
+    if (typeof value === "string") {
+        return { stringValue: value };
+    }
+    if (Array.isArray(value)) {
+        return { arrayValue: { values: value.map(encodeValue) } };
+    }
+    if (typeof value === "object") {
+        return { mapValue: { fields: encodeFields(value) } };
+    }
+    throw new Error(`encodeValue: 未対応の型です: ${typeof value}`);
+}
+export function decodeValue(value) {
+    if (!value)
+        return null;
+    if ("nullValue" in value)
+        return null;
+    if ("booleanValue" in value)
+        return value.booleanValue;
+    if ("integerValue" in value)
+        return Number(value.integerValue);
+    if ("doubleValue" in value)
+        return value.doubleValue;
+    if ("stringValue" in value)
+        return value.stringValue;
+    if ("arrayValue" in value) {
+        return (value.arrayValue.values ?? []).map(decodeValue);
+    }
+    if ("mapValue" in value) {
+        return decodeFields(value.mapValue.fields ?? {});
+    }
+    return null;
+}
+export function encodeFields(obj) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        result[key] = encodeValue(value);
+    }
+    return result;
+}
+export function decodeFields(fields) {
+    const result = {};
+    for (const [key, value] of Object.entries(fields)) {
+        result[key] = decodeValue(value);
+    }
+    return result;
+}
+/** "projects/p/databases/(default)/documents/users/uid/headers/hid" からドキュメントIDだけ取り出す。 */
+export function lastPathSegment(name) {
+    const parts = name.split("/");
+    return parts[parts.length - 1];
+}

package/dist/src/mcpContext.js

@@ -0,0 +1,11 @@
+import { loadSession } from "./auth/session.js";
+import { FirestoreRestClient } from "./firestore/restClient.js";
+let cached = null;
+/** サインイン済みセッションとFirestoreクライアントを1つだけ用意し、使い回す。 */
+export function getContext() {
+    if (!cached) {
+        const session = loadSession();
+        cached = { session, client: new FirestoreRestClient(session) };
+    }
+    return cached;
+}

package/dist/src/server.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerListMaps } from "./tools/listMaps.js";
+import { registerListElements } from "./tools/listElements.js";
+import { registerCreateMap } from "./tools/createMap.js";
+import { registerAutoStructureThought } from "./tools/autoStructureThought.js";
+import { registerUpdateTaskStatus } from "./tools/updateTaskStatus.js";
+import { registerImportMarkdownContext } from "./tools/importMarkdownContext.js";
+import { registerEditElement } from "./tools/editElement.js";
+import { registerDeleteElements } from "./tools/deleteElements.js";
+import { registerMoveElement } from "./tools/moveElement.js";
+const server = new McpServer({
+    name: "matryoshka-mindmap",
+    version: "0.1.0",
+}, {
+    instructions: "このサーバーはリアルタイム同期を行わない。各ツールは呼び出された瞬間の" +
+        "Firestoreの状態を返すだけで、アプリ側でユーザーが直接行った変更は" +
+        "自動的には通知されない。ユーザーから進捗や現在の状態を尋ねられたときは、" +
+        "それ以前の会話で見た内容を記憶に頼って答えず、必ずlist_maps/list_elementsを" +
+        "呼び直して最新の状態を確認してから答えること。",
+});
+registerListMaps(server);
+registerListElements(server);
+registerCreateMap(server);
+registerAutoStructureThought(server);
+registerUpdateTaskStatus(server);
+registerImportMarkdownContext(server);
+registerEditElement(server);
+registerDeleteElements(server);
+registerMoveElement(server);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/src/tools/autoStructureThought.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { mergeWritesByPath } from "../firestore/restClient.js";
+import { getContext } from "../mcpContext.js";
+import { isLevelsOnly, readLevelsSnapshot } from "../domain/levelsMode.js";
+import { ancestorDetailsInLevels, buildLevelsAppendWrites, locateInLevels } from "../domain/levelsOps.js";
+import { resolveMap, bodiesPathOf, levelsPathOf, formatPath, assertCanEditMap, } from "../domain/mapResolver.js";
+import { bodyFromFirestore, ancestorDetails } from "../domain/body.js";
+import { buildForestFromTree, buildAppendWrites } from "../domain/appendForest.js";
+import { assertLevelsRootExists, buildAppendLevelWrites, levelsDocExists } from "../domain/levels.js";
+const treeNodeSchema = z.lazy(() => z.object({
+    detail: z.string().min(1).describe("要素の本文"),
+    done: z.boolean().optional().describe("TODOマップのときのチェック状態(省略時false)"),
+    children: z.array(treeNodeSchema).optional().describe("この要素の内側に入れ子にする子要素"),
+}));
+export function registerAutoStructureThought(server) {
+    server.tool("auto_structure_thought", "会話中にClaudeが考えた階層構造を、既存のマップに追加する。深さは3階層固定ではなく任意。" +
+        "構造化のロジック(何をどう分解するか)はClaude側の判断で行い、このツールはFirestoreへの" +
+        "書き込みだけを行う。追加先(parentElementId)はlist_elementsの結果を見て判断すること。" +
+        "対象は既存マップのみ(新規作成が必要ならcreate_mapを先に呼ぶ)。", {
+        mapId: z.string().describe("list_mapsで得たマップのID"),
+        parentElementId: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("この要素の内側(子)として追加する。マップの最上位に追加する場合はnullまたは省略"),
+        nodes: z.array(treeNodeSchema).min(1).describe("追加する階層構造(ルートの配列)"),
+    }, async ({ mapId, parentElementId, nodes }) => {
+        const { client, session } = getContext();
+        const map = await resolveMap(client, session, mapId);
+        assertCanEditMap(map, session);
+        const levelsPath = levelsPathOf(map);
+        const bodiesPath = bodiesPathOf(map);
+        const targetParentId = parentElementId ?? null;
+        const forest = buildForestFromTree(nodes);
+        if (await isLevelsOnly(client)) {
+            let levelsPathResult = "";
+            await client.runOptimistic(async () => {
+                const snapshot = await readLevelsSnapshot(client, levelsPath, map.header.title);
+                if (targetParentId !== null && !locateInLevels(snapshot, targetParentId)) {
+                    throw new Error(`parentElementId(${targetParentId})がこのマップに見つかりません。list_elementsで確認してください。`);
+                }
+                levelsPathResult = formatPath(map.header.title, ancestorDetailsInLevels(snapshot, targetParentId));
+                return buildLevelsAppendWrites(levelsPath, snapshot, forest, targetParentId, map.header.isTodo);
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ path: levelsPathResult, addedElementCount: forest.length }, null, 2),
+                    },
+                ],
+            };
+        }
+        // 読み取り(bodies一覧・levels存在確認)から書き込みまでを楽観的
+        // ロックでまとめる。読み取り後に対象ドキュメントが他から変更される
+        // とコミットがFAILED_PRECONDITIONになり、読み取りからやり直す。
+        let createdIds = [];
+        let existingBodiesForPath = [];
+        await client.runOptimistic(async () => {
+            assertLevelsRootExists(await levelsDocExists(client, levelsPath, "root"), map.header.title);
+            const existingDocs = await client.listDocuments(bodiesPath);
+            const existingBodies = existingDocs.map((d) => bodyFromFirestore(d.id, d.data, d.updateTime));
+            existingBodiesForPath = existingBodies;
+            if (targetParentId !== null && !existingBodies.some((b) => b.id === targetParentId)) {
+                throw new Error(`parentElementId(${targetParentId})がこのマップに見つかりません。list_elementsで確認してください。`);
+            }
+            const { writes, createdIds: ids } = buildAppendWrites(bodiesPath, existingBodies, forest, targetParentId, map.header.isTodo);
+            createdIds = ids;
+            // 挿入先のlevelsドキュメントが実際に存在するかを直接確認する
+            // (bodies側の状態から推測すると、levelsとbodiesが食い違っている
+            // 場合にarrayUnion書き込みが「ドキュメントが無い」で失敗しうるため)。
+            const targetLevelId = targetParentId ?? "root";
+            const targetHasLevelsDoc = targetLevelId === "root" || (await levelsDocExists(client, levelsPath, targetLevelId));
+            const levelWrites = buildAppendLevelWrites(levelsPath, forest, targetParentId, targetHasLevelsDoc, map.header.isTodo);
+            return mergeWritesByPath([...writes, ...levelWrites]);
+        });
+        const path = formatPath(map.header.title, ancestorDetails(existingBodiesForPath, targetParentId));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ path, addedElementCount: createdIds.length }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/src/tools/createMap.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { getContext } from "../mcpContext.js";
+import { newDocId } from "../domain/idGen.js";
+export function registerCreateMap(server) {
+    server.tool("create_map", "新しいマインドマップ(マップ)を1つ作成する。" +
+        "list_mapsで確認して該当するマップが無いときだけ呼ぶこと。" +
+        "呼ぶ前に、会話でタイトル案をユーザーに提示し、明示的な確認を得ること" +
+        "(自動判断で勝手に作成しない)。", {
+        title: z.string().min(1).describe("マップのタイトル"),
+        isTodo: z.boolean().describe("TODOマップ(要素にチェックボックスを付ける)にするかどうか"),
+    }, async ({ title, isTodo }) => {
+        const { client, session } = getContext();
+        const existing = await client.listDocuments(`users/${session.uid}/headers`);
+        const maxOrder = existing.reduce((max, doc) => Math.max(max, Number(doc.data.order ?? 0)), 0);
+        // levels移行: 自前でIDを採番し、header本体と空のlevels/rootを1回の
+        // commitWritesにまとめて作る。levels/rootを最初から持たせておくことで、
+        // 直後に書き込み系ツールを呼んでも「アプリで一度開いてください」で
+        // 弾かれない(移行ではなく単なる初期化なので問題ない)。
+        // migratedはアプリの新規作成(header_add_model.dart)と揃える。無いと、
+        // 切替前のアプリが開いたときに未移行とみなしてbodiesから作り直してしまう。
+        const headerId = newDocId();
+        const headerPath = `users/${session.uid}/headers/${headerId}`;
+        await client.commitWrites([
+            {
+                path: headerPath,
+                fields: { title, order: maxOrder + 1, isTodo, editors: [], viewers: [] },
+            },
+            { path: `${headerPath}/levels/root`, fields: { children: [], migrated: true } },
+        ]);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ id: headerId, title, isTodo }, null, 2),
+                },
+            ],
+        };
+    });
+}