friday-mcp-v2 3.1.0 → 3.1.3

package/dist/mcp-server.js

@@ -14,8 +14,9 @@ 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";
 import { fileURLToPath } from "node:url";
 // package.json からバージョンを取得
@@ -457,6 +458,117 @@ function readHTMLFromFile(filePath, maxSizeBytes = 2 * 1024 * 1024) {
     return { html };
 }
 
+// ========================================
+// Markdown → Gutenberg Block Converter
+// ========================================
+
+function _convertHeading(node) {
+    const tag = node.tagName.toLowerCase();
+    const level = parseInt(tag[1]);
+    const attrs = level === 2 ? '' : ` {"level":${level}}`;
+    return `<!-- wp:heading${attrs} -->\n<${tag} class="wp-block-heading">${node.innerHTML}</${tag}>\n<!-- /wp:heading -->`;
+}
+
+function _convertParagraph(node) {
+    const img = node.querySelector('img');
+    if (img && node.childNodes.length === 1) {
+        return _convertImage(img);
+    }
+    return `<!-- wp:paragraph -->\n<p>${node.innerHTML}</p>\n<!-- /wp:paragraph -->`;
+}
+
+function _convertList(node) {
+    const tag = node.tagName.toLowerCase();
+    const ordered = tag === 'ol';
+    const attrs = ordered ? ' {"ordered":true}' : '';
+    const outerTag = ordered ? 'ol' : 'ul';
+    return `<!-- wp:list${attrs} -->\n<${outerTag} class="wp-block-list">${node.innerHTML}</${outerTag}>\n<!-- /wp:list -->`;
+}
+
+function _convertQuote(node) {
+    let inner = node.innerHTML.trim();
+    if (!inner.startsWith('<')) {
+        inner = `<p>${inner}</p>`;
+    }
+    return `<!-- wp:quote -->\n<blockquote class="wp-block-quote">${inner}</blockquote>\n<!-- /wp:quote -->`;
+}
+
+function _convertCode(node) {
+    const inner = node.innerHTML.replace(/<code\s+class="[^"]*">/g, '<code>');
+    return `<!-- wp:code -->\n<pre class="wp-block-code">${inner}</pre>\n<!-- /wp:code -->`;
+}
+
+function _convertTable(node) {
+    return `<!-- wp:table -->\n<figure class="wp-block-table"><table>${node.innerHTML}</table></figure>\n<!-- /wp:table -->`;
+}
+
+function _convertImage(node) {
+    const img = node.tagName?.toLowerCase() === 'img' ? node : node.querySelector('img');
+    if (!img) return `<!-- wp:html -->\n${node.outerHTML}\n<!-- /wp:html -->`;
+    const src = img.getAttribute('src') || '';
+    const alt = img.getAttribute('alt') || '';
+    return `<!-- wp:image -->\n<figure class="wp-block-image"><img src="${src}" alt="${alt}"/></figure>\n<!-- /wp:image -->`;
+}
+
+function htmlToGutenbergBlocks(html) {
+    const root = parseHTML(html);
+    const blocks = [];
+    for (const node of root.childNodes) {
+        if (node.nodeType === 3) {
+            const text = node.text.trim();
+            if (!text) continue;
+            blocks.push(`<!-- wp:paragraph -->\n<p>${text}</p>\n<!-- /wp:paragraph -->`);
+            continue;
+        }
+        if (node.nodeType !== 1) continue;
+        const tag = node.tagName?.toLowerCase();
+        switch (tag) {
+            case 'h1': case 'h2': case 'h3': case 'h4': case 'h5': case 'h6':
+                blocks.push(_convertHeading(node));
+                break;
+            case 'p':
+                blocks.push(_convertParagraph(node));
+                break;
+            case 'ul': case 'ol':
+                blocks.push(_convertList(node));
+                break;
+            case 'blockquote':
+                blocks.push(_convertQuote(node));
+                break;
+            case 'pre':
+                blocks.push(_convertCode(node));
+                break;
+            case 'hr':
+                blocks.push(`<!-- wp:separator -->\n<hr class="wp-block-separator has-alpha-channel-opacity"/>\n<!-- /wp:separator -->`);
+                break;
+            case 'table':
+                blocks.push(_convertTable(node));
+                break;
+            case 'figure':
+            case 'img':
+                blocks.push(_convertImage(node));
+                break;
+            default:
+                blocks.push(`<!-- wp:html -->\n${node.outerHTML}\n<!-- /wp:html -->`);
+                break;
+        }
+    }
+    return blocks.join('\n\n');
+}
+
+async function resolveFileToBlockHTML(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    const raw = readHTMLFromFile(filePath).html;
+    if (ext === '.md') {
+        const html = await marked.parse(raw);
+        return htmlToGutenbergBlocks(html);
+    } else if (ext === '.html' || ext === '.htm') {
+        return raw;
+    } else {
+        throw new Error(`対応していないファイル形式です: ${ext} (.md または .html のみ)`);
+    }
+}
+
 // ========================================
 // Media Utilities
 // ========================================
@@ -474,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 };
@@ -611,204 +726,975 @@ function generateSearchVariants(query, strip = [], prefixes = []) {
 }
 
 /**
- * 単一クライアントの Editor/Headless 判定
- * @returns {{ mode: 'editor'|'headless'|'error', postId?: number, message?: string, client?: FridayWPClient }}
+ * フォルダパス文字列の正規化 (T8)
+ * trim → NFC → 全角スラッシュ拒否 → 先頭末尾スラッシュ strip → 連続スラッシュ統合 → 空セグメント拒否
+ * @param {string} input パス文字列
+ * @returns {string} 正規化済みパス (ルート相対、先頭スラッシュなし)
  */
