@adsim/wordpress-mcp-server 4.6.0 → 5.3.1

package/src/tools/content.js

@@ -0,0 +1,395 @@
+// src/tools/content.js — content tools (13)
+// Definitions + handlers (v5.0.0 refactor Step B+C)
+
+import { json, strip, buildPaginationMeta, validateBlocks } from '../shared/utils.js';
+import { validateInput } from '../shared/governance.js';
+import { rt } from '../shared/context.js';
+
+export const definitions = [
+  { name: 'wp_list_posts', _category: 'content', description: 'Use to browse/filter posts by status, category, tag, author, or search. Read-only. Hint: use mode=\'summary\' for listings, \'ids_only\' for batch ops.', inputSchema: { type: 'object', properties: { per_page: { type: 'number', default: 10 }, page: { type: 'number', default: 1 }, status: { type: 'string', default: 'publish' }, orderby: { type: 'string', default: 'date' }, order: { type: 'string', default: 'desc' }, categories: { type: 'string' }, tags: { type: 'string' }, search: { type: 'string' }, author: { type: 'number' }, mode: { type: 'string', default: 'full', description: 'full=all fields, summary=id/title/slug/date/status/link only, ids_only=flat ID array' } }}},
+  { name: 'wp_get_post', _category: 'content', description: 'Use to read a single post with full content and meta. Read-only. Hint: use content_format=\'links_only\' for link audits (~800 chars vs 187k), \'text\' for rewrites, fields=[\'id\',\'title\',\'meta\'] for SEO-only.', inputSchema: { type: 'object', properties: { id: { type: 'number' }, fields: { type: 'array', items: { type: 'string' }, description: 'Return only specified fields (id,title,content,excerpt,slug,status,date,modified,categories,tags,author,featured_media,meta,link). Omit for all.' }, content_format: { type: 'string', default: 'html', description: 'html=raw HTML (truncated at WP_MAX_CONTENT_CHARS), text=plain text, links_only=extract internal links only' } }, required: ['id'] }},
+  { name: 'wp_create_post', _category: 'content', description: 'Use to create a post (defaults to draft). Accepts title, HTML content, categories, tags, featured_media, meta. Write — blocked by WP_READ_ONLY.', inputSchema: { type: 'object', properties: { title: { type: 'string' }, content: { type: 'string' }, status: { type: 'string', default: 'draft' }, excerpt: { type: 'string' }, categories: { type: 'array', items: { type: 'number' } }, tags: { type: 'array', items: { type: 'number' } }, slug: { type: 'string' }, featured_media: { type: 'number' }, meta: { type: 'object' }, author: { type: 'number' } }, required: ['title', 'content'] }},
+  { name: 'wp_update_post', _category: 'content', description: 'Use to modify any post field — only provided fields change. Write — blocked by WP_READ_ONLY.', inputSchema: { type: 'object', properties: { id: { type: 'number' }, title: { type: 'string' }, content: { type: 'string' }, status: { type: 'string' }, excerpt: { type: 'string' }, categories: { type: 'array', items: { type: 'number' } }, tags: { type: 'array', items: { type: 'number' } }, slug: { type: 'string' }, featured_media: { type: 'number' }, meta: { type: 'object' }, author: { type: 'number' } }, required: ['id'] }},
+  { name: 'wp_delete_post', _category: 'content', description: 'Use to trash or permanently delete a post. Write — blocked by WP_READ_ONLY, WP_DISABLE_DELETE.', inputSchema: { type: 'object', properties: { id: { type: 'number' }, force: { type: 'boolean', default: false }, confirmation_token: { type: 'string', description: 'Confirmation token returned by the first call when WP_CONFIRM_DESTRUCTIVE=true' } }, required: ['id'] }},
+  { name: 'wp_search', _category: 'content', description: 'Use for full-text search across all content types. Returns id, title, url, type. Read-only.', inputSchema: { type: 'object', properties: { search: { type: 'string' }, per_page: { type: 'number', default: 10 }, type: { type: 'string', default: '' } }, required: ['search'] }},
+  { name: 'wp_validate_block_structure', _category: 'content', description: 'Use to validate Gutenberg block HTML structure before saving. Detects unclosed blocks, malformed JSON attributes, invalid nesting, unclosed HTML tags, and deprecated blocks. Read-only.',
+        inputSchema: { type: 'object', properties: { content: { type: 'string', description: 'Gutenberg block HTML to validate' }, post_id: { type: 'number', description: 'Optional post ID for context' }, strict: { type: 'boolean', default: false, description: 'true = error on missing attributes' }, fix_suggestions: { type: 'boolean', default: true, description: 'Include fix suggestions' } }, required: ['content'] }},
+  { name: 'wp_bulk_update', _category: 'content', description: 'Use to bulk update content across multiple posts/pages. Supports text replacement, meta updates, status changes, and content append. Dry-run by default for safety. Write — blocked by WP_READ_ONLY.',
+        inputSchema: { type: 'object', properties: { post_ids: { type: 'array', items: { type: 'number' }, description: 'Specific post IDs to update. If absent, uses filters.' }, post_type: { type: 'string', default: 'post', description: 'post or page' }, filters: { type: 'object', properties: { category_id: { type: 'number' }, tag_id: { type: 'number' }, status: { type: 'string' }, date_before: { type: 'string' }, date_after: { type: 'string' } }, description: 'Filters to select posts when post_ids is absent' }, operations: { type: 'array', items: { type: 'object', properties: { type: { type: 'string', enum: ['replace_text', 'update_meta', 'update_status', 'append_content'] }, params: { type: 'object' } }, required: ['type', 'params'] }, description: 'Operations to apply to each post' }, dry_run: { type: 'boolean', default: true }, confirm: { type: 'boolean', default: false }, limit: { type: 'number', default: 50, description: 'Max posts to process (max 500)' }, batch_size: { type: 'number', default: 10, description: 'Posts per batch' } }, required: ['operations'] }},
+  { name: 'wp_list_pages', _category: 'content', description: 'Use to browse pages with hierarchy and templates. Supports parent filter, menu_order sort. Read-only. Hint: use mode=\'summary\' for listings, \'ids_only\' for batch ops.', inputSchema: { type: 'object', properties: { per_page: { type: 'number', default: 10 }, page: { type: 'number', default: 1 }, status: { type: 'string', default: 'publish' }, parent: { type: 'number' }, orderby: { type: 'string', default: 'menu_order' }, order: { type: 'string', default: 'asc' }, search: { type: 'string' }, mode: { type: 'string', enum: ['full', 'summary', 'ids_only'], default: 'full', description: 'full=all fields, summary=key fields only, ids_only=flat ID array' } }}},
+  { name: 'wp_get_page', _category: 'content', description: 'Use to read a single page with content and template. Read-only. Warning: Elementor pages can exceed 100k chars.', inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] }},
+  { name: 'wp_create_page', _category: 'content', description: 'Use to create a page (defaults to draft). Supports parent, template, menu_order. Write — blocked by WP_READ_ONLY.', inputSchema: { type: 'object', properties: { title: { type: 'string' }, content: { type: 'string' }, status: { type: 'string', default: 'draft' }, parent: { type: 'number', default: 0 }, template: { type: 'string' }, menu_order: { type: 'number', default: 0 }, excerpt: { type: 'string' }, slug: { type: 'string' }, featured_media: { type: 'number' }, meta: { type: 'object' } }, required: ['title', 'content'] }},
+  { name: 'wp_update_page', _category: 'content', description: 'Use to modify any page field. Write — blocked by WP_READ_ONLY.', inputSchema: { type: 'object', properties: { id: { type: 'number' }, title: { type: 'string' }, content: { type: 'string' }, status: { type: 'string' }, parent: { type: 'number' }, template: { type: 'string' }, menu_order: { type: 'number' }, excerpt: { type: 'string' }, slug: { type: 'string' }, featured_media: { type: 'number' }, meta: { type: 'object' } }, required: ['id'] }},
+  { name: 'wp_get_post_meta', _category: 'content', description: 'Read post meta fields. Use for ACF data if acf/v3 unavailable, or for any custom meta (_elementor_data, _yoast_wpseo_*, etc.). Returns all meta if meta_key omitted.',
+        inputSchema: { type: 'object', properties: { post_id: { type: 'number' }, post_type: { type: 'string', default: 'posts', description: 'posts or pages' }, meta_key: { type: 'string', description: 'Specific key. Omit for all meta.' }, parse_json: { type: 'boolean', default: true, description: 'Auto-parse JSON strings (e.g. _elementor_data)' } }, required: ['post_id'] }}
+];
+
+export const handlers = {};
+
+handlers['wp_list_posts'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, sanitizeParams, name, STATUSES, ORDERBY, ORDERS } = rt;
+  validateInput(args, { per_page: { type: 'number', min: 1, max: 100 }, page: { type: 'number', min: 1 }, status: { type: 'string', enum: STATUSES }, orderby: { type: 'string', enum: ORDERBY }, order: { type: 'string', enum: ORDERS }, mode: { type: 'string', enum: ['full', 'summary', 'ids_only'] } });
+  const { per_page = 10, page = 1, status = 'publish', orderby = 'date', order = 'desc', categories, tags, search, author, mode = 'full' } = args;
+  let ep = `/posts?per_page=${per_page}&page=${page}&status=${status}&orderby=${orderby}&order=${order}`;
+  if (categories) ep += `&categories=${categories}`; if (tags) ep += `&tags=${tags}`;
+  if (search) ep += `&search=${encodeURIComponent(search)}`; if (author) ep += `&author=${author}`;
+  const posts = await wpApiCall(ep);
+  let listResult;
+  if (mode === 'ids_only') {
+    listResult = { total: posts.length, page, mode: 'ids_only', ids: posts.map(p => p.id) };
+  } else if (mode === 'summary') {
+    listResult = { total: posts.length, page, mode: 'summary', posts: posts.map(p => ({ id: p.id, title: p.title.rendered, slug: p.slug, date: p.date, status: p.status, link: p.link })) };
+  } else {
+    listResult = { total: posts.length, page, posts: posts.map(p => ({ id: p.id, title: p.title.rendered, status: p.status, date: p.date, modified: p.modified, link: p.link, author: p.author, categories: p.categories, tags: p.tags, excerpt: strip(p.excerpt.rendered).substring(0, 200) })) };
+  }
+  if (posts._wpTotal !== undefined) listResult.pagination = buildPaginationMeta(posts._wpTotal, page, per_page);
+  result = json(listResult);
+  auditLog({ tool: name, action: 'list', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wp_get_post'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, getActiveAuth, auditLog, name, summarizePost, applyContentFormat } = rt;
+  validateInput(args, { id: { type: 'number', required: true, min: 1 }, fields: { type: 'array' }, content_format: { type: 'string', enum: ['html', 'text', 'links_only'] } });
+  const { content_format = 'html', fields: requestedFields } = args;
+  const p = await wpApiCall(`/posts/${args.id}`);
+  let postData = { id: p.id, title: p.title.rendered, content: p.content.rendered, excerpt: p.excerpt.rendered, status: p.status, date: p.date, modified: p.modified, link: p.link, slug: p.slug, categories: p.categories, tags: p.tags, author: p.author, featured_media: p.featured_media, comment_status: p.comment_status, meta: p.meta || {} };
+  if (p.acf && Object.keys(p.acf).length > 0) { postData.acf_fields = p.acf; }
+  else { postData.acf_fields = {}; postData.acf_hint = 'ACF returned empty. Verify Show in REST API is enabled in each Field Group settings in WordPress Admin.'; }
+  const { url: siteUrl } = getActiveAuth();
+  postData = applyContentFormat(postData, content_format, siteUrl);
+  if (requestedFields && requestedFields.length > 0) postData = summarizePost(postData, requestedFields);
+  result = json(postData);
+  auditLog({ tool: name, target: args.id, target_type: 'post', action: 'read', status: 'success', latency_ms: Date.now() - t0 });
+  return result;
+};
+handlers['wp_create_post'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, getActiveControls, auditLog, sanitizeParams, name, enforceDraftOnly, enforceAllowedStatuses, enforceAllowedTypes, STATUSES } = rt;
+  validateInput(args, { title: { type: 'string', required: true }, content: { type: 'string', required: true }, status: { type: 'string', enum: STATUSES.filter(s => s !== 'trash') } });
+  enforceDraftOnly(args.status); enforceAllowedStatuses(args.status); enforceAllowedTypes('post');
+  if (getActiveControls().require_approval && args.status === 'publish') {
+    auditLog({ tool: name, target: null, target_type: 'post', action: 'create', status: 'blocked', latency_ms: Date.now() - t0, params: sanitizeParams(args), error: 'APPROVAL REQUIRED: Use wp_submit_for_review then wp_approve_post' });
+    return { content: [{ type: 'text', text: 'Error: APPROVAL REQUIRED: Use wp_submit_for_review then wp_approve_post' }], isError: true };
+  }
+  const { title, content, status = 'draft', excerpt, categories, tags, slug, featured_media, meta, author } = args;
+  const data = { title, content, status };
+  if (excerpt) data.excerpt = excerpt; if (categories) data.categories = categories; if (tags) data.tags = tags;
+  if (slug) data.slug = slug; if (featured_media) data.featured_media = featured_media; if (meta) data.meta = meta; if (author) data.author = author;
+  const np = await wpApiCall('/posts', { method: 'POST', body: JSON.stringify(data) });
+  result = json({ success: true, message: 'Post created', post: { id: np.id, title: np.title.rendered, status: np.status, link: np.link, slug: np.slug } });
+  auditLog({ tool: name, target: np.id, target_type: 'post', action: 'create', status: 'success', latency_ms: Date.now() - t0, params: { title, status } });
+  return result;
+};
+handlers['wp_update_post'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, getActiveControls, auditLog, sanitizeParams, name, enforceDraftOnly, enforceAllowedStatuses, STATUSES } = rt;
+  validateInput(args, { id: { type: 'number', required: true, min: 1 }, status: { type: 'string', enum: STATUSES } });
+  if (args.status) { enforceDraftOnly(args.status); enforceAllowedStatuses(args.status); }
+  if (getActiveControls().require_approval && args.status === 'publish') {
+    auditLog({ tool: name, target: args.id, target_type: 'post', action: 'update', status: 'blocked', latency_ms: Date.now() - t0, params: sanitizeParams(args), error: 'APPROVAL REQUIRED: Use wp_submit_for_review then wp_approve_post' });
+    return { content: [{ type: 'text', text: 'Error: APPROVAL REQUIRED: Use wp_submit_for_review then wp_approve_post' }], isError: true };
+  }
+  const { id, ...upd } = args;
+  const up = await wpApiCall(`/posts/${id}`, { method: 'POST', body: JSON.stringify(upd) });
+  result = json({ success: true, message: `Post ${id} updated`, post: { id: up.id, title: up.title.rendered, status: up.status, link: up.link, modified: up.modified } });
+  auditLog({ tool: name, target: id, target_type: 'post', action: 'update', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(upd) });
+  return result;
+};
+handlers['wp_delete_post'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, getActiveControls, generateToken, validateToken, auditLog, name } = rt;
+  validateInput(args, { id: { type: 'number', required: true, min: 1 } });
+  const { id, force = false, confirmation_token } = args;
+  const deleteAction = force ? 'permanent_delete' : 'trash';
+
+  // Two-step confirmation when WP_CONFIRM_DESTRUCTIVE=true
+  if (getActiveControls().confirm_destructive) {
+    if (!confirmation_token) {
+      // Step 1: return confirmation_required with token
+      const p = await wpApiCall(`/posts/${id}`);
+      const token = generateToken(id, deleteAction);
+      const verb = force ? 'permanently deleted' : 'trashed';
+      result = json({ status: 'confirmation_required', post_id: id, post_title: p.title?.rendered || `Post #${id}`, action: deleteAction, confirmation_token: token, expires_in: 60, message: `Post #${id} '${p.title?.rendered || ''}' will be ${verb}. Call again with confirmation_token to confirm.` });
+      auditLog({ tool: name, target: id, target_type: 'post', action: 'delete_requested', status: 'pending', latency_ms: Date.now() - t0, params: { id, force } });
+      return result;
+    }
+    // Step 2: validate token then execute
+    const validation = validateToken(confirmation_token, id, deleteAction);
+    if (!validation.valid) {
+      auditLog({ tool: name, target: id, target_type: 'post', action: deleteAction, status: 'error', latency_ms: Date.now() - t0, params: { id, force }, error: 'Invalid or expired confirmation token' });
+      return { content: [{ type: 'text', text: 'Error: Invalid or expired confirmation token' }], isError: true };
+    }
+  }
+
+  const dp = await wpApiCall(`/posts/${id}${force ? '?force=true' : ''}`, { method: 'DELETE' });
+  result = json({ success: true, message: force ? `Post ${id} permanently deleted` : `Post ${id} trashed`, post: { id: dp.id, title: dp.title?.rendered || dp.previous?.title?.rendered, status: force ? 'deleted' : 'trash' } });
+  auditLog({ tool: name, target: id, target_type: 'post', action: deleteAction, status: 'success', latency_ms: Date.now() - t0 });
+  return result;
+};
+handlers['wp_search'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, name } = rt;
+  validateInput(args, { search: { type: 'string', required: true }, per_page: { type: 'number', min: 1, max: 100 } });
+  const { search, per_page = 10, type } = args;
+  let ep = `/search?search=${encodeURIComponent(search)}&per_page=${per_page}`;
+  if (type) ep += `&type=${type}`;
+  const r = await wpApiCall(ep);
+  result = json({ query: search, total: r.length, results: r.map(x => ({ id: x.id, title: x.title, url: x.url, type: x.type, subtype: x.subtype })) });
+  auditLog({ tool: name, action: 'search', status: 'success', latency_ms: Date.now() - t0, params: { search, type } });
+  return result;
+};
+handlers['wp_validate_block_structure'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { auditLog, name } = rt;
+  validateInput(args, { content: { type: 'string', required: true } });
+  const { content, strict = false, fix_suggestions = true } = args;
+  const validation = validateBlocks(content, strict, fix_suggestions);
+  result = json(validation);
+  auditLog({ tool: name, action: 'validate_blocks', status: validation.valid ? 'valid' : 'invalid', latency_ms: Date.now() - t0, params: { errors: validation.errors.length, warnings: validation.warnings.length } });
+  return result;
+};
+handlers['wp_bulk_update'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, sanitizeParams, name } = rt;
+  const { post_ids, post_type = 'post', filters = {}, operations, dry_run = true, confirm = false, limit = 50, batch_size = 10 } = args;
+  if (!operations || !operations.length) throw new Error('operations array is required and must not be empty.');
+  const effectiveLimit = Math.min(Math.max(1, limit), 500);
+  const effectiveBatch = Math.min(Math.max(1, batch_size), 100);
+
+  // Resolve target post IDs
+  let targetIds = [];
+  if (post_ids && post_ids.length > 0) {
+    targetIds = post_ids.slice(0, effectiveLimit);
+  } else {
+    // Build query from filters
+    const hasFilter = filters.category_id || filters.tag_id || filters.status || filters.date_before || filters.date_after;
+    if (!hasFilter) throw new Error('Either post_ids or at least one filter (category_id, tag_id, status, date_before, date_after) is required.');
+    const endpoint = post_type === 'page' ? '/pages' : '/posts';
+    let ep = `${endpoint}?per_page=${effectiveLimit}&_fields=id`;
+    if (filters.status) ep += `&status=${filters.status}`;
+    else ep += '&status=publish';
+    if (filters.category_id) ep += `&categories=${filters.category_id}`;
+    if (filters.tag_id) ep += `&tags=${filters.tag_id}`;
+    if (filters.date_before) ep += `&before=${filters.date_before}`;
+    if (filters.date_after) ep += `&after=${filters.date_after}`;
+    const fetched = await wpApiCall(ep);
+    targetIds = (Array.isArray(fetched) ? fetched : []).map(p => p.id).slice(0, effectiveLimit);
+  }
+
+  if (targetIds.length === 0) {
+    result = json({ mode: dry_run ? 'dry_run' : 'preview', posts_affected: 0, operations_preview: [], message: 'No posts matched the given criteria.' });
+    auditLog({ tool: name, action: 'bulk_update', status: 'empty', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+    return result;
+  }
+
+  // Helper: compute changes preview for a single post
+  function previewChanges(post, ops) {
+    const changes = [];
+    for (const op of ops) {
+      switch (op.type) {
+        case 'replace_text': {
+          const { search: s, replace: r, case_sensitive = true } = op.params || {};
+          const content = post.content?.rendered || '';
+          const flags = case_sensitive ? 'g' : 'gi';
+          const count = (content.match(new RegExp(s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), flags)) || []).length;
+          if (count > 0) changes.push({ type: 'replace_text', search: s, replace: r, occurrences: count });
+          break;
+        }
+        case 'update_meta': {
+          const { key, value } = op.params || {};
+          changes.push({ type: 'update_meta', key, new_value: value, old_value: post.meta?.[key] ?? null });
+          break;
+        }
+        case 'update_status': {
+          const { status: newStatus } = op.params || {};
+          if (post.status !== newStatus) changes.push({ type: 'update_status', from: post.status, to: newStatus });
+          break;
+        }
+        case 'append_content': {
+          const { content: c, position = 'after' } = op.params || {};
+          changes.push({ type: 'append_content', position, content_length: (c || '').length });
+          break;
+        }
+      }
+    }
+    return changes;
+  }
+
+  // Dry-run or preview mode
+  if (dry_run || !confirm) {
+    const previewIds = targetIds.slice(0, 10);
+    const endpoint = post_type === 'page' ? '/pages' : '/posts';
+    const previews = [];
+    for (const pid of previewIds) {
+      const p = await wpApiCall(`${endpoint}/${pid}`);
+      previews.push({ post_id: pid, title: p.title?.rendered || '', changes: previewChanges(p, operations) });
+    }
+    result = json({
+      mode: dry_run ? 'dry_run' : 'preview',
+      posts_affected: targetIds.length,
+      operations_preview: previews,
+      warning: dry_run ? 'Set dry_run=false and confirm=true to apply changes.' : 'Set confirm=true to apply changes.'
+    });
+    auditLog({ tool: name, action: 'bulk_update_preview', status: 'dry_run', latency_ms: Date.now() - t0, params: { posts_count: targetIds.length, operations: operations.map(o => o.type) } });
+    return result;
+  }
+
+  // Execute mode: dry_run=false, confirm=true
+  const endpoint = post_type === 'page' ? '/pages' : '/posts';
+  let updated = 0;
+  const failed = [];
+  for (let i = 0; i < targetIds.length; i += effectiveBatch) {
+    const batch = targetIds.slice(i, i + effectiveBatch);
+    for (const pid of batch) {
+      try {
+        const p = await wpApiCall(`${endpoint}/${pid}`);
+        const updateData = {};
+        for (const op of operations) {
+          switch (op.type) {
+            case 'replace_text': {
+              const { search: s, replace: r, case_sensitive = true } = op.params || {};
+              const content = p.content?.rendered || '';
+              const flags = case_sensitive ? 'g' : 'gi';
+              updateData.content = (updateData.content || content).replace(new RegExp(s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), flags), r);
+              break;
+            }
+            case 'update_meta': {
+              const { key, value } = op.params || {};
+              if (!updateData.meta) updateData.meta = {};
+              updateData.meta[key] = value;
+              break;
+            }
+            case 'update_status': {
+              updateData.status = op.params.status;
+              break;
+            }
+            case 'append_content': {
+              const { content: c, position = 'after' } = op.params || {};
+              const existing = updateData.content || p.content?.rendered || '';
+              updateData.content = position === 'before' ? c + existing : existing + c;
+              break;
+            }
+          }
+        }
+        if (Object.keys(updateData).length > 0) {
+          await wpApiCall(`${endpoint}/${pid}`, { method: 'POST', body: JSON.stringify(updateData) });
+          updated++;
+        }
+      } catch (e) {
+        failed.push({ post_id: pid, error: e.message });
+      }
+    }
+  }
+  result = json({ success: true, posts_updated: updated, posts_failed: failed, duration_ms: Date.now() - t0 });
+  auditLog({ tool: name, action: 'bulk_update', status: 'success', latency_ms: Date.now() - t0, params: { posts_count: updated, operations: operations.map(o => o.type) } });
+  return result;
+};
+handlers['wp_list_pages'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, name, STATUSES, ORDERS } = rt;
+  validateInput(args, { per_page: { type: 'number', min: 1, max: 100 }, page: { type: 'number', min: 1 }, status: { type: 'string', enum: STATUSES }, order: { type: 'string', enum: ORDERS }, mode: { type: 'string', enum: ['full', 'summary', 'ids_only'] } });
+  const { per_page = 10, page = 1, status = 'publish', parent, orderby = 'menu_order', order = 'asc', search, mode = 'full' } = args;
+  let ep = `/pages?per_page=${per_page}&page=${page}&status=${status}&orderby=${orderby}&order=${order}`;
+  if (parent !== undefined) ep += `&parent=${parent}`; if (search) ep += `&search=${encodeURIComponent(search)}`;
+  const pgs = await wpApiCall(ep);
+  const pgPagination = pgs._wpTotal !== undefined ? buildPaginationMeta(pgs._wpTotal, page, per_page) : undefined;
+  if (mode === 'ids_only') {
+    result = json({ total: pgs.length, page, mode: 'ids_only', ids: pgs.map(p => p.id), ...(pgPagination && { pagination: pgPagination }) });
+    auditLog({ tool: name, action: 'list', status: 'success', latency_ms: Date.now() - t0 });
+    return result;
+  }
+  if (mode === 'summary') {
+    result = json({ total: pgs.length, page, mode: 'summary', pages: pgs.map(p => ({ id: p.id, title: p.title.rendered, slug: p.slug, status: p.status, link: p.link, parent: p.parent })), ...(pgPagination && { pagination: pgPagination }) });
+    auditLog({ tool: name, action: 'list', status: 'success', latency_ms: Date.now() - t0 });
+    return result;
+  }
+  result = json({ total: pgs.length, page, pages: pgs.map(p => ({ id: p.id, title: p.title.rendered, status: p.status, date: p.date, link: p.link, parent: p.parent, menu_order: p.menu_order, template: p.template, excerpt: strip(p.excerpt.rendered).substring(0, 200) })), ...(pgPagination && { pagination: pgPagination }) });
+  auditLog({ tool: name, action: 'list', status: 'success', latency_ms: Date.now() - t0 });
+  return result;
+};
+handlers['wp_get_page'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, name } = rt;
+  validateInput(args, { id: { type: 'number', required: true, min: 1 } });
+  const pg = await wpApiCall(`/pages/${args.id}`);
+  const pageData = { id: pg.id, title: pg.title.rendered, content: pg.content.rendered, excerpt: pg.excerpt.rendered, status: pg.status, date: pg.date, modified: pg.modified, link: pg.link, slug: pg.slug, parent: pg.parent, menu_order: pg.menu_order, template: pg.template, author: pg.author, featured_media: pg.featured_media, meta: pg.meta || {} };
+  if (pg.acf && Object.keys(pg.acf).length > 0) { pageData.acf_fields = pg.acf; }
+  else { pageData.acf_fields = {}; pageData.acf_hint = 'ACF returned empty. Verify Show in REST API is enabled in each Field Group settings in WordPress Admin.'; }
+  result = json(pageData);
+  auditLog({ tool: name, target: args.id, target_type: 'page', action: 'read', status: 'success', latency_ms: Date.now() - t0 });
+  return result;
+};
+handlers['wp_create_page'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, name, enforceDraftOnly, enforceAllowedStatuses, enforceAllowedTypes, STATUSES } = rt;
+  validateInput(args, { title: { type: 'string', required: true }, content: { type: 'string', required: true }, status: { type: 'string', enum: STATUSES.filter(s => s !== 'trash') } });
+  enforceDraftOnly(args.status); enforceAllowedStatuses(args.status); enforceAllowedTypes('page');
+  const { title, content, status = 'draft', parent = 0, template, menu_order = 0, excerpt, slug, featured_media, meta } = args;
+  const data = { title, content, status, parent, menu_order };
+  if (template) data.template = template; if (excerpt) data.excerpt = excerpt; if (slug) data.slug = slug;
+  if (featured_media) data.featured_media = featured_media; if (meta) data.meta = meta;
+  const np = await wpApiCall('/pages', { method: 'POST', body: JSON.stringify(data) });
+  result = json({ success: true, message: 'Page created', page: { id: np.id, title: np.title.rendered, status: np.status, link: np.link, parent: np.parent } });
+  auditLog({ tool: name, target: np.id, target_type: 'page', action: 'create', status: 'success', latency_ms: Date.now() - t0, params: { title, status } });
+  return result;
+};
+handlers['wp_update_page'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, sanitizeParams, name, enforceDraftOnly, enforceAllowedStatuses, STATUSES } = rt;
+  validateInput(args, { id: { type: 'number', required: true, min: 1 }, status: { type: 'string', enum: STATUSES } });
+  if (args.status) { enforceDraftOnly(args.status); enforceAllowedStatuses(args.status); }
+  const { id, ...upd } = args;
+  const up = await wpApiCall(`/pages/${id}`, { method: 'POST', body: JSON.stringify(upd) });
+  result = json({ success: true, message: `Page ${id} updated`, page: { id: up.id, title: up.title.rendered, status: up.status, link: up.link, modified: up.modified } });
+  auditLog({ tool: name, target: id, target_type: 'page', action: 'update', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(upd) });
+  return result;
+};
+handlers['wp_get_post_meta'] = async (args) => {
+  const t0 = Date.now();
+  const { wpApiCall, auditLog, name } = rt;
+  validateInput(args, { post_id: { type: 'number', required: true, min: 1 }, post_type: { type: 'string', enum: ['posts', 'pages'] } });
+  const { post_id, post_type = 'posts', meta_key, parse_json = true } = args;
+  let meta, acfFields = {};
+  try {
+    const post = await wpApiCall(`/${post_type}/${post_id}?_fields=meta,acf`);
+    meta = post?.meta ?? {};
+    acfFields = post?.acf ?? {};
+  } catch (e) {
+    if (post_type === 'posts' && e.message.includes('404')) {
+      const post = await wpApiCall(`/pages/${post_id}?_fields=meta,acf`);
+      meta = post?.meta ?? {};
+      acfFields = post?.acf ?? {};
+    } else { throw e; }
+  }
+  // Auto-parse JSON strings
+  if (parse_json) {
+    for (const [k, v] of Object.entries(meta)) {
+      if (typeof v === 'string' && v.length > 1 && (v[0] === '[' || v[0] === '{')) {
+        try { meta[k] = JSON.parse(v); } catch { /* keep as string */ }
+      }
+    }
+  }
+  let result;
+  if (meta_key) {
+    const value = meta[meta_key] !== undefined ? meta[meta_key] : (acfFields[meta_key] !== undefined ? acfFields[meta_key] : null);
+    result = json({ post_id, meta_key, value });
+  } else {
+    result = json({ post_id, meta, acf_fields: acfFields, source: Object.keys(acfFields).length > 0 ? 'acf_rest' : 'wp_meta_only' });
+  }
+  auditLog({ tool: name, target: post_id, action: 'read_meta', status: 'success', latency_ms: Date.now() - t0, params: { meta_key: meta_key || 'all' } });
+  return result;
+};

