friday-mcp-v2 3.1.2 → 3.1.3

package/dist/mcp-server.js

@@ -14,7 +14,7 @@ import fetch from "node-fetch";
 import { randomUUID } from "node:crypto";
 import { readFileSync, statSync, realpathSync, appendFileSync, mkdirSync, existsSync, writeFileSync, renameSync } from "node:fs";
 import { execFile } from "node:child_process";
-import { resolve as resolvePath, sep, dirname, join as joinPath, extname } from "node:path";
+import { resolve as resolvePath, sep, dirname, join as joinPath, extname, basename } from "node:path";
 import { marked } from "marked";
 import { parse as parseHTML } from "node-html-parser";
 import os from "node:os";
@@ -586,15 +586,18 @@ function validateImageFile(filePath) {
     let stat;
     try { stat = statSync(resolved); }
     catch (e) {
-        if (e.code === 'ENOENT') throw new Error(`File not found: ${resolved}`);
-        throw new Error(`File access error: ${resolved} (${e.message})`);
+        if (e.code === 'ENOENT') throwToolError('FILE_NOT_FOUND', `File not found: ${resolved}`, false);
+        throwToolError('VALIDATION_ERROR', `File access error: ${resolved} (${e.message})`, false);
+    }
+    if (!stat.isFile()) {
+        throwToolError('VALIDATION_ERROR', `Not a file: ${resolved}`, false);
     }
     if (stat.size > MAX_IMAGE_SIZE_BYTES) {
-        throw new Error(`File too large: ${(stat.size / 1048576).toFixed(1)}MB (max: 10MB)`);
+        throwToolError('TOO_LARGE', `File too large: ${(stat.size / 1048576).toFixed(1)}MB (max: 10MB)`, false);
     }
-    const ext = resolved.slice(resolved.lastIndexOf('.')).toLowerCase();
+    const ext = extname(resolved).toLowerCase();
     if (!ALLOWED_IMAGE_EXTENSIONS.has(ext)) {
-        throw new Error(`Unsupported image format: ${ext} (allowed: ${[...ALLOWED_IMAGE_EXTENSIONS].join(', ')})`);
+        throwToolError('INVALID_MIME', `Unsupported image format: ${ext || '(none)'} (allowed: ${[...ALLOWED_IMAGE_EXTENSIONS].join(', ')})`, false);
     }
     const contentType = MIME_MAP[ext] || 'application/octet-stream';
     return { resolved, stat, ext, contentType };
@@ -722,14 +725,775 @@ function generateSearchVariants(query, strip = [], prefixes = []) {
     return [...variants];
 }
 
-function flattenFileBirdFolders(folders, result = []) {
-    for (const f of folders) {
-        result.push({ id: f.id, name: f.text || f.title || f.name || '', count: parseInt(f['data-count'], 10) || 0 });
-        if (f.children && f.children.length > 0) {
-            flattenFileBirdFolders(f.children, result);
+/**
+ * フォルダパス文字列の正規化 (T8)
+ * trim → NFC → 全角スラッシュ拒否 → 先頭末尾スラッシュ strip → 連続スラッシュ統合 → 空セグメント拒否
+ * @param {string} input パス文字列
+ * @returns {string} 正規化済みパス (ルート相対、先頭スラッシュなし)
+ */
+function normalizeFolderPath(input) {
+    if (typeof input !== 'string') {
+        throwToolError('VALIDATION_ERROR', 'フォルダパスは文字列で指定してください', false);
+    }
+    let s = input.trim().normalize('NFC');
+    if (s.includes('／')) {
+        throwToolError('VALIDATION_ERROR', `フォルダパスに全角スラッシュ "／" が含まれています。半角 "/" を使ってください: "${input}"`, false);
+    }
+    s = s.replace(/^\/+/, '').replace(/\/+$/, '').replace(/\/{2,}/g, '/');
+    if (s === '') {
+        throwToolError('VALIDATION_ERROR', 'フォルダパスが空です', false);
+    }
+    const segments = s.split('/').map(seg => seg.trim());
+    if (segments.some(seg => seg === '')) {
+        throwToolError('VALIDATION_ERROR', `フォルダパスに空のセグメントが含まれています: "${input}"`, false);
+    }
+    return segments.join('/');
+}
+
+/**
+ * FileBird /folders 生レスポンスを構造化 (T6)
+ * @param {object[]} rawFolders FileBird API の data.folders
+ * @param {number} uncategorizedCount Uncategorized 件数 (getFileBirdAttachmentCount(0) の値)
+ * @returns {{tree, byId, byPath, allNodes}}
+ *   tree: T6 スキーマのツリー (Uncategorized 先頭)
+ *   byId: Map<id, node>
+ *   byPath: Map<path, node[]> (通常フォルダのみ。同名兄弟は配列)
+ *   allNodes: フラット配列 (Uncategorized 先頭・含む)
+ */
+function normalizeFileBirdFolders(rawFolders, uncategorizedCount = 0) {
+    const byId = new Map();
+    const byPath = new Map();
+    const allNodes = [];
+
+    function walk(rawList, parentPath, parentId) {
+        const nodes = [];
+        for (const raw of rawList || []) {
+            const name = raw.text || raw.title || '';
+            const path = parentPath ? `${parentPath}/${name}` : name;
+            const node = {
+                id: raw.id,
+                name,
+                parentId,
+                path,
+                count: parseInt(raw['data-count'], 10) || 0,
+                isSystemFolder: false,
+                children: [],
+            };
+            byId.set(node.id, node);
+            if (!byPath.has(path)) byPath.set(path, []);
+            byPath.get(path).push(node);
+            allNodes.push(node);
+            node.children = walk(raw.children, path, node.id);
+            nodes.push(node);
         }
+        return nodes;
     }
-    return result;
+
+    // ルート直下フォルダの parentId は 0 (FileBird の parent=0)。
+    // id=0 は Uncategorized を指すが、buildFolderPath は parentId===0 をルート停止として扱い区別する。
+    const tree = walk(rawFolders, '', 0);
+
+    const uncategorized = {
+        id: 0,
+        name: '(未分類)',
+        parentId: null,
+        path: '',
+        count: uncategorizedCount,
+        isSystemFolder: true,
+        children: [],
+    };
+    byId.set(0, uncategorized);
+    allNodes.unshift(uncategorized);
+    tree.unshift(uncategorized);
+
+    return { tree, byId, byPath, allNodes };
+}
+
+/**
+ * パス文字列 → folder id
+ * 同名兄弟で複数マッチなら候補を path 併記でエラー (A4)
+ * @returns {number} folder id
+ */
+function resolveFolderPath(normalized, pathStr) {
+    const norm = normalizeFolderPath(pathStr);
+    if (norm === '') {
+        throwToolError('VALIDATION_ERROR', '空のフォルダパスは解決できません (ルート指定は folderId=0 を使用)', false);
+    }
+    const matches = normalized.byPath.get(norm);
+    if (!matches || matches.length === 0) {
+        const available = normalized.allNodes.filter(n => n.id !== 0).map(n => n.path).join(', ');
+        throwToolError('FOLDER_NOT_FOUND', `フォルダパス "${norm}" が見つかりません。利用可能: ${available}`, false);
+    }
+    if (matches.length > 1) {
+        const candidates = matches.map(n => `[ID: ${n.id}] ${n.path}`).join(', ');
+        throwToolError('VALIDATION_ERROR', `フォルダパス "${norm}" が複数のフォルダにマッチしました。folderId で一意に指定してください: ${candidates}`, false);
+    }
+    return matches[0].id;
+}
+
+/** folder id → パス文字列。0 (Uncategorized/ルート) は空文字 */
+function buildFolderPath(normalized, folderId) {
+    if (folderId === 0) return '';
+    const node = normalized.byId.get(folderId);
+    return node ? node.path : null;
+}
+
+/** パス文字列 → folder node (resolveFolderPath のラッパ) */
+function findFolderByPath(normalized, pathStr) {
+    const id = resolveFolderPath(normalized, pathStr);
+    return normalized.byId.get(id);
+}
+
+/**
+ * ルートフォルダから子孫を含む folder id 一覧を集める (Phase 2 recursive)
+ * 出力は folderId 昇順でソート (切り詰め契約と整合)。
+ * Uncategorized(0) は children を持たないため [0] を返す。
+ * @param {object} normalized normalizeFileBirdFolders の戻り値
+ * @param {number} rootFolderId 起点 folder id
+ * @returns {number[]} [rootId, ...全子孫 id] を昇順ソート
+ */
+function collectSubtreeFolderIds(normalized, rootFolderId) {
+    const root = normalized.byId.get(rootFolderId);
+    if (!root) return [];
+    const ids = [];
+    (function walk(node) {
+        ids.push(node.id);
+        for (const child of node.children || []) walk(child);
+    })(root);
+    return ids.sort((a, b) => a - b);
+}
+
+// Phase 2 search_media recursive の上限 (P2-5)
+const SEARCH_MAX_SCAN_FOLDERS = 200;   // 走査フォルダ数上限
+const SEARCH_MAX_UNION_IDS = 1000;     // union ID 総数上限
+const SEARCH_FETCH_CONCURRENCY = 5;    // attachment-id 取得並列度
+
+/**
+ * 複数フォルダの attachment-id を並列取得し、決定的順序 (folderId昇順→id昇順) で union する。
+ * null=取得失敗 と []=空フォルダ を区別する (中5)。
+ * @param {object} client WordPress クライアント
+ * @param {number[]} folderIds folderId 昇順想定の配列
+ * @returns {Promise<{unionIds:number[], fetchedFolderCount:number, failedFolderCount:number}>}
+ */
+async function fetchAttachmentIdsForFolders(client, folderIds) {
+    const perFolder = new Array(folderIds.length); // null=失敗, number[]=成功
+    let next = 0;
+    async function worker() {
+        while (next < folderIds.length) {
+            const i = next++;
+            try {
+                const ids = await client.getFileBirdAttachmentIds(folderIds[i]);
+                perFolder[i] = Array.isArray(ids) ? ids : null;
+            } catch {
+                perFolder[i] = null;
+            }
+        }
+    }
+    await Promise.all(
+        Array.from({ length: Math.min(SEARCH_FETCH_CONCURRENCY, folderIds.length) }, worker)
+    );
+
+    const seen = new Set();
+    const unionIds = [];
+    let fetchedFolderCount = 0;
+    let failedFolderCount = 0;
+    for (let i = 0; i < folderIds.length; i++) {
+        const ids = perFolder[i];
+        if (ids === null) { failedFolderCount++; continue; }
+        fetchedFolderCount++;
+        // FileBird の attachment_id は文字列で返るため Number 化（WP media の数値 id と突き合わせるため）
+        const numericIds = ids.map(Number).filter(n => Number.isInteger(n) && n > 0).sort((a, b) => a - b);
+        for (const id of numericIds) {
+            if (seen.has(id)) continue;
+            seen.add(id);
+            unionIds.push(id);
+        }
+    }
+    return { unionIds, fetchedFolderCount, failedFolderCount };
+}
+
+function toolError(code, message, retryable = false, extra = {}) {
+    return { code, message, retryable, ...extra };
+}
+
+function throwToolError(code, message, retryable = false, extra = {}) {
+    const err = new Error(message);
+    err.toolError = toolError(code, message, retryable, extra);
+    throw err;
+}
+
+function toToolError(error, fallbackCode = 'UNKNOWN') {
+    if (error?.toolError) return error.toolError;
+    if (error?.name === 'AbortError' || error?.name === 'TimeoutError') {
+        return toolError('TIMEOUT', error.message || 'Operation timed out', true);
+    }
+    const statusCode = error?.statusCode;
+    const wpErrorCode = error?.wpErrorCode || '';
+    if (statusCode === 401 || statusCode === 403 || wpErrorCode.includes('forbidden')) {
+        return toolError('PERMISSION_DENIED', error.message, false);
+    }
+    if (statusCode === 413) {
+        return toolError('TOO_LARGE', error.message, false);
+    }
+    if (statusCode === 404) {
+        return toolError('MEDIA_NOT_FOUND', error.message, false);
+    }
+    return toolError(fallbackCode, error?.message || String(error), true);
+}
+
+function jsonToolResponse(payload, isError = false) {
+    return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], ...(isError ? { isError: true } : {}) };
+}
+
+function jsonErrorResponse(error, fallbackCode = 'UNKNOWN') {
+    const err = toToolError(error, fallbackCode);
+    return jsonToolResponse({ success: false, error: err }, true);
+}
+
+function assertInteger(value, fieldName, { min = null, allowNegativeOne = false } = {}) {
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throwToolError('VALIDATION_ERROR', `${fieldName} は整数 number で指定してください`, false);
+    }
+    if (value === -1 && allowNegativeOne) return value;
+    if (min != null && value < min) {
+        throwToolError('VALIDATION_ERROR', `${fieldName} は ${min} 以上の整数で指定してください`, false);
+    }
+    return value;
+}
+
+function assertPositiveInteger(value, fieldName) {
+    return assertInteger(value, fieldName, { min: 1 });
+}
+
+function getTextValue(value) {
+    if (typeof value === 'string') return value;
+    if (value && typeof value === 'object') {
+        if (typeof value.raw === 'string') return value.raw;
+        if (typeof value.rendered === 'string') return value.rendered;
+    }
+    return '';
+}
+
+function formatMedia(media, folder = {}) {
+    return {
+        mediaId: media.id,
+        title: getTextValue(media.title),
+        alt: media.alt_text || '',
+        caption: getTextValue(media.caption),
+        description: getTextValue(media.description),
+        sourceUrl: media.source_url || '',
+        mimeType: media.mime_type || null,
+        folderId: folder.folderId ?? null,
+        folderPath: folder.folderPath ?? null,
+        fileSize: media.media_details?.filesize ?? null,
+        date: media.date_gmt || media.date || null,
+    };
+}
+
+async function getNormalizedFileBirdFolders(client) {
+    if (!client.filebirdToken) {
+        throwToolError('VALIDATION_ERROR', 'FileBird APIキーが未設定です。connections.json または .env に filebirdToken を追加してください', false);
+    }
+    const folders = await client.getFileBirdFolders();
+    if (!folders) {
+        throwToolError('FOLDER_NOT_FOUND', 'FileBird API へのアクセスに失敗しました', true);
+    }
+    const uncategorizedCount = (await client.getFileBirdAttachmentCount(0)) || 0;
+    return normalizeFileBirdFolders(folders, uncategorizedCount);
+}
+
+/**
+ * Phase 3: admin namespace (filebird/v1/get-folders) からツリーを取得して正規化する。
+ * public token を使わず App Password (wpCoreRequest) で認証する。
+ * admin tree は data-count を持たず件数は attachmentsCount.display (id→count・subtree込み) で
+ * 別途返るため、各ノードへ display をマージしてから既存 normalize に渡す。
+ * Phase 1/2 の public 経路 (getNormalizedFileBirdFolders) は変更しない並行実装。
+ */
+async function getNormalizedFileBirdFoldersAdmin(client) {
+    const res = await client.getFileBirdFoldersAdmin();
+    if (!res || !Array.isArray(res.tree)) {
+        throwToolError('FOLDER_NOT_FOUND', 'FileBird admin API (filebird/v1/get-folders) へのアクセスに失敗しました', true);
+    }
+    const display = (res.attachmentsCount && res.attachmentsCount.display) || {};
+    (function mergeCounts(nodes) {
+        for (const n of nodes || []) {
+            n['data-count'] = display[n.id] ?? 0;
+            if (Array.isArray(n.children)) mergeCounts(n.children);
+        }
+    })(res.tree);
+    // Uncategorized(id=0) は admin display に含まれない。Phase 3 は id=0 を操作対象にしないため 0 でよい。
+    return normalizeFileBirdFolders(res.tree, 0);
+}
+
+function getFolderNodeById(normalized, folderId, fieldName = 'folderId') {
+    if (folderId === -1) {
+        throwToolError('VALIDATION_ERROR', `${fieldName}=-1 は All 相当の予約値のため指定できません`, false);
+    }
+    if (folderId === 0) return normalized.byId.get(0);
+    const node = normalized.byId.get(folderId);
+    if (!node) {
+        throwToolError('FOLDER_NOT_FOUND', `${fieldName} ${folderId} が見つかりません`, false);
+    }
+    return node;
+}
+
+function resolveFolderTarget(normalized, { folder, folderId }) {
+    const hasFolder = folder !== undefined && folder !== null;
+    const hasFolderId = folderId !== undefined && folderId !== null;
+    if (!hasFolder && !hasFolderId) {
+        throwToolError('VALIDATION_ERROR', 'folder または folderId のどちらかは必須です', false);
+    }
+
+    let pathId = null;
+    if (hasFolder) {
+        pathId = resolveFolderPath(normalized, folder);
+    }
+
+    let idNode = null;
+    if (hasFolderId) {
+        assertInteger(folderId, 'folderId', { min: -1, allowNegativeOne: true });
+        idNode = getFolderNodeById(normalized, folderId, 'folderId');
+    }
+
+    if (hasFolder && hasFolderId && pathId !== folderId) {
+        throwToolError('VALIDATION_ERROR', `指定された folderId (${folderId}) と folder path (${folder}) が一致しません`, false, { pathResolvedFolderId: pathId });
+    }
+
+    const id = hasFolderId ? folderId : pathId;
+    const node = hasFolderId ? idNode : getFolderNodeById(normalized, id, 'folder');
+    return { id, node, path: node?.path ?? '' };
+}
+
+function resolveParentTarget(normalized, { parent, parentId }) {
+    const hasParent = parent !== undefined && parent !== null;
+    const hasParentId = parentId !== undefined && parentId !== null;
+    if (!hasParent && !hasParentId) {
+        const node = normalized.byId.get(0);
+        return { id: 0, node, path: '' };
+    }
+
+    let pathId = null;
+    if (hasParent) {
+        pathId = resolveFolderPath(normalized, parent);
+    }
+
+    let idNode = null;
+    if (hasParentId) {
+        assertInteger(parentId, 'parentId', { min: 0 });
+        idNode = getFolderNodeById(normalized, parentId, 'parentId');
+    }
+
+    if (hasParent && hasParentId && pathId !== parentId) {
+        throwToolError('VALIDATION_ERROR', `指定された parentId (${parentId}) と parent path (${parent}) が一致しません`, false, { pathResolvedParentId: pathId });
+    }
+
+    const id = hasParentId ? parentId : pathId;
+    const node = hasParentId ? idNode : getFolderNodeById(normalized, id, 'parent');
+    return { id, node, path: node?.path ?? '' };
+}
+
+async function getExistingMediaByIds(client, mediaIds) {
+    const ids = Array.isArray(mediaIds) ? mediaIds : [mediaIds];
+    if (ids.length === 0) {
+        throwToolError('VALIDATION_ERROR', 'mediaIds は1件以上指定してください', false);
+    }
+    if (ids.length > 100) {
+        throwToolError('VALIDATION_ERROR', 'mediaIds は1コール最大100件までです', false);
+    }
+    for (const id of ids) assertPositiveInteger(id, 'mediaId');
+
+    const media = await client.getMediaByIds(ids);
+    const found = new Set((media || []).map(item => item.id));
+    const missing = ids.filter(id => !found.has(id));
+    if (missing.length > 0) {
+        throwToolError('MEDIA_NOT_FOUND', '存在しない mediaId が含まれています', false, { missingMediaIds: missing });
+    }
+    return media;
+}
+
+async function findMediaFolder(client, normalized, mediaId) {
+    if (!client.filebirdToken) {
+        return { folderId: null, folderPath: null, warning: toolError('VALIDATION_ERROR', 'FileBird APIキーが未設定のため folder 情報は取得していません', false) };
+    }
+    const nodes = normalized.allNodes.filter(node => !node.isSystemFolder);
+    for (const node of nodes) {
+        const ids = await client.getFileBirdAttachmentIds(node.id);
+        if ((ids || []).map(Number).includes(mediaId)) {
+            return { folderId: node.id, folderPath: node.path };
+        }
+    }
+    const uncategorizedIds = await client.getFileBirdAttachmentIds(0);
+    if ((uncategorizedIds || []).map(Number).includes(mediaId)) {
+        return { folderId: 0, folderPath: '' };
+    }
+    return { folderId: 0, folderPath: '' };
+}
+
+const MAX_UPLOAD_FILES = 20;
+const MAX_ASP_BULK = 30;
+const MAX_UPLOAD_TOTAL_BYTES = 50 * 1024 * 1024;
+const DEFAULT_UPLOAD_CONCURRENCY = 3;
+const MAX_UPLOAD_CONCURRENCY = 5;
+const UPLOAD_FILE_TIMEOUT_MS = 30_000;
+const UPLOAD_TOTAL_TIMEOUT_MS = 5 * 60_000;
+
+function isProvided(value) {
+    return value !== undefined && value !== null;
+}
+
+function requireString(value, fieldName, { allowEmpty = false } = {}) {
+    if (typeof value !== 'string') {
+        throwToolError('VALIDATION_ERROR', `${fieldName} は文字列で指定してください`, false);
+    }
+    if (!allowEmpty && value.trim() === '') {
+        throwToolError('VALIDATION_ERROR', `${fieldName} は空にできません`, false);
+    }
+    return value;
+}
+
+function optionalString(value, fieldName) {
+    if (!isProvided(value)) return undefined;
+    if (typeof value !== 'string') {
+        throwToolError('VALIDATION_ERROR', `${fieldName} は文字列で指定してください。null は使用できません`, false);
+    }
+    return value;
+}
+
+function validateUploadMode(args = {}) {
+    const hasFilePath = isProvided(args.filePath);
+    const hasFiles = isProvided(args.files);
+    if (hasFilePath && hasFiles) {
+        throwToolError('VALIDATION_ERROR', 'filePath と files は同時指定できません', false);
+    }
+    if (!hasFilePath && !hasFiles) {
+        throwToolError('VALIDATION_ERROR', 'filePath または files のどちらかは必須です', false);
+    }
+    return hasFiles ? 'batch' : 'single';
+}
+
+function filenameStem(filePath) {
+    const base = basename(resolvePath(filePath));
+    const ext = extname(base);
+    return ext ? base.slice(0, -ext.length) : base;
+}
+
+function normalizeUploadItems(args, mode) {
+    if (mode === 'single') {
+        const warnings = [];
+        if (isProvided(args.concurrency)) {
+            warnings.push(toolError('VALIDATION_ERROR', '単一モードでは concurrency は無効なため無視しました', false));
+        }
+        const filePath = requireString(args.filePath, 'filePath');
+        const name = requireString(args.name, 'name').trim();
+        const alt = requireString(args.alt, 'alt');
+        return [{
+            index: 0,
+            filePath,
+            name,
+            alt,
+            title: optionalString(args.title, 'title') ?? alt,
+            caption: optionalString(args.caption, 'caption'),
+            description: optionalString(args.description, 'description'),
+            warnings,
+        }];
+    }
+
+    if (!Array.isArray(args.files)) {
+        throwToolError('VALIDATION_ERROR', 'files は配列で指定してください', false);
+    }
+    if (args.files.length === 0) {
+        throwToolError('VALIDATION_ERROR', 'files は1件以上指定してください', false);
+    }
+    if (args.files.length > MAX_UPLOAD_FILES) {
+        throwToolError('VALIDATION_ERROR', `files は1コール最大${MAX_UPLOAD_FILES}件までです`, false);
+    }
+
+    return args.files.map((file, index) => {
+        if (!file || typeof file !== 'object' || Array.isArray(file)) {
+            throwToolError('VALIDATION_ERROR', `files[${index}] は object で指定してください`, false);
+        }
+        const filePath = requireString(file.filePath, `files[${index}].filePath`);
+        const warnings = [];
+        const rawName = optionalString(file.name, `files[${index}].name`);
+        const name = rawName && rawName.trim() ? rawName.trim() : filenameStem(filePath);
+        const altProvided = Object.prototype.hasOwnProperty.call(file, 'alt');
+        const alt = altProvided ? optionalString(file.alt, `files[${index}].alt`) : '';
+        if (!altProvided) {
+            warnings.push(toolError('VALIDATION_ERROR', 'alt が未指定のため空文字でアップロードします', false));
+        }
+        return {
+            index,
+            filePath,
+            name,
+            alt,
+            title: optionalString(file.title, `files[${index}].title`) ?? name,
+            caption: optionalString(file.caption, `files[${index}].caption`),
+            description: optionalString(file.description, `files[${index}].description`),
+            warnings,
+        };
+    });
+}
+
+function getUploadConcurrency(args, mode) {
+    if (mode === 'single') return 1;
+    if (!isProvided(args.concurrency)) return DEFAULT_UPLOAD_CONCURRENCY;
+    const concurrency = assertInteger(args.concurrency, 'concurrency', { min: 1 });
+    if (concurrency > MAX_UPLOAD_CONCURRENCY) {
+        throwToolError('VALIDATION_ERROR', `concurrency は最大${MAX_UPLOAD_CONCURRENCY}です`, false);
+    }
+    return concurrency;
+}
+
+function prepareUploadItems(items) {
+    const seenPaths = new Map();
+    let totalBytes = 0;
+    for (const item of items) {
+        const resolved = resolvePath(item.filePath);
+        item.resolvedPath = resolved;
+        if (seenPaths.has(resolved)) {
+            item.warnings.push(toolError('VALIDATION_ERROR', `同一 filePath が重複しています (firstIndex=${seenPaths.get(resolved)})`, false));
+        } else {
+            seenPaths.set(resolved, item.index);
+        }
+        try {
+            const stat = statSync(resolved);
+            if (!stat.isFile()) {
+                item.preError = toolError('VALIDATION_ERROR', `Not a file: ${resolved}`, false);
+                continue;
+            }
+            totalBytes += stat.size;
+            try {
+                item.fileInfo = validateImageFile(item.filePath);
+            } catch (e) {
+                item.preError = toToolError(e);
+            }
+        } catch (e) {
+            item.preError = e.code === 'ENOENT'
+                ? toolError('FILE_NOT_FOUND', `File not found: ${resolved}`, false)
+                : toolError('VALIDATION_ERROR', `File access error: ${resolved} (${e.message})`, false);
+        }
+    }
+    if (totalBytes > MAX_UPLOAD_TOTAL_BYTES) {
+        throwToolError('TOO_LARGE', `Total upload size too large: ${(totalBytes / 1048576).toFixed(1)}MB (max: 50MB)`, false);
+    }
+    return items;
+}
+
+function buildUploadMetaData(item) {
+    const data = { title: item.title, alt_text: item.alt };
+    if (item.caption !== undefined) data.caption = item.caption;
+    if (item.description !== undefined) data.description = item.description;
+    return data;
+}
+
+async function createMissingUploadFolder(client, normalized, folderPath) {
+    let normalizedPath;
+    try {
+        normalizedPath = normalizeFolderPath(folderPath);
+    } catch (e) {
+        throwToolError('VALIDATION_ERROR', e.message, false);
+    }
+    const segments = normalizedPath.split('/');
+    const folderName = segments[segments.length - 1];
+    const parentPath = segments.slice(0, -1).join('/');
+    let parent;
+    if (parentPath) {
+        let parentId;
+        try {
+            parentId = resolveFolderPath(normalized, parentPath);
+        } catch (_e) {
+            throwToolError('FOLDER_NOT_FOUND', `createIfMissing は最後の1セグメントのみ作成できます。親フォルダ "${parentPath}" が存在しません`, false);
+        }
+        parent = getFolderNodeById(normalized, parentId, 'parent');
+    } else {
+        parent = normalized.byId.get(0);
+    }
+
+    const existing = normalized.allNodes.find(node =>
+        !node.isSystemFolder && node.parentId === parent.id && node.name === folderName
+    );
+    if (existing) {
+        return { id: existing.id, node: existing, path: existing.path, created: false };
+    }
+
+    const created = await client.createFileBirdFolder(folderName, parent.id);
+    if (!created?.id) {
+        throwToolError('UNKNOWN', 'FileBird フォルダ作成 API が id を返しませんでした', true);
+    }
+
+    const after = await getNormalizedFileBirdFolders(client);
+    const node = after.byId.get(created.id);
+    const expectedPath = parent.path ? `${parent.path}/${folderName}` : folderName;
+    if (!node || node.name !== folderName || node.parentId !== parent.id || node.path !== expectedPath) {
+        throwToolError('DUPLICATE_FOLDER_NAME', '作成後検証でフォルダ名またはパスが期待値と一致しません。FileBird が同名フォルダを自動リネームした可能性があります', false, {
+            expected: { name: folderName, parentId: parent.id, path: expectedPath },
+            actualFolder: node ? { id: node.id, name: node.name, parentId: node.parentId, path: node.path, count: node.count } : null,
+            recoveryHint: 'WordPress 管理画面で actualFolder を確認し、必要なら手動整理してください',
+        });
+    }
+    return { id: node.id, node, path: node.path, created: true };
+}
+
+async function resolveUploadFolder(client, args = {}) {
+    const hasFolder = isProvided(args.folder);
+    const hasFolderId = isProvided(args.folderId);
+    const createIfMissing = args.createIfMissing === true;
+    if (isProvided(args.createIfMissing) && typeof args.createIfMissing !== 'boolean') {
+        throwToolError('VALIDATION_ERROR', 'createIfMissing は boolean で指定してください', false);
+    }
+    if (!hasFolder && !hasFolderId) {
+        if (createIfMissing) {
+            throwToolError('VALIDATION_ERROR', 'createIfMissing=true の場合は folder を指定してください', false);
+        }
+        return null;
+    }
+    if (createIfMissing && !hasFolder) {
+        throwToolError('VALIDATION_ERROR', 'folderId のみ指定時は createIfMissing を使用できません', false);
+    }
+    if (hasFolder && typeof args.folder !== 'string') {
+        throwToolError('VALIDATION_ERROR', 'folder は文字列で指定してください', false);
+    }
+
+    const normalized = await getNormalizedFileBirdFolders(client);
+    try {
+        return resolveFolderTarget(normalized, { folder: args.folder, folderId: args.folderId });
+    } catch (e) {
+        if (!createIfMissing) {
+            if (e?.toolError) throw e;
+            throwToolError('FOLDER_NOT_FOUND', e.message, false);
+        }
+        if (e?.toolError?.code === 'VALIDATION_ERROR') {
+            throw e;
+        }
+        if (hasFolderId) {
+            throwToolError('VALIDATION_ERROR', 'folder + folderId 指定時に folder が存在しないため createIfMissing できません', false);
+        }
+        return createMissingUploadFolder(client, normalized, args.folder);
+    }
+}
+
+async function runWithConcurrency(items, concurrency, worker, deadline = null) {
+    const results = new Array(items.length);
+    let next = 0;
+    async function run() {
+        while (next < items.length) {
+            const current = next++;
+            const item = items[current];
+            if (deadline && Date.now() >= deadline) {
+                results[current] = {
+                    index: item.index,
+                    success: false,
+                    filePath: item.filePath,
+                    error: toolError('TIMEOUT', 'upload_media の全体タイムアウトに達したため、このファイルは開始されませんでした', true),
+                    warnings: item.warnings || [],
+                };
+                continue;
+            }
+            try {
+                results[current] = await worker(item);
+            } catch (error) {
+                results[current] = {
+                    index: item.index,
+                    success: false,
+                    filePath: item.filePath,
+                    error: toToolError(error),
+                    warnings: item.warnings || [],
+                };
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, run));
+    return results;
+}
+
+async function uploadOneMedia(client, item) {
+    const warnings = [...(item.warnings || [])];
+    if (item.preError) {
+        return { index: item.index, success: false, filePath: item.filePath, error: item.preError, warnings };
+    }
+
+    let fileInfo;
+    try {
+        fileInfo = item.fileInfo || validateImageFile(item.filePath);
+    } catch (e) {
+        return { index: item.index, success: false, filePath: item.filePath, error: toToolError(e), warnings };
+    }
+
+    let media;
+    const uploadFilename = `${item.name}${fileInfo.ext}`;
+    try {
+        const fileBuffer = readFileSync(fileInfo.resolved);
+        media = await client.uploadMedia(fileBuffer, uploadFilename, fileInfo.contentType, { timeoutMs: UPLOAD_FILE_TIMEOUT_MS });
+    } catch (e) {
+        return { index: item.index, success: false, filePath: item.filePath, error: toToolError(e), warnings };
+    }
+
+    try {
+        await client.updateMediaMeta(media.id, buildUploadMetaData(item));
+    } catch (e) {
+        warnings.push(toToolError(e));
+    }
+
+    return {
+        index: item.index,
+        success: true,
+        mediaId: media.id,
+        sourceUrl: media.source_url || '',
+        filePath: item.filePath,
+        filename: uploadFilename,
+        title: item.title,
+        alt: item.alt,
+        width: media.media_details?.width || null,
+        height: media.media_details?.height || null,
+        folderId: null,
+        folderPath: null,
+        folderAssignmentSuccess: null,
+        warnings,
+    };
+}
+
+async function applyFolderAssignment(client, results, targetFolder) {
+    if (!targetFolder) return results;
+    const successResults = results.filter(result => result?.success && result.mediaId);
+    if (successResults.length === 0) return results;
+
+    let ok = false;
+    let assignmentError = null;
+    try {
+        ok = await client.setFileBirdAttachmentFolder(successResults.map(result => result.mediaId), targetFolder.id);
+        if (ok !== true) {
+            assignmentError = toolError('FILEBIRD_SET_ATTACHMENT_FAILED', 'アップロードは成功しましたが FileBird フォルダ割当に失敗しました', true);
+        }
+    } catch (e) {
+        assignmentError = toToolError(e, 'FILEBIRD_SET_ATTACHMENT_FAILED');
+        assignmentError.code = assignmentError.code === 'UNKNOWN' ? 'FILEBIRD_SET_ATTACHMENT_FAILED' : assignmentError.code;
+        assignmentError.retryable = assignmentError.retryable ?? true;
+    }
+
+    for (const result of successResults) {
+        if (ok === true) {
+            result.folderId = targetFolder.id;
+            result.folderPath = targetFolder.path;
+            result.folderAssignmentSuccess = true;
+        } else {
+            result.folderId = null;
+            result.folderPath = null;
+            result.folderAssignmentSuccess = false;
+            result.folderAssignmentError = {
+                ...assignmentError,
+                recoveryHint: `move_media_to_folder で mediaId ${result.mediaId} を folderId ${targetFolder.id} に移動可能`,
+            };
+        }
+    }
+    return results;
+}
+
+function buildUploadSummary(results) {
+    const total = results.length;
+    const succeeded = results.filter(result => result?.success).length;
+    const failed = total - succeeded;
+    const folderAssignmentFailed = results.filter(result => result?.success && result.folderAssignmentSuccess === false).length;
+    return { total, succeeded, failed, folderAssignmentFailed };
 }
 
 /**
@@ -1986,14 +2750,26 @@ function buildBatchDiffInfo(resolvedOps, snapshot) {
  * @param {string} siteName
  * @param {string} _modeTag
  * @param {string} toolName
+ * @param {string} [expectedRevision]
+ * @param {object} [options]
+ * @param {object} [options.preFetchedState] - 呼び出し元が同一 tick で取得済みの currentState を渡せば、
+ *   内部の getCurrentStructure 再実行をスキップして使い回す（重複取得の回避）。
+ *   渡す側は「revision check 済み or 同 tick の state」であることを保証する責任を負う。
+ * @returns {Promise<{content:Array, isError?:boolean, _structuredResult?:object}>}
+ *   成功時は _structuredResult.operations[].status ('updated'|'expanded'|'failed'|'skipped') と
+ *   snapshot/successCount/totalCount を含む。エラー早期 return では _structuredResult は付かない。
  */
-async function handleBatchOperations(operations, snapshotId, mode, client, postId, sessionId, siteName, _modeTag, toolName, expectedRevision) {
+async function handleBatchOperations(operations, snapshotId, mode, client, postId, sessionId, siteName, _modeTag, toolName, expectedRevision, options = {}) {
     // 1. 全 operation の target を正規化 & ref を一括解決
     let currentState;
-    try {
-        currentState = await getCurrentStructure(mode, client, postId, sessionId, { safetyCritical: true });
-    } catch (e) {
-        return { content: [{ type: "text", text: `❌ 現在のブロック構造を取得できませんでした: ${e.message}` }], isError: true };
+    if (options.preFetchedState && Array.isArray(options.preFetchedState.allBlocks)) {
+        currentState = options.preFetchedState;
+    } else {
+        try {
+            currentState = await getCurrentStructure(mode, client, postId, sessionId, { safetyCritical: true });
+        } catch (e) {
+            return { content: [{ type: "text", text: `❌ 現在のブロック構造を取得できませんでした: ${e.message}` }], isError: true };
+        }
     }
 
     // revision 楽観的ロック（expectedRevision が指定されている場合のみ）
@@ -2064,7 +2840,7 @@ async function handleBatchOperations(operations, snapshotId, mode, client, postI
     for (const op of resolvedOps) {
         if (indexSet.has(op.resolvedIndex)) {
             return {
-                content: [{ type: "text", text: `❌ index ${op.resolvedIndex} (ref: ${op.ref}) に対して複数の operation が指定されています。同一ブロックへの複数操作は許可されていません。` }],
+                content: [{ type: "text", text: `❌ duplicate target: multiple operations point to the same block (index ${op.resolvedIndex}, ref ${op.ref}). Each block can be modified at most once per call. To apply multiple changes to one block, split them into separate calls and chain the snapshotId returned by each write response.` }],
                 isError: true,
             };
         }
@@ -2199,7 +2975,21 @@ async function handleBatchOperations(operations, snapshotId, mode, client, postI
         text = appendSnapshotToTextLegacy(text + _modeTag, snapshot);
     }
 
-    return { content: [{ type: "text", text }] };
+    const _structuredResult = {
+        operations: resolvedOps.map(op => ({
+            opIndex: op.opIndex,
+            ref: op.ref,
+            status: op.status,
+            error: op.error || null,
+            rawNewIndices: op.rawNewIndices || [],
+            rebasedNewIndices: op.rebasedNewIndices || [],
+        })),
+        snapshot: snapshot ? { snapshotId: snapshot.snapshotId, revision: snapshot.revision } : null,
+        successCount,
+        totalCount,
+    };
+
+    return { content: [{ type: "text", text }], _structuredResult };
 }
 
 // フィードバック送信ヘルパー
@@ -2820,37 +3610,62 @@ const tools = [
     },
     {
         name: "upload_media",
-        description: "Upload image to WordPress media library. Returns media ID, URL, dimensions.",
+        description: "Upload one or more images to WordPress media library. Supports FileBird folder assignment and structured JSON results.",
         inputSchema: {
             type: "object",
             properties: {
                 site: siteParam,
-                filePath: { type: "string", description: "Absolute path to image file on local machine" },
-                name: { type: "string", description: "New filename (without extension, ASCII/hyphens recommended)" },
-                alt: { type: "string", description: "Alt text and title (Japanese OK)" },
-                title: { type: "string", description: "Title (defaults to alt if omitted)" },
+                filePath: { type: "string", description: "Single mode: absolute path to image file on local machine. Mutually exclusive with files." },
+                name: { type: "string", description: "Single mode: new filename without extension (required with filePath)" },
+                alt: { type: "string", description: "Single mode: alt text (required with filePath)" },
+                title: { type: "string", description: "Single mode: title (defaults to alt if omitted)" },
+                caption: { type: "string", description: "Single mode: caption. Omit to leave unset; empty string clears." },
+                description: { type: "string", description: "Single mode: description. Omit to leave unset; empty string clears." },
+                files: {
+                    type: "array",
+                    minItems: 1,
+                    maxItems: 20,
+                    description: "Batch mode: upload 1-20 files. Mutually exclusive with filePath.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            filePath: { type: "string", description: "Absolute path to image file on local machine" },
+                            name: { type: "string", description: "Filename without extension. Defaults to basename(filePath)." },
+                            alt: { type: "string", description: "Alt text. Defaults to empty string with warning." },
+                            title: { type: "string", description: "Title. Defaults to name." },
+                            caption: { type: "string", description: "Caption. Omit to leave unset; empty string clears." },
+                            description: { type: "string", description: "Description. Omit to leave unset; empty string clears." },
+                        },
+                        required: ["filePath"],
+                    },
+                },
+                folder: { type: "string", description: "FileBird destination folder path, e.g. '親/子'. May be combined with folderId for consistency check." },
+                folderId: { type: "integer", description: "FileBird destination folder ID. 0 means Uncategorized; -1 is invalid." },
+                createIfMissing: { type: "boolean", description: "Create the missing final folder segment when folder path parent exists. Does not create multi-segment paths." },
+                concurrency: { type: "integer", minimum: 1, maximum: 5, description: "Batch mode concurrency. Default 3, max 5. Ignored in single mode with warning." },
             },
-            required: ["filePath", "name", "alt"],
         },
     },
     {
         name: "search_media",
-        description: "Search WordPress media library. Auto-generates hiragana/katakana/romaji variants for broader matching.",
+        description: "Search WordPress media library (images). Auto-generates hiragana/katakana/romaji variants. Returns structured JSON. Scope to a FileBird folder by path or folderId, optionally recursive (include descendant folders).",
         inputSchema: {
             type: "object",
             properties: {
                 site: siteParam,
-                query: { type: "string", description: "Search keyword" },
-                folder: { type: "string", description: "FileBird folder name (partial match). Filters media to this folder." },
+                query: { type: "string", description: "Search keyword. Either query or folder/folderId is required." },
+                folder: { type: "string", description: "FileBird folder path, e.g. '親/子'. Scopes search/listing to this folder." },
+                folderId: { type: "integer", description: "FileBird folder ID (fallback for folder; 0 = Uncategorized). If both folder and folderId are given they must agree." },
+                recursive: { type: "boolean", description: "When scoping by folder/folderId, also include media in descendant folders. Default false." },
                 strip: { type: "array", items: { type: "string" }, description: "Suffixes to strip (e.g. ['先生', 'さん'])" },
                 prefix: { type: "array", items: { type: "string" }, description: "Prefixes to add (e.g. ['エキサイト-'])" },
-                per_page: { type: "integer", description: "Results per variant (1-20, default: 10)", minimum: 1, maximum: 20 },
+                per_page: { type: "integer", description: "Results per variant for global search (1-20, default 10). Ignored when scoped by folder/folderId (all in-scope matches are returned).", minimum: 1, maximum: 20 },
             },
         },
     },
     {
         name: "list_media_folders",
-        description: "List FileBird media folders. Returns folder names, IDs, and file counts.",
+        description: "List FileBird media folders. Returns structured JSON with nested folders, IDs, paths, and file counts.",
         inputSchema: {
             type: "object",
             properties: {
@@ -2858,6 +3673,90 @@ const tools = [
             },
         },
     },
+    {
+        name: "create_media_folder",
+        description: "Create a FileBird media folder. Use parent path or parentId; folder names containing / are rejected. Does not delete or rename folders.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                site: siteParam,
+                name: { type: "string", description: "Folder name (single segment; / and full-width slash are rejected)" },
+                parent: { type: "string", description: "Parent folder path, e.g. '親/子'. Omit for root." },
+                parentId: { type: "integer", description: "Parent FileBird folder ID. 0 means root." },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "move_media_to_folder",
+        description: "Move existing WordPress media items to a FileBird folder. This is not deletion. Use folder path or folderId; folderId=0 means Uncategorized, folderId=-1 is rejected.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                site: siteParam,
+                mediaIds: { type: "array", items: { type: "integer" }, minItems: 1, maxItems: 100, description: "Media IDs to move (1-100)" },
+                folder: { type: "string", description: "Destination FileBird folder path, e.g. '親/子'" },
+                folderId: { type: "integer", description: "Destination FileBird folder ID. 0 means Uncategorized; -1 is invalid." },
+            },
+            required: ["mediaIds"],
+        },
+    },
+    {
+        name: "update_media_meta",
+        description: "Update one media item's metadata. PATCH semantics: omitted fields are unchanged, empty string clears a field, null is rejected.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                site: siteParam,
+                mediaId: { type: "integer", description: "Media ID" },
+                title: { type: "string", description: "Title. Omit to keep unchanged; empty string clears." },
+                alt: { type: "string", description: "Alt text. Omit to keep unchanged; empty string clears." },
+                caption: { type: "string", description: "Caption. Omit to keep unchanged; empty string clears." },
+                description: { type: "string", description: "Description. Omit to keep unchanged; empty string clears." },
+            },
+            required: ["mediaId"],
+        },
+    },
+    {
+        name: "get_media",
+        description: "Get one media item's metadata, URL, and FileBird folder assignment when FileBird token is configured.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                site: siteParam,
+                mediaId: { type: "integer", description: "Media ID" },
+            },
+            required: ["mediaId"],
+        },
+    },
+    {
+        name: "rename_media_folder",
+        description: "Rename a FileBird media folder (changes name only, not its parent). Use folder path or folderId. New name containing / is rejected. This does not move or delete the folder. Renaming changes the path of this folder and all its descendants.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                site: siteParam,
+                folder: { type: "string", description: "Target folder path, e.g. '親/子'" },
+                folderId: { type: "integer", description: "Target FileBird folder ID. 0/-1 (system folders) are rejected." },
+                newName: { type: "string", description: "New folder name (single segment; / and full-width slash are rejected)" },
+            },
+            required: ["newName"],
+        },
+    },
+    {
+        name: "delete_media_folder",
+        description: "Delete a FileBird media folder. This deletes ONLY the folder (and recursively its subfolders); the media files inside are NOT deleted but moved to Uncategorized. Two-step confirmation: call first without confirmFolderPath to get a summary (child folder count, attachment count), then call again passing confirmFolderPath equal to the target folder path (or confirmFolderId equal to its ID) to execute. System folders (0/-1) are rejected.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                site: siteParam,
+                folder: { type: "string", description: "Target folder path to delete, e.g. '親/子'" },
+                folderId: { type: "integer", description: "Target FileBird folder ID. 0/-1 (system folders) are rejected." },
+                confirmFolderPath: { type: "string", description: "Echo confirmation: pass the exact target folder path to execute the deletion. If absent or mismatched, the tool returns a summary without deleting." },
+                confirmFolderId: { type: "integer", description: "Echo confirmation alternative: pass the exact target folder ID to execute the deletion." },
+            },
+        },
+    },
     {
         name: "list_connections",
         description: "List connections.",
@@ -2905,7 +3804,7 @@ const tools = [
     },
     {
         name: "register_asp_link",
-        description: "Register a new ASP affiliate link. Creates a jump post with ASP metadata.",
+        description: "Register new ASP affiliate links. Single mode creates one jump post with top-level title/slug/asp_url. Batch mode uses items[] (1-30) and allows partial success. Do not combine top-level single fields with items.",
         inputSchema: {
             type: "object",
             properties: {
@@ -2918,8 +3817,86 @@ const tools = [
                 asp_url_sp: { type: "string", description: "ASP URL (B) for A/B testing (optional)" },
                 direct_url: { type: "string", description: "Direct URL bypassing ASP (optional)" },
                 permalink: { type: "string", description: "WordPress permalink slug (defaults to asp_id, then slug if omitted)" },
+                items: {
+                    type: "array",
+                    minItems: 1,
+                    maxItems: MAX_ASP_BULK,
+                    description: "Batch mode: ASP links to register. Mutually exclusive with top-level title/slug/asp_url fields.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            title: { type: "string", description: "Display name" },
+                            slug: { type: "string", description: "Fallback ASP ID and legacy slug input" },
+                            asp_id: { type: "string", description: "ASP案件ID — data-id attribute used by JSLinkHelper (defaults to slug if omitted)" },
+                            asp_name: { type: "string", description: "案件名 (defaults to title if omitted)" },
+                            asp_url: { type: "string", description: "ASP affiliate URL" },
+                            asp_url_sp: { type: "string", description: "ASP URL (B) for A/B testing (optional)" },
+                            direct_url: { type: "string", description: "Direct URL bypassing ASP (optional)" },
+                            permalink: { type: "string", description: "WordPress permalink slug (defaults to asp_id, then slug if omitted)" },
+                        },
+                        required: ["title", "slug", "asp_url"],
+                    },
+                },
+            },
+        },
+    },
+    {
+        name: "update_asp_link",
+        description: "Update an existing ASP affiliate link. Only provided non-empty fields are updated. permalink changes the WordPress permalink/post_name; asp_id changes the data-id key and can break existing inserted tags because article tags are not updated automatically.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                site: siteParam,
+                id: { type: "integer", description: "ASP link jump post ID" },
+                title: { type: "string", description: "Display name" },
+                permalink: { type: "string", description: "WordPress permalink/post_name" },
+                slug: { type: "string", description: "Compatibility alias for permalink. Do not use together with permalink." },
+                asp_id: { type: "string", description: "ASP案件ID — data-id attribute used by JSLinkHelper. Existing article tags are not migrated." },
+                asp_name: { type: "string", description: "案件名" },
+                asp_url: { type: "string", description: "ASP affiliate URL" },
+                asp_url_sp: { type: "string", description: "ASP URL (B) for A/B testing" },
+                direct_url: { type: "string", description: "Direct URL bypassing ASP" },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "insert_asp_tag",
+        description: "Insert ASP affiliate tags into target blocks. Supports core/paragraph, core/image, sbd/btn, core/table. Block-type behavior: core/image → sets dataId attribute; sbd/btn → sets ad attribute (span with button label as inner text); core/paragraph → wraps text with inline span; core/table → targets a specific cell via the \"cell\" parameter and auto-detects cell content (inline-button cell vs normal cell). For core/paragraph: omit \"text\" to wrap the entire paragraph; specify \"text\" to wrap only that exact substring (must match uniquely — if it matches multiple times, the tool returns multiple_matches with previews so you can extend \"text\" with surrounding chars until unique). Paragraphs containing non-ASP inline HTML (e.g., <strong>, <a>) are not supported for partial insertion. For core/table: \"cell\" is REQUIRED. The tool inspects the targeted cell's content — if it contains a swl-inline-btn (Gutenberg inline button) wrapping an <a>, the tool overwrites that anchor's href with the ASP url (asp_url field of the registered ASP link); otherwise it wraps the cell content with the inline span template (same logic as core/paragraph, supports \"text\" for partial wrap). To put two spans in the same paragraph/cell, call this tool twice with snapshotId chaining (one assignment per ref per call). Existing jsl-custom-label tags / existing real anchor hrefs are skipped unless force:true (placeholders like #, ###, empty hrefs are treated as unset). Per-assignment result statuses: inserted (success) / skipped (existing tag or existing href, use force) / not_found (text not in paragraph or cell) / multiple_matches (text matches >1 times, extend it) / unsupported_inline_html (non-ASP inline HTML present, partial mode unsupported) / unsupported (block type not supported) / empty_text (text is empty string, omit it instead) / empty_paragraph (no content to wrap) / empty_cell (cell has no content to wrap) / cell_required (core/table requires cell) / cell_out_of_range (row/col exceeds table size) / missing_asp_url (inline-button cell but ASP has no asp_url registered) / inline_btn_no_anchor (inline button without <a> inside) / tag_template_missing (ASP has no inline template) / ref_failed (snapshotId or ref invalid). PREFER THIS over update_blocks / table_operations for ASP tag insertion to avoid block structure corruption.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                site: siteParam,
+                postId: { oneOf: [{ type: "integer" }, { type: "string" }], description: "Post ID (number) or slug (string). Required if no editor connected." },
+                snapshotId: { type: "string", description: "Snapshot ID from get_article_structure or any write response. Required for ref resolution." },
+                expectedRevision: { type: "string", description: "Revision from snapshot. Rejects update when structure has changed." },
+                assignments: {
+                    type: "array",
+                    maxItems: 30,
+                    description: "List of (ref, asp_id) pairs. Same asp_id may repeat. Same ref may NOT repeat in a single call — split into separate calls with snapshotId chaining. Max 30 items.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            ref: { type: "string", description: "Block ref from snapshot (e.g. 'r5')" },
+                            asp_id: { type: "string", description: "Registered ASP id to insert (e.g. 'mocom')" },
+                            text: { type: "string", description: "core/paragraph: omit to wrap the whole paragraph in the inline span; specify an exact substring (case-sensitive, plain text — HTML entities are decoded for matching) to wrap only that substring. Must match uniquely. sbd/btn: inner label text of the ad span (defaults to button content). core/table (normal cell): same semantics as core/paragraph applied to the targeted cell content. Ignored for core/image and for inline-button cells (which use href overwrite instead)." },
+                            force: { type: "boolean", description: "Overwrite existing tag/href if true. Default false (skip). For core/paragraph and core/table normal cells, only effective in whole-content mode. For inline-button cells, force overrides a real (non-placeholder) href." },
+                            cell: {
+                                type: "object",
+                                description: "REQUIRED when ref points to a core/table block. Specifies which cell to target. Ignored for other block types.",
+                                properties: {
+                                    section: { enum: ["head", "body"], description: "thead or tbody" },
+                                    row: { type: "integer", minimum: 0, description: "0-based row index within the section" },
+                                    col: { type: "integer", minimum: 0, description: "0-based column index within the row" },
+                                },
+                                required: ["section", "row", "col"],
+                            },
+                        },
+                        required: ["ref", "asp_id"],
+                    },
+                },
             },
