@adsim/wordpress-mcp-server 3.0.0 → 4.4.0

package/tests/unit/tools/approval.test.js

@@ -0,0 +1,251 @@
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+vi.mock('node-fetch', () => ({ default: vi.fn() }));
+
+import fetch from 'node-fetch';
+import { handleToolCall } from '../../../index.js';
+import { mockSuccess, getAuditLogs, makeRequest, parseResult } from '../../helpers/mockWpRequest.js';
+
+function call(name, args = {}) {
+  return handleToolCall(makeRequest(name, args));
+}
+
+// ────────────────────────────────────────────────────────────
+// wp_submit_for_review
+// ────────────────────────────────────────────────────────────
+
+describe('wp_submit_for_review', () => {
+  let consoleSpy;
+  beforeEach(() => { fetch.mockReset(); consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {}); });
+  afterEach(() => { consoleSpy.mockRestore(); });
+
+  it('transitions draft → pending on success', async () => {
+    mockSuccess({ id: 10, title: { rendered: 'Draft Post' }, status: 'draft', meta: {} });
+    mockSuccess({ id: 10, title: { rendered: 'Draft Post' }, status: 'pending', link: 'https://test.example.com/?p=10' });
+
+    const result = await call('wp_submit_for_review', { id: 10, note: 'Please review' });
+    const data = parseResult(result);
+
+    expect(data.success).toBe(true);
+    expect(data.post.id).toBe(10);
+    expect(data.post.status).toBe('pending');
+
+    const logs = getAuditLogs(consoleSpy);
+    const entry = logs.find(l => l.tool === 'wp_submit_for_review');
+    expect(entry).toBeDefined();
+    expect(entry.status).toBe('success');
+    expect(entry.action).toBe('submit_for_review');
+    expect(entry.target).toBe(10);
+  });
+
+  it('returns error if post is not in draft status', async () => {
+    mockSuccess({ id: 10, title: { rendered: 'Published Post' }, status: 'publish', meta: {} });
+
+    const result = await call('wp_submit_for_review', { id: 10 });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('draft');
+
+    const logs = getAuditLogs(consoleSpy);
+    const entry = logs.find(l => l.tool === 'wp_submit_for_review');
+    expect(entry).toBeDefined();
+    expect(entry.status).toBe('error');
+  });
+
+  it('is blocked by WP_READ_ONLY', async () => {
+    process.env.WP_READ_ONLY = 'true';
+    try {
+      const result = await call('wp_submit_for_review', { id: 10 });
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain('READ-ONLY');
+
+      const logs = getAuditLogs(consoleSpy);
+      const entry = logs.find(l => l.tool === 'wp_submit_for_review');
+      expect(entry).toBeDefined();
+      expect(entry.status).toBe('blocked');
+    } finally {
+      delete process.env.WP_READ_ONLY;
+    }
+  });
+});
+
+// ────────────────────────────────────────────────────────────
+// wp_approve_post
+// ────────────────────────────────────────────────────────────
+
+describe('wp_approve_post', () => {
+  let consoleSpy;
+  beforeEach(() => { fetch.mockReset(); consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {}); });
+  afterEach(() => { consoleSpy.mockRestore(); });
+
+  it('transitions pending → publish on success', async () => {
+    mockSuccess({ id: 10, title: { rendered: 'Pending Post' }, status: 'pending', meta: {} });
+    mockSuccess({ id: 10, title: { rendered: 'Pending Post' }, status: 'publish', link: 'https://test.example.com/pending-post' });
+
+    const result = await call('wp_approve_post', { id: 10 });
+    const data = parseResult(result);
+
+    expect(data.success).toBe(true);
+    expect(data.post.id).toBe(10);
+    expect(data.post.status).toBe('publish');
+
+    const logs = getAuditLogs(consoleSpy);
+    const entry = logs.find(l => l.tool === 'wp_approve_post');
+    expect(entry).toBeDefined();
+    expect(entry.status).toBe('success');
+    expect(entry.action).toBe('approve');
+    expect(entry.target).toBe(10);
+  });
+
+  it('returns error if post is not in pending status', async () => {
+    mockSuccess({ id: 10, title: { rendered: 'Draft Post' }, status: 'draft', meta: {} });
+
+    const result = await call('wp_approve_post', { id: 10 });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('pending');
+
+    const logs = getAuditLogs(consoleSpy);
+    const entry = logs.find(l => l.tool === 'wp_approve_post');
+    expect(entry).toBeDefined();
+    expect(entry.status).toBe('error');
+  });
+
+  it('is blocked by WP_READ_ONLY', async () => {
+    process.env.WP_READ_ONLY = 'true';
+    try {
+      const result = await call('wp_approve_post', { id: 10 });
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain('READ-ONLY');
+
+      const logs = getAuditLogs(consoleSpy);
+      const entry = logs.find(l => l.tool === 'wp_approve_post');
+      expect(entry).toBeDefined();
+      expect(entry.status).toBe('blocked');
+    } finally {
+      delete process.env.WP_READ_ONLY;
+    }
+  });
+
+  it('is blocked by WP_DRAFT_ONLY', async () => {
+    process.env.WP_DRAFT_ONLY = 'true';
+    try {
+      const result = await call('wp_approve_post', { id: 10 });
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain('DRAFT-ONLY');
+
+      const logs = getAuditLogs(consoleSpy);
+      const entry = logs.find(l => l.tool === 'wp_approve_post');
+      expect(entry).toBeDefined();
+      expect(entry.status).toBe('blocked');
+    } finally {
+      delete process.env.WP_DRAFT_ONLY;
+    }
+  });
+});
+
+// ────────────────────────────────────────────────────────────
+// wp_reject_post
+// ────────────────────────────────────────────────────────────
+
+describe('wp_reject_post', () => {
+  let consoleSpy;
+  beforeEach(() => { fetch.mockReset(); consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {}); });
+  afterEach(() => { consoleSpy.mockRestore(); });
+
+  it('transitions pending → draft with reason and incremented rejection count', async () => {
+    mockSuccess({ id: 10, title: { rendered: 'Pending Post' }, status: 'pending', meta: { _mcp_rejection_count: 1 } });
+    mockSuccess({ id: 10, title: { rendered: 'Pending Post' }, status: 'draft' });
+
+    const result = await call('wp_reject_post', { id: 10, reason: 'Needs more detail' });
+    const data = parseResult(result);
+
+    expect(data.success).toBe(true);
+    expect(data.post.id).toBe(10);
+    expect(data.post.status).toBe('draft');
+    expect(data.rejection.reason).toBe('Needs more detail');
+    expect(data.rejection.count).toBe(2);
+
+    const logs = getAuditLogs(consoleSpy);
+    const entry = logs.find(l => l.tool === 'wp_reject_post');
+    expect(entry).toBeDefined();
+    expect(entry.status).toBe('success');
+    expect(entry.action).toBe('reject');
+    expect(entry.target).toBe(10);
+  });
+
+  it('returns error if post is not in pending status', async () => {
+    mockSuccess({ id: 10, title: { rendered: 'Draft Post' }, status: 'draft', meta: {} });
+
+    const result = await call('wp_reject_post', { id: 10, reason: 'Bad' });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('pending');
+
+    const logs = getAuditLogs(consoleSpy);
+    const entry = logs.find(l => l.tool === 'wp_reject_post');
+    expect(entry).toBeDefined();
+    expect(entry.status).toBe('error');
+  });
+
+  it('is blocked by WP_READ_ONLY', async () => {
+    process.env.WP_READ_ONLY = 'true';
+    try {
+      const result = await call('wp_reject_post', { id: 10, reason: 'Bad' });
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain('READ-ONLY');
+
+      const logs = getAuditLogs(consoleSpy);
+      const entry = logs.find(l => l.tool === 'wp_reject_post');
+      expect(entry).toBeDefined();
+      expect(entry.status).toBe('blocked');
+    } finally {
+      delete process.env.WP_READ_ONLY;
+    }
+  });
+});
+
+// ────────────────────────────────────────────────────────────
+// WP_REQUIRE_APPROVAL governance
+// ────────────────────────────────────────────────────────────
+
+describe('WP_REQUIRE_APPROVAL=true', () => {
+  let consoleSpy;
+  beforeEach(() => {
+    fetch.mockReset();
+    consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    process.env.WP_REQUIRE_APPROVAL = 'true';
+  });
+  afterEach(() => {
+    consoleSpy.mockRestore();
+    delete process.env.WP_REQUIRE_APPROVAL;
+  });
+
+  it('blocks wp_update_post when status is publish', async () => {
+    const result = await call('wp_update_post', { id: 1, status: 'publish' });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('APPROVAL REQUIRED');
+
+    const logs = getAuditLogs(consoleSpy);
+    const entry = logs.find(l => l.tool === 'wp_update_post');
+    expect(entry).toBeDefined();
+    expect(entry.status).toBe('blocked');
+  });
+
+  it('blocks wp_create_post when status is publish', async () => {
+    const result = await call('wp_create_post', { title: 'T', content: 'C', status: 'publish' });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('APPROVAL REQUIRED');
+
+    const logs = getAuditLogs(consoleSpy);
+    const entry = logs.find(l => l.tool === 'wp_create_post');
+    expect(entry).toBeDefined();
+    expect(entry.status).toBe('blocked');
+  });
+});

