wp-mcp-gateway 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# MCP Server (TypeScript)
+
+Local MCP server that connects Claude to a scoped WordPress plugin gateway.
+
+## Run
+
+1. Copy `.env.example` to `.env` and fill credentials.
+2. Install dependencies:
+   - `npm install`
+3. Start development server:
+   - `npm run dev`
+
+## Test
+
+- `npm test`
+
+## Key constraints
+
+- Allowed content types default to: `post,page,featured_item`
+- Permanent delete is intentionally not exposed in v1
+- Yoast operations are limited to allowlisted Tier A/B routes

package/dist/client/pluginApiClient.js

@@ -0,0 +1,150 @@
+import { ToolError } from "../utils/errors.js";
+export class PluginApiClient {
+    config;
+    authHeader;
+    constructor(config) {
+        this.config = config;
+        const raw = `${config.wpUsername}:${config.wpAppPassword}`;
+        this.authHeader = `Basic ${Buffer.from(raw).toString("base64")}`;
+    }
+    async siteInfo() {
+        return this.request("GET", "/site-info");
+    }
+    async listContentTypes() {
+        return this.request("GET", "/content-types");
+    }
+    async findContent(query) {
+        return this.request("GET", "/content", { query: query });
+    }
+    async getContent(id) {
+        return this.request("GET", `/content/${id}`);
+    }
+    async createContent(body) {
+        return this.request("POST", "/content", { body });
+    }
+    async updateContent(id, body) {
+        return this.request("PATCH", `/content/${id}`, { body });
+    }
+    async publishContent(id, body) {
+        return this.request("POST", `/content/${id}/publish`, { body });
+    }
+    async trashContent(id) {
+        return this.request("POST", `/content/${id}/trash`, { body: {} });
+    }
+    async restoreContent(id) {
+        return this.request("POST", `/content/${id}/restore`, { body: {} });
+    }
+    async listRevisions(id) {
+        return this.request("GET", `/content/${id}/revisions`);
+    }
+    async restoreRevision(id, revisionId) {
+        return this.request("POST", `/content/${id}/revisions/${revisionId}/restore`, { body: {} });
+    }
+    async listAuthors() {
+        return this.request("GET", "/authors");
+    }
+    async assignAuthor(id, authorId) {
+        return this.request("POST", `/content/${id}/author`, { body: { author_id: authorId } });
+    }
+    async listTerms(taxonomy, query) {
+        return this.request("GET", `/taxonomies/${encodeURIComponent(taxonomy)}/terms`, {
+            query: query,
+        });
+    }
+    async createTerm(taxonomy, body) {
+        return this.request("POST", `/taxonomies/${encodeURIComponent(taxonomy)}/terms`, { body });
+    }
+    async assignTerms(id, body) {
+        return this.request("POST", `/content/${id}/terms`, { body });
+    }
+    async uploadMedia(body) {
+        return this.request("POST", "/media", { body });
+    }
+    async searchMedia(query) {
+        return this.request("GET", "/media", { query: query });
+    }
+    async updateMedia(id, body) {
+        return this.request("PATCH", `/media/${id}`, { body });
+    }
+    async setFeaturedImage(id, mediaId) {
+        return this.request("POST", `/content/${id}/featured-image`, { body: { media_id: mediaId } });
+    }
+    async insertInlineImage(id, body) {
+        return this.request("POST", `/content/${id}/inline-image/insert`, { body });
+    }
+    async replaceInlineImage(id, body) {
+        return this.request("POST", `/content/${id}/inline-image/replace`, { body });
+    }
+    async removeInlineImage(id, body) {
+        return this.request("POST", `/content/${id}/inline-image/remove`, { body });
+    }
+    async getYoastAnalysis(id) {
+        return this.request("GET", `/yoast/analysis/${id}`);
+    }
+    async updateYoastMetadata(id, body) {
+        return this.request("PATCH", `/yoast/metadata/${id}`, { body });
+    }
+    async getYoastHeadPreview(id) {
+        return this.request("GET", `/yoast/head/${id}`);
+    }
+    async getPreviewLink(id) {
+        return this.request("POST", `/content/${id}/preview-link`, { body: {} });
+    }
+    async getMedia(mediaId) {
+        return this.request("GET", `/media/${mediaId}`);
+    }
+    async uploadMediaFromUrl(params) {
+        return this.request("POST", "/media/from-url", params);
+    }
+    async cloneContent(id, params) {
+        return this.request("POST", `/content/${id}/clone`, params);
+    }
+    async request(method, path, options = {}) {
+        const url = new URL(`${this.config.wpPluginBaseUrl}${path}`);
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            if (value === null || value === undefined || value === "") {
+                continue;
+            }
+            url.searchParams.set(key, String(value));
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.requestTimeoutMs);
+        try {
+            const response = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: this.authHeader,
+                    "Content-Type": "application/json",
+                },
+                body: options.body ? JSON.stringify(options.body) : undefined,
+                signal: controller.signal,
+            });
+            const payload = (await response.json().catch(() => ({})));
+            if (!response.ok || !payload.success) {
+                const error = payload.error;
+                throw new ToolError(error?.code ?? "PLUGIN_REQUEST_FAILED", error?.message ?? "Plugin request failed", {
+                    details: error?.details ?? payload,
+                    httpStatus: error?.http_status ?? response.status,
+                    retryable: Boolean(error?.retryable),
+                });
+            }
+            return payload.data;
+        }
+        catch (error) {
+            if (error instanceof ToolError) {
+                throw error;
+            }
+            if (error instanceof DOMException && error.name === "AbortError") {
+                throw new ToolError("PLUGIN_REQUEST_TIMEOUT", `Request timed out after ${this.config.requestTimeoutMs}ms`, {
+                    retryable: true,
+                });
+            }
+            throw new ToolError("PLUGIN_REQUEST_FAILED", "Failed to call WordPress plugin API", {
+                details: error,
+            });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}