-            required: ["title", "slug", "asp_url"],
+            required: ["postId", "snapshotId", "assignments"],
         },
     },
 ];
@@ -3032,10 +4009,10 @@ async function handleUpdateBlocksTool(args, toolName) {
     const _inputRef = (snapshotId && args?.target?.ref) ? args.target.ref : null;
     const _isRefInsert = !!(insertOnly && _inputRef);
 
-    // [INSERT_OBSERVE] Step 5: insert_block 経由時の送信パラメータログ
-    if (process.env.FRIDAY_DEBUG === '1' && _fromInsertBlock) {
-        console.log(`[INSERT_OBSERVE] mcp-send: index=${index}, postId=${postId}, sessionId=${_sessionId || 'none'}, mode=${mode}, appendToEnd=${appendToEnd}, htmlLen=${(newHTML || '').length}`);
-    }
+    // [INSERT_OBSERVE] Step 5: insert_block 経由時の送信パラメータログ
+    if (process.env.FRIDAY_DEBUG === '1' && _fromInsertBlock) {
+        console.error(`[INSERT_OBSERVE] mcp-send: index=${index}, postId=${postId}, sessionId=${_sessionId || 'none'}, mode=${mode}, appendToEnd=${appendToEnd}, htmlLen=${(newHTML || '').length}`);
+    }
 
     // --- filePath → newHTML 解決（update_blocks 直接呼び出し時） ---
     if (args?.filePath) {
@@ -3319,7 +4296,7 @@ async function handleUpdateBlocksTool(args, toolName) {
 }
 
 // ツール実行のハンドラ
-const _WRITE_TOOLS = new Set(['update_blocks', 'delete_block', 'move_block', 'duplicate_block', 'insert_block', 'table_operations', 'update_blog_parts', 'insert_blog_parts']);
+const _WRITE_TOOLS = new Set(['update_blocks', 'delete_block', 'move_block', 'duplicate_block', 'insert_block', 'table_operations', 'update_blog_parts', 'insert_blog_parts', 'insert_asp_tag']);
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     const _toolLogStart = Date.now();
@@ -5268,172 +6245,620 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const siteName = args?.site || 'default';
                 let client;
                 try { client = registry.get(siteName); }
-                catch (e) { return errorResponse("upload_media", e.message, siteName); }
-
-                if (!args?.filePath) return errorResponse("upload_media", "filePath is required", siteName);
-                if (!args?.name) return errorResponse("upload_media", "name is required", siteName);
-                if (!args?.alt) return errorResponse("upload_media", "alt is required", siteName);
-
-                let fileInfo;
-                try { fileInfo = validateImageFile(args.filePath); }
-                catch (e) { return errorResponse("upload_media", e.message, siteName); }
+                catch (e) { return jsonToolResponse({ success: false, error: toolError('VALIDATION_ERROR', e.message, false) }, true); }
 
-                const uploadFilename = `${args.name}${fileInfo.ext}`;
-                const fileBuffer = readFileSync(fileInfo.resolved);
-
-                let media;
                 try {
-                    media = await client.uploadMedia(fileBuffer, uploadFilename, fileInfo.contentType);
+                    const mode = validateUploadMode(args || {});
+                    const items = prepareUploadItems(normalizeUploadItems(args || {}, mode));
+                    const concurrency = getUploadConcurrency(args || {}, mode);
+                    const targetFolder = await resolveUploadFolder(client, args || {});
+                    const deadline = Date.now() + UPLOAD_TOTAL_TIMEOUT_MS;
+
+                    let results = await runWithConcurrency(items, concurrency, item => uploadOneMedia(client, item), deadline);
+                    results.sort((a, b) => a.index - b.index);
+                    results = await applyFolderAssignment(client, results, targetFolder);
+                    const summary = buildUploadSummary(results);
+                    return jsonToolResponse({
+                        success: summary.succeeded > 0,
+                        results,
+                        summary,
+                    }, summary.succeeded === 0);
                 } catch (e) {
-                    return errorResponse("upload_media", `Upload failed: ${e.message}`, siteName);
+                    return jsonErrorResponse(e);
                 }
+            }
+
+            case "search_media": {
+                const siteName = args?.site || 'default';
+                let client;
+                try { client = registry.get(siteName); }
+                catch (e) { return jsonErrorResponse(e, 'VALIDATION_ERROR'); }
 
-                const titleText = args?.title || args.alt;
                 try {
-                    await client.updateMediaMeta(media.id, { title: titleText, alt_text: args.alt });
+                    const hasQuery = typeof args?.query === 'string' && args.query.length > 0;
+                    const hasScope = (args?.folder !== undefined && args?.folder !== null) ||
+                                     (args?.folderId !== undefined && args?.folderId !== null);
+                    if (!hasQuery && !hasScope) {
+                        throwToolError('VALIDATION_ERROR', 'query または folder/folderId のどちらかは必須です', false);
+                    }
+
+                    const warnings = [];
+                    const recursive = args?.recursive === true;
+                    if (recursive && !hasScope) {
+                        warnings.push(toolError('VALIDATION_ERROR', 'recursive は folder/folderId 指定時のみ有効です。無視しました', false));
+                    }
+
+                    // WP media item → 出力行
+                    const toRow = (item, matched) => ({
+                        id: item.id,
+                        title: item.title?.rendered || '',
+                        alt: item.alt_text || '',
+                        url: item.source_url || '',
+                        width: item.media_details?.width || null,
+                        height: item.media_details?.height || null,
+                        ...(matched !== undefined ? { matched } : {}),
+                    });
+                    const chunk100 = (arr) => {
+                        const out = [];
+                        for (let i = 0; i < arr.length; i += 100) out.push(arr.slice(i, i + 100));
+                        return out;
+                    };
+
+                    // ---- スコープ解決 (folder/folderId) ----
+                    let scope = null;
+                    let includeIds = null;
+                    if (hasScope) {
+                        const normalized = await getNormalizedFileBirdFolders(client);
+                        const target = resolveFolderTarget(normalized, { folder: args?.folder, folderId: args?.folderId });
+
+                        let folderIds = recursive ? collectSubtreeFolderIds(normalized, target.id) : [target.id];
+                        if (recursive && target.id === 0) {
+                            warnings.push(toolError('VALIDATION_ERROR', 'Uncategorized(folderId=0) は子フォルダを持たないため recursive は単一フォルダとして扱いました', false));
+                        }
+                        const totalFolderCount = folderIds.length;
+                        let folderScanTruncated = false;
+                        if (folderIds.length > SEARCH_MAX_SCAN_FOLDERS) {
+                            folderIds = folderIds.slice(0, SEARCH_MAX_SCAN_FOLDERS);
+                            folderScanTruncated = true;
+                            warnings.push(toolError('VALIDATION_ERROR', `走査フォルダ数が上限 ${SEARCH_MAX_SCAN_FOLDERS} を超えたため打ち切りました（${totalFolderCount} フォルダ中、folderId 昇順で先頭 ${SEARCH_MAX_SCAN_FOLDERS}）`, false));
+                        }
+
+                        const { unionIds, fetchedFolderCount, failedFolderCount } = await fetchAttachmentIdsForFolders(client, folderIds);
+                        const totalInScope = unionIds.length;
+                        let truncated = false;
+                        let scopedIds = unionIds;
+                        if (scopedIds.length > SEARCH_MAX_UNION_IDS) {
+                            scopedIds = scopedIds.slice(0, SEARCH_MAX_UNION_IDS);
+                            truncated = true;
+                            warnings.push(toolError('VALIDATION_ERROR', `スコープ内メディアが上限 ${SEARCH_MAX_UNION_IDS} 件を超えたため先頭 ${SEARCH_MAX_UNION_IDS} 件で切り詰めました（順序: folderId 昇順→id 昇順）`, false));
+                        }
+                        if (failedFolderCount > 0) {
+                            warnings.push(toolError('UNKNOWN', `${folderIds.length} フォルダ中 ${failedFolderCount} フォルダの attachment-id 取得に失敗したため union に欠落の可能性があります`, true));
+                        }
+
+                        includeIds = scopedIds;
+                        scope = {
+                            folderId: target.id,
+                            folderPath: target.path,
+                            recursive,
+                            folderCount: folderIds.length,
+                            fetchedFolderCount,
+                            failedFolderCount,
+                            // failedFolderCount>0 のとき totalInScope は「収集できた範囲の件数」であり真の総数ではない (#6)
+                            partial: failedFolderCount > 0,
+                            totalInScope,
+                            nonImageExcluded: null,
+                            truncated: truncated || folderScanTruncated,
+                        };
+
+                        if (includeIds.length === 0) {
+                            if (hasQuery) {
+                                // 検索パスと応答スキーマを揃える (variants を含める) (#3)
+                                const variants = generateSearchVariants(args.query, args?.strip, args?.prefix);
+                                return jsonToolResponse({ scope, query: args.query, variants, results: [], count: 0, warnings });
+                            }
+                            // 列挙パス(query なし): 空スコープは非画像除外0件 (#4)
+                            scope.nonImageExcluded = 0;
+                            return jsonToolResponse({ scope, results: [], count: 0, warnings });
+                        }
+                    }
+
+                    // ---- 検索パス (query あり) ----
+                    if (hasQuery) {
+                        const variants = generateSearchVariants(args.query, args?.strip, args?.prefix);
+                        const seenIds = new Set();
+                        const results = [];
+
+                        if (hasScope) {
+                            // スコープ検索: per_page 無視 → スコープ内マッチを全件返す (新1)
+                            warnings.push(toolError('UNKNOWN', '検索パスでは非画像件数 (nonImageExcluded) は未集計です', false));
+                            const chunks = chunk100(includeIds);
+                            let scopedCallTotal = 0;
+                            let scopedCallFailed = 0;
+                            for (let vi = 0; vi < variants.length; vi++) {
+                                for (const c of chunks) {
+                                    scopedCallTotal++;
+                                    let items;
+                                    try { items = await client.searchMedia(variants[vi], 100, c); }
+                                    catch { scopedCallFailed++; continue; }
+                                    for (const item of items || []) {
+                                        if (seenIds.has(item.id)) continue;
+                                        seenIds.add(item.id);
+                                        results.push(toRow(item, variants[vi]));
+                                    }
+                                }
+                            }
+                            // 全問い合わせ失敗は error、部分失敗は warnings で可視化 (#5)
+                            if (scopedCallTotal > 0 && scopedCallFailed === scopedCallTotal) {
+                                throwToolError('UNKNOWN', `スコープ検索の全 ${scopedCallTotal} 件の問い合わせが失敗しました`, true);
+                            }
+                            if (scopedCallFailed > 0) {
+                                warnings.push(toolError('UNKNOWN', `スコープ検索 ${scopedCallTotal} 件中 ${scopedCallFailed} 件が失敗したため結果に欠落の可能性があります`, true));
+                            }
+                        } else {
+                            // グローバル検索: 既存挙動 (per_page 1-20)
+                            const perPage = Math.min(Math.max(1, args?.per_page || 10), 20);
+                            const settled = await Promise.allSettled(variants.map(v => client.searchMedia(v, perPage, null)));
+                            // 全 variant 失敗は error、部分失敗は warnings で可視化 (#7)
+                            const failedVariants = settled.filter(s => s.status !== 'fulfilled').length;
+                            if (settled.length > 0 && failedVariants === settled.length) {
+                                throwToolError('UNKNOWN', `グローバル検索の全 ${settled.length} variant が失敗しました`, true);
+                            }
+                            if (failedVariants > 0) {
+                                warnings.push(toolError('UNKNOWN', `グローバル検索 ${settled.length} variant 中 ${failedVariants} 件が失敗したため結果に欠落の可能性があります`, true));
+                            }
+                            for (let i = 0; i < settled.length; i++) {
+                                if (settled[i].status !== 'fulfilled') continue;
+                                for (const item of settled[i].value || []) {
+                                    if (seenIds.has(item.id)) continue;
+                                    seenIds.add(item.id);
+                                    results.push(toRow(item, variants[i]));
+                                }
+                            }
+                        }
+
+                        return jsonToolResponse({
+                            scope,
+                            query: args.query,
+                            variants,
+                            results,
+                            count: results.length,
+                            warnings,
+                        });
+                    }
+
+                    // ---- 列挙パス (スコープあり・query なし) ----
+                    const media = await client.getMediaByIds(includeIds, { mediaType: 'image' });
+                    const byId = new Map((media || []).map(m => [m.id, m]));
+                    const results = [];
+                    for (const id of includeIds) {
+                        const item = byId.get(id);
+                        if (item) results.push(toRow(item));
+                    }
+                    // 切り詰め時は results が union の部分集合のため totalInScope と基準が合わない → null (#8)
+                    scope.nonImageExcluded = includeIds.length < scope.totalInScope
+                        ? null
+                        : includeIds.length - results.length;
+
+                    return jsonToolResponse({
+                        scope,
+                        results,
+                        count: results.length,
+                        warnings,
+                    });
                 } catch (e) {
-                    // meta 更新失敗は警告のみ（アップロード自体は成功）
-                }
-
-                const url = media.source_url || '';
-                const width = media.media_details?.width || null;
-                const height = media.media_details?.height || null;
-                const text = `✅ Uploaded: ID=${media.id}\n` +
-                    `   Title: ${titleText}\n` +
-                    `   Alt: ${args.alt}\n` +
-                    `   URL: ${url}\n` +
-                    (width && height ? `   Size: ${width}x${height}\n` : '') +
-                    `   Filename: ${uploadFilename}`;
-                return { content: [{ type: "text", text }] };
+                    return jsonErrorResponse(e);
+                }
             }
 
