WP Astro MCP

1# WP Astro MCP
2
3> Migrate any WordPress site to Astro — from a single blog to a network of 12 sites with 6,000+ posts. Fully automated via Claude Code.
4
5[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
6[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org)
7[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
8
9**WP Astro MCP** is a [Model Context Protocol](https://modelcontextprotocol.io) server that turns WordPress sites into production-ready Astro projects. It connects to your WordPress REST API, extracts everything (posts, pages, CPTs, SEO, ACF, menus, media), converts HTML to clean Markdown, scaffolds a complete Astro project, and pushes to GitHub — all through conversational commands in Claude Code.
10
11---
12
13## Why This Exists
14
15Migrating WordPress to Astro involves dozens of tedious steps: fetching content via API, cleaning up page builder markup, resolving shortcodes, building frontmatter, setting up content collections, handling media URLs, generating redirects, deploying. Each site has its own plugins, page builders, and content patterns.
16
17This MCP server handles all of it. Tell Claude to migrate your site, and it orchestrates 55 specialized tools to get it done.
18
19---
20
21## Table of Contents
22
23- [Quick Start](#quick-start)
24- [How It Works](#how-it-works)
25- [Use Cases](#use-cases)
26- [Full Workflow](#full-workflow)
27- [Tool Reference](#tool-reference)
28- [Configuration](#configuration)
29- [Architecture](#architecture)
30- [FAQ](#faq)
31- [Troubleshooting](#troubleshooting)
32- [Contributing](#contributing)
33
34---
35
36## Quick Start
37
38### 1. Install
39
40```bash
41git clone https://github.com/vapvarun/wp-astro-mcp.git
42cd wp-astro-mcp
43npm install
44npm run build
45```
46
47### 2. Add to Claude Code
48
49Add to your MCP config (`~/.claude.json` or project `.mcp.json`):
50
51```json
52{
53  "mcpServers": {
54    "wp-astro-mcp": {
55      "command": "node",
56      "args": ["/path/to/wp-astro-mcp/dist/index.js"]
57    }
58  }
59}
60```
61
62### 3. Generate a WordPress Application Password
63
64Go to your WordPress admin → **Users → Profile → Application Passwords**. Enter a name, click "Add New", and copy the password.
65
66### 4. Start Migrating
67
68In Claude Code, just say:
69
70```
71Add my WordPress site example.com with username admin
72and app password "xxxx xxxx xxxx xxxx xxxx xxxx"
73```
74
75Claude will register the site, auto-detect its capabilities (SEO plugin, page builder, ACF, post types), and guide you through the migration.
76
77---
78
79## How It Works
80
81```
82WordPress Site                    WP Astro MCP                      Astro Project
83┌─────────────┐     REST API     ┌──────────────┐     Files        ┌─────────────┐
84│ Posts        │────────────────►│ Extract      │───────────────►│ content/    │
85│ Pages       │                  │ Transform    │                │ blog/       │
86│ CPTs        │                  │ Scaffold     │                │ pages/      │
87│ Media       │                  │ Write        │                │ layouts/    │
88│ SEO         │                  │              │                │ pages/      │
89│ ACF         │                  │ SQLite state │                │ astro.config│
90│ Menus       │                  │ for resume   │                │ package.json│
91└─────────────┘                  └──────────────┘                └─────────────┘
92                                       │                               │
93                                       │ GitHub API                    │
94                                       ▼                               ▼
95                                 ┌──────────────┐              ┌─────────────┐
96                                 │ git init     │              │ Vercel      │
97                                 │ create repo  │──────────────│ Netlify     │
98                                 │ push         │              │ Cloudflare  │
99                                 └──────────────┘              └─────────────┘
100```
101
102### The Conversion Pipeline
103
104Every post goes through a 13-step conversion:
105
1061. **Sanitize** — DOMPurify removes XSS vectors while preserving content
1072. **Resolve shortcodes** — 20+ built-in handlers (gallery, video, WPBakery, Divi, CF7) + custom per-site rules
1083. **Clean page builders** — Strip Elementor/WPBakery/Divi wrapper divs, keep content
1094. **Process Gutenberg** — Remove block comments (`<!-- wp:paragraph -->`), preserve content
1105. **Normalize HTML** — Decode entities, remove empty paragraphs, clean inline styles
1116. **Convert to Markdown** — Turndown with 12 WordPress-specific rules (captions, galleries, code blocks, embeds)
1127. **Rewrite links** — Internal WordPress URLs → Astro paths using URL map
1138. **Rewrite media** — Swap domains for media URLs (e.g., `example.com` → `app.example.com`)
1149. **Clean artifacts** — Remove conversion leftovers, fix double-encoded entities
11510. **Process embeds** — YouTube/Vimeo iframes → plain URLs
11611. **Handle galleries** — WordPress galleries → image grids
11712. **Fix whitespace** — Ensure proper spacing around headings, lists, code blocks
11813. **Validate** — Flag remaining HTML, broken images, content loss
119
120---
121
122## Use Cases
123
124### Migrate a Personal Blog
125
126You have a WordPress blog with 200 posts and want to move to Astro for better performance.
127
128```
1291. "Add my site myblog.com with username admin and password xxxx"
1302. "Analyze the site"
1313. "Set output to C:/projects/myblog-astro with Vercel deployment"
1324. "Preview some converted posts"
1335. "Scaffold the Astro project and export all content"
1346. "Push to GitHub"
135```
136
137### Migrate a Business Website
138
139A company site with Elementor, Yoast SEO, ACF custom fields, and 500 pages.
140
141```
1421. "Add site company.com" (auto-detects Elementor, Yoast, ACF)
1432. "Run a content audit" (finds shortcodes, page builder usage, complexity)
1443. "Configure shortcodes for CF7 forms and custom widgets"
1454. "Preview 5 pages to check Elementor conversion quality"
1465. "Export all content, media URLs pointing to app.company.com"
1476. "Generate Netlify redirects and push to GitHub"
148```
149
150### Migrate Multiple Sites
151
152An agency managing 12 WordPress sites that all need to move to Astro.
153
154```
1551. "Add all my sites" (register each with credentials)
1562. "List all sites" (see capabilities and content counts)
1573. "Analyze buddyxtheme.com" (1,941 posts, RankMath, Elementor)
1584. "Export buddyxtheme.com with year/month directories"
1595. "Now do vapvarun.com" (switch sites seamlessly)
160```
161
162### Incremental Updates
163
164Your WordPress site is still active and content keeps changing. Run exports periodically.
165
166```
1671. "Export only posts modified after 2024-01-01"
1682. "Resume the export" (picks up where it left off)
1693. "Validate the export" (check for missing files or failures)
170```
171
172### Go-Live Domain Swap
173
174WordPress moves from `example.com` to `app.example.com` (backend), and Astro takes over `example.com`.
175
176```
1771. During development: media URLs point to example.com (no changes needed)
1782. At go-live: "Rewrite all media URLs from example.com to app.example.com"
1793. "Generate redirects for Vercel"
180```
181
182---
183
184## Full Workflow
185
186Here's the complete migration workflow, step by step:
187
188### Phase 1: Connect & Discover
189
190```
191site_add          → Register site, auto-detect WP version, SEO plugin,
192                    page builder, ACF, WooCommerce, post types, taxonomies
193site_analyze      → Count all content, estimate migration time
194site_export_config → Set output directory, media strategy, deploy platform
195```
196
197### Phase 2: Audit & Prepare
198
199```
200content_audit     → Sample posts, detect shortcodes, blocks, page builders,
201                    embeds, galleries, tables, forms — assess complexity
202shortcode_scan    → Find all shortcodes in use across the site
203shortcode_configure → Set handling rules (strip, keep content, map to component)
204cache_terms       → Pre-cache all taxonomy terms in SQLite
205cache_authors     → Pre-cache all authors in SQLite
206```
207
208### Phase 3: Preview & Verify
209
210```
211convert_preview   → Convert 3-5 sample posts, review Markdown quality
212convert_post      → Convert a specific post to inspect in detail
213extract_post      → View raw WordPress data for debugging
214```
215
216### Phase 4: Scaffold & Export
217
218```
219scaffold_project  → Create Astro project (config, layouts, pages, collections, RSS)
220export_plan       → Pre-flight check: content counts, config validation, time estimate
221export_start      → Begin batch export (processes first batch, creates SQLite job)
222export_resume     → Continue processing (call repeatedly until done)
223export_progress   → Check completion percentage and failures
224export_retry      → Re-process any failed posts
225export_validate   → Verify all output files exist and are valid
226```
227
228### Phase 5: Finalize & Publish
229
230```
231generate_redirects → Create redirect rules (Netlify, Vercel, Cloudflare, Apache, Nginx)
232media_audit       → Check all media references, find broken URLs
233media_rewrite     → Bulk swap media domains for go-live
234github_init       → Initialize git repository
235github_create_repo → Create GitHub repo (public or private)
236github_commit     → Stage and commit all changes
237github_push       → Push to GitHub
238github_deploy_config → Generate Vercel/Netlify/Cloudflare config
239```
240
241---
242
243## Tool Reference
244
245### Site Management (9 tools)
246
247| Tool | Description |
248|------|-------------|
249| `site_add` | Register a WordPress site with credentials. Auto-detects WP version, REST namespaces, SEO plugin (Yoast/RankMath/AIOSEO), page builder (Elementor/WPBakery/Divi/Beaver/Bricks/Oxygen), ACF, WooCommerce, post types, taxonomies. |
250| `site_test` | Re-test connection and refresh detected capabilities. |
251| `site_list` | List all registered sites with status, version, and content stats. |
252| `site_get` | Get full details for a site (credentials are masked). |
253| `site_update` | Update site credentials or settings. |
254| `site_remove` | Deactivate a site (soft delete, can be reactivated). |
255| `site_set_default` | Set a site as default (used when site_id is omitted). |
256| `site_analyze` | Deep analysis: count all content types, detect capabilities, estimate migration time, recommend REST API vs WXR. |
257| `site_export_config` | Configure per-site export: output dir, content format (md/mdx), media strategy, filters, component library, deploy platform, rate limit. |
258
259### Content Extraction (13 tools)
260
261| Tool | Description |
262|------|-------------|
263| `extract_posts` | Fetch posts with pagination. Any post type, status/date filters, embedded author/media/terms. |
264| `extract_post` | Fetch single post with full content (edit context) and content analysis. |
265| `extract_all_ids` | Lightweight fetch of all post IDs for two-phase strategy on large sites. |
266| `extract_terms` | Fetch taxonomy terms (categories, tags, custom) with pagination. |
267| `extract_authors` | Fetch all site authors with avatars. |
268| `extract_media` | Fetch media items — single by ID or paginated list. |
269| `extract_menus` | Fetch navigation menus (WP 5.9+ and classic). |
270| `extract_comments` | Fetch approved comments, optionally filtered by post. |
271| `extract_settings` | Fetch site settings (title, tagline, timezone, permalink structure). |
272| `extract_widgets` | Fetch sidebar/widget areas (WP 5.8+). |
273| `cache_terms` | Bulk cache ALL terms for ALL taxonomies in SQLite. Run before export. |
274| `cache_authors` | Bulk cache ALL authors in SQLite. Run before export. |
275| `content_audit` | Sample posts, analyze shortcodes/blocks/page builders/embeds, assess complexity distribution. |
276
277### Transform (6 tools)
278
279| Tool | Description |
280|------|-------------|
281| `convert_post` | Convert a single post to Astro Markdown with full frontmatter and issue report. |
282| `convert_preview` | Convert a sample batch to preview output quality before full export. |
283| `convert_html` | Convert raw HTML to Markdown. Useful for testing conversion rules. |
284| `shortcode_list` | List all configured shortcode handling rules for a site. |
285| `shortcode_configure` | Set how a shortcode is handled: strip, keep_content, remove, component, html. |
286| `shortcode_scan` | Scan posts for all shortcodes in use, find unconfigured ones. |
287
288### Output & Media (7 tools)
289
290| Tool | Description |
291|------|-------------|
292| `scaffold_project` | Create complete Astro project: package.json, astro.config, layouts, content collections, pages, RSS, deploy config. |
293| `write_post` | Convert and write a single post as Markdown to the content directory. Supports dry_run. |
294| `write_batch` | Convert and write a page of posts. Use with pagination for incremental writing. |
295| `generate_redirects` | Generate redirect rules from WordPress→Astro URL map. Supports Netlify, Vercel, Cloudflare, Apache, Nginx. |
296| `media_audit` | Scan exported files for media references. Report domains, counts, broken refs. |
297| `media_rewrite` | Bulk rewrite media domains in all content files (for go-live domain swap). |
298| `list_output` | List files in output directory with stats (counts, sizes, collections). |
299
300### GitHub (6 tools)
301
302| Tool | Description |
303|------|-------------|
304| `github_init` | Initialize git repository with initial commit. |
305| `github_create_repo` | Create GitHub repository (personal or org, public or private) and set remote. |
306| `github_commit` | Stage all changes and commit with auto-generated message. |
307| `github_push` | Push to remote repository. |
308| `github_status` | Show git status: branch, changes, remotes, recent commits. |
309| `github_deploy_config` | Generate deploy platform config (Vercel, Netlify, Cloudflare Pages). |
310
311### Export Pipeline (7 tools)
312
313| Tool | Description |
314|------|-------------|
315| `export_plan` | Pre-flight check: content counts, config validation, estimated time, recommended batch size. |
316| `export_start` | Start batch export. Fetches all post IDs, registers in SQLite, processes first batch. |
317| `export_resume` | Continue an in-progress export. Call repeatedly until complete. |
318| `export_progress` | Show completion percentage, posts done/failed/pending, recent failures. |
319| `export_retry` | Reset failed posts to pending and reprocess them. |
320| `export_validate` | Verify output: check files exist, count issues, confirm completeness. |
321| `export_cleanup` | Delete export job data from database (does not delete files). |
322
323### Content Sync (7 tools)
324
325WordPress is a living CMS — people publish new posts, update content, change images, and delete old pages daily. The sync tools keep your Astro site current without re-running a full export.
326
327| Tool | Description |
328|------|-------------|
329| `sync_check` | Compare WordPress vs local files. Report new, updated, and deleted posts without making changes. |
330| `sync_pull` | Fetch and write only changed content. Handles new posts, updated posts, and slug changes. |
331| `sync_delete` | Remove local files for posts deleted/trashed in WordPress. Cleans up URL map entries. |
332| `sync_full` | Complete sync in one command: check → pull → delete → optionally commit to git. |
333| `sync_status` | Show sync history: last sync time, changes made, error counts. |
334| `sync_schedule` | Generate automated sync config: GitHub Actions workflow, cron script, Netlify/Vercel webhooks. |
335| `sync_reset` | Clear sync tracking to force a full re-check on next sync. |
336
337**How it works:**
3381. Queries WordPress REST API for posts modified after the last sync
3392. Compares `modified_gmt` timestamps against stored values in SQLite
3403. New posts (not in DB) → fetched, converted, written as new Markdown files
3414. Updated posts (newer `modified_gmt`) → re-fetched, re-converted, file overwritten
3425. Deleted posts (404 from WordPress) → local file removed, URL map cleaned up
3436. Slug changes → old file deleted, new file written, redirects updated
344
345**Sync workflows:**
346```
347# Manual sync — check what changed, then pull
348sync_check → sync_pull → github_commit → github_push
349
350# One-command sync with auto-commit
351sync_full → github_push
352
353# Automated daily sync via GitHub Actions
354sync_schedule (platform: github-actions, interval: daily)
355
356# Real-time sync via WordPress webhooks
357sync_schedule (platform: vercel)  # or netlify
358```
359
360---
361
362## Configuration
363
364### Site Config (`config/sites.json`)
365
366```json
367{
368  "sites": [
369    {
370      "id": "my-blog",
371      "name": "My WordPress Blog",
372      "url": "https://example.com",
373      "username": "admin",
374      "app_password": "xxxx xxxx xxxx xxxx xxxx xxxx",
375      "default": true,
376      "export": {
377        "output_dir": "C:/projects/my-blog-astro",
378        "content_format": "md",
379        "media_strategy": "rewrite",
380        "media_domain": "app.example.com",
381        "include_statuses": ["publish"],
382        "year_month_dirs": true,
383        "component_library": "starwind",
384        "deploy_platform": "vercel",
385        "rate_limit": 10
386      }
387    }
388  ],
389  "github_token": "ghp_your_github_token_here",
390  "global_settings": {
391    "default_rate_limit": 10,
392    "default_content_format": "md",
393    "default_component_library": "starwind",
394    "default_deploy_platform": "vercel"
395  }
396}
397```
398
399### Export Config Options
400
401| Option | Values | Description |
402|--------|--------|-------------|
403| `output_dir` | Path | Where the Astro project is created |
404| `content_format` | `md`, `mdx`, `json` | Markdown, MDX, or JSON output. **Use `json` for sites with 500+ posts** — avoids Astro's markdown parsing OOM. |
405| `media_strategy` | `keep`, `rewrite`, `download` | How to handle media URLs |
406| `media_domain` | Domain | New domain for media (used with `rewrite` strategy) |
407| `include_post_types` | Array | Only export these post types |
408| `exclude_post_types` | Array | Skip these post types |
409| `include_statuses` | Array | Post statuses to include (default: `["publish"]`) |
410| `include_drafts` | Boolean | Include draft posts |
411| `include_comments` | Boolean | Export comments |
412| `year_month_dirs` | Boolean | Organize posts in `YYYY/MM/` directories |
413| `date_after` | ISO date | Only export content after this date |
414| `date_before` | ISO date | Only export content before this date |
415| `exclude_categories` | Array | Category slugs to skip |
416| `exclude_tags` | Array | Tag slugs to skip |
417| `component_library` | `starwind`, `fulldev`, `webcoreui`, `none` | Astro UI component library |
418| `deploy_platform` | `vercel`, `netlify`, `cloudflare`, `none` | Deploy target |
419| `rate_limit` | Number | API requests per second (default: 10) |
420
421### Environment Variables
422
423| Variable | Default | Description |
424|----------|---------|-------------|
425| `WP_ASTRO_MODE` | `router` | `router` (3 tools) or `full` (all 48) |
426| `WP_ASTRO_CONFIG` | `config/sites.json` | Config file path |
427| `WP_ASTRO_DB` | `data/wp-astro.db` | SQLite database path |
428| `WP_ASTRO_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |
429
430---
431
432## Architecture
433
434### Project Structure
435
436```
437src/
438  index.ts                — MCP server entry point (stdio transport)
439  types/
440    index.ts              — All TypeScript type definitions
441    turndown-plugin-gfm.d.ts — Type declarations for turndown-plugin-gfm
442  config/
443    sites.ts              — SiteManager singleton (multi-site config)
444    database.ts           — DatabaseManager singleton (SQLite state)
445  tools/
446    index.ts              — Tool aggregation and mode switching
447    router.ts             — 3 router tools (wp_astro_run/help/describe)
448    sites.ts              — 9 site management tools
449    extract.ts            — 13 content extraction tools
450    transform.ts          — 6 transform tools
451    output.ts             — 7 output & media tools
452    github.ts             — 6 GitHub tools
453    export.ts             — 7 export pipeline tools
454  schemas/
455    sites.ts              — Zod schemas for site tools
456    extract.ts            — Zod schemas for extract tools
457    transform.ts          — Zod schemas for transform tools
458    output.ts             — Zod schemas for output tools
459    github.ts             — Zod schemas for GitHub tools
460    export.ts             — Zod schemas for export tools
461  services/
462    wp-rest-client.ts     — WordPress REST API client
463    content-analyzer.ts   — Content analysis engine
464    html-to-markdown.ts   — 13-step conversion pipeline
465    shortcode-resolver.ts — Shortcode parser and resolver
466    link-rewriter.ts      — URL rewriting service
467    frontmatter-builder.ts — Astro frontmatter generator
468    astro-scaffolder.ts   — Project structure generator
469    content-writer.ts     — File writer and media tools
470  utils/
471    errors.ts             — Error classes and response formatters
472    logger.ts             — Logger singleton (stderr)
473config/
474  sites.json              — Site credentials (gitignored)
475  sites.example.json      — Config template
476data/
477  wp-astro.db             — SQLite database (gitignored)
478```
479
480### Key Patterns
481
482- **Router mode**: 3 meta-tools expose 48 actions via `wp_astro_run`, keeping the tool list clean for Claude
483- **Singleton managers**: SiteManager, DatabaseManager, Logger — initialized once, shared everywhere
484- **Token bucket rate limiting**: Per-site rate limiters with automatic backoff on 429 responses
485- **HTTP connection pooling**: Keep-alive agents with 10 max sockets per site
486- **SQLite state machine**: Export jobs and per-post state for crash recovery and resumability
487- **Zod validation**: All tool inputs validated before processing
488- **Error hierarchy**: `WPAstroError` base class with specific subclasses for clean error reporting
489
490### Database Schema
491
492```sql
493export_jobs      — Tracks each migration run (site, status, progress counts)
494export_posts     — Per-post state (pending/in_progress/completed/failed, retry count)
495cached_terms     — Pre-fetched taxonomy terms for fast lookups
496cached_authors   — Pre-fetched authors for fast lookups
497url_map          — WordPress URL → Astro URL mappings (for redirects and link rewriting)
498shortcode_map    — Per-site shortcode handling rules
499audit_log        — Timestamped operation log for debugging
500```
501
502---
503
504## FAQ
505
506### General
507
508**Q: Does this work with any WordPress site?**
509Yes. It connects via the standard WordPress REST API, which is available on all WordPress sites since version 4.7. You just need a username and application password.
510
511**Q: How many posts can it handle?**
512It's designed for sites with 2,000-6,000+ posts. The SQLite-backed export engine processes in batches with full resumability — if it gets interrupted, just run `export_resume` and it picks up where it left off.
513
514**Q: Does it download media/images?**
515By default, no. Media stays on your WordPress server. The `rewrite` strategy swaps the domain in URLs (e.g., when WordPress moves to `app.example.com` and Astro takes over the main domain). A `download` strategy is planned for fully self-contained sites.
516
517**Q: What Astro version does it target?**
518Astro 5.x with content collections using the glob loader pattern.
519
520### WordPress Compatibility
521
522**Q: Does it work with Elementor?**
523Yes. It detects Elementor from REST API namespaces and post meta, strips the wrapper `<div>` elements (sections, columns, widgets), and preserves the actual content.
524
525**Q: Does it work with WPBakery / Divi / Beaver Builder?**
526Yes. Page builder detection covers WPBakery (`[vc_row]` shortcodes), Divi (`et_pb_` classes), Beaver Builder (`fl-` classes), Bricks, and Oxygen. Builder markup is cleaned and content is extracted.
527
528**Q: Does it preserve Yoast/RankMath SEO data?**
529Yes. SEO metadata (title, description, canonical URL, OG image, robots, focus keyword) is extracted from Yoast (`yoast_head_json`) or RankMath (`rank_math_seo`) and included in the frontmatter.
530
531**Q: Does it handle ACF fields?**
532Yes. ACF data from the REST API is normalized: images become `{url, alt, width, height}`, post objects become `{wpId, slug, title}`, repeater fields become arrays, and groups are flattened.
533
534**Q: What about custom post types?**
535All registered post types are auto-detected and can be exported. Each CPT gets its own content collection directory.
536
537**Q: Does it handle WordPress shortcodes?**
538Yes. 20+ shortcodes are handled out of the box (gallery, video, audio, caption, WPBakery elements, Divi modules, Contact Form 7, WPForms, Gravity Forms, buttons, tabs, accordions). You can configure additional shortcodes per-site with `shortcode_configure`.
539
540### Content Sync & Ongoing Updates
541
542**Q: How do I keep the Astro site updated when WordPress content changes?**
543Use the sync tools: `sync_check` to see what changed, `sync_pull` to fetch updates, or `sync_full` to do everything in one command. Sync detects new posts, updated content, slug changes, and deleted posts by comparing `modified_gmt` timestamps.
544
545**Q: Can I automate the sync?**
546Yes. `sync_schedule` generates GitHub Actions workflows (cron-based), cron scripts, or Netlify/Vercel webhooks for real-time sync on every WordPress post save.
547
548**Q: What happens when a post is updated in WordPress?**
549On the next sync, the tool detects the newer `modified_gmt` timestamp, re-fetches the post from the REST API, re-converts it to Markdown with updated frontmatter (categories, SEO, ACF, images), and overwrites the local file.
550
551### Export & Deployment
552
553**Q: Can I preview before doing a full export?**
554Yes. Run `convert_preview` to see 3-5 sample posts converted to Markdown. Run `content_audit` to see a complexity report before committing to a full export.
555
556**Q: What if the export fails halfway?**
557Every post's state is tracked in SQLite. Run `export_resume` to continue from where it stopped. Run `export_retry` to reprocess any failed posts.
558
559**Q: Does it generate redirects?**
560Yes. `generate_redirects` creates redirect rules from the WordPress→Astro URL map. Supports Netlify (`_redirects`), Vercel (`vercel.json`), Cloudflare (`_redirects`), Apache (`.htaccess`), and Nginx.
561
562**Q: Can I deploy to Vercel/Netlify/Cloudflare?**
563Yes. The scaffolder generates platform-specific config files, and `github_deploy_config` creates the deploy configuration. Push to GitHub and connect your deploy platform.
564
565**Q: Can I manage multiple sites?**
566Yes. Register as many sites as you want. Each site has its own config, export settings, and state. Set a default site or specify `site_id` per command.
567
568### Technical
569
570**Q: What's the difference between `router` and `full` mode?**
571In `router` mode (default), only 3 tools are exposed to Claude: `wp_astro_run`, `wp_astro_help`, `wp_astro_describe`. This saves tokens. In `full` mode, all 55 tools are exposed directly. Set via `WP_ASTRO_MODE` env var.
572
573**Q: Does it handle rate limiting?**
574Yes. Each site has a token-bucket rate limiter (default: 10 req/s). If WordPress returns a 429, the rate is automatically halved. Configurable via `rate_limit` in export config.
575
576**Q: Is content sanitized for XSS?**
577Yes. All HTML passes through DOMPurify before conversion. Only safe tags and attributes are allowed. No `<script>`, `onclick`, or `javascript:` URLs survive.
578
579**Q: Where is state stored?**
580In a SQLite database at `data/wp-astro.db` (gitignored). Contains export job state, cached terms/authors, URL mappings, shortcode rules, and audit logs. WAL mode enabled for concurrent reads.
581
582---
583
584## Troubleshooting
585
586### "Authentication failed"
587- Verify your application password is correct (generate a new one at `/wp-admin/profile.php`)
588- Make sure the username matches exactly (case-sensitive)
589- Check that the REST API is not blocked by a security plugin
590
591### "Cannot connect to site"
592- Verify the site URL is correct and includes `https://`
593- Check that `/wp-json/` is accessible (try visiting `https://yoursite.com/wp-json/` in a browser)
594- Some hosts block REST API access — check with your hosting provider
595
596### "Rate limited"
597- The default rate limit is 10 requests/second. Lower it via `site_export_config` if your host is strict
598- The server automatically halves the rate on 429 responses
599
600### "Export stalled"
601- Run `export_progress` to check the current state
602- Run `export_resume` to continue processing
603- Run `export_retry` if posts failed
604
605### "Page builder content looks wrong"
606- Run `content_audit` to see which builders are detected
607- Run `convert_preview` to inspect specific posts
608- The pipeline strips builder wrappers and keeps content — some complex layouts may need manual review
609
610### Astro build OOM with many posts (500+)
611
612If the **generated Astro site** runs out of memory during `astro build`, the problem is Astro's content collection parsing 500+ markdown files. Each `.md` file goes through Astro's markdown pipeline, which eats ~2MB per file.
613
614**Fix:** Switch to JSON mode in your export config:
615```
616site_export_config → content_format: "json"
617```
618
619This writes a single `src/data/blog.json` instead of individual `.md` files. Astro imports the JSON directly — no markdown parsing, no OOM. Content stays as HTML and is rendered via `set:html`.
620
621| Posts | Recommended Format |
622|-------|-------------------|
623| < 500 | `md` (content collections) |
624| 500-2000 | `json` (recommended) |
625| 2000+ | `json` (required for CI/CD) |
626
627### Build fails with "JavaScript heap out of memory"
628
629If the **MCP server build** (`npm run build`) runs out of memory, the problem is TypeScript compilation on CI/CD platforms with limited memory (Cloudflare Pages ~4GB, Netlify ~3GB).
630
631**Quick fix:** Use the built-in memory-optimized build scripts:
632```bash
633npm run build          # 4GB heap limit
634npm run build:low-mem  # 2GB heap + incremental compilation
635```
636
637**Per-platform fixes:**
638
639| Platform | Solution |
640|----------|----------|
641| Cloudflare Pages | Set build command to `npm run build` or add env var `NODE_OPTIONS=--max-old-space-size=3072` |
642| Netlify | Add env var `NODE_OPTIONS=--max-old-space-size=3072` in Site Settings → Build & Deploy → Environment |
643| Vercel | Usually fine (8GB default). If failing, add `NODE_OPTIONS=--max-old-space-size=4096` in Project Settings → Environment Variables |
644| GitHub Actions | Add `env: NODE_OPTIONS: --max-old-space-size=4096` to your build step |
645
646**Still failing?** Pre-build locally and commit the `dist/` folder — skip compilation on CI entirely.
647
648See [docs/faq.md](docs/faq.md#build--deployment) for detailed CI/CD setup guides per platform.
649
650---
651
652## Requirements
653
654- **Node.js** 18 or later
655- **WordPress** 4.7+ with REST API enabled
656- **Application password** (WordPress 5.6+ built-in, or via plugin for older versions)
657- **GitHub token** (optional, for repo creation — generate at github.com/settings/tokens)
658
659---
660
661## Contributing
662
663Contributions are welcome. Please:
664
6651. Fork the repository
6662. Create a feature branch
6673. Make your changes
6684. Run `npm run build` to verify
6695. Submit a pull request
670
671---
672
673## License
674
675MIT License. See [LICENSE](LICENSE) for details.
676