wp-astro-mcp: Instructions file for Claude Code

WP Astro MCP Server

Headless WordPress MCP server — adds an Astro frontend to any WordPress site, with multi-site support.

Astro Target Version: 6.0

• Generates Astro 6 projects (Content Layer API, Zod 4, Fonts API)
• Requires Node.js 22.12+ (generates .nvmrc)
• Adapter versions: Vercel 9, Netlify 7, Cloudflare 13
• Zod imported from astro/zod (not astro:content)
• Content collections use glob loader from astro/loaders
• JSON-LD structured data on post pages
• Responsive image layout with aspect-ratio preservation

Project Structure

src/
  index.ts              — Server entry point (MCP SDK, stdio transport)
  types/index.ts        — All TypeScript type definitions
  config/
    sites.ts            — SiteManager singleton (multi-site config)
    database.ts         — DatabaseManager singleton (SQLite state)
  tools/
    index.ts            — Tool aggregation (allTools, allHandlers, mode switching)
    router.ts           — 3 router tools (wp_astro_run/help/describe)
    sites.ts            — Site management tools (add, test, list, analyze, etc.)
    extract.ts          — Content extraction tools (13 tools: posts, terms, authors, media, menus, etc.)
    transform.ts        — Transform tools (6 tools: convert, preview, HTML, shortcodes)
    output.ts           — Output & media tools (7 tools: scaffold, write, redirects, media)
    github.ts           — GitHub tools (6 tools: init, repo, commit, push, status, deploy)
    export.ts           — Export pipeline tools (7 tools: plan, start, resume, progress, retry, validate, cleanup)
    sync.ts             — Content sync tools (8 tools: check, pull, delete, full, status, schedule, reset, webhook)
    wizard.ts           — Setup wizard tool (1 tool: setup_wizard)
  schemas/
    sites.ts            — Zod schemas for site tools
    extract.ts          — Zod schemas for extract tools
    transform.ts        — Zod schemas for transform tools
    output.ts           — Zod schemas for output/media tools
    github.ts           — Zod schemas for GitHub tools
    export.ts           — Zod schemas for export pipeline tools
    sync.ts             — Zod schemas for content sync tools
    wizard.ts           — Zod schema for setup wizard
  services/
    wp-rest-client.ts   — WordPress REST API client (rate limiting, retry, auth)
    content-analyzer.ts — Content analysis (shortcodes, blocks, page builders, embeds)
    html-to-markdown.ts — 13-step HTML→Markdown pipeline (Turndown + custom rules)
    shortcode-resolver.ts — WordPress shortcode parser and resolver (built-in + per-site rules)
    link-rewriter.ts    — Internal link + media URL rewriter
    frontmatter-builder.ts — Astro frontmatter builder (SEO, ACF, taxonomies, reading time)
    astro-scaffolder.ts — Astro project scaffolder (config, layouts, pages, collections)
    content-writer.ts   — Write Markdown to disk, redirects, media audit/rewrite
  utils/
    errors.ts           — Error classes + formatSuccessResponse/formatErrorResponse
    logger.ts           — Logger singleton (stderr output)
config/
  sites.json            — Site credentials (gitignored)
  sites.example.json    — Config template
data/
  wp-astro.db           — SQLite database (gitignored)