package/dist/config.js

@@ -0,0 +1,71 @@
+const DEFAULT_ALLOWED_CONTENT_TYPES = ["post", "page", "featured_item"];
+const DEFAULT_ALLOWED_TAXONOMIES = [
+    "category",
+    "post_tag",
+    "featured_item_category",
+    "featured_item_tag",
+];
+const DEFAULT_YOAST_ALLOWED_PATHS = ["/yoast/analysis", "/yoast/metadata", "/yoast/head"];
+const DEFAULT_MEDIA_ALLOWED_MIME_TYPES = ["image/jpeg", "image/png", "image/webp", "image/gif"];
+function readList(raw, fallback) {
+    if (!raw || !raw.trim()) {
+        return [...fallback];
+    }
+    return raw
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function readNumber(raw, fallback) {
+    if (!raw || !raw.trim()) {
+        return fallback;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed)) {
+        return fallback;
+    }
+    return parsed;
+}
+function readBoolean(raw, fallback) {
+    if (!raw || !raw.trim()) {
+        return fallback;
+    }
+    const lowered = raw.toLowerCase();
+    if (["true", "1", "yes", "y", "on"].includes(lowered)) {
+        return true;
+    }
+    if (["false", "0", "no", "n", "off"].includes(lowered)) {
+        return false;
+    }
+    return fallback;
+}
+function ensure(name, value) {
+    if (!value || !value.trim()) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value;
+}
+export function loadConfig(env = process.env) {
+    const allowedAuthorIds = readList(env.ALLOWED_AUTHOR_IDS, [])
+        .map((raw) => Number(raw))
+        .filter((value) => Number.isInteger(value) && value > 0);
+    return {
+        wpPluginBaseUrl: ensure("WP_PLUGIN_BASE_URL", env.WP_PLUGIN_BASE_URL).replace(/\/$/, ""),
+        wpUsername: ensure("WP_USERNAME", env.WP_USERNAME),
+        wpAppPassword: ensure("WP_APP_PASSWORD", env.WP_APP_PASSWORD),
+        allowedContentTypes: readList(env.ALLOWED_CONTENT_TYPES, DEFAULT_ALLOWED_CONTENT_TYPES),
+        allowedTaxonomies: readList(env.ALLOWED_TAXONOMIES, DEFAULT_ALLOWED_TAXONOMIES),
+        allowedAuthorIds,
+        solutionsRootSlug: env.SOLUTIONS_ROOT_SLUG?.trim() || "solutions",
+        yoastAllowedPaths: readList(env.YOAST_ALLOWED_PATHS, DEFAULT_YOAST_ALLOWED_PATHS),
+        mediaAllowedMimeTypes: readList(env.MEDIA_ALLOWED_MIME_TYPES, DEFAULT_MEDIA_ALLOWED_MIME_TYPES),
+        mediaMaxSizeMb: readNumber(env.MEDIA_MAX_SIZE_MB, 10),
+        mediaRequireAltText: readBoolean(env.MEDIA_REQUIRE_ALT_TEXT, true),
+        mediaAllowedImportDomains: readList(env.MEDIA_ALLOWED_IMPORT_DOMAINS, []),
+        previewTokenTtlMinutes: readNumber(env.PREVIEW_TOKEN_TTL_MINUTES, 1440),
+        confirmationTtlSeconds: readNumber(env.CONFIRMATION_TTL_SECONDS, 300),
+        requestTimeoutMs: readNumber(env.REQUEST_TIMEOUT_MS, 30_000),
+        rateLimitMaxBurst: readNumber(env.RATE_LIMIT_MAX_BURST, 30),
+        rateLimitRefillPerSecond: readNumber(env.RATE_LIMIT_REFILL_PER_SECOND, 1),
+    };
+}