package/src/tools/core.js

@@ -0,0 +1,114 @@
+// src/tools/core.js — core tools (3)
+// Definitions + handlers (v5.0.0 refactor Step B+C)
+
+import { json } from '../shared/utils.js';
+import { validateInput } from '../shared/governance.js';
+import { rt } from '../shared/context.js';
+
+export const definitions = [
+  { name: 'wp_set_target', _category: 'core', description: 'Use to switch active WordPress site in multi-target mode. Write.',
+        inputSchema: { type: 'object', properties: { site: { type: 'string', description: 'Site key from targets config' } }, required: ['site'] }},
+  { name: 'wp_site_info', _category: 'core', description: 'Use first to discover site config, user, post types, governance flags, and available targets. Read-only.',
+        inputSchema: { type: 'object', properties: {} }},
+  { name: 'wp_get_site_options', _category: 'core', description: 'Use to read WordPress site settings (title, tagline, language, timezone, etc.) via /wp/v2/settings. Requires manage_options. Read-only.',
+        inputSchema: { type: 'object', properties: { keys: { type: 'array', items: { type: 'string' }, description: 'Return only these option keys (returns all if omitted)' } }}}
+];
+
+export const handlers = {};
+
+handlers['wp_set_target'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { getActiveControls, currentTarget, targets, log, auditLog, name } = rt;
+  validateInput(args, { site: { type: 'string', required: true } });
+  const { site } = args;
+  if (!targets[site]) {
+    const available = Object.keys(targets);
+    throw new Error(`Site "${site}" not found. Available: ${available.length > 0 ? available.join(', ') : 'none (configure WP_TARGETS_JSON or WP_TARGETS_FILE)'}`);
+  }
+  const prev = currentTarget?.name || 'default';
+  rt.currentTarget = { name: site, ...targets[site] };
+  log.info(`Target switched: ${prev} → ${site} (${rt.currentTarget.url})`);
+  const effectiveControls = getActiveControls();
+  result = json({ success: true, message: `Active site: ${site}`, previous: prev, current: { name: site, url: rt.currentTarget.url }, effective_controls: effectiveControls });
+  auditLog({ tool: name, action: 'switch_target', status: 'success', latency_ms: Date.now() - t0, params: { from: prev, to: site }, effective_controls: effectiveControls });
+  return result;
+};
+handlers['wp_site_info'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, getActiveAuth, getActiveControls, getControlSources, currentTarget, targets, isMultiTarget, VERSION, TIMEOUT_MS, TOOLS_COUNT, AUDIT_LOG, ALLOWED_TYPES, ALLOWED_STATUSES, fetch, auditLog, name, getFilteredTools, getEnabledCategories, pluginRegistry, TOOLS_DEFINITIONS } = rt;
+  const { url: baseUrl, auth: activeAuth } = getActiveAuth();
+  const ctrl = new AbortController();
+  const tid = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+  const resp = await fetch(`${baseUrl}/wp-json`, { headers: { 'Authorization': `Basic ${activeAuth}`, 'User-Agent': `WordPress-MCP-Server/${VERSION}` }, signal: ctrl.signal });
+  clearTimeout(tid);
+  const si = await resp.json();
+  const uResp = await fetch(`${baseUrl}/wp-json/wp/v2/users/me`, { headers: { 'Authorization': `Basic ${activeAuth}`, 'User-Agent': `WordPress-MCP-Server/${VERSION}` } });
+  const u = uResp.ok ? await uResp.json() : null;
+  let postTypes = [];
+  try { const t = await wpApiCall('/types'); postTypes = Object.values(t).map(x => ({ slug: x.slug, name: x.name, rest_base: x.rest_base })); } catch {}
+
+  result = json({
+    site: { name: si.name, description: si.description, url: si.url || baseUrl, gmt_offset: si.gmt_offset, timezone_string: si.timezone_string },
+    current_user: u ? { id: u.id, name: u.name, slug: u.slug, roles: u.roles } : null,
+    post_types: postTypes,
+    enterprise_controls: (() => {
+      const c = getActiveControls();
+      const s = getControlSources();
+      return {
+        read_only: c.read_only, draft_only: c.draft_only, delete_disabled: c.disable_delete, plugin_management_disabled: c.disable_plugin_management, require_approval: c.require_approval, confirm_destructive: c.confirm_destructive,
+        rate_limit: c.max_calls_per_minute > 0 ? `${c.max_calls_per_minute}/min` : 'unlimited',
+        allowed_types: ALLOWED_TYPES || 'all', allowed_statuses: ALLOWED_STATUSES || 'all',
+        audit_log: AUDIT_LOG,
+        ...s
+      };
+    })(),
+    multi_target: {
+      enabled: isMultiTarget, active_site: currentTarget?.name || 'default',
+      available_sites: Object.keys(targets)
+    },
+    server: (() => {
+      const exposed = getFilteredTools().length;
+      const groups = [];
+      if (!process.env.WC_CONSUMER_KEY) groups.push('woocommerce');
+      if (process.env.WP_REQUIRE_APPROVAL !== 'true') groups.push('editorial');
+      if (process.env.WP_ENABLE_PLUGIN_INTELLIGENCE !== 'true') groups.push('plugin_intelligence');
+      return { mcp_version: VERSION, tools_total: TOOLS_COUNT, tools_exposed: exposed, filtered_out: groups };
+    })(),
+    tool_categories: (() => {
+      const ec = getEnabledCategories();
+      const expCount = getFilteredTools().length;
+      return {
+        available: ['core','content','media','taxonomy','engagement','users','seo','schema','intelligence','editorial','fse','plugins','workflow','links','woocommerce','security','performance','health'],
+        active: ec ?? ['all'],
+        tools_exposed: expCount,
+        tools_total: TOOLS_DEFINITIONS.length,
+        hint: ec
+          ? `Showing ${expCount} tools. Set WP_TOOL_CATEGORIES= (empty) for all ${TOOLS_DEFINITIONS.length} tools.`
+          : `Showing all ${TOOLS_DEFINITIONS.length} tools. Set WP_TOOL_CATEGORIES=seo,content to reduce context.`
+      };
+    })(),
+    plugin_layer: pluginRegistry.getSummary()
+  });
+  auditLog({ tool: name, action: 'info', status: 'success', latency_ms: Date.now() - t0 });
+  return result;
+};
+handlers['wp_get_site_options'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, name } = rt;
+  validateInput(args, { keys: { type: 'array' } });
+  const { keys } = args;
+  const settings = await wpApiCall('/settings');
+  let data = settings;
+  if (keys && keys.length > 0) {
+    data = {};
+    for (const k of keys) {
+      if (k in settings) data[k] = settings[k];
+    }
+  }
+  result = json(data);
+  auditLog({ tool: name, action: 'read_options', status: 'success', latency_ms: Date.now() - t0, params: { keys_requested: keys?.length || 'all', keys_returned: Object.keys(data).length } });
+  return result;
+};