-async function checkSingleClient(client, args) {
-    try {
-        const rawPostId = args?.postId;
-        const numPostId = rawPostId != null ? Number(rawPostId) : null;
-        const isNumeric = numPostId != null && Number.isFinite(numPostId) && numPostId > 0;
-
-        let connectedEditors = [];
+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('/');
+}
 
-        // Bridge 経由で editor 一覧取得（Bridge 必須）
-        if (bridgeClient) {
-            const siteUrl = client.wpUrl?.replace(/\/+$/, '');
-            connectedEditors = await getBridgeEditors(siteUrl);
+/**
+ * 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;
+    }
 
-        const hasEditors = connectedEditors.length > 0;
-        if (!hasEditors) {
-            if (rawPostId == null) return { mode: 'error', message: 'エディタ未接続' };
-            if (isNumeric) return { mode: 'headless', postId: numPostId, client, connectedEditors };
-            return { mode: 'headless', postId: null, client, connectedEditors };
-        }
+    // ルート直下フォルダの 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);
 
-        // connectedEditors 配列を使った editor/headless 判定
-        if (rawPostId != null) {
-            if (isNumeric) {
-                const isEditing = connectedEditors.some(e => Number(e.postId) === numPostId);
-                if (isEditing) {
-                    const sessions = connectedEditors.filter(e => Number(e.postId) === numPostId);
-                    const sessionId = sessions.length === 1 ? sessions[0].sessionId : null;
-                    return { mode: 'editor', postId: numPostId, client, sessionId, connectedEditors };
-                }
-                return { mode: 'headless', postId: numPostId, client, connectedEditors };
-            }
-            return { mode: 'headless', postId: null, client, connectedEditors };
-        }
+    return { tree, byId, byPath, allNodes };
+}
 
-        // postId 省略
-        if (connectedEditors.length === 1) {
-            return { mode: 'editor', postId: connectedEditors[0].postId, client, sessionId: connectedEditors[0].sessionId, connectedEditors };
-        }
-        if (connectedEditors.length > 1) {
-            const list = connectedEditors.map(e =>
-                `  postId: ${e.postId} (${e.postTitle || 'untitled'}) sessionId: ${e.sessionId}`
-            ).join('\n');
-            return {
-                mode: 'error',
-                message: `複数のエディタが接続中です。postId を指定してください。\n\n接続中:\n${list}`,
-                connectedEditors,
-            };
-        }
-        return { mode: 'error', message: 'エディタ未接続' };
-    } catch (e) {
-        return { mode: 'error', message: `接続エラー: ${e.message}` };
+/**
+ * パス文字列 → 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;
 }
 
-function formatHeadlessConflictError(e) {
-    if (e.wpErrorCode === 'headless_conflict') {
-        return {
-            content: [{ type: "text", text:
-                "❌ この記事はエディタで開かれているため、headless アクセスがブロックされました。" +
-                "\nエディタコマンドを使用するか、エディタのタブを閉じてから再試行してください。"
-            }],
-            isError: true,
-        };
-    }
-    return null;
+/** 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);
 }
 
 /**
- * Editor/Headless モード判定ヘルパー（複数接続自動検出対応）
- * @returns {{ mode: 'editor'|'headless'|'error', postId?: number, message?: string, client?: FridayWPClient }}
+ * ルートフォルダから子孫を含む folder id 一覧を集める (Phase 2 recursive)
+ * 出力は folderId 昇順でソート (切り詰め契約と整合)。
+ * Uncategorized(0) は children を持たないため [0] を返す。
+ * @param {object} normalized normalizeFileBirdFolders の戻り値
+ * @param {number} rootFolderId 起点 folder id
+ * @returns {number[]} [rootId, ...全子孫 id] を昇順ソート
  */
-async function resolveMode(args, _callerTool) {
-    const _debugRM = process.env.FRIDAY_DEBUG === '1';
-    function _logResolve(result, path) {
-        if (_debugRM) console.error(`[resolveMode] tool=${_callerTool||'?'} mode=${result.mode} postId=${result.postId||'?'} site=${result.siteName||args?.site||'?'} path=${path}`);
-        return result;
-    }
-    // site 明示指定
-    if (args?.site) {
-        let client;
-        try { client = registry.get(args.site); }
-        catch (e) { return _logResolve({ mode: 'error', message: e.message }, 'site-error'); }
-        const result = await checkSingleClient(client, args);
-        return _logResolve({ ...result, siteName: args.site }, 'site-explicit');
-    }
+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);
+}
 
-    const allConns = registry.getAll();
-    const isMultiSite = allConns.length > 1;
+// 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 取得並列度
 
-    // 単一接続 → 従来通り
-    if (!isMultiSite) {
-        const result = await checkSingleClient(registry.get(), args);
-        return _logResolve({ ...result, siteName: allConns[0].name }, 'single');
+/**
+ * 複数フォルダの 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)
+    );
 
-    // 複数接続 + sticky キャッシュ有効
-    const cached = statusCache.getLast();
-    if (cached) {
-        const cachedResult = await checkSingleClient(cached.client, args);
-        if (cachedResult.mode === 'editor') {
-            return _logResolve({ ...cachedResult, siteName: cached.site }, 'cache-hit');
+    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);
         }
-        statusCache.clear(cached.site);
     }
+    return { unionIds, fetchedFolderCount, failedFolderCount };
+}
 
-    // default を先に確認
-    const defaultClient = registry.get();
-    const defaultName = allConns.find(c => c.client === defaultClient)?.name || 'default';
-    const defaultResult = await checkSingleClient(defaultClient, args);
-    if (defaultResult.mode === 'editor') {
-        statusCache.set(defaultName, defaultClient, defaultResult.postId);
-        return _logResolve({ ...defaultResult, siteName: defaultName }, 'default-editor');
+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);
     }
-    // defaultResult.mode === 'headless' の場合:
-    // 他の接続にエディタが接続中の可能性があるため、並列スキャンに進む
+    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);
+}
 
-    // Bridge ルート（IPC 経由で即座に判定）
-    if (bridgeClient) {
-        let storeConnected;
-        try {
-            storeConnected = [];
-            for (const { name, client } of allConns) {
-                const siteUrl = client.wpUrl?.replace(/\/+$/, '');
-                const editors = await getBridgeEditors(siteUrl);
-                if (editors.length > 0) {
-                    storeConnected.push({ name, client, connectedEditors: editors });
-                }
-            }
-        } catch (bridgeErr) {
-            return _logResolve({
-                mode: 'error',
-                message: `Bridge 接続エラー: ${bridgeErr.message}\nBridge が起動しているか確認してください。`,
-            }, 'bridge-connection-error');
-        }
-        if (storeConnected.length === 1) {
-            const { name, client, connectedEditors } = storeConnected[0];
-            if (args?.postId != null) {
-                const numPid = Number(args.postId);
-                const isNum = Number.isFinite(numPid) && numPid > 0;
-                const isEditing = isNum && connectedEditors.some(e => Number(e.postId) === numPid);
-                if (!isEditing) {
-                    const connNames = allConns.map(c => c.name).join(', ');
-                    return _logResolve({
-                        mode: 'error',
-                        message: `複数サイトが登録されています。Headless モードでは site の指定が必須です。\n利用可能: ${connNames}`,
-                    }, 'store-scan-mismatch');
-                }
-                const sessions = connectedEditors.filter(e => Number(e.postId) === numPid);
-                const sessionId = sessions.length === 1 ? sessions[0].sessionId : null;
-                statusCache.set(name, client, numPid);
-                return _logResolve({ mode: 'editor', postId: numPid, client, siteName: name, sessionId, connectedEditors }, 'store-scan-editor');
-            }
-            // postId 省略
-            if (connectedEditors.length === 1) {
-                statusCache.set(name, client, connectedEditors[0].postId);
-                return _logResolve({ mode: 'editor', postId: connectedEditors[0].postId, client, siteName: name, sessionId: connectedEditors[0].sessionId, connectedEditors }, 'store-scan-single');
-            }
-            if (connectedEditors.length > 1) {
-                const list = connectedEditors.map(e =>
-                    `  postId: ${e.postId} (${e.postTitle || 'untitled'}) sessionId: ${e.sessionId}`
-                ).join('\n');
-                return _logResolve({ mode: 'error', message: `複数のエディタが接続中です。postId を指定してください。\n\n接続中:\n${list}`, connectedEditors }, 'store-scan-multi-editor');
-            }
-        }
-        if (storeConnected.length > 1) {
-            const list = storeConnected.map(c =>
-                `  ${c.name}: ${c.connectedEditors.map(e => `postId ${e.postId}`).join(', ')} (${c.client.wpUrl})`
-            ).join('\n');
-            return _logResolve({
-                mode: 'error',
-                message: `複数のエディタが接続中です。site パラメータで接続先を指定してください。\n\n接続中:\n${list}\n\n例: get_article_structure({ site: "${storeConnected[0].name}" })`
-            }, 'store-scan-multi-site');
-        }
-        // Store で見つからない → Bridge 経由で見つからない = エディタ未接続
+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;
+}
 
-    // Bridge で全接続にエディタが見つからなかった
-    if (args?.postId != null) {
-        const connNames = allConns.map(c => c.name).join(', ');
-        return _logResolve({
-            mode: 'error',
-            message: `複数サイトが登録されています。Headless モードでは site の指定が必須です。\n利用可能: ${connNames}`,
-        }, 'bridge-no-editor-postId');
+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 '';
+}
 
-    return _logResolve({
-        mode: 'error',
-        message: 'エディタ未接続です。postId を指定して Headless モードを使用するか、エディタで記事を開いてください。\n接続一覧の確認: list_connections()'
-    }, 'bridge-no-editor-noPid');
+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);
 }
 
 /**
- * postId を解決する（数値はそのまま、文字列は slug として検索）
- * slug 解決後にエディタ競合チェックも実施
+ * 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 };
+}
+
+/**
+ * 単一クライアントの Editor/Headless 判定
+ * @returns {{ mode: 'editor'|'headless'|'error', postId?: number, message?: string, client?: FridayWPClient }}
+ */
+async function checkSingleClient(client, args) {
+    try {
+        const rawPostId = args?.postId;
+        const numPostId = rawPostId != null ? Number(rawPostId) : null;
+        const isNumeric = numPostId != null && Number.isFinite(numPostId) && numPostId > 0;
+
+        let connectedEditors = [];
+
+        // Bridge 経由で editor 一覧取得（Bridge 必須）
+        if (bridgeClient) {
+            const siteUrl = client.wpUrl?.replace(/\/+$/, '');
+            connectedEditors = await getBridgeEditors(siteUrl);
+        }
+
+        const hasEditors = connectedEditors.length > 0;
+        if (!hasEditors) {
+            if (rawPostId == null) return { mode: 'error', message: 'エディタ未接続' };
+            if (isNumeric) return { mode: 'headless', postId: numPostId, client, connectedEditors };
+            return { mode: 'headless', postId: null, client, connectedEditors };
+        }
+
+        // connectedEditors 配列を使った editor/headless 判定
+        if (rawPostId != null) {
+            if (isNumeric) {
+                const isEditing = connectedEditors.some(e => Number(e.postId) === numPostId);
+                if (isEditing) {
+                    const sessions = connectedEditors.filter(e => Number(e.postId) === numPostId);
+                    const sessionId = sessions.length === 1 ? sessions[0].sessionId : null;
+                    return { mode: 'editor', postId: numPostId, client, sessionId, connectedEditors };
+                }
+                return { mode: 'headless', postId: numPostId, client, connectedEditors };
+            }
+            return { mode: 'headless', postId: null, client, connectedEditors };
+        }
+
+        // postId 省略
+        if (connectedEditors.length === 1) {
+            return { mode: 'editor', postId: connectedEditors[0].postId, client, sessionId: connectedEditors[0].sessionId, connectedEditors };
+        }
+        if (connectedEditors.length > 1) {
+            const list = connectedEditors.map(e =>
+                `  postId: ${e.postId} (${e.postTitle || 'untitled'}) sessionId: ${e.sessionId}`
+            ).join('\n');
+            return {
+                mode: 'error',
+                message: `複数のエディタが接続中です。postId を指定してください。\n\n接続中:\n${list}`,
+                connectedEditors,
+            };
+        }
+        return { mode: 'error', message: 'エディタ未接続' };
+    } catch (e) {
+        return { mode: 'error', message: `接続エラー: ${e.message}` };
+    }
+}
+
+function formatHeadlessConflictError(e) {
+    if (e.wpErrorCode === 'headless_conflict') {
+        return {
+            content: [{ type: "text", text:
+                "❌ この記事はエディタで開かれているため、headless アクセスがブロックされました。" +
+                "\nエディタコマンドを使用するか、エディタのタブを閉じてから再試行してください。"
+            }],
+            isError: true,
+        };
+    }
+    return null;
+}
+
+/**
+ * Editor/Headless モード判定ヘルパー（複数接続自動検出対応）
+ * @returns {{ mode: 'editor'|'headless'|'error', postId?: number, message?: string, client?: FridayWPClient }}
+ */
+async function resolveMode(args, _callerTool) {
+    const _debugRM = process.env.FRIDAY_DEBUG === '1';
+    function _logResolve(result, path) {
+        if (_debugRM) console.error(`[resolveMode] tool=${_callerTool||'?'} mode=${result.mode} postId=${result.postId||'?'} site=${result.siteName||args?.site||'?'} path=${path}`);
+        return result;
+    }
+    // site 明示指定
+    if (args?.site) {
+        let client;
+        try { client = registry.get(args.site); }
+        catch (e) { return _logResolve({ mode: 'error', message: e.message }, 'site-error'); }
+        const result = await checkSingleClient(client, args);
+        return _logResolve({ ...result, siteName: args.site }, 'site-explicit');
+    }
+
+    const allConns = registry.getAll();
+    const isMultiSite = allConns.length > 1;
+
+    // 単一接続 → 従来通り
+    if (!isMultiSite) {
+        const result = await checkSingleClient(registry.get(), args);
+        return _logResolve({ ...result, siteName: allConns[0].name }, 'single');
+    }
+
+    // 複数接続 + sticky キャッシュ有効
+    const cached = statusCache.getLast();
+    if (cached) {
+        const cachedResult = await checkSingleClient(cached.client, args);
+        if (cachedResult.mode === 'editor') {
+            return _logResolve({ ...cachedResult, siteName: cached.site }, 'cache-hit');
+        }
+        statusCache.clear(cached.site);
+    }
+
+    // default を先に確認
+    const defaultClient = registry.get();
+    const defaultName = allConns.find(c => c.client === defaultClient)?.name || 'default';
+    const defaultResult = await checkSingleClient(defaultClient, args);
+    if (defaultResult.mode === 'editor') {
+        statusCache.set(defaultName, defaultClient, defaultResult.postId);
+        return _logResolve({ ...defaultResult, siteName: defaultName }, 'default-editor');
+    }
+    // defaultResult.mode === 'headless' の場合:
+    // 他の接続にエディタが接続中の可能性があるため、並列スキャンに進む
+
+    // Bridge ルート（IPC 経由で即座に判定）
+    if (bridgeClient) {
+        let storeConnected;
+        try {
+            storeConnected = [];
+            for (const { name, client } of allConns) {
+                const siteUrl = client.wpUrl?.replace(/\/+$/, '');
+                const editors = await getBridgeEditors(siteUrl);
+                if (editors.length > 0) {
+                    storeConnected.push({ name, client, connectedEditors: editors });
+                }
+            }
+        } catch (bridgeErr) {
+            return _logResolve({
+                mode: 'error',
+                message: `Bridge 接続エラー: ${bridgeErr.message}\nBridge が起動しているか確認してください。`,
+            }, 'bridge-connection-error');
+        }
+        if (storeConnected.length === 1) {
+            const { name, client, connectedEditors } = storeConnected[0];
+            if (args?.postId != null) {
+                const numPid = Number(args.postId);
+                const isNum = Number.isFinite(numPid) && numPid > 0;
+                const isEditing = isNum && connectedEditors.some(e => Number(e.postId) === numPid);
+                if (!isEditing) {
+                    const connNames = allConns.map(c => c.name).join(', ');
+                    return _logResolve({
+                        mode: 'error',
+                        message: `複数サイトが登録されています。Headless モードでは site の指定が必須です。\n利用可能: ${connNames}`,
+                    }, 'store-scan-mismatch');
+                }
+                const sessions = connectedEditors.filter(e => Number(e.postId) === numPid);
+                const sessionId = sessions.length === 1 ? sessions[0].sessionId : null;
+                statusCache.set(name, client, numPid);
+                return _logResolve({ mode: 'editor', postId: numPid, client, siteName: name, sessionId, connectedEditors }, 'store-scan-editor');
+            }
+            // postId 省略
+            if (connectedEditors.length === 1) {
+                statusCache.set(name, client, connectedEditors[0].postId);
+                return _logResolve({ mode: 'editor', postId: connectedEditors[0].postId, client, siteName: name, sessionId: connectedEditors[0].sessionId, connectedEditors }, 'store-scan-single');
+            }
+            if (connectedEditors.length > 1) {
+                const list = connectedEditors.map(e =>
+                    `  postId: ${e.postId} (${e.postTitle || 'untitled'}) sessionId: ${e.sessionId}`
+                ).join('\n');
+                return _logResolve({ mode: 'error', message: `複数のエディタが接続中です。postId を指定してください。\n\n接続中:\n${list}`, connectedEditors }, 'store-scan-multi-editor');
+            }
+        }
+        if (storeConnected.length > 1) {
+            const list = storeConnected.map(c =>
+                `  ${c.name}: ${c.connectedEditors.map(e => `postId ${e.postId}`).join(', ')} (${c.client.wpUrl})`
+            ).join('\n');
+            return _logResolve({
+                mode: 'error',
+                message: `複数のエディタが接続中です。site パラメータで接続先を指定してください。\n\n接続中:\n${list}\n\n例: get_article_structure({ site: "${storeConnected[0].name}" })`
+            }, 'store-scan-multi-site');
+        }
+        // Store で見つからない → Bridge 経由で見つからない = エディタ未接続
+    }
+
+    // Bridge で全接続にエディタが見つからなかった
+    if (args?.postId != null) {
+        const connNames = allConns.map(c => c.name).join(', ');
+        return _logResolve({
+            mode: 'error',
+            message: `複数サイトが登録されています。Headless モードでは site の指定が必須です。\n利用可能: ${connNames}`,
+        }, 'bridge-no-editor-postId');
+    }
+
+    return _logResolve({
+        mode: 'error',
+        message: 'エディタ未接続です。postId を指定して Headless モードを使用するか、エディタで記事を開いてください。\n接続一覧の確認: list_connections()'
+    }, 'bridge-no-editor-noPid');
+}
+
+/**
+ * postId を解決する（数値はそのまま、文字列は slug として検索）
+ * slug 解決後にエディタ競合チェックも実施
  */
 async function resolvePostId(rawPostId, client, { skipConflictCheck = false } = {}) {
     if (rawPostId == null) return { postId: null };
@@ -1864,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) {
-    // 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 };
+async function handleBatchOperations(operations, snapshotId, mode, client, postId, sessionId, siteName, _modeTag, toolName, expectedRevision, options = {}) {
+    // 1. 全 operation の target を正規化 & ref を一括解決
+    let currentState;
+    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 が指定されている場合のみ）
@@ -1942,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,
             };
         }
@@ -2077,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 };
 }
 
 // フィードバック送信ヘルパー
