wordpress-developer-mcp-server: Instructions file for Codex

WordPress Developer MCP Server

Project Overview

This repository builds and ships a standalone MCP server that lets AI assistants manage local WordPress sites. The TypeScript source lives in src/, the bundled release entrypoint is dist/index.cjs, and the macOS/Windows installers wire the bundled server into supported AI apps.

Release artifacts contain only the bundled server file from dist/, so changes to src/ must be followed by npm run build.

Common Commands

• Install dependencies: npm ci
• Build release bundle: npm run build
• Typecheck: npm run typecheck
• Inspect MCP server locally: npm run inspect
• Shell syntax checks: bash -n install.sh and bash -n uninstall.sh

If PowerShell is available, parse-check the Windows scripts after editing them:

$errors = $null
$null = [System.Management.Automation.Language.Parser]::ParseFile("install.ps1", [ref]$null, [ref]$errors)
if ($errors.Count) { $errors | ForEach-Object { Write-Error $_ }; exit 1 }
$null = [System.Management.Automation.Language.Parser]::ParseFile("uninstall.ps1", [ref]$null, [ref]$errors)
if ($errors.Count) { $errors | ForEach-Object { Write-Error $_ }; exit 1 }

Code Style

• Use TypeScript ESM imports and keep strict typechecking clean.
• Match the existing formatting: tabs for indentation, single quotes, semicolons.
• Keep comments short and only where they explain non-obvious platform behavior or workarounds.
• Prefer existing helper patterns over new abstractions.
• Keep installer changes conservative; they run on user machines and should be easy to audit.

Architecture Notes

• src/index.ts creates the MCP server and concatenates always-on server instructions.
• src/tools/ contains tool registrations grouped by feature area.
• src/lib/studio-cli.ts owns Studio CLI process execution. Windows .cmd behavior is delicate; do not simplify it without retesting Windows.
• src/lib/node-runtime.ts owns lookup for commands provided by the Node runtime. Installed MCP uses the bundled Node/npm under ~/.wordpress-developer-mcp/node; runtime code that needs npm or Node-provided commands must resolve them through this helper instead of assuming global node, npm, or npm.cmd are on PATH.
• src/lib/package.ts derives MCP serverInfo.version from package.json.
• install.sh is macOS-focused. install.ps1 is Windows-focused and also supports the programmatic -Update path used by the MCP update tool.
• Update mode should refresh runtime/server/wrappers only; avoid auth prompts or app configuration during programmatic updates.