mmm-mcp-server 0.1.0

package/dist/src/tools/deleteElements.js

@@ -0,0 +1,150 @@
+import { z } from "zod";
+import { getContext } from "../mcpContext.js";
+import { isLevelsOnly, readLevelsSnapshot } from "../domain/levelsMode.js";
+import { ancestorDetailsInLevels, buildLevelsDeleteWrites, locateInLevels, subtreeIdsInLevels } from "../domain/levelsOps.js";
+import { resolveMap, bodiesPathOf, levelsPathOf, formatPath, assertCanEditMap, } from "../domain/mapResolver.js";
+import { bodyFromFirestore, ancestorDetails, collectSubtreeIds } from "../domain/body.js";
+import { assertLevelsRootExists, levelsDocExists } from "../domain/levels.js";
+import { buildDeleteElementWrites } from "../domain/deleteElements.js";
+export function registerDeleteElements(server) {
+    server.tool("delete_elements", "既存マップから要素を削除する。指定した要素とその配下(子孫)を丸ごと削除する。" +
+        "削除は取り返しがつかないため、まずconfirmedを省略(またはfalse)で呼び、" +
+        "返ってくる削除対象の一覧(パスと配下件数)をユーザーに提示して明示的な同意を得てから、" +
+        "confirmed: trueで呼び直すこと。", {
+        mapId: z.string().describe("list_mapsで得たマップのID"),
+        elementIds: z.array(z.string()).min(1).describe("list_elementsで得た要素のID(複数可)"),
+        confirmed: z
+            .boolean()
+            .optional()
+            .describe("true以外(省略時false)は削除対象の確認情報だけを返し、実際には削除しない"),
+    }, async ({ mapId, elementIds, confirmed }) => {
+        const { client, session } = getContext();
+        const map = await resolveMap(client, session, mapId);
+        assertCanEditMap(map, session);
+        const levelsPath = levelsPathOf(map);
+        const bodiesPath = bodiesPathOf(map);
+        assertLevelsRootExists(await levelsDocExists(client, levelsPath, "root"), map.header.title);
+        if (await isLevelsOnly(client)) {
+            if (confirmed !== true) {
+                const snapshot = await readLevelsSnapshot(client, levelsPath, map.header.title);
+                const allTargets = new Set();
+                const targets = [];
+                for (const elementId of elementIds) {
+                    if (!locateInLevels(snapshot, elementId)) {
+                        throw new Error(`elementId(${elementId})がこのマップに見つかりません。list_elementsで確認してください。`);
+                    }
+                    const subtree = subtreeIdsInLevels(snapshot, elementId);
+                    for (const id of subtree)
+                        allTargets.add(id);
+                    targets.push({
+                        elementId,
+                        path: formatPath(map.header.title, ancestorDetailsInLevels(snapshot, elementId)),
+                        subtreeCount: subtree.length,
+                    });
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                confirmationRequired: true,
+                                message: "削除は取り返しがつきません。以下の内容をユーザーに提示して明示的な同意を得てから、" +
+                                    "confirmed: trueで呼び直してください。",
+                                targets,
+                                totalElementCount: allTargets.size,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const levelsDeleted = [];
+            let levelsTotal = 0;
+            await client.runOptimistic(async () => {
+                levelsDeleted.length = 0;
+                const snapshot = await readLevelsSnapshot(client, levelsPath, map.header.title);
+                for (const elementId of elementIds) {
+                    if (!locateInLevels(snapshot, elementId))
+                        continue; // 既に削除済み(リトライ時など)
+                    levelsDeleted.push({
+                        elementId,
+                        path: formatPath(map.header.title, ancestorDetailsInLevels(snapshot, elementId)),
+                        subtreeCount: subtreeIdsInLevels(snapshot, elementId).length,
+                    });
+                }
+                const { writes, deletedIds } = buildLevelsDeleteWrites(levelsPath, snapshot, elementIds);
+                levelsTotal = deletedIds.size;
+                return writes;
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ deleted: levelsDeleted, totalElementCount: levelsTotal }, null, 2),
+                    },
+                ],
+            };
+        }
+        if (confirmed !== true) {
+            const existingDocs = await client.listDocuments(bodiesPath);
+            const existingBodies = existingDocs.map((d) => bodyFromFirestore(d.id, d.data, d.updateTime));
+            const byId = new Map(existingBodies.map((b) => [b.id, b]));
+            const allTargets = new Set();
+            const targets = [];
+            for (const elementId of elementIds) {
+                if (!byId.has(elementId)) {
+                    throw new Error(`elementId(${elementId})がこのマップに見つかりません。list_elementsで確認してください。`);
+                }
+                const subtree = collectSubtreeIds(existingBodies, elementId);
+                for (const id of subtree)
+                    allTargets.add(id);
+                targets.push({
+                    elementId,
+                    path: formatPath(map.header.title, ancestorDetails(existingBodies, elementId)),
+                    subtreeCount: subtree.length,
+                });
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            confirmationRequired: true,
+                            message: "削除は取り返しがつきません。以下の内容をユーザーに提示して明示的な同意を得てから、" +
+                                "confirmed: trueで呼び直してください。",
+                            targets,
+                            totalElementCount: allTargets.size,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const deletedPaths = [];
+        let totalDeleted = 0;
+        await client.runOptimistic(async () => {
+            deletedPaths.length = 0;
+            totalDeleted = 0;
+            const currentDocs = await client.listDocuments(bodiesPath);
+            const currentBodies = currentDocs.map((d) => bodyFromFirestore(d.id, d.data, d.updateTime));
+            for (const elementId of elementIds) {
+                if (!currentBodies.some((b) => b.id === elementId))
+                    continue; // 既に削除済み(リトライ時など)
+                deletedPaths.push({
+                    elementId,
+                    path: formatPath(map.header.title, ancestorDetails(currentBodies, elementId)),
+                    subtreeCount: collectSubtreeIds(currentBodies, elementId).length,
+                });
+            }
+            const { writes, deletedIds } = await buildDeleteElementWrites(client, bodiesPath, levelsPath, currentBodies, elementIds);
+            totalDeleted = deletedIds.size;
+            return writes;
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ deleted: deletedPaths, totalElementCount: totalDeleted }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/src/tools/editElement.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { getContext } from "../mcpContext.js";
+import { isLevelsOnly, readLevelsSnapshot } from "../domain/levelsMode.js";
+import { ancestorDetailsInLevels, buildLevelsPatchWrites } from "../domain/levelsOps.js";
+import { resolveMap, bodiesPathOf, levelsPathOf, formatPath, assertCanEditMap, } from "../domain/mapResolver.js";
+import { bodyFromFirestore, ancestorDetails } from "../domain/body.js";
+import { mergeWritesByPath } from "../firestore/restClient.js";
+import { assertLevelsRootExists, buildUpdateEntryWrites, levelsDocExists } from "../domain/levels.js";
+export function registerEditElement(server) {
+    server.tool("edit_element", "既存マップの要素1件の本文(detail)を書き換える。要素の追加はauto_structure_thought・" +
+        "import_markdown_contextを、チェック状態の変更はupdate_task_statusを使うこと。", {
+        mapId: z.string().describe("list_mapsで得たマップのID"),
+        elementId: z.string().describe("list_elementsで得た要素のID"),
+        detail: z.string().min(1).describe("書き換え後の本文"),
+    }, async ({ mapId, elementId, detail }) => {
+        const { client, session } = getContext();
+        const map = await resolveMap(client, session, mapId);
+        assertCanEditMap(map, session);
+        const levelsPath = levelsPathOf(map);
+        const bodiesPath = bodiesPathOf(map);
+        if (await isLevelsOnly(client)) {
+            let levelsPathResult = null;
+            await client.runOptimistic(async () => {
+                const snapshot = await readLevelsSnapshot(client, levelsPath, map.header.title);
+                const { writes, found } = buildLevelsPatchWrites(levelsPath, snapshot, [
+                    { elementId, patch: { detail } },
+                ]);
+                if (!found.has(elementId)) {
+                    throw new Error(`elementId(${elementId})がこのマップに見つかりません。list_elementsで確認してください。`);
+                }
+                levelsPathResult = formatPath(map.header.title, ancestorDetailsInLevels(snapshot, elementId));
+                return writes;
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ path: levelsPathResult }, null, 2) }],
+            };
+        }
+        assertLevelsRootExists(await levelsDocExists(client, levelsPath, "root"), map.header.title);
+        let path = null;
+        await client.runOptimistic(async () => {
+            const bodyDoc = await client.getDocument(`${bodiesPath}/${elementId}`);
+            if (!bodyDoc) {
+                throw new Error(`elementId(${elementId})がこのマップに見つかりません。list_elementsで確認してください。`);
+            }
+            const body = bodyFromFirestore(elementId, bodyDoc.data, bodyDoc.updateTime);
+            const existingDocs = await client.listDocuments(bodiesPath);
+            const existingBodies = existingDocs.map((d) => bodyFromFirestore(d.id, d.data, d.updateTime));
+            path = formatPath(map.header.title, ancestorDetails(existingBodies, elementId));
+            const writes = [
+                {
+                    path: `${bodiesPath}/${elementId}`,
+                    fields: { detail },
+                    requireUpdateTime: body.updateTime,
+                },
+            ];
+            const levelWrites = await buildUpdateEntryWrites(client, levelsPath, [
+                { parentId: body.parent, elementId, patch: { detail } },
+            ]);
+            return mergeWritesByPath([...writes, ...levelWrites]);
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify({ path }, null, 2) }],
+        };
+    });
+}

package/dist/src/tools/importMarkdownContext.js

@@ -0,0 +1,95 @@
+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 { buildAppendWrites } from "../domain/appendForest.js";
+import { parseMarkdownForImport } from "../domain/markdownParser.js";
+import { assertLevelsRootExists, buildAppendLevelWrites, levelsDocExists } from "../domain/levels.js";
+export function registerImportMarkdownContext(server) {
+    server.tool("import_markdown_context", "任意の深さのMarkdown(インデントで階層を表現したリスト、見出しは`#`)を組み立てて、" +
+        "既存のマップに流し込む。見出しも1つの要素として取り込む。" +
+        "取り込み先がTODOマップでない場合、`- [ ]`/`- [x]`のチェックボックス記法は取り除かれ" +
+        "チェック状態も反映されない(アプリ本体の挙動と同じ)。" +
+        "対象は既存マップのみ(新規作成が必要ならcreate_mapを先に呼ぶ)。", {
+        mapId: z.string().describe("list_mapsで得たマップのID"),
+        markdown: z.string().min(1).describe("取り込むMarkdownテキスト"),
+        parentElementId: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("この要素の内側(子)として取り込む。マップの最上位に取り込む場合はnullまたは省略"),
+    }, async ({ mapId, markdown, parentElementId }) => {
+        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 parsed = parseMarkdownForImport(markdown, { headingsAsNodes: true });
+        if (parsed.nodes.length === 0) {
+            throw new Error("Markdownからリスト項目・見出しが見つかりませんでした。");
+        }
+        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, parsed.nodes, targetParentId, map.header.isTodo);
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            path: levelsPathResult,
+                            addedElementCount: parsed.nodes.length,
+                            checkboxIgnored: !map.header.isTodo && parsed.hasCheckbox,
+                        }, 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, parsed.nodes, 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, parsed.nodes, 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,
+                        checkboxIgnored: !map.header.isTodo && parsed.hasCheckbox,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/src/tools/listElements.js

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { getContext } from "../mcpContext.js";
+import { resolveMap, levelsPathOf } from "../domain/mapResolver.js";
+import { assertLevelsInitialized, buildTreeFromLevels, readAllLevelDocs, } from "../domain/levels.js";
+// ElementNodeの`done`を`checked`という名前で公開する(仕様書の用語に合わせる)。
+function toChecked(nodes) {
+    return nodes.map((n) => ({
+        id: n.id,
+        detail: n.detail,
+        checked: n.done,
+        children: toChecked(n.children),
+    }));
+}
+// マップの中身には秘匿情報が含まれ得るため、実際の要素を返す前に必ず本人の
+// 明示的な許可を得る。このサーバープロセスが生きている間(概ね1会話)、
+// 同じマップへの確認は1回でよい。
+//
+// 当初はMCP標準のelicitInputで確認していたが、接続クライアントが対応を
+// 広告していても実際にはダイアログを一切出さないまま失敗することがあり
+// (2026-09-03、Claude Codeデスクトップアプリで確認)、本人が一度も確認画面を
+// 見ないまま恒久的に読み取り不能になる不具合があった。ホストごとの
+// elicitation対応状況に依存しない、呼び出し側(Claude等)への文面提示+
+// confirmedパラメータの方式に一本化した。呼び出し側が実際にユーザーへ
+// 確認したかをこちらで検証する手段は無いため、確実な強制ではなく
+// ベストエフォートであることを理解した上で採用している。
+const confirmedMapIds = new Set();
+function buildConfirmationRequestText(title) {
+    return (`「${title}」の中身を読み取る前に、ユーザー本人に直接「中身を確認してよいか」と` +
+        "尋ねてください。まだ実データは返していません。同意が得られたら、confirmed: true を" +
+        "付けてこのツールを再度呼び出してください。");
+}
+class AiReadDeniedError extends Error {
+    constructor(title) {
+        super(`「${title}」はAIからの読み取りが「常に拒否」に設定されているため、このツールでは読めません。` +
+            "読む必要がある場合は、アプリのマップ編集画面で設定を変更するようユーザーに伝えてください。");
+        this.name = "AiReadDeniedError";
+    }
+}
+export function registerListElements(server) {
+    server.tool("list_elements", "指定したマップ内の全要素と親子関係、チェック状態(checked)を返す。" +
+        "checkedは各要素にFirestoreへ実際に保存されている生の値であり、" +
+        "「祖先がチェック済みなら配下も完了とみなす」という加工は行っていない。" +
+        "そう解釈したい場合は、返ってきたツリーを見てこちら(呼び出す側)で判断すること。" +
+        "マップの中身には秘匿情報が含まれ得るため、初めて読むマップでは呼び出し前に" +
+        "ユーザー本人の許可が必要。confirmed: trueを付けずに呼ぶと、このツールは" +
+        "実データを返す代わりに確認を促すメッセージだけを返すので、その指示に従って" +
+        "ユーザーに直接確認してからconfirmed: trueで呼び直すこと。" +
+        "アプリ側での直接の編集はこのツールを呼ぶまで反映されないため、" +
+        "ユーザーから進捗や状態を尋ねられたときは記憶に頼らず必ず呼び直すこと。", {
+        mapId: z.string().describe("list_mapsで得たマップのID"),
+        confirmed: z
+            .boolean()
+            .optional()
+            .describe("ユーザー本人に直接「中身を確認してよいか」と尋ね、同意を得てからtrueを付けて呼ぶこと。" +
+            "確認前にtrueを付けてはならない。"),
+    }, async ({ mapId, confirmed }) => {
+        const { client, session } = getContext();
+        const map = await resolveMap(client, session, mapId);
+        // マップ単位のAI読み取り許可(aiReadPermission)。このフィールドは
+        // アプリのマップ編集画面からのみ変更でき、MCPサーバーのどの
+        // ツールからも書き込まない(AIが自分自身に許可を与えられると
+        // 確認の仕組みが意味を失うため)。
+        if (map.header.aiReadPermission === "deny") {
+            throw new AiReadDeniedError(map.header.title);
+        }
+        const alwaysAllowed = map.header.aiReadPermission === "allow";
+        // 未確認のマップでは、確認を促す文面だけを返して終える。levelsの
+        // 実データはこのゲートを通過するまで一切読みに行かない
+        // (以前はlevels/rootの存在確認のために先に読んでしまっていたが、
+        // 「実際の要素を返す前に必ず本人の明示的な許可を得る」という設計
+        // 意図に反するため、確認ゲートの後に読む順序へ戻した)。
+        if (!alwaysAllowed && !confirmedMapIds.has(mapId)) {
+            if (confirmed === true) {
+                confirmedMapIds.add(mapId);
+            }
+            else {
+                return { content: [{ type: "text", text: buildConfirmationRequestText(map.header.title) }] };
+            }
+        }
+        const levelsById = await readAllLevelDocs(client, levelsPathOf(map));
+        assertLevelsInitialized(levelsById, map.header.title);
+        const tree = buildTreeFromLevels(levelsById);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        mapId: map.headerId,
+                        title: map.header.title,
+                        isTodo: map.header.isTodo,
+                        elements: toChecked(tree),
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/src/tools/listMaps.js

@@ -0,0 +1,47 @@
+import { getContext } from "../mcpContext.js";
+import { canEditHeader, headerFromFirestore } from "../domain/header.js";
+export function registerListMaps(server) {
+    server.tool("list_maps", "自分のMatryoshka Mind Mapの全マップ(タイトル・ID・TODOかどうか)を返す。" +
+        "他のツールでmapIdを指定する前に、まずこれで存在するマップとそのIDを確認する。" +
+        "自分が所有するマップに加え、他のユーザーから共有されて見えているマップも含む" +
+        "(共有マップのroleが'viewer'の場合は閲覧のみで、書き込み系ツールは使えない)。" +
+        "アプリ側での直接の編集(新規マップ作成等)はこのツールを呼ぶまで反映されないため、" +
+        "ユーザーから状態を尋ねられたときは記憶に頼らず必ず呼び直すこと。", {}, async () => {
+        const { client, session } = getContext();
+        const own = await client.listDocuments(`users/${session.uid}/headers`);
+        const ownMaps = own.map((doc) => {
+            const header = headerFromFirestore(doc.id, session.uid, doc.data);
+            return {
+                id: header.id,
+                title: header.title,
+                isTodo: header.isTodo,
+                shared: false,
+            };
+        });
+        const refs = await client.listDocuments(`users/${session.uid}/refs`);
+        const sharedMaps = (await Promise.all(refs.map(async (ref) => {
+            const ownerUid = ref.data.userId;
+            const headerId = ref.data.headerId;
+            if (typeof ownerUid !== "string" || typeof headerId !== "string") {
+                return null; // 壊れたrefsは無視する
+            }
+            const doc = await client.getDocument(`users/${ownerUid}/headers/${headerId}`);
+            if (!doc)
+                return null; // 共有元で削除済み
+            const header = headerFromFirestore(headerId, ownerUid, doc.data);
+            const ownerDoc = await client.getDocument(`users/${ownerUid}`);
+            return {
+                id: header.id,
+                title: header.title,
+                isTodo: header.isTodo,
+                shared: true,
+                role: canEditHeader(header, session.uid, session.email) ? "editor" : "viewer",
+                ownerEmail: ownerDoc?.data.email ?? null,
+            };
+        }))).filter((m) => m !== null);
+        const maps = [...ownMaps, ...sharedMaps];
+        return {
+            content: [{ type: "text", text: JSON.stringify({ maps }, null, 2) }],
+        };
+    });
+}

package/dist/src/tools/moveElement.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { getContext } from "../mcpContext.js";
+import { isLevelsOnly, readLevelsSnapshot } from "../domain/levelsMode.js";
+import { ancestorDetailsInLevels, buildLevelsMoveWrites, locateInLevels } from "../domain/levelsOps.js";
+import { resolveMap, bodiesPathOf, levelsPathOf, formatPath, assertCanEditMap, } from "../domain/mapResolver.js";
+import { bodyFromFirestore, ancestorDetails } from "../domain/body.js";
+import { assertLevelsRootExists, levelsDocExists } from "../domain/levels.js";
+import { buildMoveElementWrites } from "../domain/moveElement.js";
+export function registerMoveElement(server) {
+    server.tool("move_element", "既存マップの要素1件(配下ごと)を、同じマップ内の別の場所へ移動する。" +
+        "階層をまたいだ移動(昇格・降格)も、同じ階層内の並べ替えも、これ1つで行える。", {
+        mapId: z.string().describe("list_mapsで得たマップのID"),
+        elementId: z.string().describe("移動する要素のID"),
+        newParentElementId: z
+            .string()
+            .nullable()
+            .describe("移動先の親要素のID。マップの最上位へ移動する場合はnull"),
+        afterElementId: z
+            .string()
+            .nullable()
+            .describe("移動先の中で、このIDの要素の直後に置く。先頭に置く場合はnull"),
+    }, async ({ mapId, elementId, newParentElementId, afterElementId }) => {
+        const { client, session } = getContext();
+        const map = await resolveMap(client, session, mapId);
+        assertCanEditMap(map, session);
+        const levelsPath = levelsPathOf(map);
+        const bodiesPath = bodiesPathOf(map);
+        assertLevelsRootExists(await levelsDocExists(client, levelsPath, "root"), map.header.title);
+        if (elementId === newParentElementId) {
+            throw new Error("要素を自分自身の子にすることはできません。");
+        }
+        if (elementId === afterElementId) {
+            throw new Error("afterElementIdにelementId自身は指定できません。");
+        }
+        if (await isLevelsOnly(client)) {
+            let levelsPathResult = null;
+            await client.runOptimistic(async () => {
+                const snapshot = await readLevelsSnapshot(client, levelsPath, map.header.title);
+                if (afterElementId !== null && !locateInLevels(snapshot, afterElementId)) {
+                    throw new Error(`afterElementId(${afterElementId})がこのマップに見つかりません。`);
+                }
+                const writes = buildLevelsMoveWrites(levelsPath, snapshot, elementId, newParentElementId, afterElementId);
+                levelsPathResult = formatPath(map.header.title, ancestorDetailsInLevels(snapshot, newParentElementId));
+                return writes;
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ path: levelsPathResult }, null, 2) }],
+            };
+        }
+        let path = null;
+        await client.runOptimistic(async () => {
+            const existingDocs = await client.listDocuments(bodiesPath);
+            const existingBodies = existingDocs.map((d) => bodyFromFirestore(d.id, d.data, d.updateTime));
+            const byId = new Map(existingBodies.map((b) => [b.id, b]));
+            const body = byId.get(elementId);
+            if (!body) {
+                throw new Error(`elementId(${elementId})がこのマップに見つかりません。list_elementsで確認してください。`);
+            }
+            if (newParentElementId !== null && !byId.has(newParentElementId)) {
+                throw new Error(`newParentElementId(${newParentElementId})がこのマップに見つかりません。`);
+            }
+            if (afterElementId !== null && !byId.has(afterElementId)) {
+                throw new Error(`afterElementId(${afterElementId})がこのマップに見つかりません。`);
+            }
+            // 移動先が自分自身の配下(子孫)だと、木構造が壊れる(循環になる)。
+            for (let cur = newParentElementId; cur !== null; cur = byId.get(cur)?.parent ?? null) {
+                if (cur === elementId) {
+                    throw new Error("要素を自分自身の配下(子孫)の中へ移動することはできません。");
+                }
+            }
+            const writes = await buildMoveElementWrites(client, bodiesPath, levelsPath, existingBodies, elementId, newParentElementId, afterElementId);
+            path = formatPath(map.header.title, newParentElementId === null
+                ? []
+                : ancestorDetails(existingBodies, newParentElementId));
+            return writes;
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify({ path }, null, 2) }],
+        };
+    });
+}

package/dist/src/tools/updateTaskStatus.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { getContext } from "../mcpContext.js";
+import { isLevelsOnly, readLevelsSnapshot } from "../domain/levelsMode.js";
+import { ancestorDetailsInLevels, buildLevelsPatchWrites } from "../domain/levelsOps.js";
+import { resolveMap, bodiesPathOf, levelsPathOf, formatPath, assertCanEditMap, } from "../domain/mapResolver.js";
+import { bodyFromFirestore, ancestorDetails } from "../domain/body.js";
+import { mergeWritesByPath } from "../firestore/restClient.js";
+import { assertLevelsRootExists, buildUpdateEntryWrites, levelsDocExists } from "../domain/levels.js";
+export function registerUpdateTaskStatus(server) {
+    server.tool("update_task_status", "TODOマップの要素のチェック状態を書き換える。1件でも複数件でもよい。" +
+        "「親をチェックすると配下も完了扱いになる」というアプリ内の表示上の挙動は" +
+        "このツールでは再現しない(指定した要素だけを書き換える、配下への自動連鎖はしない)。" +
+        "配下も揃えたい場合は、対象の要素をすべてupdatesに列挙すること。", {
+        mapId: z.string().describe("list_mapsで得たマップのID"),
+        updates: z
+            .array(z.object({
+            elementId: z.string().describe("list_elementsで得た要素のID"),
+            checked: z.boolean().describe("設定するチェック状態"),
+        }))
+            .min(1),
+    }, async ({ mapId, updates }) => {
+        const { client, session } = getContext();
+        const map = await resolveMap(client, session, mapId);
+        assertCanEditMap(map, session);
+        if (!map.header.isTodo) {
+            throw new Error(`「${map.header.title}」はTODOマップではないため、チェック状態を持ちません。`);
+        }
+        const levelsPath = levelsPathOf(map);
+        const bodiesPath = bodiesPathOf(map);
+        if (await isLevelsOnly(client)) {
+            let levelsResults = [];
+            await client.runOptimistic(async () => {
+                const snapshot = await readLevelsSnapshot(client, levelsPath, map.header.title);
+                const { writes, found } = buildLevelsPatchWrites(levelsPath, snapshot, updates.map((u) => ({ elementId: u.elementId, patch: { done: u.checked } })));
+                levelsResults = updates.map((u) => ({
+                    elementId: u.elementId,
+                    path: found.has(u.elementId)
+                        ? formatPath(map.header.title, ancestorDetailsInLevels(snapshot, u.elementId))
+                        : null,
+                    checked: u.checked,
+                    found: found.has(u.elementId),
+                }));
+                return writes;
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ results: levelsResults }, null, 2) }],
+            };
+        }
+        // 読み取り(bodies一覧・levelsの該当ドキュメント)から書き込みまでを
+        // 楽観的ロックでまとめる。読み取り後に他の操作が同じlevelsドキュメントを
+        // 書き換えていた場合はコミットがFAILED_PRECONDITIONになり、
+        // 読み取りからやり直す(runOptimisticが自動でリトライする)。
+        let results = [];
+        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));
+            const byId = new Map(existingBodies.map((b) => [b.id, b]));
+            const writes = [];
+            const levelUpdates = [];
+            results = [];
+            for (const update of updates) {
+                const body = byId.get(update.elementId);
+                if (!body) {
+                    results.push({ elementId: update.elementId, path: null, checked: update.checked, found: false });
+                    continue;
+                }
+                writes.push({
+                    path: `${bodiesPath}/${update.elementId}`,
+                    fields: { done: update.checked },
+                });
+                levelUpdates.push({
+                    parentId: body.parent,
+                    elementId: update.elementId,
+                    patch: { done: update.checked },
+                });
+                const path = formatPath(map.header.title, ancestorDetails(existingBodies, update.elementId));
+                results.push({ elementId: update.elementId, path, checked: update.checked, found: true });
+            }
+            const levelWrites = await buildUpdateEntryWrites(client, levelsPath, levelUpdates);
+            return mergeWritesByPath([...writes, ...levelWrites]);
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify({ results }, null, 2) }],
+        };
+    });
+}