wp-mcp-gateway 0.1.0

package/dist/services/confirmationService.js

@@ -0,0 +1,40 @@
+import { randomUUID } from "node:crypto";
+import { ToolError } from "../utils/errors.js";
+export class ConfirmationService {
+    ttlSeconds;
+    store = new Map();
+    constructor(ttlSeconds) {
+        this.ttlSeconds = ttlSeconds;
+    }
+    issue(action, key, input) {
+        const token = randomUUID();
+        const issuedAt = new Date();
+        const expiresAt = new Date(issuedAt.getTime() + this.ttlSeconds * 1000);
+        const payload = {
+            action,
+            key,
+            input,
+            issued_at: issuedAt.toISOString(),
+            expires_at: expiresAt.toISOString(),
+        };
+        this.store.set(token, {
+            payload,
+            expiresAtEpochMs: expiresAt.getTime(),
+        });
+        return { token, payload };
+    }
+    consume(token, expectedAction, expectedKey) {
+        const stored = this.store.get(token);
+        if (!stored) {
+            throw new ToolError("INVALID_CONFIRMATION_TOKEN", "Confirmation token is invalid or already used");
+        }
+        this.store.delete(token);
+        if (Date.now() > stored.expiresAtEpochMs) {
+            throw new ToolError("EXPIRED_CONFIRMATION_TOKEN", "Confirmation token has expired");
+        }
+        if (stored.payload.action !== expectedAction || stored.payload.key !== expectedKey) {
+            throw new ToolError("MISMATCH_CONFIRMATION_TOKEN", "Confirmation token does not match action payload");
+        }
+        return stored.payload;
+    }
+}

package/dist/services/markdownService.js

@@ -0,0 +1,37 @@
+import MarkdownIt from "markdown-it";
+const md = new MarkdownIt({
+    html: true, // Allow HTML passthrough (content may already contain HTML)
+    linkify: true, // Auto-convert URLs to links
+    typographer: true, // Smart quotes, dashes
+});
+/**
+ * Detect whether content is likely Markdown vs HTML.
+ * Heuristic: if it contains block-level HTML tags, treat as HTML.
+ */
+function looksLikeHtml(content) {
+    // Check for common block-level HTML elements
+    return /<(div|p|h[1-6]|ul|ol|table|figure|section|article|blockquote)\b/i.test(content);
+}
+/**
+ * Convert content to HTML based on the specified format.
+ * - "html": pass through unchanged
+ * - "markdown": always convert
+ * - "auto" (default): detect and convert if it looks like markdown
+ */
+export function toHtml(content, format = "auto") {
+    if (!content || !content.trim()) {
+        return content;
+    }
+    if (format === "html") {
+        return content;
+    }
+    if (format === "markdown") {
+        return md.render(content);
+    }
+    // Auto mode: if it already looks like HTML, leave it alone
+    if (looksLikeHtml(content)) {
+        return content;
+    }
+    // Otherwise, convert from markdown
+    return md.render(content);
+}

package/dist/services/policyService.js