@@ -2381,13 +3293,14 @@ const tools = [
     },
     {
         name: "list_blog_parts",
-        description: "List or search blog parts (reusable blocks). SWELL theme only.",
+        description: "List or search blog parts (reusable blocks). When partsId is specified, returns posts/pages that directly use that blog parts. SWELL theme only.",
         inputSchema: {
             type: "object",
             properties: {
                 site: siteParam,
-                search: { type: "string", description: "Keyword search" },
-                status: { type: "string", enum: ["publish", "draft", "private", "any"], description: "Status filter (default: publish)" },
+                partsId: { type: "integer", description: "Blog parts ID. When specified, returns posts/pages that directly use this blog parts instead of listing blog parts." },
+                search: { type: "string", description: "Keyword search (ignored when partsId is set)" },
+                status: { type: "string", enum: ["publish", "draft", "private", "any"], description: "Status filter (default: publish, ignored when partsId is set)" },
                 per_page: { type: "integer", description: "Per page (1-100)", minimum: 1, maximum: 100 },
                 page: { type: "integer", description: "Page number", minimum: 1 },
             },
@@ -2411,12 +3324,12 @@ const tools = [
     },
     {
         name: "create_blog_parts",
-        description: "Create a new blog parts (reusable block). SWELL theme only. Returns ID and editor URL.",
+        description: "Create a new blog parts (reusable block). SWELL theme only. Returns partsId and editor URL. To insert into an article, use insert_blog_parts with the returned partsId.",
         inputSchema: {
             type: "object",
             properties: {
                 title:     { type: "string", description: "Blog parts title" },
-                status:    { type: "string", enum: ["publish", "draft", "pending", "private"], description: "Status (default: draft)" },
+                status:    { type: "string", enum: ["publish", "draft", "pending", "private"], description: "Status (default: publish)" },
                 slug:      { type: "string", description: "URL slug" },
                 content:   { type: "string", description: "HTML content (exclusive with filePath)" },
                 filePath:  { type: "string", description: "Local file path (.md or .html, exclusive with content)" },
@@ -2456,6 +3369,23 @@ const tools = [
             required: ["partsId"],
         },
     },
+    {
+        name: "insert_blog_parts",
+        description: "Insert a blog parts block into an article. Builds the correct block HTML automatically.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                partsId:   { type: "integer", description: "Blog parts ID (required)" },
+                postId:    postIdParam,
+                site:      siteParam,
+                snapshotId: { type: "string", description: "Snapshot ID (from get_article_structure or any write response). Required when using beforeRef/afterRef. Omit to append to end." },
+                expectedRevision: { type: "string", description: "Revision from snapshot. Rejects if structure changed." },
+                beforeRef: { type: "string", description: "Insert before this ref." },
+                afterRef:  { type: "string", description: "Insert after this ref." },
+            },
+            required: ["partsId"],
+        },
+    },
     {
         name: "list_taxonomies",
         description: "List categories or tags.",
@@ -2504,7 +3434,7 @@ const tools = [
     },
     {
         name: "get_block_html",
-        description: "Get block HTML. Use before newHTML to safely edit custom/theme blocks.",
+        description: "Get block HTML. Use before newHTML to safely edit custom/theme blocks. Blog parts (loos/blog-parts) are auto-expanded to show inner content. To edit blog parts content, use update_blog_parts.",
         inputSchema: {
             type: "object",
             properties: {
@@ -2680,32 +3610,151 @@ 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" },
+                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 structured JSON with nested folders, IDs, paths, and file counts.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                site: siteParam,
+            },
+        },
+    },
+    {
+        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." },
             },
-            required: ["query"],
         },
     },
     {
@@ -2755,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: {
@@ -2767,8 +3816,87 @@ const tools = [
                 asp_url: { type: "string", description: "ASP affiliate URL (required)" },
                 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"],
         },
     },
 ];
@@ -2881,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) {
@@ -2898,7 +4026,7 @@ async function handleUpdateBlocksTool(args, toolName) {
             return { content: [{ type: "text", text: "❌ filePath は attributeUpdates と併用できません。" }], isError: true };
         }
         try {
-            newHTML = readHTMLFromFile(args.filePath).html;
+            newHTML = await resolveFileToBlockHTML(args.filePath);
         } catch (e) {
             return { content: [{ type: "text", text: `❌ ${e.message}` }], isError: true };
         }
@@ -3168,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']);
+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();
@@ -4230,15 +5358,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
                 if (filePath) {
                     try {
-                        const ext = extname(filePath).toLowerCase();
-                        const raw = readHTMLFromFile(filePath).html;
-                        if (ext === '.md') {
-                            content = await marked.parse(raw);
-                        } else if (ext === '.html' || ext === '.htm') {
-                            content = raw;
-                        } else {
-                            return { content: [{ type: "text", text: `❌ 対応していないファイル形式です: ${ext} (.md または .html のみ)` }], isError: true };
-                        }
+                        content = await resolveFileToBlockHTML(filePath);
                     } catch (e) {
                         return { content: [{ type: "text", text: `❌ ${e.message}` }], isError: true };
                     }
@@ -4360,15 +5480,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
                 if (filePath) {
                     try {
-                        const ext = extname(filePath).toLowerCase();
-                        const raw = readHTMLFromFile(filePath).html;
-                        if (ext === '.md') {
-                            content = await marked.parse(raw);
-                        } else if (ext === '.html' || ext === '.htm') {
-                            content = raw;
-                        } else {
-                            return { content: [{ type: "text", text: `❌ 対応していないファイル形式です: ${ext} (.md または .html のみ)` }], isError: true };
-                        }
+                        content = await resolveFileToBlockHTML(filePath);
                     } catch (e) {
                         return { content: [{ type: "text", text: `❌ ${e.message}` }], isError: true };
                     }
@@ -4376,7 +5488,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
                 const postData = {
                     title,
-                    status: args?.status || 'draft',
+                    status: args?.status || 'publish',
                     post_type: 'blog_parts',
                 };
                 if (args?.slug !== undefined)      postData.slug = args.slug;
@@ -4410,6 +5522,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
 
                 const bpResult = await client.searchBlogParts(args || {});
+
+                if (args?.partsId) {
+                    const usedBy = bpResult.usedBy || [];
+                    if (usedBy.length === 0) {
+                        return { content: [{ type: "text", text: `📋 ブログパーツ [${bpResult.partsId}] "${bpResult.partsTitle}" はどの記事でも使用されていません。` }] };
+                    }
+                    const usageList = usedBy.map(p =>
+                        `  [${p.postId}] ${p.title || '(無題)'}\n    ステータス: ${p.status} | 更新: ${p.modified || '-'}`
+                    ).join('\n\n');
+                    let usageText = `📋 ブログパーツ [${bpResult.partsId}] "${bpResult.partsTitle}" の直接使用箇所 (${usedBy.length}件 / 全${bpResult.total}件)\n\n${usageList}`;
+                    if (bpResult.total_pages > 1) {
+                        const pg = args?.page || 1;
+                        usageText += `\n\n📄 ページ: ${pg} / ${bpResult.total_pages}`;
+                        if (pg < bpResult.total_pages) usageText += ` (次: page=${pg + 1})`;
+                    }
+                    return { content: [{ type: "text", text: usageText }] };
+                }
+
                 const bpParts = bpResult.items || [];
                 const bpTotal = bpResult.total || 0;
                 const bpTotalPages = bpResult.total_pages || 0;
@@ -4423,7 +5553,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return `  [${p.id}] ${p.title || '(無題)'}\n    ステータス: ${p.status} | 更新: ${p.modified || '-'}`;
                 }).join('\n\n');
 
-                let bpText = `📋 ブログ��ーツ一覧 (${bpParts.length}件 / 全${bpTotal}件)\n\n${bpList}`;
+                let bpText = `📋 ブログパーツ一覧 (${bpParts.length}件 / 全${bpTotal}件)\n\n${bpList}`;
                 if (bpTotalPages > 1) {
                     bpText += `\n\n📄 ページ: ${bpPage} / ${bpTotalPages}`;
                     if (bpPage < bpTotalPages) {
@@ -4629,6 +5759,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: "text", text }] };
             }
 