package/tests/unit/tools/auditCanonicals.test.js

@@ -0,0 +1,149 @@
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+vi.mock('node-fetch', () => ({ default: vi.fn() }));
+
+import fetch from 'node-fetch';
+import { handleToolCall, _testSetTarget } from '../../../index.js';
+import { mockSuccess, mockError, getAuditLogs, makeRequest, parseResult } from '../../helpers/mockWpRequest.js';
+
+function call(name, args = {}) {
+  return handleToolCall(makeRequest(name, args));
+}
+
+let consoleSpy;
+beforeEach(() => { fetch.mockReset(); consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {}); });
+afterEach(() => { consoleSpy.mockRestore(); _testSetTarget(null); });
+
+// =========================================================================
+// Helper
+// =========================================================================
+
+function makePost(id, canonical, link) {
+  return {
+    id, title: { rendered: `Post ${id}` },
+    link: link || `https://mysite.example.com/post-${id}/`,
+    meta: canonical !== undefined ? { rank_math_canonical_url: canonical } : {}
+  };
+}
+
+// =========================================================================
+// wp_audit_canonicals
+// =========================================================================
+
+describe('wp_audit_canonicals', () => {
+  it('SUCCESS — all canonicals valid', async () => {
+    _testSetTarget('test', { url: 'https://mysite.example.com', username: 'u', password: 'p' });
+    mockSuccess([
+      makePost(1, 'https://mysite.example.com/post-1/'),
+      makePost(2, 'https://mysite.example.com/post-2/')
+    ]);
+
+    const res = await call('wp_audit_canonicals');
+    const data = parseResult(res);
+
+    expect(data.total_issues).toBe(0);
+    expect(data.total_audited).toBe(2);
+  });
+
+  it('ISSUE — missing_canonical detected', async () => {
+    _testSetTarget('test', { url: 'https://mysite.example.com', username: 'u', password: 'p' });
+    mockSuccess([makePost(1, '')]);
+
+    const res = await call('wp_audit_canonicals');
+    const data = parseResult(res);
+
+    expect(data.issues_by_type.missing_canonical).toBe(1);
+    expect(data.audits[0].issues).toContain('missing_canonical');
+  });
+
+  it('ISSUE — http_on_https_site detected', async () => {
+    _testSetTarget('test', { url: 'https://mysite.example.com', username: 'u', password: 'p' });
+    mockSuccess([makePost(1, 'http://test.example.com/post-1/')]);
+
+    const res = await call('wp_audit_canonicals');
+    const data = parseResult(res);
+
+    expect(data.issues_by_type.http_on_https_site).toBe(1);
+    expect(data.audits[0].issues).toContain('http_on_https_site');
+  });
+
+  it('ISSUE — staging_url detected', async () => {
+    _testSetTarget('test', { url: 'https://mysite.example.com', username: 'u', password: 'p' });
+    mockSuccess([makePost(1, 'https://staging.example.com/post-1/')]);
+
+    const res = await call('wp_audit_canonicals');
+    const data = parseResult(res);
+
+    expect(data.issues_by_type.staging_url).toBe(1);
+    expect(data.audits[0].issues).toContain('staging_url');
+  });
+
+  it('ISSUE — wrong_domain detected', async () => {
+    _testSetTarget('test', { url: 'https://mysite.example.com', username: 'u', password: 'p' });
+    mockSuccess([makePost(1, 'https://other-domain.com/post-1/')]);
+
+    const res = await call('wp_audit_canonicals');
+    const data = parseResult(res);
+
+    expect(data.issues_by_type.wrong_domain).toBe(1);
+    expect(data.audits[0].issues).toContain('wrong_domain');
+  });
+
+  it('ISSUE — trailing_slash_mismatch detected', async () => {
+    _testSetTarget('test', { url: 'https://mysite.example.com', username: 'u', password: 'p' });
+    // Post link has trailing slash, canonical does not
+    mockSuccess([makePost(1, 'https://mysite.example.com/post-1', 'https://mysite.example.com/post-1/')]);
+
+    const res = await call('wp_audit_canonicals');
+    const data = parseResult(res);
+
+    expect(data.issues_by_type.trailing_slash_mismatch).toBe(1);
+    expect(data.audits[0].issues).toContain('trailing_slash_mismatch');
+  });
+
+  it('SUCCESS — SEO plugin auto-detected (RankMath vs Yoast)', async () => {
+    _testSetTarget('test', { url: 'https://mysite.example.com', username: 'u', password: 'p' });
+
+    // RankMath detection
+    mockSuccess([makePost(1, 'https://mysite.example.com/post-1/')]);
+    let res = await call('wp_audit_canonicals');
+    let data = parseResult(res);
+    expect(data.seo_plugin_detected).toBe('RankMath');
+
+    // Yoast detection
+    fetch.mockReset();
+    mockSuccess([{
+      id: 2, title: { rendered: 'Post 2' }, link: 'https://mysite.example.com/post-2/',
+      meta: { _yoast_wpseo_canonical: 'https://mysite.example.com/post-2/' }
+    }]);
+    res = await call('wp_audit_canonicals');
+    data = parseResult(res);
+    expect(data.seo_plugin_detected).toBe('Yoast');
+  });
+
+  it('AUDIT — logs success entry', async () => {
+    _testSetTarget('test', { url: 'https://mysite.example.com', username: 'u', password: 'p' });
+    mockSuccess([makePost(1, 'https://mysite.example.com/post-1/')]);
+
+    await call('wp_audit_canonicals');
+
+    const logs = getAuditLogs();
+    const entry = logs.find(l => l.tool === 'wp_audit_canonicals');
+    expect(entry).toBeDefined();
+    expect(entry.status).toBe('success');
+    expect(entry.action).toBe('audit_seo');
+  });
+
+  it('ERROR — logs error on API failure', async () => {
+    _testSetTarget('test', { url: 'https://mysite.example.com', username: 'u', password: 'p' });
+    mockError(403, '{"code":"rest_forbidden","message":"Forbidden"}');
+
+    const res = await call('wp_audit_canonicals');
+    expect(res.isError).toBe(true);
+
+    const logs = getAuditLogs();
+    const entry = logs.find(l => l.tool === 'wp_audit_canonicals');
+    expect(entry).toBeDefined();
+    expect(entry.status).toBe('error');
+  });
+});