-            case "search_media": {
+            case "list_media_folders": {
                 const siteName = args?.site || 'default';
                 let client;
                 try { client = registry.get(siteName); }
-                catch (e) { return errorResponse("search_media", e.message, siteName); }
+                catch (e) { return errorResponse("list_media_folders", e.message, siteName); }
 
-                if (!args?.query && !args?.folder) return errorResponse("search_media", "query または folder のどちらかは必須です", siteName);
+                if (!client.filebirdToken) {
+                    return { content: [{ type: "text", text: "⚠️ FileBird 未導入または APIキーが未設定です。\nconnections.json に filebirdToken を追加してください。" }] };
+                }
+                const folders = await client.getFileBirdFolders();
+                if (!folders) {
+                    return errorResponse("list_media_folders", "FileBird API へのアクセスに失敗しました", siteName);
+                }
+                const uncategorizedCount = (await client.getFileBirdAttachmentCount(0)) || 0;
+                const normalized = normalizeFileBirdFolders(folders, uncategorizedCount);
+                return { content: [{ type: "text", text: JSON.stringify({ folders: normalized.tree }, null, 2) }] };
+            }
 
-                const perPage = args?.per_page || 10;
+            case "create_media_folder": {
+                const siteName = args?.site || 'default';
+                let client;
+                try { client = registry.get(siteName); }
+                catch (e) { return jsonToolResponse({ success: false, error: toolError('VALIDATION_ERROR', e.message, false) }, true); }
 
-                // --- FileBird folder filtering ---
-                let folderIncludeIds = null;
-                let folderInfo = '';
-                if (args?.folder) {
-                    if (!client.filebirdToken) {
-                        return errorResponse("search_media", "FileBird APIキーが未設定です。connections.json に filebirdToken を追加してください", siteName);
+                try {
+                    if (typeof args?.name !== 'string') {
+                        throwToolError('VALIDATION_ERROR', 'name は必須の文字列です', false);
                     }
-                    const folders = await client.getFileBirdFolders();
-                    if (!folders) {
-                        return errorResponse("search_media", "FileBird API へのアクセスに失敗しました", siteName);
+                    const folderName = args.name.trim().normalize('NFC');
+                    if (!folderName) {
+                        throwToolError('VALIDATION_ERROR', 'name は空にできません', false);
                     }
-                    const flat = flattenFileBirdFolders(folders);
-                    const matched = flat.filter(f => f.name.includes(args.folder));
-                    if (matched.length === 0) {
-                        return errorResponse("search_media", `フォルダ "${args.folder}" が見つかりません。\n利用可能: ${flat.map(f => f.name).join(', ')}`, siteName);
+                    if (folderName.includes('/') || folderName.includes('／')) {
+                        throwToolError('VALIDATION_ERROR', 'name にスラッシュは使用できません。親フォルダは parent または parentId で指定してください', false);
                     }
-                    if (matched.length > 1) {
-                        let text = `📁 "${args.folder}" に複数のフォルダがマッチしました。絞り込んでください:\n\n`;
-                        for (const f of matched) {
-                            text += `  [ID: ${f.id}] ${f.name} (${f.count}件)\n`;
-                        }
-                        return { content: [{ type: "text", text }] };
+
+                    const normalized = await getNormalizedFileBirdFolders(client);
+                    const parent = resolveParentTarget(normalized, { parent: args?.parent, parentId: args?.parentId });
+                    const existing = normalized.allNodes.find(node =>
+                        !node.isSystemFolder && node.parentId === parent.id && node.name === folderName
+                    );
+                    if (existing) {
+                        return jsonToolResponse({
+                            success: true,
+                            created: false,
+                            folder: {
+                                id: existing.id,
+                                name: existing.name,
+                                parentId: existing.parentId,
+                                path: existing.path,
+                                count: existing.count,
+                            },
+                            warning: toolError('DUPLICATE_FOLDER_NAME', '同一親配下に同名フォルダが既に存在するため、既存フォルダを返しました', false),
+                        });
+                    }
+
+                    const created = await client.createFileBirdFolder(folderName, parent.id);
+                    if (!created?.id) {
+                        throwToolError('UNKNOWN', 'FileBird フォルダ作成 API が id を返しませんでした', true);
                     }
-                    const folder = matched[0];
-                    const attachmentIds = await client.getFileBirdAttachmentIds(folder.id);
-                    if (!attachmentIds || attachmentIds.length === 0) {
-                        return { content: [{ type: "text", text: `📁 ${folder.name} (0件)\n\n❌ フォルダ内にメディアがありません。` }] };
+
+                    const after = await getNormalizedFileBirdFolders(client);
+                    const node = after.byId.get(created.id);
+                    const expectedPath = parent.path ? `${parent.path}/${folderName}` : folderName;
+                    if (!node || node.name !== folderName || node.parentId !== parent.id || node.path !== expectedPath) {
+                        return jsonToolResponse({
+                            success: false,
+                            created: true,
+                            error: toolError('DUPLICATE_FOLDER_NAME', '作成後検証でフォルダ名またはパスが期待値と一致しません。FileBird が同名フォルダを自動リネームした可能性があります', false, {
+                                recoveryHint: 'WordPress 管理画面で actualFolder を確認し、必要なら手動整理してください',
+                            }),
+                            expected: { name: folderName, parentId: parent.id, path: expectedPath },
+                            actualFolder: node ? {
+                                id: node.id,
+                                name: node.name,
+                                parentId: node.parentId,
+                                path: node.path,
+                                count: node.count,
+                            } : null,
+                        }, true);
                     }
-                    folderIncludeIds = attachmentIds;
-                    const totalCount = attachmentIds.length;
-                    const limited = totalCount > 100;
-                    folderInfo = `📁 Folder: ${folder.name} (${totalCount}件${limited ? '、先頭100件から検索' : ''})\n`;
+
+                    return jsonToolResponse({
+                        success: true,
+                        created: true,
+                        folder: {
+                            id: node.id,
+                            name: node.name,
+                            parentId: node.parentId,
+                            path: node.path,
+                            count: node.count,
+                        },
+                    });
+                } catch (e) {
+                    return jsonErrorResponse(e);
                 }
+            }
 
-                // --- keyword search (with or without folder filter) ---
-                if (args?.query) {
-                    const variants = generateSearchVariants(args.query, args?.strip, args?.prefix);
-                    const results = await Promise.allSettled(
-                        variants.map(v => client.searchMedia(v, perPage, folderIncludeIds))
-                    );
+            case "move_media_to_folder": {
+                const siteName = args?.site || 'default';
+                let client;
+                try { client = registry.get(siteName); }
+                catch (e) { return jsonToolResponse({ success: false, error: toolError('VALIDATION_ERROR', e.message, false) }, true); }
 
-                    const seenIds = new Set();
-                    const hits = [];
-                    for (let i = 0; i < results.length; i++) {
-                        if (results[i].status !== 'fulfilled') continue;
-                        for (const item of results[i].value) {
-                            if (seenIds.has(item.id)) continue;
-                            seenIds.add(item.id);
-                            hits.push({
-                                id: item.id,
-                                title: item.title?.rendered || '',
-                                alt: item.alt_text || '',
-                                url: item.source_url || '',
-                                width: item.media_details?.width || null,
-                                height: item.media_details?.height || null,
-                                matched: variants[i],
-                            });
-                        }
+                let mediaIds = [];
+                try {
+                    if (!Array.isArray(args?.mediaIds)) {
+                        throwToolError('VALIDATION_ERROR', 'mediaIds は必須の配列です', false);
+                    }
+                    mediaIds = args.mediaIds;
+                    if (mediaIds.length === 0) {
+                        throwToolError('VALIDATION_ERROR', 'mediaIds は1件以上指定してください', false);
                     }
+                    if (mediaIds.length > 100) {
+                        throwToolError('VALIDATION_ERROR', 'mediaIds は1コール最大100件までです', false);
+                    }
+                    for (const id of mediaIds) assertPositiveInteger(id, 'mediaId');
 
-                    let text = folderInfo;
-                    text += `🔍 Search: "${args.query}"\n`;
-                    text += `🔄 Variants (${variants.length}): ${variants.join(', ')}\n\n`;
+                    const normalized = await getNormalizedFileBirdFolders(client);
+                    const target = resolveFolderTarget(normalized, { folder: args?.folder, folderId: args?.folderId });
 
-                    if (hits.length === 0) {
-                        text += '❌ No results found.';
-                    } else {
-                        text += `📷 ${hits.length} result(s):\n\n`;
-                        for (const h of hits) {
-                            text += `  [ID: ${h.id}] ${h.title}\n`;
-                            text += `    Alt: ${h.alt}\n`;
-                            text += `    URL: ${h.url}\n`;
-                            if (h.width && h.height) text += `    Size: ${h.width}x${h.height}\n`;
-                            text += `    Matched: "${h.matched}"\n\n`;
+                    try {
+                        await getExistingMediaByIds(client, mediaIds);
+                    } catch (validationError) {
+                        const err = toToolError(validationError);
+                        if (err.code === 'MEDIA_NOT_FOUND') {
+                            const missing = new Set((err.missingMediaIds || []).map(Number));
+                            return jsonToolResponse({
+                                success: false,
+                                error: err,
+                                results: mediaIds.map(mediaId => missing.has(Number(mediaId))
+                                    ? { mediaId, success: false, error: toolError('MEDIA_NOT_FOUND', `mediaId ${mediaId} が存在しません`, false) }
+                                    : { mediaId, success: false, skipped: true, error: toolError('VALIDATION_ERROR', '他の mediaId が存在しないため、このメディアも移動していません', false) }
+                                ),
+                                summary: { total: mediaIds.length, succeeded: 0, failed: mediaIds.length },
+                            }, true);
                         }
+                        throw validationError;
                     }
-                    return { content: [{ type: "text", text }] };
+
+                    const ok = await client.setFileBirdAttachmentFolder(mediaIds, target.id);
+                    if (ok !== true) {
+                        return jsonToolResponse({
+                            success: false,
+                            results: mediaIds.map(mediaId => ({
+                                mediaId,
+                                success: false,
+                                error: toolError('FILEBIRD_SET_ATTACHMENT_FAILED', 'FileBird のフォルダ割当 API が失敗しました', true),
+                            })),
+                            summary: { total: mediaIds.length, succeeded: 0, failed: mediaIds.length },
+                        }, true);
+                    }
+
+                    return jsonToolResponse({
+                        success: true,
+                        results: mediaIds.map(mediaId => ({
+                            mediaId,
+                            success: true,
+                            newFolderId: target.id,
+                            newFolderPath: target.path,
+                        })),
+                        summary: { total: mediaIds.length, succeeded: mediaIds.length, failed: 0 },
+                    });
+                } catch (e) {
+                    return jsonErrorResponse(e);
                 }
+            }
 
-                // --- folder only (no query) ---
-                const mediaItems = await client.searchMedia(null, perPage, folderIncludeIds);
-                let text = folderInfo + '\n';
-                if (!mediaItems || mediaItems.length === 0) {
-                    text += '❌ No results found.';
-                } else {
-                    text += `📷 ${mediaItems.length} result(s):\n\n`;
-                    for (const item of mediaItems) {
-                        text += `  [ID: ${item.id}] ${item.title?.rendered || ''}\n`;
-                        text += `    Alt: ${item.alt_text || ''}\n`;
-                        text += `    URL: ${item.source_url || ''}\n`;
-                        const w = item.media_details?.width, h = item.media_details?.height;
-                        if (w && h) text += `    Size: ${w}x${h}\n`;
-                        text += '\n';
+            case "update_media_meta": {
+                const siteName = args?.site || 'default';
+                let client;
+                try { client = registry.get(siteName); }
+                catch (e) { return jsonToolResponse({ success: false, error: toolError('VALIDATION_ERROR', e.message, false) }, true); }
+
+                try {
+                    const mediaId = assertPositiveInteger(args?.mediaId, 'mediaId');
+                    const fields = ['title', 'alt', 'caption', 'description'];
+                    const provided = fields.filter(field => Object.prototype.hasOwnProperty.call(args || {}, field));
+                    if (provided.length === 0) {
+                        throwToolError('VALIDATION_ERROR', 'title / alt / caption / description のうち1つ以上を指定してください', false);
                     }
+                    const data = {};
+                    for (const field of provided) {
+                        const value = args[field];
+                        if (typeof value !== 'string') {
+                            throwToolError('VALIDATION_ERROR', `${field} は文字列で指定してください。null は使用できません`, false);
+                        }
+                        if (field === 'alt') data.alt_text = value;
+                        else data[field] = value;
+                    }
+
+                    await client.getMedia(mediaId);
+                    const updatedMedia = await client.updateMediaMeta(mediaId, data);
+                    const formatted = formatMedia(updatedMedia);
+                    return jsonToolResponse({
+                        success: true,
+                        mediaId,
+                        updated: {
+                            title: provided.includes('title'),
+                            alt: provided.includes('alt'),
+                            caption: provided.includes('caption'),
+                            description: provided.includes('description'),
+                        },
+                        media: formatted,
+                    });
+                } catch (e) {
+                    return jsonErrorResponse(e);
                 }
-                return { content: [{ type: "text", text }] };
             }
 
-            case "list_media_folders": {
+            case "get_media": {
                 const siteName = args?.site || 'default';
                 let client;
                 try { client = registry.get(siteName); }
-                catch (e) { return errorResponse("list_media_folders", e.message, siteName); }
+                catch (e) { return jsonToolResponse({ success: false, error: toolError('VALIDATION_ERROR', e.message, false) }, true); }
 
-                if (!client.filebirdToken) {
-                    return { content: [{ type: "text", text: "⚠️ FileBird 未導入または APIキーが未設定です。\nconnections.json に filebirdToken を追加してください。" }] };
+                try {
+                    const mediaId = assertPositiveInteger(args?.mediaId, 'mediaId');
+                    const media = await client.getMedia(mediaId);
+                    let folderInfo = { folderId: null, folderPath: null };
+                    const warnings = [];
+                    if (client.filebirdToken) {
+                        try {
+                            const normalized = await getNormalizedFileBirdFolders(client);
+                            folderInfo = await findMediaFolder(client, normalized, mediaId);
+                            if (folderInfo.warning) warnings.push(folderInfo.warning);
+                        } catch (folderError) {
+                            warnings.push(toToolError(folderError, 'FOLDER_NOT_FOUND'));
+                        }
+                    } else {
+                        warnings.push(toolError('VALIDATION_ERROR', 'FileBird APIキーが未設定のため folder 情報は取得していません', false));
+                    }
+                    const payload = formatMedia(media, folderInfo);
+                    if (warnings.length > 0) payload.warnings = warnings;
+                    return jsonToolResponse(payload);
+                } catch (e) {
+                    return jsonErrorResponse(e);
                 }
-                const folders = await client.getFileBirdFolders();
-                if (!folders) {
-                    return errorResponse("list_media_folders", "FileBird API へのアクセスに失敗しました", siteName);
+            }
+
+            case "rename_media_folder": {
+                const siteName = args?.site || 'default';
+                let client;
+                try { client = registry.get(siteName); }
+                catch (e) { return jsonToolResponse({ success: false, error: toolError('VALIDATION_ERROR', e.message, false) }, true); }
+
+                try {
+                    const newName = (typeof args?.newName === 'string' ? args.newName : '').trim().normalize('NFC');
+                    if (!newName) {
+                        throwToolError('VALIDATION_ERROR', 'newName は空にできません', false);
+                    }
+                    if (newName.includes('/') || newName.includes('／')) {
+                        throwToolError('VALIDATION_ERROR', 'newName にスラッシュは使用できません', false);
+                    }
+
+                    const normalized = await getNormalizedFileBirdFoldersAdmin(client);
+                    const target = resolveFolderTarget(normalized, { folder: args?.folder, folderId: args?.folderId });
+                    if (target.id <= 0) {
+                        throwToolError('VALIDATION_ERROR', 'システムフォルダ (Uncategorized / All) は rename できません', false);
+                    }
+
+                    const oldName = target.node.name;
+                    const parentId = target.node.parentId;
+
+                    // 事前同名チェック（同一親配下）
+                    const dup = normalized.allNodes.find(n =>
+                        !n.isSystemFolder && n.id !== target.id && n.parentId === parentId && n.name === newName
+                    );
+                    if (dup) {
+                        return jsonToolResponse({
+                            success: false,
+                            error: toolError('DUPLICATE_FOLDER_NAME', `同一親配下に同名フォルダ "${newName}" が既に存在します (ID: ${dup.id})`, false, { existingFolderId: dup.id }),
+                        }, true);
+                    }
+
+                    if (oldName === newName) {
+                        return jsonToolResponse({
+                            success: true,
+                            changed: false,
+                            folder: { id: target.id, name: newName, parentId, path: target.path },
+                            warning: toolError('VALIDATION_ERROR', '新旧の名前が同一のため変更していません', false),
+                        });
+                    }
+
+                    try {
+                        await client.renameFileBirdFolder(target.id, parentId, newName);
+                    } catch (renameError) {
+                        if ((renameError?.wpErrorCode || '').includes('folder_name_exist')) {
+                            throwToolError('DUPLICATE_FOLDER_NAME', `同一親配下に同名フォルダ "${newName}" が既に存在します`, false);
+                        }
+                        throw renameError;
+                    }
+
+                    // 作成後検証
+                    const after = await getNormalizedFileBirdFoldersAdmin(client);
+                    const node = after.byId.get(target.id);
+                    if (!node || node.name !== newName) {
+                        return jsonToolResponse({
+                            success: false,
+                            error: toolError('UNKNOWN', 'rename 後検証で名前が期待値と一致しません', true),
+                            expected: { id: target.id, name: newName },
+                            actualFolder: node ? { id: node.id, name: node.name, parentId: node.parentId, path: node.path } : null,
+                        }, true);
+                    }
+
+                    return jsonToolResponse({
+                        success: true,
+                        changed: true,
+                        folder: { id: node.id, name: node.name, parentId: node.parentId, path: node.path, oldName },
+                        note: 'このフォルダと全子孫の path が変わりました。古い path を保持している場合は再取得してください。',
+                    });
+                } catch (e) {
+                    return jsonErrorResponse(e);
                 }
-                const flat = flattenFileBirdFolders(folders);
-                let text = `📁 FileBird フォルダ一覧 (${flat.length}件)\n\n`;
-                for (const f of flat) {
-                    text += `  [ID: ${f.id}] ${f.name} (${f.count}件)\n`;
+            }
+
+            case "delete_media_folder": {
+                const siteName = args?.site || 'default';
+                let client;
+                try { client = registry.get(siteName); }
+                catch (e) { return jsonToolResponse({ success: false, error: toolError('VALIDATION_ERROR', e.message, false) }, true); }
+
+                const safeNormalizePath = (p) => {
+                    if (typeof p !== 'string') return null;
+                    try { return normalizeFolderPath(p); } catch { return null; }
+                };
+
+                // サブツリーの添付件数を集計（token あれば union=正確、無ければ subtree込み count で近似）
+                const countAttachments = async (normalized, subtreeIds, rootNode) => {
+                    if (client.filebirdToken) {
+                        try {
+                            const { unionIds, failedFolderCount } = await fetchAttachmentIdsForFolders(client, subtreeIds);
+                            return { attachmentCount: unionIds.length, approximate: failedFolderCount > 0, failedFolderCount };
+                        } catch { /* fall through to approximate */ }
+                    }
+                    // display は subtree 込みのため root の count をそのまま採用（合算しない）
+                    return { attachmentCount: rootNode?.count ?? 0, approximate: true, failedFolderCount: 0 };
+                };
+
+                try {
+                    const normalized = await getNormalizedFileBirdFoldersAdmin(client);
+                    const target = resolveFolderTarget(normalized, { folder: args?.folder, folderId: args?.folderId });
+                    if (target.id <= 0) {
+                        throwToolError('VALIDATION_ERROR', 'システムフォルダ (Uncategorized / All) は削除できません', false);
+                    }
+
+                    const subtreeIds = collectSubtreeFolderIds(normalized, target.id);
+                    const childFolderCount = subtreeIds.length - 1;
+                    const counts = await countAttachments(normalized, subtreeIds, target.node);
+
+                    // echo confirm 判定
+                    const hasFolderIdConfirm = typeof args?.confirmFolderId === 'number';
+                    const pathConfirmNorm = safeNormalizePath(args?.confirmFolderPath);
+                    const confirmMatch =
+                        (hasFolderIdConfirm && args.confirmFolderId === target.id) ||
+                        (pathConfirmNorm !== null && pathConfirmNorm === target.path);
+
+                    if (!confirmMatch) {
+                        return jsonToolResponse({
+                            success: true,
+                            deleted: false,
+                            requireConfirm: true,
+                            summary: {
+                                folderId: target.id,
+                                folderPath: target.path,
+                                folderName: target.node.name,
+                                childFolderCount,
+                                descendantFolderIds: subtreeIds,
+                                attachmentCount: counts.attachmentCount,
+                                attachmentCountApproximate: counts.approximate,
+                            },
+                            message: `このフォルダと子フォルダ ${childFolderCount} 個が削除されます。中の画像 ${counts.attachmentCount} 枚は削除されず Uncategorized に移動します。実行するには confirmFolderPath="${target.path}" を指定してください。`,
+                        });
+                    }
+
+                    // --- 実行（TOCTOU 対策: 直前に再取得して再集計） ---
+                    const fresh = await getNormalizedFileBirdFoldersAdmin(client);
+                    const freshNode = fresh.byId.get(target.id);
+                    if (!freshNode || target.id <= 0) {
+                        throwToolError('FOLDER_NOT_FOUND', `削除対象 (ID: ${target.id}) が見つかりません。既に削除された可能性があります`, false);
+                    }
+                    const freshSubtreeIds = collectSubtreeFolderIds(fresh, target.id);
+                    const freshCounts = await countAttachments(fresh, freshSubtreeIds, freshNode);
+
+                    await client.deleteFileBirdFolder(target.id);
+
+                    // 削除後検証
+                    const verify = await getNormalizedFileBirdFoldersAdmin(client);
+                    const remaining = freshSubtreeIds.filter(id => verify.byId.has(id));
+                    if (remaining.length > 0) {
+                        return jsonToolResponse({
+                            success: false,
+                            deleted: false,
+                            error: toolError('UNKNOWN', `削除後検証でフォルダが残存しています (ID: ${remaining.join(', ')})。FileBird 側の所有権制限 (folder-per-user) で拒否された可能性があります`, true, { remainingFolderIds: remaining }),
+                        }, true);
+                    }
+
+                    return jsonToolResponse({
+                        success: true,
+                        deleted: true,
+                        deletedFolderIds: freshSubtreeIds,
+                        detachedAttachmentCount: freshCounts.attachmentCount,
+                        detachedAttachmentCountApproximate: freshCounts.approximate,
+                        note: '画像は削除されていません。Uncategorized に移動しました。',
+                    });
+                } catch (e) {
+                    return jsonErrorResponse(e);
                 }
-                return { content: [{ type: "text", text }] };
             }
 
             case "list_connections": {
@@ -5536,6 +6961,66 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return { content: [{ type: "text", text: `❌ ${e.message}` }], isError: true };
                 }
 
+                const singleFields = ['title', 'slug', 'asp_id', 'asp_name', 'asp_url', 'asp_url_sp', 'direct_url', 'permalink'];
+                const hasItems = isProvided(args?.items);
+                const hasSingleFields = singleFields.some(field => isProvided(args?.[field]));
+
+                if (hasItems) {
+                    if (hasSingleFields) {
+                        return { content: [{ type: "text", text: "❌ items と単一登録用フィールド（title/slug/asp_url など）は同時指定できません。" }], isError: true };
+                    }
+                    if (!Array.isArray(args.items)) {
+                        return { content: [{ type: "text", text: "❌ items は配列で指定してください。" }], isError: true };
+                    }
+                    if (args.items.length === 0) {
+                        return { content: [{ type: "text", text: "❌ items は1件以上指定してください。" }], isError: true };
+                    }
+                    if (args.items.length > MAX_ASP_BULK) {
+                        return { content: [{ type: "text", text: `❌ items は最大${MAX_ASP_BULK}件までです。` }], isError: true };
+                    }
+                    for (let i = 0; i < args.items.length; i++) {
+                        const item = args.items[i];
+                        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+                            return { content: [{ type: "text", text: `❌ items[${i}] は object で指定してください。` }], isError: true };
+                        }
+                        if (!item.title || !item.slug || !item.asp_url) {
+                            return { content: [{ type: "text", text: `❌ items[${i}].title, slug, asp_url は必須です。` }], isError: true };
+                        }
+                    }
+
+                    let result;
+                    try {
+                        result = await client.bulkCreateAspLinks(args.items);
+                    } catch (e) {
+                        return { content: [{ type: "text", text: `❌ ASPリンク一括登録エラー: ${e.message}` }], isError: true };
+                    }
+
+                    const summary = result.summary || {};
+                    const lines = [
+                        `✅ ASPリンク一括登録完了`,
+                        ``,
+                        `  total: ${summary.total ?? args.items.length}`,
+                        `  registered: ${summary.registered ?? 0}`,
+                        `  duplicate: ${summary.duplicate ?? 0}`,
+                        `  duplicate_in_batch: ${summary.duplicate_in_batch ?? 0}`,
+                        `  error: ${summary.error ?? 0}`,
+                        ``,
+                        `件別結果:`,
+                    ];
+                    for (const item of result.items || []) {
+                        if (item.status === 'registered') {
+                            lines.push(`  [${item.index}] registered: ${item.title} (ID: ${item.id}, asp_id: ${item.data_id}, permalink: ${item.permalink})`);
+                        } else if (item.status === 'duplicate') {
+                            lines.push(`  [${item.index}] duplicate: ${item.message}${item.existingId ? ` (existing ID: ${item.existingId})` : ''}`);
+                        } else if (item.status === 'duplicate_in_batch') {
+                            lines.push(`  [${item.index}] duplicate_in_batch: ${item.asp_id} (first index: ${item.firstIndex})`);
+                        } else {
+                            lines.push(`  [${item.index}] error: ${item.code || 'error'} ${item.message || ''}`.trimEnd());
+                        }
+                    }
+                    return { content: [{ type: "text", text: lines.join('\n') }] };
+                }
+
                 if (!args?.title || !args?.slug || !args?.asp_url) {
                     return { content: [{ type: "text", text: "❌ title, slug, asp_url は必須です。" }], isError: true };
                 }
@@ -5573,6 +7058,656 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: "text", text: lines.join('\n') }] };
             }
 
+            case "update_asp_link": {
+                let client;
+                try {
+                    client = registry.get(args?.site);
+                } catch (e) {
+                    return { content: [{ type: "text", text: `❌ ${e.message}` }], isError: true };
+                }
+
+                const id = Number(args?.id);
+                if (!Number.isInteger(id) || id <= 0) {
+                    return { content: [{ type: "text", text: "❌ id は正の整数で指定してください。" }], isError: true };
+                }
+                if (isProvided(args?.permalink) && isProvided(args?.slug)) {
+                    return { content: [{ type: "text", text: "❌ ambiguous_permalink: permalink と slug は同時指定できません。" }], isError: true };
+                }
+
+                const updateFields = ['title', 'permalink', 'slug', 'asp_id', 'asp_name', 'asp_url', 'asp_url_sp', 'direct_url'];
+                const data = {};
+                for (const field of updateFields) {
+                    if (isProvided(args?.[field])) data[field] = args[field];
+                }
+                const hasEffectiveField = Object.values(data).some(value => typeof value === 'string' ? value.trim() !== '' : isProvided(value));
+                if (!hasEffectiveField) {
+                    return { content: [{ type: "text", text: "❌ no_update_fields: 更新する非空フィールドを1つ以上指定してください。" }], isError: true };
+                }
+
+                let result;
+                try {
+                    result = await client.updateAspLink(id, data);
+                } catch (e) {
+                    return { content: [{ type: "text", text: `❌ ASPリンク更新エラー: ${e.message}` }], isError: true };
+                }
+
+                const lines = [
+                    `✅ ASPリンク更新完了`,
+                    ``,
+                    `  ID: ${result.id}`,
+                    `  タイトル: ${result.title}`,
+                    `  slug: ${result.slug}`,
+                    `  permalink: ${result.permalink}`,
+                    `  案件ID: ${result.data_id}`,
+                ];
+                if (result.asp_url) lines.push(`  ASP URL: ${result.asp_url}`);
+                if (result.asp_url_sp) lines.push(`  ASP URL(B): ${result.asp_url_sp}`);
+                if (result.direct_url) lines.push(`  直リンク: ${result.direct_url}`);
+                if (result.warning) lines.push(`  警告: ${result.warning}`);
+                lines.push(`  tag: ${result.tag}`);
+
+                return { content: [{ type: "text", text: lines.join('\n') }] };
+            }
+
+            case "insert_asp_tag": {
+                const siteName = args?.site || 'default';
+                let { mode, postId: _postId, sessionId: _sessionId, message, client } = await resolveMode(args, name);
+                if (mode === 'error') {
+                    return errorResponse(name, message, args?.site);
+                }
+                const _resolved = mode === 'headless' ? await resolvePostId(args?.postId, client) : { postId: _postId };
+                if (_resolved.error) return { content: [{ type: "text", text: _resolved.error }], isError: true };
+                if (_resolved.editorConnected) mode = 'editor';
+                const postId = _resolved.postId ?? _postId;
+                const _siteName = siteName;
+                const _modeTag = process.env.FRIDAY_DEBUG === '1' ? `\n[DEBUG] mode=${mode}` : '';
+
+                const assignments = Array.isArray(args?.assignments) ? args.assignments : [];
+                if (assignments.length === 0) {
+                    return { content: [{ type: "text", text: "❌ assignments は必須です（1件以上）" }], isError: true };
+                }
+                if (assignments.length > 30) {
+                    return { content: [{ type: "text", text: "❌ assignments は最大30件までです" }], isError: true };
+                }
+                if (!args?.snapshotId) {
+                    return { content: [{ type: "text", text: "❌ snapshotId は必須です" }], isError: true };
+                }
+                for (let i = 0; i < assignments.length; i++) {
+                    const a = assignments[i];
+                    if (!a || typeof a.ref !== 'string' || !a.ref) {
+                        return { content: [{ type: "text", text: `❌ assignments[${i}].ref は必須です` }], isError: true };
+                    }
+                    if (typeof a.asp_id !== 'string' || !a.asp_id) {
+                        return { content: [{ type: "text", text: `❌ assignments[${i}].asp_id は必須です` }], isError: true };
+                    }
+                }
+
+                // ASP id 一括解決
+                const aspIds = [...new Set(assignments.map(a => a.asp_id))];
+                let aspMap;
+                try {
+                    const res = await client.resolveAspLinksBulk(aspIds);
+                    aspMap = res?.items || {};
+                } catch (e) {
+                    return { content: [{ type: "text", text: `❌ ASPリンク解決エラー: ${e.message}` }], isError: true };
+                }
+                const unknownIds = aspIds.filter(aid => !aspMap[aid]);
+                if (unknownIds.length > 0) {
+                    return { content: [{ type: "text", text: `❌ 未登録の asp_id: ${unknownIds.join(', ')}` }], isError: true };
+                }
+
+                // 現在構造取得
+                let currentState;
+                try {
+                    currentState = await getCurrentStructure(mode, client, postId, _sessionId, { safetyCritical: true });
+                } catch (e) {
+                    return { content: [{ type: "text", text: `❌ 現在のブロック構造を取得できませんでした: ${e.message}` }], isError: true };
+                }
+
+                // revision check
+                if (args?.expectedRevision) {
+                    const mismatch = checkRevisionMismatch(args.expectedRevision, currentState, mode, postId, _sessionId, _siteName);
+                    if (mismatch) return mismatch;
+                }
+
+                // ヘルパー: HTML エスケープ
+                const escapeHtml = (s) => String(s).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+                // ヘルパー: 基本 HTML エンティティの decode（部分一致比較用）
+                const decodeHtml = (s) => String(s)
+                    .replace(/&lt;/g, '<')
+                    .replace(/&gt;/g, '>')
+                    .replace(/&quot;/g, '"')
+                    .replace(/&#34;/g, '"')
+                    .replace(/&apos;/g, "'")
+                    .replace(/&#39;/g, "'")
+                    .replace(/&nbsp;/g, ' ')
+                    .replace(/&amp;/g, '&'); // & は最後
+                // 既存タグ検知 regex（jsl-custom-label + data-id の組合せ）
+                const inlineTagRegex = /<span[^>]*\bjsl-custom-label\b[^>]*\bdata-id=["'][^"']*["'][^>]*>[\s\S]*?<\/span>/i;
+                // jsl-custom-label span 抽出用（既存タグ領域の範囲特定）
+                const inlineSpanGlobalRegex = /<span[^>]*\bjsl-custom-label\b[^>]*>[\s\S]*?<\/span>/gi;
+                // span テンプレに text を埋める（既に escape 済みの inner HTML を入れる場合は rawInner=true）
+                const fillSpanInner = (spanHtml, text, rawInner = false) => {
+                    const inner = rawInner ? String(text || '') : (text ? escapeHtml(text) : '');
+                    return spanHtml.replace(/><\/span>\s*$/, `>${inner}</span>`);
+                };
+                // 段落 innerHTML を [text 領域 / jsl span 領域] のパートに分解
+                const splitParagraphParts = (innerHtml) => {
+                    const parts = [];
+                    let lastIdx = 0;
+                    let m;
+                    inlineSpanGlobalRegex.lastIndex = 0;
+                    while ((m = inlineSpanGlobalRegex.exec(innerHtml)) !== null) {
+                        if (m.index > lastIdx) parts.push({ type: 'text', raw: innerHtml.substring(lastIdx, m.index) });
+                        parts.push({ type: 'span', raw: m[0] });
+                        lastIdx = m.index + m[0].length;
+                    }
+                    if (lastIdx < innerHtml.length) parts.push({ type: 'text', raw: innerHtml.substring(lastIdx) });
+                    return parts;
+                };
+                // text 領域に jsl-custom-label 以外のタグが含まれるか判定（部分付与の可否判定）
+                const hasOtherTags = (textPartRaw) => /<[a-zA-Z!\/]/.test(textPartRaw);
+
+                // === core/table 用ヘルパー ===
+                // テーブル HTML から (section, row, col) のセル位置を特定
+                const findTableCell = (blockHtml, section, row, col) => {
+                    const tableMatch = blockHtml.match(/<table[^>]*>[\s\S]*?<\/table>/i);
+                    if (!tableMatch) return { error: 'no_table' };
+                    const tableStartInBlock = tableMatch.index;
+                    const tableHtml = tableMatch[0];
+
+                    const sectionTag = section === 'head' ? 'thead' : 'tbody';
+                    const sectionRegex = new RegExp(`<${sectionTag}[^>]*>([\\s\\S]*?)</${sectionTag}>`, 'i');
+                    const sectionMatch = tableHtml.match(sectionRegex);
+                    if (!sectionMatch) return { error: 'section_not_found' };
+                    const sectionStartInTable = sectionMatch.index;
+                    const sectionContent = sectionMatch[1];
+                    const sectionContentStart = sectionStartInTable + sectionMatch[0].indexOf('>') + 1;
+
+                    const trRegex = /<tr[^>]*>([\s\S]*?)<\/tr>/gi;
+                    let m;
+                    let rowIdx = 0;
+                    while ((m = trRegex.exec(sectionContent)) !== null) {
+                        if (rowIdx === row) {
+                            const rowInner = m[1];
+                            const rowInnerStart = sectionContentStart + m.index + m[0].indexOf('>') + 1;
+                            const cellRegex = /<(th|td)((?:\s[^>]*)?)>([\s\S]*?)<\/\1>/gi;
+                            let cm;
+                            let colIdx = 0;
+                            while ((cm = cellRegex.exec(rowInner)) !== null) {
+                                if (colIdx === col) {
+                                    const cellStartInTable = rowInnerStart + cm.index;
+                                    const openTagLen = cm[0].indexOf('>') + 1;
+                                    const closeTagLen = `</${cm[1]}>`.length;
+                                    return {
+                                        tag: cm[1],
+                                        attrs: cm[2],
+                                        inner: cm[3],
+                                        innerStart: tableStartInBlock + cellStartInTable + openTagLen,
+                                        innerEnd: tableStartInBlock + cellStartInTable + cm[0].length - closeTagLen,
+                                    };
+                                }
+                                colIdx++;
+                            }
+                            return { error: 'col_out_of_range', colCount: colIdx };
+                        }
+                        rowIdx++;
+                    }
+                    return { error: 'row_out_of_range', rowCount: rowIdx };
+                };
+                // ブロック HTML のセル中身を newInner に置換
+                const replaceCellInner = (blockHtml, cellInfo, newInner) =>
+                    blockHtml.substring(0, cellInfo.innerStart) + newInner + blockHtml.substring(cellInfo.innerEnd);
+                // インラインボタン判定（swl-inline-btn を含む）
+                const isInlineButtonCell = (cellInner) => /class=["'][^"']*\bswl-inline-btn\b/.test(cellInner);
+                // 最初の <a> の href 値を取得（href 属性が無い場合は空文字、<a> 自体が無い場合は null）
+                const getFirstAnchorHref = (cellInner) => {
+                    const m = cellInner.match(/<a\b([^>]*)>/i);
+                    if (!m) return null;
+                    const hrefMatch = m[1].match(/\bhref=["']([^"']*)["']/);
+                    return hrefMatch ? hrefMatch[1] : '';
+                };
+                // href プレースホルダ判定（未設定として扱う値）
+                const isPlaceholderHref = (href) => {
+                    if (typeof href !== 'string') return true;
+                    const t = href.trim();
+                    return t === '' || t === '#' || t === '###';
+                };
+                // 最初の <a> の href を newHref に書き換え（href 属性が無ければ追加）
+                const setFirstAnchorHref = (cellInner, newHref) => {
+                    return cellInner.replace(/<a\b([^>]*)>/i, (_full, attrs) => {
+                        if (/\bhref=["'][^"']*["']/.test(attrs)) {
+                            return `<a${attrs.replace(/\bhref=["'][^"']*["']/, `href="${newHref}"`)}>`;
+                        }
+                        return `<a href="${newHref}"${attrs}>`;
+                    });
+                };
+
+                // core/table の処理ロジック（switch 内の見通しを保つため関数化）
+                // 戻り値: { preResult, operation? }
+                const processTableCell = (block, a, aspInfo, force) => {
+                    const cell = a.cell;
+                    if (!cell || typeof cell.row !== 'number' || typeof cell.col !== 'number' || (cell.section !== 'head' && cell.section !== 'body')) {
+                        return { preResult: { ref: a.ref, status: 'cell_required', blockType: 'core/table', asp_id: a.asp_id, reason: 'cell { section: "head"|"body", row, col } is required for core/table' } };
+                    }
+                    if (typeof block.html !== 'string' || !block.html) {
+                        return { preResult: { ref: a.ref, status: 'ref_failed', blockType: 'core/table', asp_id: a.asp_id, reason: 'block HTML not available for cell resolution' } };
+                    }
+                    const cellInfo = findTableCell(block.html, cell.section, cell.row, cell.col);
+                    if (cellInfo.error) {
+                        let reason;
+                        if (cellInfo.error === 'no_table') reason = 'no <table> element found in block';
+                        else if (cellInfo.error === 'section_not_found') reason = `section "${cell.section}" (${cell.section === 'head' ? 'thead' : 'tbody'}) not found in table`;
+                        else if (cellInfo.error === 'row_out_of_range') reason = `row ${cell.row} out of range (only ${cellInfo.rowCount} rows in ${cell.section})`;
+                        else if (cellInfo.error === 'col_out_of_range') reason = `col ${cell.col} out of range (only ${cellInfo.colCount} cols in row ${cell.row} of ${cell.section})`;
+                        else reason = `cell lookup error: ${cellInfo.error}`;
+                        return { preResult: { ref: a.ref, status: 'cell_out_of_range', blockType: 'core/table', asp_id: a.asp_id, reason } };
+                    }
+                    const cellInner = cellInfo.inner;
+
+                    // セル種別判定: swl-inline-btn → href 書き換え経路
+                    if (isInlineButtonCell(cellInner)) {
+                        if (!aspInfo.asp_url) {
+                            return { preResult: { ref: a.ref, status: 'missing_asp_url', blockType: 'core/table', asp_id: a.asp_id, reason: `ASP "${a.asp_id}" has no asp_url registered (required for inline-button cells)` } };
+                        }
+                        const currentHref = getFirstAnchorHref(cellInner);
+                        if (currentHref === null) {
+                            return { preResult: { ref: a.ref, status: 'inline_btn_no_anchor', blockType: 'core/table', asp_id: a.asp_id, reason: 'inline button cell has no <a> element inside' } };
+                        }
+                        if (currentHref === aspInfo.asp_url) {
+                            return { preResult: { ref: a.ref, status: 'skipped', blockType: 'core/table', asp_id: a.asp_id, reason: 'href already matches asp_url' } };
+                        }
+                        const placeholder = isPlaceholderHref(currentHref);
+                        if (!placeholder && !force) {
+                            return { preResult: { ref: a.ref, status: 'skipped', blockType: 'core/table', asp_id: a.asp_id, reason: `existing href "${currentHref}" (use force:true to overwrite)` } };
+                        }
+                        const newInner = setFirstAnchorHref(cellInner, aspInfo.asp_url);
+                        const newBlockHtml = replaceCellInner(block.html, cellInfo, newInner);
+                        return {
+                            preResult: { ref: a.ref, status: 'pending', blockType: 'core/table', asp_id: a.asp_id, mode: 'inline_button_href' },
+                            operation: { target: { ref: a.ref }, newHTML: newBlockHtml },
+                        };
+                    }
+
+                    // 通常セル経路: core/paragraph と同じ全体/部分ラップ ロジック
+                    const tplInline = aspInfo?.tags?.inline || '';
+                    if (!tplInline) {
+                        return { preResult: { ref: a.ref, status: 'tag_template_missing', blockType: 'core/table', asp_id: a.asp_id } };
+                    }
+                    const userTextProvided = typeof a.text === 'string';
+                    if (userTextProvided && a.text.length === 0) {
+                        return { preResult: { ref: a.ref, status: 'empty_text', blockType: 'core/table', asp_id: a.asp_id, reason: 'text must not be empty string' } };
+                    }
+                    const isPartial = userTextProvided;
+                    const userText = isPartial ? a.text : '';
+                    let newCellInner = '';
+
+                    if (isPartial) {
+                        const parts = splitParagraphParts(cellInner);
+                        const hasInlineHtml = parts.some(p => p.type === 'text' && hasOtherTags(p.raw));
+                        if (hasInlineHtml) {
+                            return { preResult: { ref: a.ref, status: 'unsupported_inline_html', blockType: 'core/table', asp_id: a.asp_id, reason: 'cell contains non-ASP inline HTML; partial insertion not supported' } };
+                        }
+                        const allMatches = [];
+                        for (let pi = 0; pi < parts.length; pi++) {
+                            const p = parts[pi];
+                            if (p.type !== 'text') continue;
+                            const decoded = decodeHtml(p.raw);
+                            let pos = 0;
+                            while (true) {
+                                const idx = decoded.indexOf(userText, pos);
+                                if (idx === -1) break;
+                                allMatches.push({ partIndex: pi, decodedIndex: idx, decoded });
+                                pos = idx + Math.max(1, userText.length);
+                            }
+                        }
+                        if (allMatches.length === 0) {
+                            return { preResult: { ref: a.ref, status: 'not_found', blockType: 'core/table', asp_id: a.asp_id, reason: 'text not found in cell' } };
+                        }
+                        if (allMatches.length > 1) {
+                            const matchPreviews = allMatches.slice(0, 5).map(mm => {
+                                const before = mm.decoded.substring(Math.max(0, mm.decodedIndex - 12), mm.decodedIndex);
+                                const after = mm.decoded.substring(mm.decodedIndex + userText.length, Math.min(mm.decoded.length, mm.decodedIndex + userText.length + 12));
+                                return `${before}【${userText}】${after}`;
+                            });
+                            return { preResult: { ref: a.ref, status: 'multiple_matches', blockType: 'core/table', asp_id: a.asp_id, reason: `text matches ${allMatches.length} times in cell`, matchCount: allMatches.length, matchPreviews } };
+                        }
+                        const hit = allMatches[0];
+                        const inlineSpan = fillSpanInner(tplInline, userText);
+                        const before = escapeHtml(hit.decoded.substring(0, hit.decodedIndex));
+                        const after = escapeHtml(hit.decoded.substring(hit.decodedIndex + userText.length));
+                        const newPartRaw = before + inlineSpan + after;
+                        newCellInner = parts.map((p, i) => i === hit.partIndex ? newPartRaw : p.raw).join('');
+                    } else {
+                        const hasExisting = inlineTagRegex.test(cellInner);
+                        if (hasExisting && !force) {
+                            return { preResult: { ref: a.ref, status: 'skipped', blockType: 'core/table', asp_id: a.asp_id, reason: 'existing inline tag' } };
+                        }
+                        const baseInner = hasExisting
+                            ? cellInner.replace(inlineSpanGlobalRegex, (_m) => {
+                                const im = _m.match(/<span[^>]*>([\s\S]*?)<\/span>/i);
+                                return im ? im[1] : '';
+                            })
+                            : cellInner;
+                        if (!baseInner || baseInner.length === 0) {
+                            return { preResult: { ref: a.ref, status: 'empty_cell', blockType: 'core/table', asp_id: a.asp_id, reason: 'cell is empty' } };
+                        }
+                        newCellInner = fillSpanInner(tplInline, baseInner, true);
+                    }
+
+                    const newBlockHtml = replaceCellInner(block.html, cellInfo, newCellInner);
+                    return {
+                        preResult: { ref: a.ref, status: 'pending', blockType: 'core/table', asp_id: a.asp_id, mode: isPartial ? 'partial' : 'whole' },
+                        operation: { target: { ref: a.ref }, newHTML: newBlockHtml },
+                    };
+                };
+
+                // 各 assignment を MCP 側で事前判定 → operations を組み立て
+                const operations = [];
+                const preResults = [];
+                for (let i = 0; i < assignments.length; i++) {
+                    const a = assignments[i];
+                    const aspInfo = aspMap[a.asp_id];
+                    const dataId = aspInfo.data_id;
+                    const force = !!a.force;
+
+                    let index;
+                    try {
+                        index = resolveRefFromState(args.snapshotId, a.ref, mode, _sessionId, postId, currentState);
+                    } catch (e) {
+                        preResults.push({ ref: a.ref, status: 'ref_failed', reason: e.message, asp_id: a.asp_id });
+                        continue;
+                    }
+                    const block = currentState.allBlocks.find(b => b.index === index);
+                    if (!block) {
+                        preResults.push({ ref: a.ref, status: 'block_not_found', reason: `index ${index} not found`, asp_id: a.asp_id });
+                        continue;
+                    }
+
+                    const blockType = block.type;
+                    const attrs = block.attributes || {};
+
+                    if (blockType === 'core/image') {
+                        const existing = !!(attrs.dataId && String(attrs.dataId).length > 0);
+                        if (existing && !force) {
+                            preResults.push({ ref: a.ref, status: 'skipped', blockType, reason: 'existing dataId', asp_id: a.asp_id });
+                            continue;
+                        }
+                        operations.push({ target: { ref: a.ref }, attributeUpdates: { set: { dataId } } });
+                        preResults.push({ ref: a.ref, status: 'pending', blockType, asp_id: a.asp_id, dataId });
+                    } else if (blockType === 'sbd/btn') {
+                        const existing = !!(attrs.ad && String(attrs.ad).includes('jsl-custom-label'));
+                        if (existing && !force) {
+                            preResults.push({ ref: a.ref, status: 'skipped', blockType, reason: 'existing ad', asp_id: a.asp_id });
+                            continue;
+                        }
+                        const text = (typeof a.text === 'string' && a.text.length > 0)
+                            ? a.text
+                            : (typeof attrs.content === 'string' ? attrs.content : '');
+                        const adSpan = fillSpanInner(aspInfo?.tags?.button?.ad || '', text);
+                        if (!adSpan) {
+                            preResults.push({ ref: a.ref, status: 'tag_template_missing', blockType, asp_id: a.asp_id });
+                            continue;
+                        }
+                        operations.push({ target: { ref: a.ref }, attributeUpdates: { set: { ad: adSpan } } });
+                        preResults.push({ ref: a.ref, status: 'pending', blockType, asp_id: a.asp_id });
+                    } else if (blockType === 'core/paragraph') {
+                        // Gutenberg core/paragraph の content は innerHTML（<p>...</p> の中身）が正本。
+                        // attrs.content は標準保存形式では空配列で返ることが多い（parse_blocks の仕様）。
+                        // 両モードで安全に動かすため block.html から innerHTML を抽出し、newHTML で全体を再構築する。
+                        let oldInnerHtml = '';
+                        if (typeof block.html === 'string') {
+                            const m = block.html.match(/<p[^>]*>([\s\S]*?)<\/p>/i);
+                            if (m) oldInnerHtml = m[1];
+                        }
+                        if (!oldInnerHtml && typeof attrs.content === 'string') {
+                            oldInnerHtml = attrs.content;
+                        }
+
+                        const tplInline = aspInfo?.tags?.inline || '';
+                        if (!tplInline) {
+                            preResults.push({ ref: a.ref, status: 'tag_template_missing', blockType, asp_id: a.asp_id });
+                            continue;
+                        }
+
+                        // text の指定モード判定
+                        // - undefined → 全体付与
+                        // - '' → empty_text エラー
+                        // - 文字列 → 部分付与
+                        const userTextProvided = typeof a.text === 'string';
+                        if (userTextProvided && a.text.length === 0) {
+                            preResults.push({ ref: a.ref, status: 'empty_text', blockType, asp_id: a.asp_id, reason: 'text must not be empty string' });
+                            continue;
+                        }
+                        const isPartial = userTextProvided;
+                        const userText = isPartial ? a.text : '';
+
+                        let newInnerHtml = '';
+
+                        if (isPartial) {
+                            // === 部分付与 ===
+                            const parts = splitParagraphParts(oldInnerHtml);
+                            // text 領域に jsl-custom-label 以外のタグが含まれる段落は v1 では未対応
+                            const hasInlineHtml = parts.some(p => p.type === 'text' && hasOtherTags(p.raw));
+                            if (hasInlineHtml) {
+                                preResults.push({ ref: a.ref, status: 'unsupported_inline_html', blockType, asp_id: a.asp_id, reason: 'paragraph contains non-ASP inline HTML; partial insertion not supported' });
+                                continue;
+                            }
+                            // 各 text 領域を decode してマッチ箇所を全列挙
+                            const allMatches = [];
+                            for (let pi = 0; pi < parts.length; pi++) {
+                                const p = parts[pi];
+                                if (p.type !== 'text') continue;
+                                const decoded = decodeHtml(p.raw);
+                                let pos = 0;
+                                while (true) {
+                                    const idx = decoded.indexOf(userText, pos);
+                                    if (idx === -1) break;
+                                    allMatches.push({ partIndex: pi, decodedIndex: idx, decoded });
+                                    pos = idx + Math.max(1, userText.length);
+                                }
+                            }
+                            if (allMatches.length === 0) {
+                                preResults.push({ ref: a.ref, status: 'not_found', blockType, asp_id: a.asp_id, reason: `text not found in paragraph` });
+                                continue;
+                            }
+                            if (allMatches.length > 1) {
+                                const matchPreviews = allMatches.slice(0, 5).map(mm => {
+                                    const before = mm.decoded.substring(Math.max(0, mm.decodedIndex - 12), mm.decodedIndex);
+                                    const after = mm.decoded.substring(mm.decodedIndex + userText.length, Math.min(mm.decoded.length, mm.decodedIndex + userText.length + 12));
+                                    return `${before}【${userText}】${after}`;
+                                });
+                                preResults.push({
+                                    ref: a.ref,
+                                    status: 'multiple_matches',
+                                    blockType,
+                                    asp_id: a.asp_id,
+                                    reason: `text matches ${allMatches.length} times in paragraph`,
+                                    matchCount: allMatches.length,
+                                    matchPreviews,
+                                });
+                                continue;
+                            }
+                            // 一意の一致 → そのテキスト領域内で span を挿入
+                            const hit = allMatches[0];
+                            const inlineSpan = fillSpanInner(tplInline, userText);
+                            const before = escapeHtml(hit.decoded.substring(0, hit.decodedIndex));
+                            const after = escapeHtml(hit.decoded.substring(hit.decodedIndex + userText.length));
+                            const newPartRaw = before + inlineSpan + after;
+                            const rebuilt = parts.map((p, i) => i === hit.partIndex ? newPartRaw : p.raw).join('');
+                            newInnerHtml = rebuilt;
+                        } else {
+                            // === 全体付与 ===
+                            // 既存 jsl-custom-label span がある場合は force 必須
+                            const hasExisting = inlineTagRegex.test(oldInnerHtml);
+                            if (hasExisting && !force) {
+                                preResults.push({ ref: a.ref, status: 'skipped', blockType, reason: 'existing inline tag', asp_id: a.asp_id });
+                                continue;
+                            }
+                            // 既存 span は中身に展開して取り除き、全体を新 span で包む
+                            const baseInnerHtml = hasExisting
+                                ? oldInnerHtml.replace(inlineSpanGlobalRegex, (_m, ...rest) => {
+                                    // capture group は無いので raw 全体を再パース
+                                    const im = _m.match(/<span[^>]*>([\s\S]*?)<\/span>/i);
+                                    return im ? im[1] : '';
+                                })
+                                : oldInnerHtml;
+                            if (!baseInnerHtml || baseInnerHtml.length === 0) {
+                                preResults.push({ ref: a.ref, status: 'empty_paragraph', blockType, asp_id: a.asp_id, reason: 'paragraph is empty' });
+                                continue;
+                            }
+                            // baseInnerHtml をそのまま span の中身として埋める（タグ構造を保持）
+                            newInnerHtml = fillSpanInner(tplInline, baseInnerHtml, true);
+                        }
+
+                        // 元 attrs から content を除去（content は innerHTML が正本）し、他 attrs（dropCap 等）は保持
+                        let attrsStr = '';
+                        if (typeof block.html === 'string') {
+                            const commentMatch = block.html.match(/^<!--\s*wp:paragraph(\s+(\{[\s\S]*?\}))?\s*-->/);
+                            if (commentMatch && commentMatch[2]) {
+                                try {
+                                    const parsedAttrs = JSON.parse(commentMatch[2]);
+                                    delete parsedAttrs.content;
+                                    if (Object.keys(parsedAttrs).length > 0) {
+                                        attrsStr = ' ' + JSON.stringify(parsedAttrs);
+                                    }
+                                } catch (_e) { /* attrs 破棄（安全側） */ }
+                            }
+                        }
+                        // <p> タグの属性（class 等）を保持
+                        let pTagOpen = '<p>';
+                        if (typeof block.html === 'string') {
+                            const pOpenMatch = block.html.match(/<p([^>]*)>/i);
+                            if (pOpenMatch) pTagOpen = `<p${pOpenMatch[1]}>`;
+                        }
+                        const newBlockHtml = `<!-- wp:paragraph${attrsStr} -->\n${pTagOpen}${newInnerHtml}</p>\n<!-- /wp:paragraph -->`;
+                        operations.push({ target: { ref: a.ref }, newHTML: newBlockHtml });
+                        preResults.push({ ref: a.ref, status: 'pending', blockType, asp_id: a.asp_id, mode: isPartial ? 'partial' : 'whole' });
+                    } else if (blockType === 'core/table') {
+                        const result = processTableCell(block, a, aspInfo, force);
+                        preResults.push(result.preResult);
+                        if (result.operation) operations.push(result.operation);
+                    } else {
+                        preResults.push({ ref: a.ref, status: 'unsupported', blockType, reason: `${blockType} is not supported`, asp_id: a.asp_id });
+                    }
+                }
+
+                // operations を handleBatchOperations に委譲
+                // preFetchedState で currentState を渡し、内部での getCurrentStructure 再取得を回避
+                let batchResult = null;
+                if (operations.length > 0) {
+                    batchResult = await handleBatchOperations(
+                        operations, args.snapshotId, mode, client, postId,
+                        _sessionId, _siteName, _modeTag, "insert_asp_tag", args?.expectedRevision,
+                        { preFetchedState: currentState }
+                    );
+                    if (batchResult?.isError) return batchResult;
+                }
+
+                // batch 結果 → 構造化結果から成功/失敗 ref を抽出
+                const successRefs = new Set();
+                const failedRefs = new Set();
+                if (batchResult?._structuredResult?.operations) {
+                    for (const op of batchResult._structuredResult.operations) {
+                        if (op.status === 'updated' || op.status === 'expanded') {
+                            successRefs.add(op.ref);
+                        } else if (op.status === 'failed') {
+                            failedRefs.add(op.ref);
+                        }
+                        // 'skipped' は handleBatchOperations 内で発生しうるが、
+                        // insert_asp_tag は事前判定で skipped を弾いて operations に積まないため
+                        // ここに到達するのは異常系。successRefs に入れず failedRefs にも入れない
+                    }
+                }
+
+                // 結果整形
+                let success = 0, failed = 0, skipped = 0, unsupported = 0;
+                const lines = [];
+                for (const r of preResults) {
+                    if (r.status === 'pending') {
+                        if (successRefs.has(r.ref)) {
+                            success++;
+                            let detail = '';
+                            if (r.blockType === 'core/image') detail = ` (dataId=${r.dataId})`;
+                            else if (r.blockType === 'sbd/btn') detail = ' (ad set)';
+                            else if (r.blockType === 'core/paragraph') detail = r.mode === 'partial' ? ' (partial span wrapped)' : ' (whole paragraph wrapped)';
+                            else if (r.blockType === 'core/table') {
+                                if (r.mode === 'inline_button_href') detail = ' (anchor href set)';
+                                else if (r.mode === 'partial') detail = ' (partial span wrapped in cell)';
+                                else detail = ' (whole cell wrapped)';
+                            }
+                            lines.push(`  [${r.ref}] inserted: ${r.blockType}${detail}`);
+                        } else {
+                            failed++;
+                            lines.push(`  [${r.ref}] failed: ${r.blockType}`);
+                        }
+                    } else if (r.status === 'skipped') {
+                        skipped++;
+                        lines.push(`  [${r.ref}] skipped: ${r.reason} (use force:true to overwrite)`);
+                    } else if (r.status === 'unsupported') {
+                        unsupported++;
+                        lines.push(`  [${r.ref}] unsupported: ${r.blockType}`);
+                    } else if (r.status === 'unsupported_inline_html') {
+                        unsupported++;
+                        lines.push(`  [${r.ref}] unsupported_inline_html: paragraph contains non-ASP inline HTML; partial insertion not supported (try whole-paragraph insert by omitting "text")`);
+                    } else if (r.status === 'not_found') {
+                        failed++;
+                        lines.push(`  [${r.ref}] not_found: target text was not found in paragraph`);
+                    } else if (r.status === 'multiple_matches') {
+                        failed++;
+                        const head = `  [${r.ref}] multiple_matches: text matches ${r.matchCount} times — extend "text" with surrounding characters until unique`;
+                        const previews = (r.matchPreviews || []).map((p, i) => `      ${i + 1}. ${p}`).join('\n');
+                        lines.push(previews ? `${head}\n${previews}` : head);
+                    } else if (r.status === 'empty_paragraph') {
+                        failed++;
+                        lines.push(`  [${r.ref}] empty_paragraph: paragraph has no text to wrap`);
+                    } else if (r.status === 'empty_text') {
+                        failed++;
+                        lines.push(`  [${r.ref}] empty_text: text must not be empty string (omit "text" for whole wrap)`);
+                    } else if (r.status === 'empty_cell') {
+                        failed++;
+                        lines.push(`  [${r.ref}] empty_cell: ${r.reason || 'cell has no content to wrap'}`);
+                    } else if (r.status === 'cell_required') {
+                        failed++;
+                        lines.push(`  [${r.ref}] cell_required: ${r.reason || 'cell { section, row, col } is required for core/table'}`);
+                    } else if (r.status === 'cell_out_of_range') {
+                        failed++;
+                        lines.push(`  [${r.ref}] cell_out_of_range: ${r.reason || ''}`);
+                    } else if (r.status === 'missing_asp_url') {
+                        failed++;
+                        lines.push(`  [${r.ref}] missing_asp_url: ${r.reason || `ASP "${r.asp_id}" has no asp_url`}`);
+                    } else if (r.status === 'inline_btn_no_anchor') {
+                        failed++;
+                        lines.push(`  [${r.ref}] inline_btn_no_anchor: ${r.reason || 'inline button cell missing <a>'}`);
+                    } else if (r.status === 'tag_template_missing') {
+                        failed++;
+                        lines.push(`  [${r.ref}] tag_template_missing: ASP "${r.asp_id}" has no inline template`);
+                    } else if (r.status === 'ref_failed') {
+                        failed++;
+                        lines.push(`  [${r.ref}] ref_failed: ${r.reason}`);
+                    } else {
+                        failed++;
+                        lines.push(`  [${r.ref}] ${r.status}: ${r.reason || ''}`);
+                    }
+                }
+
+                // snapshot 抽出（構造化結果から）
+                let snapshotLine = '';
+                const snap = batchResult?._structuredResult?.snapshot;
+                if (snap?.snapshotId) {
+                    snapshotLine = `\n[snapshot:${snap.snapshotId}${snap.revision ? ` rev:${snap.revision}` : ''}]`;
+                }
+
+                const total = preResults.length;
+                const summary = [`${success}/${total} 成功`];
+                if (skipped > 0) summary.push(`${skipped} skipped`);
+                if (unsupported > 0) summary.push(`${unsupported} unsupported`);
+                if (failed > 0) summary.push(`${failed} failed`);
+                const headerText = `✅ ASPタグ挿入完了 (${summary.join(', ')})${_modeTag}`;
+                const text = `${headerText}\n${lines.join('\n')}${snapshotLine}`;
+                return { content: [{ type: "text", text }] };
+            }
+
             default:
                 throw new Error(`Unknown tool: ${name}`);
         } })();