+            case "insert_blog_parts": {
+                if (!args?.partsId) {
+                    return { content: [{ type: "text", text: "❌ partsId は必須です。" }], isError: true };
+                }
+                args.rawHTML = `<!-- wp:loos/blog-parts {"partsID":"${args.partsId}"} /-->`;
+                // insert_block に fallthrough
+            }
+
             case "insert_block": {
                 let { rawHTML, filePath } = (args || {});
 
@@ -4644,7 +5782,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
                 // filePath → rawHTML 解決
                 if (filePath) {
-                    try { rawHTML = readHTMLFromFile(filePath).html; }
+                    try { rawHTML = await resolveFileToBlockHTML(filePath); }
                     catch (e) { return { content: [{ type: "text", text: `❌ ${e.message}` }], isError: true }; }
                 }
                 if (!rawHTML) {
@@ -4757,10 +5895,36 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     blocks = result.blocks || [];
                 }
 
+                // エディタモード時、ブログパーツの展開を補完
+                if (mode === 'editor' && client) {
+                    for (const b of blocks) {
+                        if (b.type === 'loos/blog-parts' && !b.blogParts) {
+                            const pid = parseInt(b.html?.match(/partsID["\s:]+["']?(\d+)/)?.[1], 10);
+                            if (pid > 0) {
+                                try {
+                                    const bpResult = await client.headlessGetBlockHtml(pid, {});
+                                    b.blogParts = {
+                                        partsId: pid,
+                                        blocks: bpResult?.blocks || [],
+                                    };
+                                } catch (_) {}
+                            }
+                        }
+                    }
+                }
+
                 const _modeTag = process.env.FRIDAY_DEBUG === '1' ? `\n[DEBUG] mode=${mode}` : '';
                 let text = `📦 ブロックHTML取得 (${blocks.length}件)\n`;
                 for (const b of blocks) {
-                    text += `\n[${b.index}] ${b.type}\n${b.html}\n`;
+                    text += `\n[${b.index}] ${b.type}\n`;
+                    if (b.blogParts && b.blogParts.blocks) {
+                        for (const inner of b.blogParts.blocks) {
+                            if ((inner.depth || 0) > 0) continue;
+                            text += `${inner.html}\n`;
+                        }
+                    } else {
+                        text += `${b.html}\n`;
+                    }
                 }
                 text += _modeTag;
                 return { content: [{ type: "text", text }] };
@@ -5061,116 +6225,640 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const profileOpen = openInChromeProfile(url);
                 if (profileOpen) {
                     try {
-                        await profileOpen;
-                        return { content: [{ type: "text", text: `🌐 ${label}をブラウザで開きました（Chrome プロファイル指定）\nURL: ${url}${_mt_oib}` }] };
-                    } catch (_) {
-                        // Chrome プロファイル起動失敗 → フォールバック
+                        await profileOpen;
+                        return { content: [{ type: "text", text: `🌐 ${label}をブラウザで開きました（Chrome プロファイル指定）\nURL: ${url}${_mt_oib}` }] };
+                    } catch (_) {
+                        // Chrome プロファイル起動失敗 → フォールバック
+                    }
+                }
+
+                // 3. OS デフォルト（最終フォールバック）
+                try {
+                    await openInBrowser(url);
+                    return { content: [{ type: "text", text: `🌐 ${label}をブラウザで開きました（OSデフォルト）\nURL: ${url}\n\n⚠️ プロファイル固定するには FRIDAY_CHROME_PATH と FRIDAY_CHROME_PROFILE を設定してください。${_mt_oib}` }] };
+                } catch (e) {
+                    return { content: [{ type: "text", text: `⚠️ ブラウザの起動に失敗しました。URLを手動で開いてください:\n${url}\n\nエラー: ${e.message}` }], isError: true };
+                }
+            }
+
+            case "upload_media": {
+                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 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 jsonErrorResponse(e);
+                }
+            }
+
+            case "search_media": {
+                const siteName = args?.site || 'default';
+                let client;
+                try { client = registry.get(siteName); }
+                catch (e) { return jsonErrorResponse(e, 'VALIDATION_ERROR'); }
+
+                try {
+                    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) {
+                    return jsonErrorResponse(e);
+                }
+            }
+
+            case "list_media_folders": {
+                const siteName = args?.site || 'default';
+                let client;
+                try { client = registry.get(siteName); }
+                catch (e) { return errorResponse("list_media_folders", e.message, 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) }] };
+            }
+
+            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); }
+
+                try {
+                    if (typeof args?.name !== 'string') {
+                        throwToolError('VALIDATION_ERROR', 'name は必須の文字列です', false);
+                    }
+                    const folderName = args.name.trim().normalize('NFC');
+                    if (!folderName) {
+                        throwToolError('VALIDATION_ERROR', 'name は空にできません', false);
+                    }
+                    if (folderName.includes('/') || folderName.includes('／')) {
+                        throwToolError('VALIDATION_ERROR', 'name にスラッシュは使用できません。親フォルダは parent または parentId で指定してください', false);
+                    }
+
+                    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 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);
+                    }
+
+                    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);
+                }
+            }
+
+            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); }
+
+                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');
+
+                    const normalized = await getNormalizedFileBirdFolders(client);
+                    const target = resolveFolderTarget(normalized, { folder: args?.folder, folderId: args?.folderId });
+
+                    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;
                     }