package/dist/guides/generic-guide.md

@@ -0,0 +1,204 @@
+# Generic WordPress Content Format Guide
+
+## Overview
+For standard WordPress sites without custom shortcodes, use plain HTML or Gutenberg block markup. No special theme-specific shortcuts—just semantic HTML.
+
+## Content Formats Supported
+
+### Option 1: HTML (Recommended for Simplicity)
+```html
+<p>Regular paragraph text.</p>
+
+<h2>Heading</h2>
+
+<p>More paragraph text with <strong>bold</strong> and <em>italic</em>.</p>
+
+<ul>
+  <li>List item 1</li>
+  <li>List item 2</li>
+</ul>
+
+<img src="https://..." alt="Image description">
+
+<a href="https://...">Link text</a>
+
+<blockquote>Quote text</blockquote>
+```
+
+Use `content_format: "html"` with this approach.
+
+### Option 2: Markdown (Auto-Converted to HTML)
+```markdown
+# Heading 1
+
+## Heading 2
+
+Regular paragraph text with **bold** and *italic*.
+
+- List item 1
+- List item 2
+
+[Link text](https://...)
+
+> Blockquote text
+
+![Image description](https://...)
+```
+
+Use `content_format: "markdown"` with this approach.
+
+### Option 3: Gutenberg Block Markup
+```html
+<!-- wp:paragraph -->
+<p>Paragraph content</p>
+<!-- /wp:paragraph -->
+
+<!-- wp:heading {"level":2} -->
+<h2>Heading</h2>
+<!-- /wp:heading -->
+
+<!-- wp:image {"id":123,"sizeSlug":"large"} -->
+<figure class="wp-block-image size-large">
+  <img src="https://..." alt=""/>
+</figure>
+<!-- /wp:image -->
+
+<!-- wp:list -->
+<ul>
+  <li>Item 1</li>
+  <li>Item 2</li>
+</ul>
+<!-- /wp:list -->
+```
+
+Use `content_format: "html"` with this approach.
+
+## Common HTML Elements
+
+### Headings
+```html
+<h1>Page Title</h1>
+<h2>Section Heading</h2>
+<h3>Subsection</h3>
+<h4>Small Heading</h4>
+```
+
+### Text Formatting
+```html
+<p>Regular paragraph.</p>
+<strong>Bold text</strong>
+<em>Italic text</em>
+<u>Underlined text</u>
+<code>Code snippet</code>
+```
+
+### Lists
+```html
+<ul>
+  <li>Unordered item 1</li>
+  <li>Unordered item 2</li>
+</ul>
+
+<ol>
+  <li>Ordered item 1</li>
+  <li>Ordered item 2</li>
+</ol>
+```
+
+### Images
+```html
+<img src="https://example.com/image.jpg" alt="Image description">
+
+<!-- Or with figure element -->
+<figure>
+  <img src="https://example.com/image.jpg" alt="">
+  <figcaption>Optional image caption</figcaption>
+</figure>
+```
+
+### Links
+```html
+<a href="https://example.com">Link text</a>
+<a href="https://example.com" target="_blank">External link</a>
+```
+
+### Blockquote
+```html
+<blockquote>
+  <p>Quote text here</p>
+  <cite>— Author Name</cite>
+</blockquote>
+```
+
+### Separator/Divider
+```html
+<hr>
+```
+
+## Image Workflow
+
+### Selecting images from the media library
+1. Call `wp_search_media` with relevant keywords
+2. **Display the thumbnail URLs visually** — show the images inline so the user can see their options
+3. Present as numbered choices with titles and dimensions
+4. The user picks by number, or drops a new image into the chat
+
+### Uploading new images
+- **User drops image in chat**: Read the file, base64-encode it, call `wp_upload_media`
+- **Image at a URL**: Call `wp_upload_media_from_url` (server-side download)
+- Use the returned source_url in `<img src="RETURNED_URL" alt="description">`
+
+### Featured image
+- Call `wp_set_featured_image` with the media ID (separate from inline content images)
+
+## Simple Content Template
+
+```html
+<h1>Post Title</h1>
+
+<p>Opening paragraph introducing the topic.</p>
+
+<h2>First Section</h2>
+
+<p>Section content goes here. Use natural paragraphs.</p>
+
+<img src="https://..." alt="Relevant image">
+
+<h2>Second Section</h2>
+
+<p>More content.</p>
+
+<ul>
+  <li>Key point 1</li>
+  <li>Key point 2</li>
+  <li>Key point 3</li>
+</ul>
+
+<h2>Conclusion</h2>
+
+<p>Closing thoughts.</p>
+```
+
+## Content Format Selection
+
+- **`content_format: "html"`** — Use for HTML, Gutenberg blocks, or mixed content
+- **`content_format: "markdown"`** — Use for markdown-formatted content (will auto-convert to HTML)
+- **`content_format: "auto"`** — WordPress auto-detects format (usually works fine)
+
+## Pro Tips
+
+- **Keep it semantic**: Use proper HTML tags (h1-h6 for headings, p for paragraphs, etc.)
+- **Alt text required**: Always include `alt` attribute on images for accessibility
+- **Link target**: Use `target="_blank"` for external links only
+- **No inline styles**: Let WordPress/theme handle styling via CSS classes
+- **Use lists**: Break up text with lists for readability
+- **Short paragraphs**: 2-4 sentences per paragraph is ideal for web reading
+
+## When to Use Custom Theme Guides
+
+If the WordPress site uses:
+- **XMPro + Flatsome theme** → Use `xmpro-post-guide.md` or `xmpro-page-guide.md`
+- **Custom shortcodes** → Ask the user for theme/plugin documentation
+- **Gutenberg patterns** → This generic guide works fine
+
+Otherwise, this generic HTML approach works for any WordPress site.