package/tests/unit/tools/auditHeadingStructure.test.js

@@ -0,0 +1,150 @@
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+vi.mock('node-fetch', () => ({ default: vi.fn() }));
+
+import fetch from 'node-fetch';
+import { handleToolCall } from '../../../index.js';
+import { mockSuccess, mockError, getAuditLogs, makeRequest, parseResult } from '../../helpers/mockWpRequest.js';
+
+function call(name, args = {}) {
+  return handleToolCall(makeRequest(name, args));
+}
+
+let consoleSpy;
+beforeEach(() => { fetch.mockReset(); consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {}); });
+afterEach(() => { consoleSpy.mockRestore(); });
+
+function makePost(content) {
+  return {
+    id: 1, title: { rendered: 'Test Post' }, slug: 'test-post', status: 'publish',
+    link: 'https://test.example.com/test-post/',
+    content: { rendered: content },
+    meta: {}
+  };
+}
+
+// =========================================================================
+// wp_audit_heading_structure
+// =========================================================================
+
+describe('wp_audit_heading_structure', () => {
+  it('SUCCESS — clean heading structure', async () => {
+    mockSuccess(makePost('<h2>Introduction</h2><p>Text.</p><h3>Details</h3><p>More text.</p><h2>Conclusion</h2><p>End.</p>'));
+
+    const res = await call('wp_audit_heading_structure', { id: 1 });
+    const data = parseResult(res);
+
+    expect(data.score).toBe(100);
+    expect(data.issues).toHaveLength(0);
+    expect(data.headings).toHaveLength(3);
+    expect(data.summary.h2_count).toBe(2);
+    expect(data.summary.h3_count).toBe(1);
+  });
+
+  it('ISSUE — H1 in content', async () => {
+    mockSuccess(makePost('<h1>Bad Title</h1><h2>Section</h2><p>Text.</p>'));
+
+    const res = await call('wp_audit_heading_structure', { id: 1 });
+    const data = parseResult(res);
+
+    const h1Issue = data.issues.find(i => i.type === 'h1_in_content');
+    expect(h1Issue).toBeDefined();
+    expect(h1Issue.count).toBe(1);
+    expect(data.score).toBeLessThan(100);
+  });
+
+  it('ISSUE — heading level skip', async () => {
+    mockSuccess(makePost('<h2>Section</h2><h4>Subsub</h4><p>Text.</p>'));
+
+    const res = await call('wp_audit_heading_structure', { id: 1 });
+    const data = parseResult(res);
+
+    const skipIssue = data.issues.find(i => i.type === 'heading_skip');
+    expect(skipIssue).toBeDefined();
+    expect(skipIssue.from).toBe('H2');
+    expect(skipIssue.to).toBe('H4');
+  });
+
+  it('ISSUE — empty heading', async () => {
+    mockSuccess(makePost('<h2></h2><h2>Good Heading</h2>'));
+
+    const res = await call('wp_audit_heading_structure', { id: 1 });
+    const data = parseResult(res);
+
+    const emptyIssue = data.issues.find(i => i.type === 'empty_heading');
+    expect(emptyIssue).toBeDefined();
+    expect(emptyIssue.count).toBe(1);
+  });
+
+  it('ISSUE — keyword stuffing in H2s', async () => {
+    mockSuccess(makePost(
+      '<h2>Best SEO Tips</h2><h2>SEO Tips Guide</h2><h2>SEO Tips Tutorial</h2><h2>More Stuff</h2>'
+    ));
+
+    const res = await call('wp_audit_heading_structure', { id: 1, focus_keyword: 'SEO Tips' });
+    const data = parseResult(res);
+
+    const stuffing = data.issues.find(i => i.type === 'keyword_stuffing');
+    expect(stuffing).toBeDefined();
+    expect(stuffing.count).toBe(3);
+  });
+
+  it('ISSUE — no H2 headings', async () => {
+    mockSuccess(makePost('<h3>Minor heading</h3><p>Text.</p>'));
+
+    const res = await call('wp_audit_heading_structure', { id: 1 });
+    const data = parseResult(res);
+
+    const noH2 = data.issues.find(i => i.type === 'no_h2');
+    expect(noH2).toBeDefined();
+    expect(data.summary.h2_count).toBe(0);
+  });
+
+  it('ISSUE — keyword absent from all H2s', async () => {
+    mockSuccess(makePost('<h2>Introduction</h2><h2>Conclusion</h2>'));
+
+    const res = await call('wp_audit_heading_structure', { id: 1, focus_keyword: 'WordPress' });
+    const data = parseResult(res);
+
+    const absent = data.issues.find(i => i.type === 'keyword_absent_h2');
+    expect(absent).toBeDefined();
+    expect(absent.message).toContain('WordPress');
+  });
+
+  it('SUCCESS — correct score with multiple deductions', async () => {
+    // H1 in content: -20, heading skip (H1→H3): -10, empty heading: -10, no_h2: -15 → 45
+    mockSuccess(makePost('<h1>Bad H1</h1><h3>Skip</h3><h3></h3>'));
+
+    const res = await call('wp_audit_heading_structure', { id: 1 });
+    const data = parseResult(res);
+
+    expect(data.score).toBe(45);
+  });
+
+  it('SUCCESS — multiple issues combined', async () => {
+    mockSuccess(makePost(
+      '<h1>Bad</h1><h2>SEO SEO SEO</h2><h4>Skip</h4><h2></h2><h2>SEO keyword</h2><h2>SEO again</h2>'
+    ));
+
+    const res = await call('wp_audit_heading_structure', { id: 1, focus_keyword: 'SEO' });
+    const data = parseResult(res);
+
+    const issueTypes = data.issues.map(i => i.type);
+    expect(issueTypes).toContain('h1_in_content');
+    expect(issueTypes).toContain('heading_skip');
+    expect(issueTypes).toContain('empty_heading');
+    expect(data.score).toBeLessThan(100);
+  });
+
+  it('AUDIT — logs audit entry', async () => {
+    mockSuccess(makePost('<h2>Hello</h2>'));
+
+    await call('wp_audit_heading_structure', { id: 1 });
+
+    const logs = getAuditLogs();
+    const entry = logs.find(l => l.tool === 'wp_audit_heading_structure');
+    expect(entry).toBeDefined();
+    expect(entry.status).toBe('success');
+    expect(entry.action).toBe('audit_heading_structure');
+  });
+});