-                }
 
-                // 3. OS デフォルト（最終フォールバック）
-                try {
-                    await openInBrowser(url);
-                    return { content: [{ type: "text", text: `🌐 ${label}をブラウザで開きました（OSデフォルト）\nURL: ${url}\n\n⚠️ プロファイル固定するには FRIDAY_CHROME_PATH と FRIDAY_CHROME_PROFILE を設定してください。${_mt_oib}` }] };
+                    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 { content: [{ type: "text", text: `⚠️ ブラウザの起動に失敗しました。URLを手動で開いてください:\n${url}\n\nエラー: ${e.message}` }], isError: true };
+                    return jsonErrorResponse(e);
                 }
             }
 
-            case "upload_media": {
+            case "update_media_meta": {
                 const siteName = args?.site || 'default';
                 let client;
                 try { client = registry.get(siteName); }
-                catch (e) { return errorResponse("upload_media", e.message, siteName); }
+                catch (e) { return jsonToolResponse({ success: false, error: toolError('VALIDATION_ERROR', e.message, false) }, true); }
 
-                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);
+                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;
+                    }
 
-                let fileInfo;
-                try { fileInfo = validateImageFile(args.filePath); }
-                catch (e) { return errorResponse("upload_media", e.message, siteName); }
+                    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);
+                }
+            }
 