package/dist/guides/guides/generic-guide.md

@@ -0,0 +1,204 @@
+# Generic WordPress Content Format Guide
+
+## Overview
+For standard WordPress sites without custom shortcodes, use plain HTML or Gutenberg block markup. No special theme-specific shortcuts—just semantic HTML.
+
+## Content Formats Supported
+
+### Option 1: HTML (Recommended for Simplicity)
+```html
+<p>Regular paragraph text.</p>
+
+<h2>Heading</h2>
+
+<p>More paragraph text with <strong>bold</strong> and <em>italic</em>.</p>
+
+<ul>
+  <li>List item 1</li>
+  <li>List item 2</li>
+</ul>
+
+<img src="https://..." alt="Image description">
+
+<a href="https://...">Link text</a>
+
+<blockquote>Quote text</blockquote>
+```
+
+Use `content_format: "html"` with this approach.
+
+### Option 2: Markdown (Auto-Converted to HTML)
+```markdown
+# Heading 1
+
+## Heading 2
+
+Regular paragraph text with **bold** and *italic*.
+
+- List item 1
+- List item 2
+
+[Link text](https://...)
+
+> Blockquote text
+
+![Image description](https://...)
+```
+
+Use `content_format: "markdown"` with this approach.
+
+### Option 3: Gutenberg Block Markup
+```html
+<!-- wp:paragraph -->
+<p>Paragraph content</p>
+<!-- /wp:paragraph -->
+
+<!-- wp:heading {"level":2} -->
+<h2>Heading</h2>
+<!-- /wp:heading -->
+
+<!-- wp:image {"id":123,"sizeSlug":"large"} -->
+<figure class="wp-block-image size-large">
+  <img src="https://..." alt=""/>
+</figure>
+<!-- /wp:image -->
+
+<!-- wp:list -->
+<ul>
+  <li>Item 1</li>
+  <li>Item 2</li>
+</ul>
+<!-- /wp:list -->
+```
+
+Use `content_format: "html"` with this approach.
+
+## Common HTML Elements
+
+### Headings
+```html
+<h1>Page Title</h1>
+<h2>Section Heading</h2>
+<h3>Subsection</h3>
+<h4>Small Heading</h4>
+```
+
+### Text Formatting
+```html
+<p>Regular paragraph.</p>
+<strong>Bold text</strong>
+<em>Italic text</em>
+<u>Underlined text</u>
+<code>Code snippet</code>
+```
+
+### Lists
+```html
+<ul>
+  <li>Unordered item 1</li>
+  <li>Unordered item 2</li>
+</ul>
+
+<ol>
+  <li>Ordered item 1</li>
+  <li>Ordered item 2</li>
+</ol>
+```
+
+### Images
+```html
+<img src="https://example.com/image.jpg" alt="Image description">
+
+<!-- Or with figure element -->
+<figure>
+  <img src="https://example.com/image.jpg" alt="">
+  <figcaption>Optional image caption</figcaption>
+</figure>
+```
+
+### Links
+```html
+<a href="https://example.com">Link text</a>
+<a href="https://example.com" target="_blank">External link</a>
+```
+
+### Blockquote
+```html
+<blockquote>
+  <p>Quote text here</p>
+  <cite>— Author Name</cite>
+</blockquote>
+```
+
+### Separator/Divider
+```html
+<hr>
+```
+
+## Image Workflow
+
+### Selecting images from the media library
+1. Call `wp_search_media` with relevant keywords
+2. **Display the thumbnail URLs visually** — show the images inline so the user can see their options
+3. Present as numbered choices with titles and dimensions
+4. The user picks by number, or drops a new image into the chat
+
+### Uploading new images
+- **User drops image in chat**: Read the file, base64-encode it, call `wp_upload_media`
+- **Image at a URL**: Call `wp_upload_media_from_url` (server-side download)
+- Use the returned source_url in `<img src="RETURNED_URL" alt="description">`
+
+### Featured image
+- Call `wp_set_featured_image` with the media ID (separate from inline content images)
+
+## Simple Content Template
+
+```html
+<h1>Post Title</h1>
+
+<p>Opening paragraph introducing the topic.</p>
+
+<h2>First Section</h2>
+
+<p>Section content goes here. Use natural paragraphs.</p>
+
+<img src="https://..." alt="Relevant image">
+
+<h2>Second Section</h2>
+
+<p>More content.</p>
+
+<ul>
+  <li>Key point 1</li>
+  <li>Key point 2</li>
+  <li>Key point 3</li>
+</ul>
+
+<h2>Conclusion</h2>
+
+<p>Closing thoughts.</p>
+```
+
+## Content Format Selection
+
+- **`content_format: "html"`** — Use for HTML, Gutenberg blocks, or mixed content
+- **`content_format: "markdown"`** — Use for markdown-formatted content (will auto-convert to HTML)
+- **`content_format: "auto"`** — WordPress auto-detects format (usually works fine)
+
+## Pro Tips
+
+- **Keep it semantic**: Use proper HTML tags (h1-h6 for headings, p for paragraphs, etc.)
+- **Alt text required**: Always include `alt` attribute on images for accessibility
+- **Link target**: Use `target="_blank"` for external links only
+- **No inline styles**: Let WordPress/theme handle styling via CSS classes
+- **Use lists**: Break up text with lists for readability
+- **Short paragraphs**: 2-4 sentences per paragraph is ideal for web reading
+
+## When to Use Custom Theme Guides
+
+If the WordPress site uses:
+- **XMPro + Flatsome theme** → Use `xmpro-post-guide.md` or `xmpro-page-guide.md`
+- **Custom shortcodes** → Ask the user for theme/plugin documentation
+- **Gutenberg patterns** → This generic guide works fine
+
+Otherwise, this generic HTML approach works for any WordPress site.