@@ -0,0 +1,75 @@
+import { ToolError } from "../utils/errors.js";
+const DEFAULT_PATCH_FIELDS = new Set([
+    "title",
+    "content",
+    "excerpt",
+    "slug",
+    "featured_media",
+    "author",
+    "date",
+]);
+const DEFAULT_YOAST_META_FIELDS = new Set([
+    "yoast_wpseo_title",
+    "yoast_wpseo_metadesc",
+    "yoast_wpseo_canonical",
+    "yoast_wpseo_focuskw",
+    "yoast_wpseo_opengraph-title",
+    "yoast_wpseo_opengraph-description",
+    "yoast_wpseo_twitter-title",
+    "yoast_wpseo_twitter-description",
+]);
+export class PolicyService {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    assertAllowedContentType(contentType) {
+        if (!this.config.allowedContentTypes.includes(contentType)) {
+            throw new ToolError("DISALLOWED_CONTENT_TYPE", `Content type is not allowed: ${contentType}`);
+        }
+    }
+    assertAllowedTaxonomy(taxonomy) {
+        if (!this.config.allowedTaxonomies.includes(taxonomy)) {
+            throw new ToolError("DISALLOWED_TAXONOMY", `Taxonomy is not allowed: ${taxonomy}`);
+        }
+    }
+    assertAllowedAuthor(authorId) {
+        if (this.config.allowedAuthorIds.length === 0) {
+            return;
+        }
+        if (!this.config.allowedAuthorIds.includes(authorId)) {
+            throw new ToolError("DISALLOWED_AUTHOR", `Author is not allowlisted: ${authorId}`);
+        }
+    }
+    assertPatchFields(patch) {
+        for (const field of Object.keys(patch)) {
+            if (!DEFAULT_PATCH_FIELDS.has(field)) {
+                throw new ToolError("DISALLOWED_PATCH_FIELD", `Patch field is not allowed: ${field}`);
+            }
+        }
+    }
+    assertYoastPath(path) {
+        if (!this.config.yoastAllowedPaths.some((allowed) => path.startsWith(allowed))) {
+            throw new ToolError("DISALLOWED_YOAST_PATH", `Yoast path is not allowed: ${path}`);
+        }
+    }
+    assertYoastMetaKeys(meta) {
+        for (const key of Object.keys(meta)) {
+            if (!DEFAULT_YOAST_META_FIELDS.has(key)) {
+                throw new ToolError("DISALLOWED_YOAST_META_KEY", `Yoast meta key is not allowed: ${key}`);
+            }
+        }
+    }
+    assertMediaPolicy(mimeType, sizeBytes, altText) {
+        if (!this.config.mediaAllowedMimeTypes.includes(mimeType)) {
+            throw new ToolError("DISALLOWED_MEDIA_MIME", `MIME type is not allowed: ${mimeType}`);
+        }
+        const maxBytes = this.config.mediaMaxSizeMb * 1024 * 1024;
+        if (sizeBytes > maxBytes) {
+            throw new ToolError("MEDIA_SIZE_EXCEEDED", `Media exceeds max size of ${this.config.mediaMaxSizeMb}MB`);
+        }
+        if (this.config.mediaRequireAltText && (!altText || !altText.trim())) {
+            throw new ToolError("MISSING_ALT_TEXT", "Alt text is required by policy");
+        }
+    }
+}

package/dist/services/rateLimiter.js

@@ -0,0 +1,46 @@
+import { ToolError } from "../utils/errors.js";
+/**
+ * Simple token-bucket rate limiter.
+ * Limits the number of outgoing requests per time window.
+ */
+export class RateLimiter {
+    maxTokens;
+    refillRatePerSecond;
+    bucket;
+    /**
+     * @param maxTokens Maximum burst size (requests)
+     * @param refillRatePerSecond Tokens added per second
+     */
+    constructor(maxTokens = 30, refillRatePerSecond = 1) {
+        this.maxTokens = maxTokens;
+        this.refillRatePerSecond = refillRatePerSecond;
+        this.bucket = {
+            tokens: maxTokens,
+            lastRefillEpochMs: Date.now(),
+        };
+    }
+    /**
+     * Consume one token. Throws if rate limit exceeded.
+     */
+    consume() {
+        this.refill();
+        if (this.bucket.tokens < 1) {
+            throw new ToolError("RATE_LIMIT_EXCEEDED", "Too many requests. Please wait before retrying.", { retryable: true });
+        }
+        this.bucket.tokens -= 1;
+    }
+    /**
+     * Check remaining tokens without consuming.
+     */
+    remaining() {
+        this.refill();
+        return Math.floor(this.bucket.tokens);
+    }
+    refill() {
+        const now = Date.now();
+        const elapsedSeconds = (now - this.bucket.lastRefillEpochMs) / 1000;
+        const newTokens = elapsedSeconds * this.refillRatePerSecond;
+        this.bucket.tokens = Math.min(this.maxTokens, this.bucket.tokens + newTokens);
+        this.bucket.lastRefillEpochMs = now;
+    }
+}

package/dist/tools/registerTools.js