-                const uploadFilename = `${args.name}${fileInfo.ext}`;
-                const fileBuffer = readFileSync(fileInfo.resolved);
+            case "get_media": {
+                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); }
 
-                let media;
                 try {
-                    media = await client.uploadMedia(fileBuffer, uploadFilename, fileInfo.contentType);
+                    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 errorResponse("upload_media", `Upload failed: ${e.message}`, siteName);
+                    return jsonErrorResponse(e);
                 }
+            }
+
+            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); }
 
-                const titleText = args?.title || args.alt;
                 try {
-                    await client.updateMediaMeta(media.id, { title: titleText, alt_text: args.alt });
+                    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) {
-                    // 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 "delete_media_folder": {
                 const siteName = args?.site || 'default';
                 let client;
                 try { client = registry.get(siteName); }
-                catch (e) { return errorResponse("search_media", e.message, siteName); }
-
-                if (!args?.query) return errorResponse("search_media", "query is required", siteName);
-
-                const variants = generateSearchVariants(args.query, args?.strip, args?.prefix);
-                const perPage = args?.per_page || 10;
-
-                const results = await Promise.allSettled(
-                    variants.map(v => client.searchMedia(v, perPage))
-                );
-
-                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],
-                        });
+                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 };
+                };
 
-                let text = `🔍 Search: "${args.query}"\n`;
-                text += `🔄 Variants (${variants.length}): ${variants.join(', ')}\n\n`;
+                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);
+                    }
 