package/tests/unit/tools/auditMediaSeo.test.js

@@ -0,0 +1,123 @@
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+vi.mock('node-fetch', () => ({ default: vi.fn() }));
+
+import fetch from 'node-fetch';
+import { handleToolCall } from '../../../index.js';
+import { mockSuccess, mockError, getAuditLogs, makeRequest, parseResult } from '../../helpers/mockWpRequest.js';
+
+function call(name, args = {}) {
+  return handleToolCall(makeRequest(name, args));
+}
+
+let consoleSpy;
+beforeEach(() => { fetch.mockReset(); consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {}); });
+afterEach(() => { consoleSpy.mockRestore(); });
+
+// =========================================================================
+// wp_audit_media_seo
+// =========================================================================
+
+describe('wp_audit_media_seo', () => {
+  it('SUCCESS — empty audit when no images', async () => {
+    mockSuccess([]);
+
+    const res = await call('wp_audit_media_seo');
+    const data = parseResult(res);
+
+    expect(data.summary.total_audited).toBe(0);
+    expect(data.summary.average_score).toBe(0);
+    expect(data.media).toHaveLength(0);
+  });
+
+  it('SUCCESS — detects missing alt text', async () => {
+    mockSuccess([
+      { id: 1, title: { rendered: 'Photo' }, source_url: 'https://test.example.com/wp-content/uploads/photo.jpg', alt_text: '', media_details: {} }
+    ]);
+
+    const res = await call('wp_audit_media_seo');
+    const data = parseResult(res);
+
+    expect(data.media[0].issues).toContain('missing_alt');
+    expect(data.summary.issues_breakdown.missing_alt).toBe(1);
+  });
+
+  it('SUCCESS — detects filename used as alt text', async () => {
+    mockSuccess([
+      { id: 2, title: { rendered: 'My Photo' }, source_url: 'https://test.example.com/wp-content/uploads/my-photo.jpg', alt_text: 'my photo', media_details: {} }
+    ]);
+
+    const res = await call('wp_audit_media_seo');
+    const data = parseResult(res);
+
+    expect(data.media[0].issues).toContain('filename_as_alt');
+    expect(data.summary.issues_breakdown.filename_as_alt).toBe(1);
+  });
+
+  it('SUCCESS — detects alt text too short', async () => {
+    mockSuccess([
+      { id: 3, title: { rendered: 'Icon' }, source_url: 'https://test.example.com/wp-content/uploads/icon.png', alt_text: 'img', media_details: {} }
+    ]);
+
+    const res = await call('wp_audit_media_seo');
+    const data = parseResult(res);
+
+    expect(data.media[0].issues).toContain('alt_too_short');
+    expect(data.summary.issues_breakdown.alt_too_short).toBe(1);
+  });
+
+  it('SUCCESS — scans inline images when post_id provided', async () => {
+    // 1. GET media library (empty)
+    mockSuccess([]);
+    // 2. GET post content with inline images
+    mockSuccess({
+      id: 10, title: { rendered: 'Blog Post' },
+      content: { rendered: '<p>Text</p><img src="https://test.example.com/inline.jpg" alt=""><img src="https://test.example.com/good.jpg" alt="A good image description">' }
+    });
+
+    const res = await call('wp_audit_media_seo', { post_id: 10 });
+    const data = parseResult(res);
+
+    expect(data.inline_images).toHaveLength(2);
+    expect(data.inline_images[0].alt).toBe('');
+    expect(data.inline_images[1].alt).toBe('A good image description');
+  });
+
+  it('SUCCESS — calculates correct scores', async () => {
+    mockSuccess([
+      { id: 1, title: { rendered: 'Good' }, source_url: 'https://test.example.com/wp-content/uploads/landscape.jpg', alt_text: 'Beautiful mountain landscape at sunset', media_details: {} },
+      { id: 2, title: { rendered: 'Bad' }, source_url: 'https://test.example.com/wp-content/uploads/photo.jpg', alt_text: '', media_details: {} }
+    ]);
+
+    const res = await call('wp_audit_media_seo');
+    const data = parseResult(res);
+
+    expect(data.media[0].score).toBe(100);
+    expect(data.media[1].score).toBe(60);
+    expect(data.summary.average_score).toBe(80);
+  });
+
+  it('AUDIT — logs success entry', async () => {
+    mockSuccess([]);
+
+    await call('wp_audit_media_seo');
+
+    const logs = getAuditLogs();
+    const entry = logs.find(l => l.tool === 'wp_audit_media_seo');
+    expect(entry).toBeDefined();
+    expect(entry.status).toBe('success');
+    expect(entry.action).toBe('audit_media_seo');
+  });
+
+  it('ERROR — logs error on API failure', async () => {
+    mockError(403, '{"code":"rest_forbidden","message":"Forbidden"}');
+
+    const res = await call('wp_audit_media_seo');
+    expect(res.isError).toBe(true);
+
+    const logs = getAuditLogs();
+    const entry = logs.find(l => l.tool === 'wp_audit_media_seo');
+    expect(entry).toBeDefined();
+    expect(entry.status).toBe('error');
+  });
+});