@@ -0,0 +1,384 @@
+import { z } from "zod";
+import { serializeError, ToolError } from "../utils/errors.js";
+import { logger } from "../utils/logger.js";
+import { toHtml } from "../services/markdownService.js";
+const ContentTypeSchema = z.enum(["post", "page", "featured_item"]);
+const PlacementSchema = z.enum(["start", "end", "before_heading", "after_heading", "marker"]);
+function respond(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+function requireConfirmation(confirmations, action, key, input, confirmationToken) {
+    if (!confirmationToken) {
+        const issued = confirmations.issue(action, key, input);
+        return {
+            confirmed: false,
+            payload: {
+                requires_confirmation: true,
+                confirmation_token: issued.token,
+                confirmation_payload: issued.payload,
+            },
+        };
+    }
+    confirmations.consume(confirmationToken, action, key);
+    return { confirmed: true };
+}
+export function registerTools(context) {
+    const { server, client, policy, confirmations, rateLimiter } = context;
+    async function runToolWithLimit(name, input, fn) {
+        try {
+            rateLimiter.consume();
+            const result = await fn();
+            return respond({ success: true, tool: name, data: result });
+        }
+        catch (error) {
+            const serialized = serializeError(error);
+            logger.error(`Tool ${name} failed`, { input, error: serialized });
+            return respond({ success: false, tool: name, error: serialized });
+        }
+    }
+    server.tool("wp_site_info", "Get site and capability metadata.", {}, async () => runToolWithLimit("wp_site_info", {}, async () => client.siteInfo()));
+    server.tool("wp_list_content_types", "List content types allowed for this MCP server.", {}, async () => runToolWithLimit("wp_list_content_types", {}, async () => client.listContentTypes()));
+    server.tool("wp_find_content", "Search and list content items across allowed content types.", {
+        content_type: ContentTypeSchema.optional(),
+        search: z.string().optional(),
+        status: z.string().optional(),
+        author: z.number().int().positive().optional(),
+        page: z.number().int().positive().optional(),
+        per_page: z.number().int().positive().max(100).optional(),
+        parent_term_slug: z.string().optional(),
+        parent_taxonomy: z.string().optional(),
+        solutions_only: z.boolean().optional(),
+    }, async (rawInput) => runToolWithLimit("wp_find_content", rawInput, async () => {
+        if (typeof rawInput.content_type === "string") {
+            policy.assertAllowedContentType(rawInput.content_type);
+        }
+        if (typeof rawInput.author === "number") {
+            policy.assertAllowedAuthor(rawInput.author);
+        }
+        return client.findContent(rawInput);
+    }));
+    server.tool("wp_get_content", "Get a single content item with edit context.", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+    }, async (rawInput) => runToolWithLimit("wp_get_content", rawInput, async () => {
+        policy.assertAllowedContentType(String(rawInput.content_type));
+        return client.getContent(Number(rawInput.id));
+    }));
+    server.tool("wp_create_draft", "Create a draft for an allowed content type.", {
+        content_type: ContentTypeSchema,
+        title: z.string().min(1),
+        content: z.string().optional(),
+        excerpt: z.string().optional(),
+        content_format: z.enum(["html", "markdown", "auto"]).optional(),
+        slug: z.string().optional(),
+        author: z.number().int().positive().optional(),
+        date: z.string().optional(),
+        terms: z.record(z.array(z.number().int().positive())).optional(),
+        yoast_meta: z.record(z.unknown()).optional(),
+    }, async (rawInput) => runToolWithLimit("wp_create_draft", rawInput, async () => {
+        const contentType = String(rawInput.content_type);
+        policy.assertAllowedContentType(contentType);
+        if (typeof rawInput.author === "number") {
+            policy.assertAllowedAuthor(rawInput.author);
+        }
+        if (rawInput.terms && typeof rawInput.terms === "object") {
+            for (const taxonomy of Object.keys(rawInput.terms)) {
+                policy.assertAllowedTaxonomy(taxonomy);
+            }
+        }
+        if (rawInput.yoast_meta && typeof rawInput.yoast_meta === "object") {
+            policy.assertYoastMetaKeys(rawInput.yoast_meta);
+        }
+        const contentFormat = rawInput.content_format || "auto";
+        const processedInput = { ...rawInput, status: "draft" };
+        if (typeof processedInput.content === "string") {
+            processedInput.content = toHtml(processedInput.content, contentFormat);
+        }
+        if (typeof processedInput.excerpt === "string" && processedInput.excerpt) {
+            processedInput.excerpt = toHtml(processedInput.excerpt, contentFormat);
+        }
+        return client.createContent(processedInput);
+    }));
+    server.tool("wp_update_content", "Patch an existing content item.", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+        patch: z.record(z.unknown()),
+        content_format: z.enum(["html", "markdown", "auto"]).optional(),
+    }, async (rawInput) => runToolWithLimit("wp_update_content", rawInput, async () => {
+        const contentType = String(rawInput.content_type);
+        policy.assertAllowedContentType(contentType);
+        const patch = rawInput.patch;
+        policy.assertPatchFields(patch);
+        if (typeof patch.author === "number") {
+            policy.assertAllowedAuthor(patch.author);
+        }
+        const contentFormat = rawInput.content_format || "auto";
+        if (typeof patch.content === "string") {
+            patch.content = toHtml(patch.content, contentFormat);
+        }
+        if (typeof patch.excerpt === "string" && patch.excerpt) {
+            patch.excerpt = toHtml(patch.excerpt, contentFormat);
+        }
+        return client.updateContent(Number(rawInput.id), {
+            content_type: contentType,
+            patch,
+        });
+    }));
+    server.tool("wp_publish_content", "Publish or schedule content with confirmation flow.", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+        date: z.string().optional(),
+        confirmation_token: z.string().optional(),
+    }, async (rawInput) => runToolWithLimit("wp_publish_content", rawInput, async () => {
+        const id = Number(rawInput.id);
+        const contentType = String(rawInput.content_type);
+        policy.assertAllowedContentType(contentType);
+        const key = `${contentType}:${id}:publish`;
+        const gate = requireConfirmation(confirmations, "publish_content", key, rawInput, rawInput.confirmation_token);
+        if (!gate.confirmed) {
+            return gate.payload;
+        }
+        return client.publishContent(id, {
+            content_type: contentType,
+            date: rawInput.date,
+        });
+    }));
+    server.tool("wp_trash_content", "Move content to trash (confirmation required).", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+        confirmation_token: z.string().optional(),
+    }, async (rawInput) => runToolWithLimit("wp_trash_content", rawInput, async () => {
+        const id = Number(rawInput.id);
+        const contentType = String(rawInput.content_type);
+        policy.assertAllowedContentType(contentType);
+        const key = `${contentType}:${id}:trash`;
+        const gate = requireConfirmation(confirmations, "trash_content", key, rawInput, rawInput.confirmation_token);
+        if (!gate.confirmed) {
+            return gate.payload;
+        }
+        return client.trashContent(id);
+    }));
+    server.tool("wp_restore_content", "Restore content from trash (confirmation required).", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+        confirmation_token: z.string().optional(),
+    }, async (rawInput) => runToolWithLimit("wp_restore_content", rawInput, async () => {
+        const id = Number(rawInput.id);
+        const contentType = String(rawInput.content_type);
+        policy.assertAllowedContentType(contentType);
+        const key = `${contentType}:${id}:restore`;
+        const gate = requireConfirmation(confirmations, "restore_content", key, rawInput, rawInput.confirmation_token);
+        if (!gate.confirmed) {
+            return gate.payload;
+        }
+        return client.restoreContent(id);
+    }));
+    server.tool("wp_list_revisions", "List revisions for a content item.", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+    }, async (rawInput) => runToolWithLimit("wp_list_revisions", rawInput, async () => {
+        policy.assertAllowedContentType(String(rawInput.content_type));
+        return client.listRevisions(Number(rawInput.id));
+    }));
+    server.tool("wp_restore_revision", "Restore a specific revision (confirmation required).", {
+        id: z.number().int().positive(),
+        revision_id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+        confirmation_token: z.string().optional(),
+    }, async (rawInput) => runToolWithLimit("wp_restore_revision", rawInput, async () => {
+        const id = Number(rawInput.id);
+        const revisionId = Number(rawInput.revision_id);
+        const contentType = String(rawInput.content_type);
+        policy.assertAllowedContentType(contentType);
+        const key = `${contentType}:${id}:revision:${revisionId}`;
+        const gate = requireConfirmation(confirmations, "restore_revision", key, rawInput, rawInput.confirmation_token);
+        if (!gate.confirmed) {
+            return gate.payload;
+        }
+        return client.restoreRevision(id, revisionId);
+    }));
+    server.tool("wp_list_authors", "List allowlisted authors.", {}, async () => runToolWithLimit("wp_list_authors", {}, async () => client.listAuthors()));
+    server.tool("wp_assign_author", "Assign an allowlisted author to content.", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+        author_id: z.number().int().positive(),
+    }, async (rawInput) => runToolWithLimit("wp_assign_author", rawInput, async () => {
+        policy.assertAllowedContentType(String(rawInput.content_type));
+        policy.assertAllowedAuthor(Number(rawInput.author_id));
+        return client.assignAuthor(Number(rawInput.id), Number(rawInput.author_id));
+    }));
+    server.tool("wp_list_terms", "List terms for an allowlisted taxonomy.", {
+        taxonomy: z.string().min(1),
+        search: z.string().optional(),
+        parent: z.number().int().min(0).optional(),
+        page: z.number().int().positive().optional(),
+        per_page: z.number().int().positive().max(100).optional(),
+    }, async (rawInput) => runToolWithLimit("wp_list_terms", rawInput, async () => {
+        const taxonomy = String(rawInput.taxonomy);
+        policy.assertAllowedTaxonomy(taxonomy);
+        return client.listTerms(taxonomy, rawInput);
+    }));
+    server.tool("wp_create_term", "Create a term in an allowlisted taxonomy.", {
+        taxonomy: z.string().min(1),
+        name: z.string().min(1),
+        slug: z.string().optional(),
+        parent: z.number().int().min(0).optional(),
+        description: z.string().optional(),
+    }, async (rawInput) => runToolWithLimit("wp_create_term", rawInput, async () => {
+        const taxonomy = String(rawInput.taxonomy);
+        policy.assertAllowedTaxonomy(taxonomy);
+        return client.createTerm(taxonomy, rawInput);
+    }));
+    server.tool("wp_assign_terms", "Assign term IDs to a content item.", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+        terms: z.record(z.array(z.number().int().positive())),
+    }, async (rawInput) => runToolWithLimit("wp_assign_terms", rawInput, async () => {
+        policy.assertAllowedContentType(String(rawInput.content_type));
+        const terms = rawInput.terms;
+        for (const taxonomy of Object.keys(terms)) {
+            policy.assertAllowedTaxonomy(taxonomy);
+        }
+        return client.assignTerms(Number(rawInput.id), {
+            content_type: rawInput.content_type,
+            terms,
+        });
+    }));
+    server.tool("wp_upload_media", "Upload media with policy validation.", {
+        filename: z.string().min(1),
+        mime_type: z.string().min(1),
+        bytes_base64: z.string().min(1),
+        alt_text: z.string().optional(),
+        caption: z.string().optional(),
+        description: z.string().optional(),
+        title: z.string().optional(),
+    }, async (rawInput) => runToolWithLimit("wp_upload_media", rawInput, async () => {
+        const mimeType = String(rawInput.mime_type);
+        const bytes = Buffer.from(String(rawInput.bytes_base64), "base64").byteLength;
+        policy.assertMediaPolicy(mimeType, bytes, rawInput.alt_text);
+        return client.uploadMedia(rawInput);
+    }));
+    server.tool("wp_search_media", "Search media library.", {
+        search: z.string().optional(),
+        page: z.number().int().positive().optional(),
+        per_page: z.number().int().positive().max(100).optional(),
+        mime_type: z.string().optional(),
+    }, async (rawInput) => runToolWithLimit("wp_search_media", rawInput, async () => client.searchMedia(rawInput)));
+    server.tool("wp_update_media", "Update media metadata.", {
+        id: z.number().int().positive(),
+        alt_text: z.string().optional(),
+        caption: z.string().optional(),
+        description: z.string().optional(),
+        title: z.string().optional(),
+    }, async (rawInput) => runToolWithLimit("wp_update_media", rawInput, async () => client.updateMedia(Number(rawInput.id), rawInput)));
+    server.tool("wp_set_featured_image", "Set or remove a featured image on content.", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+        media_id: z.number().int().positive().nullable(),
+    }, async (rawInput) => runToolWithLimit("wp_set_featured_image", rawInput, async () => {
+        policy.assertAllowedContentType(String(rawInput.content_type));
+        return client.setFeaturedImage(Number(rawInput.id), rawInput.media_id);
+    }));
+    server.tool("wp_insert_inline_image", "Insert an inline image into content in block-aware mode with HTML fallback.", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+        media_id: z.number().int().positive(),
+        placement: PlacementSchema,
+        heading_text: z.string().optional(),
+        marker: z.string().optional(),
+        align: z.enum(["none", "left", "center", "right", "wide", "full"]).optional(),
+        size_slug: z.string().optional(),
+        caption: z.string().optional(),
+        alt_text: z.string().optional(),
+    }, async (rawInput) => runToolWithLimit("wp_insert_inline_image", rawInput, async () => {
+        policy.assertAllowedContentType(String(rawInput.content_type));
+        return client.insertInlineImage(Number(rawInput.id), rawInput);
+    }));
+    server.tool("wp_replace_inline_image", "Replace an inline image reference in content.", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+        new_media_id: z.number().int().positive(),
+        match_media_id: z.number().int().positive().optional(),
+        match_src_substring: z.string().optional(),
+        alt_text: z.string().optional(),
+        caption: z.string().optional(),
+    }, async (rawInput) => runToolWithLimit("wp_replace_inline_image", rawInput, async () => {
+        policy.assertAllowedContentType(String(rawInput.content_type));
+        if (!rawInput.match_media_id && !rawInput.match_src_substring) {
+            throw new ToolError("INLINE_MATCH_REQUIRED", "Either match_media_id or match_src_substring must be provided");
+        }
+        return client.replaceInlineImage(Number(rawInput.id), rawInput);
+    }));
+    server.tool("wp_remove_inline_image", "Remove an inline image from content.", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+        match_media_id: z.number().int().positive().optional(),
+        match_src_substring: z.string().optional(),
+    }, async (rawInput) => runToolWithLimit("wp_remove_inline_image", rawInput, async () => {
+        policy.assertAllowedContentType(String(rawInput.content_type));
+        if (!rawInput.match_media_id && !rawInput.match_src_substring) {
+            throw new ToolError("INLINE_MATCH_REQUIRED", "Either match_media_id or match_src_substring must be provided");
+        }
+        return client.removeInlineImage(Number(rawInput.id), rawInput);
+    }));
+    server.tool("wp_get_yoast_analysis", "Get Yoast readability and SEO analysis for content.", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+    }, async (rawInput) => runToolWithLimit("wp_get_yoast_analysis", rawInput, async () => {
+        policy.assertAllowedContentType(String(rawInput.content_type));
+        policy.assertYoastPath("/yoast/analysis");
+        return client.getYoastAnalysis(Number(rawInput.id));
+    }));
+    server.tool("wp_update_yoast_metadata", "Update allowlisted Yoast metadata for content.", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+        yoast_meta: z.record(z.unknown()),
+    }, async (rawInput) => runToolWithLimit("wp_update_yoast_metadata", rawInput, async () => {
+        policy.assertAllowedContentType(String(rawInput.content_type));
+        policy.assertYoastPath("/yoast/metadata");
+        policy.assertYoastMetaKeys(rawInput.yoast_meta);
+        return client.updateYoastMetadata(Number(rawInput.id), {
+            content_type: rawInput.content_type,
+            yoast_meta: rawInput.yoast_meta,
+        });
+    }));
+    server.tool("wp_get_yoast_head_preview", "Get Yoast head/meta preview payload.", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+    }, async (rawInput) => runToolWithLimit("wp_get_yoast_head_preview", rawInput, async () => {
+        policy.assertAllowedContentType(String(rawInput.content_type));
+        policy.assertYoastPath("/yoast/head");
+        return client.getYoastHeadPreview(Number(rawInput.id));
+    }));
+    server.tool("wp_get_preview_link", "Return both WordPress preview and signed shareable preview URLs.", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+    }, async (rawInput) => runToolWithLimit("wp_get_preview_link", rawInput, async () => {
+        policy.assertAllowedContentType(String(rawInput.content_type));
+        return client.getPreviewLink(Number(rawInput.id));
+    }));
+    server.tool("wp_get_media", "Get a single media item by ID with full metadata (dimensions, URLs, alt text).", {
+        id: z.number().int().positive(),
+    }, async (rawInput) => runToolWithLimit("wp_get_media", rawInput, async () => {
+        return client.getMedia(Number(rawInput.id));
+    }));
+    server.tool("wp_upload_media_from_url", "Upload media to WordPress by fetching from a URL (server-side download, no base64 needed).", {
+        url: z.string().url(),
+        alt_text: z.string().optional(),
+        title: z.string().optional(),
+        caption: z.string().optional(),
+        description: z.string().optional(),
+    }, async (rawInput) => runToolWithLimit("wp_upload_media_from_url", rawInput, async () => {
+        return client.uploadMediaFromUrl(rawInput);
+    }));
+    server.tool("wp_clone_content", "Clone an existing post or page as a new draft. Copies content, taxonomies, featured image, and Yoast meta.", {
+        id: z.number().int().positive(),
+        content_type: ContentTypeSchema,
+        title: z.string().optional(),
+    }, async (rawInput) => runToolWithLimit("wp_clone_content", rawInput, async () => {
+        policy.assertAllowedContentType(String(rawInput.content_type));
+        return client.cloneContent(Number(rawInput.id), rawInput);
+    }));
+}