-                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`;
+                    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}" を指定してください。`,
+                        });
                     }
-                }
 
-                return { content: [{ type: "text", text }] };
+                    // --- 実行（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);
+                }
             }
 
             case "list_connections": {
@@ -5248,7 +6936,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const list = items.map(item => {
                     const lines = [
                         `  [${item.id}] ${item.title}`,
-                        `    案件ID: ${item.data_id} | slug: ${item.slug}`,
+                        `    案件ID: ${item.data_id} | slug: ${item.slug} | permalink: ${item.permalink}`,
                     ];
                     if (item.asp_url) lines.push(`    ASP URL: ${item.asp_url}`);
                     if (item.asp_url_sp) lines.push(`    ASP URL(B): ${item.asp_url_sp}`);
@@ -5273,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 };
                 }
@@ -5287,6 +7035,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         asp_url: args.asp_url,
                         asp_url_sp: args?.asp_url_sp,
                         direct_url: args?.direct_url,
+                        permalink: args?.permalink,
                     });
                 } catch (e) {
                     return { content: [{ type: "text", text: `❌ ASPリンク登録エラー: ${e.message}` }], isError: true };
@@ -5298,16 +7047,667 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     `  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}`);
+                lines.push(`  tag: ${result.tag}`);
+
+                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}`);
         } })();