package/dist/types/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/errors.js

@@ -0,0 +1,33 @@
+export class ToolError extends Error {
+    code;
+    details;
+    httpStatus;
+    retryable;
+    constructor(code, message, options) {
+        super(message);
+        this.name = "ToolError";
+        this.code = code;
+        this.details = options?.details;
+        this.httpStatus = options?.httpStatus;
+        this.retryable = options?.retryable ?? false;
+    }
+}
+export function toToolError(error) {
+    if (error instanceof ToolError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new ToolError("UNEXPECTED_ERROR", error.message);
+    }
+    return new ToolError("UNEXPECTED_ERROR", "Unexpected unknown error", { details: error });
+}
+export function serializeError(error) {
+    const normalized = toToolError(error);
+    return {
+        code: normalized.code,
+        message: normalized.message,
+        details: normalized.details,
+        http_status: normalized.httpStatus,
+        retryable: normalized.retryable,
+    };
+}

package/dist/utils/logger.js

@@ -0,0 +1,40 @@
+const SENSITIVE_KEYS = new Set([
+    "authorization",
+    "wpAppPassword",
+    "password",
+    "token",
+    "secret",
+    "wp_app_password",
+]);
+function redact(value) {
+    if (!value || typeof value !== "object") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(redact);
+    }
+    const redacted = {};
+    for (const [key, nested] of Object.entries(value)) {
+        if (SENSITIVE_KEYS.has(key)) {
+            redacted[key] = "[REDACTED]";
+            continue;
+        }
+        redacted[key] = redact(nested);
+    }
+    return redacted;
+}
+function write(level, message, context) {
+    const payload = {
+        level,
+        message,
+        timestamp: new Date().toISOString(),
+        context: redact(context),
+    };
+    // Keep logs structured for easy ingestion.
+    console.error(JSON.stringify(payload));
+}
+export const logger = {
+    info: (message, context) => write("info", message, context),
+    warn: (message, context) => write("warn", message, context),
+    error: (message, context) => write("error", message, context),
+};