@mangerik/wordpress-mcp 0.1.0

package/dist/tools/seo.js

@@ -0,0 +1,269 @@
+import { z } from "zod";
+/**
+ * SEO tools for Yoast SEO and Rank Math.
+ *
+ * Both plugins primarily store SEO data in WordPress post meta. The keys
+ * differ; we expose them through a uniform getter/setter that targets the
+ * right plugin based on a `plugin` argument.
+ *
+ * Yoast also ships REST endpoints under `/yoast/v1/*` for SERP previews,
+ * which we wrap as dedicated tools.
+ */
+// ─── Meta key maps ────────────────────────────────────────────────────────
+const YOAST_KEYS = {
+    title: "_yoast_wpseo_title",
+    description: "_yoast_wpseo_metadesc",
+    focus_keyword: "_yoast_wpseo_focuskw",
+    canonical: "_yoast_wpseo_canonical",
+    noindex: "_yoast_wpseo_meta-robots-noindex", // "0" | "1" | "2"
+    nofollow: "_yoast_wpseo_meta-robots-nofollow", // "0" | "1"
+    og_title: "_yoast_wpseo_opengraph-title",
+    og_description: "_yoast_wpseo_opengraph-description",
+    og_image: "_yoast_wpseo_opengraph-image",
+    twitter_title: "_yoast_wpseo_twitter-title",
+    twitter_description: "_yoast_wpseo_twitter-description",
+    twitter_image: "_yoast_wpseo_twitter-image",
+    schema_type: "_yoast_wpseo_schema_page_type",
+};
+const RANK_MATH_KEYS = {
+    title: "rank_math_title",
+    description: "rank_math_description",
+    focus_keyword: "rank_math_focus_keyword",
+    canonical: "rank_math_canonical_url",
+    robots: "rank_math_robots", // serialized array, e.g. ["index","follow"]
+    og_title: "rank_math_facebook_title",
+    og_description: "rank_math_facebook_description",
+    og_image: "rank_math_facebook_image",
+    twitter_title: "rank_math_twitter_title",
+    twitter_description: "rank_math_twitter_description",
+    twitter_image: "rank_math_twitter_image",
+    schema_type: "rank_math_rich_snippet",
+};
+const PLUGIN = z.enum(["yoast", "rank_math"]);
+const POST_TYPES = ["post", "page"];
+const postTypeEnum = z.enum(POST_TYPES);
+const seoFields = {
+    title: z.string().optional().describe("SEO title tag"),
+    description: z.string().optional().describe("Meta description"),
+    focus_keyword: z.string().optional(),
+    canonical: z.string().url().optional(),
+    noindex: z.boolean().optional(),
+    nofollow: z.boolean().optional(),
+    og_title: z.string().optional(),
+    og_description: z.string().optional(),
+    og_image: z.string().url().optional(),
+    twitter_title: z.string().optional(),
+    twitter_description: z.string().optional(),
+    twitter_image: z.string().url().optional(),
+};
+function pickKeys(plugin) {
+    return plugin === "yoast" ? YOAST_KEYS : RANK_MATH_KEYS;
+}
+/**
+ * Translate friendly SEO fields to plugin-specific meta key/values.
+ * Yoast uses string flags, Rank Math uses serialized robots array.
+ */
+function buildMetaPayload(plugin, input) {
+    const keys = pickKeys(plugin);
+    const meta = {};
+    const set = (k, v) => {
+        if (k && v !== undefined && v !== null)
+            meta[k] = v;
+    };
+    set(keys.title, input.title);
+    set(keys.description, input.description);
+    set(keys.focus_keyword, input.focus_keyword);
+    set(keys.canonical, input.canonical);
+    set(keys.og_title, input.og_title);
+    set(keys.og_description, input.og_description);
+    set(keys.og_image, input.og_image);
+    set(keys.twitter_title, input.twitter_title);
+    set(keys.twitter_description, input.twitter_description);
+    set(keys.twitter_image, input.twitter_image);
+    if (plugin === "yoast") {
+        if (input.noindex !== undefined) {
+            // Yoast: "0" default, "1" noindex, "2" index (force)
+            meta[YOAST_KEYS.noindex] = input.noindex ? "1" : "2";
+        }
+        if (input.nofollow !== undefined) {
+            meta[YOAST_KEYS.nofollow] = input.nofollow ? "1" : "0";
+        }
+    }
+    else {
+        // Rank Math stores robots as a serialized array of flags.
+        const flags = [];
+        if (input.noindex !== undefined)
+            flags.push(input.noindex ? "noindex" : "index");
+        if (input.nofollow !== undefined)
+            flags.push(input.nofollow ? "nofollow" : "follow");
+        if (flags.length)
+            meta[RANK_MATH_KEYS.robots] = flags;
+    }
+    return meta;
+}
+/** Reverse of buildMetaPayload: read raw meta back into friendly fields. */
+function readMetaPayload(plugin, meta) {
+    if (!meta)
+        return {};
+    const keys = pickKeys(plugin);
+    const out = {};
+    const get = (k) => (k ? meta[k] : undefined);
+    out.title = get(keys.title);
+    out.description = get(keys.description);
+    out.focus_keyword = get(keys.focus_keyword);
+    out.canonical = get(keys.canonical);
+    out.og_title = get(keys.og_title);
+    out.og_description = get(keys.og_description);
+    out.og_image = get(keys.og_image);
+    out.twitter_title = get(keys.twitter_title);
+    out.twitter_description = get(keys.twitter_description);
+    out.twitter_image = get(keys.twitter_image);
+    if (plugin === "yoast") {
+        const ni = get(YOAST_KEYS.noindex);
+        out.noindex = ni === "1" ? true : ni === "2" ? false : undefined;
+        const nf = get(YOAST_KEYS.nofollow);
+        out.nofollow = nf === "1" ? true : nf === "0" ? false : undefined;
+    }
+    else {
+        const robots = get(RANK_MATH_KEYS.robots);
+        if (Array.isArray(robots)) {
+            out.noindex = robots.includes("noindex") || undefined;
+            out.nofollow = robots.includes("nofollow") || undefined;
+        }
+    }
+    return out;
+}
+function routeFor(postType) {
+    if (postType === "post")
+        return "wp/v2/posts";
+    if (postType === "page")
+        return "wp/v2/pages";
+    return `wp/v2/${postType}`;
+}
+export const seoTools = (wp) => [
+    // ── Get/set SEO meta on a post or page ──────────────────────────────────
+    {
+        name: "seo_get_meta",
+        title: "Get SEO meta (Yoast / Rank Math)",
+        description: "Read SEO meta (title, description, focus keyword, robots, OG, Twitter) " +
+            "for a post or page. Specify which SEO plugin you use.",
+        inputSchema: {
+            plugin: PLUGIN,
+            post_type: postTypeEnum.default("post"),
+            id: z.number().int().positive(),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async (input) => {
+            const { plugin, post_type, id } = input;
+            const route = routeFor(post_type);
+            const data = (await wp.get(route, id, { context: "edit", _fields: "id,slug,meta" }));
+            return {
+                plugin,
+                post_id: data?.id,
+                slug: data?.slug,
+                seo: readMetaPayload(plugin, data?.meta),
+                raw_meta: data?.meta,
+            };
+        },
+    },
+    {
+        name: "seo_set_meta",
+        title: "Set SEO meta (Yoast / Rank Math)",
+        description: "Write SEO meta (title, description, focus keyword, robots, OG, Twitter) " +
+            "to a post or page via the chosen SEO plugin's meta keys. " +
+            "NOTE: the meta keys must be exposed via REST (Yoast does this automatically; " +
+            "Rank Math may require enabling REST API in plugin settings).",
+        inputSchema: {
+            plugin: PLUGIN,
+            post_type: postTypeEnum.default("post"),
+            id: z.number().int().positive(),
+            ...seoFields,
+        },
+        annotations: { openWorldHint: true },
+        handler: async (input) => {
+            const { plugin, post_type, id, ...fields } = input;
+            const meta = buildMetaPayload(plugin, fields);
+            if (Object.keys(meta).length === 0) {
+                return { updated: false, reason: "no SEO fields provided" };
+            }
+            const route = routeFor(post_type);
+            const result = (await wp.update(route, id, { meta }));
+            return {
+                plugin,
+                post_id: result.id,
+                applied_keys: Object.keys(meta),
+                seo: readMetaPayload(plugin, result.meta),
+            };
+        },
+    },
+    // ── Yoast-specific endpoints ────────────────────────────────────────────
+    {
+        name: "yoast_get_head",
+        title: "Yoast: get rendered SEO head HTML",
+        description: "Use Yoast's /yoast/v1/get_head endpoint to fetch the rendered <head> HTML " +
+            "for a given URL — useful for previewing what search engines will see.",
+        inputSchema: {
+            url: z.string().url(),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async (input) => {
+            const { url } = input;
+            const r = await wp.list("yoast/v1/get_head", { url });
+            return { yoast_head: r.data };
+        },
+    },
+    {
+        name: "yoast_indexable_for_post",
+        title: "Yoast: get post 'indexable' (computed SEO snapshot)",
+        description: "Read the Yoast indexable record (title, description, canonical, breadcrumbs) " +
+            "for a post via /yoast/v1/indexable.",
+        inputSchema: { id: z.number().int().positive() },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async (input) => {
+            const { id } = input;
+            // Yoast exposes /yoast/v1/indexable?object_id=ID&object_type=post
+            const r = await wp.list("yoast/v1/indexable", {
+                object_id: id,
+                object_type: "post",
+            });
+            return { indexable: r.data };
+        },
+    },
+    // ── Rank Math: redirections (very common use case) ─────────────────────
+    {
+        name: "rankmath_list_redirections",
+        title: "Rank Math: list redirections",
+        description: "List Rank Math redirection rules (requires Rank Math Pro REST API enabled).",
+        inputSchema: {
+            page: z.number().int().positive().optional(),
+            per_page: z.number().int().min(1).max(100).optional(),
+            search: z.string().optional(),
+            status: z.enum(["any", "active", "inactive"]).optional(),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async (input) => {
+            const r = await wp.list("rankmath/v1/rm/redirections", input);
+            return { redirections: r.data, total: r.total };
+        },
+    },
+    {
+        name: "rankmath_create_redirection",
+        title: "Rank Math: create redirection",
+        description: "Create a redirection rule.",
+        inputSchema: {
+            sources: z
+                .array(z.object({
+                pattern: z.string(),
+                comparison: z.enum(["exact", "contains", "start", "end", "regex"]).optional(),
+                ignore: z.array(z.enum(["case", "query"])).optional(),
+            }))
+                .min(1),
+            url_to: z.string(),
+            header_code: z.enum(["301", "302", "307", "410", "451"]).optional(),
+            status: z.enum(["active", "inactive"]).optional(),
+        },
+        annotations: { openWorldHint: true },
+        handler: async (input) => wp.create("rankmath/v1/rm/redirections", input),
+    },
+];
+//# sourceMappingURL=seo.js.map

package/dist/tools/site.d.ts

@@ -0,0 +1,4 @@
+import { WordPressClient } from "../wordpress-client.js";
+import type { ToolDef } from "../types.js";
+export declare const siteTools: (wp: WordPressClient) => ToolDef[];
+//# sourceMappingURL=site.d.ts.map

package/dist/tools/site.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+export const siteTools = (wp) => [
+    {
+        name: "wp_site_info",
+        title: "Site info",
+        description: "Get the REST API root index: site name, description, namespaces, and discovered routes. " +
+            "Use this to detect WooCommerce, Yoast, or other plugins exposing REST endpoints.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async () => {
+            const info = (await wp.siteInfo());
+            // Trim noisy fields to save tokens.
+            const slim = {
+                name: info.name,
+                description: info.description,
+                url: info.url,
+                home: info.home,
+                gmt_offset: info.gmt_offset,
+                timezone_string: info.timezone_string,
+                site_logo: info.site_logo,
+                site_icon_url: info.site_icon_url,
+                namespaces: info.namespaces,
+                authentication: info.authentication,
+            };
+            return slim;
+        },
+    },
+    {
+        name: "wp_get_settings",
+        title: "Get site settings",
+        description: "Get WordPress site settings (requires manage_options).",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async () => wp.settings(),
+    },
+    {
+        name: "wp_update_settings",
+        title: "Update site settings",
+        description: "Update site settings such as title, description, timezone, or default category. " +
+            "Use with caution.",
+        inputSchema: {
+            title: z.string().optional(),
+            description: z.string().optional(),
+            url: z.string().url().optional(),
+            email: z.string().email().optional(),
+            timezone: z.string().optional(),
+            date_format: z.string().optional(),
+            time_format: z.string().optional(),
+            start_of_week: z.number().int().min(0).max(6).optional(),
+            language: z.string().optional(),
+            use_smilies: z.boolean().optional(),
+            default_category: z.number().int().optional(),
+            default_post_format: z.string().optional(),
+            posts_per_page: z.number().int().positive().optional(),
+            default_ping_status: z.enum(["open", "closed"]).optional(),
+            default_comment_status: z.enum(["open", "closed"]).optional(),
+        },
+        annotations: { openWorldHint: true },
+        handler: async (input) => wp.updateSettings(input),
+    },
+    {
+        name: "wp_get_post_types",
+        title: "List post types",
+        description: "List registered post types (post, page, attachment, plus any custom post types).",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async () => wp.types(),
+    },
+    {
+        name: "wp_get_taxonomies",
+        title: "List taxonomies",
+        description: "List registered taxonomies (category, post_tag, plus custom taxonomies).",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async () => wp.taxonomies(),
+    },
+    {
+        name: "wp_search",
+        title: "Search content",
+        description: "Universal search across posts, pages, and other public content via /wp/v2/search.",
+        inputSchema: {
+            query: z.string().min(1),
+            type: z.enum(["post", "term", "post-format"]).optional(),
+            subtype: z.string().optional().describe("Post type slug or taxonomy slug"),
+            page: z.number().int().positive().optional(),
+            per_page: z.number().int().min(1).max(100).optional(),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async (input) => {
+            const { query, ...rest } = input;
+            const result = await wp.search(query, rest);
+            return { results: result.data, total: result.total };
+        },
+    },
+];
+//# sourceMappingURL=site.js.map

package/dist/tools/taxonomy.d.ts

@@ -0,0 +1,4 @@
+import { WordPressClient } from "../wordpress-client.js";
+import type { ToolDef } from "../types.js";
+export declare const taxonomyTools: (wp: WordPressClient) => ToolDef[];
+//# sourceMappingURL=taxonomy.d.ts.map

package/dist/tools/taxonomy.js

@@ -0,0 +1,147 @@
+import { z } from "zod";
+export const taxonomyTools = (wp) => [
+    // ── CATEGORIES ──────────────────────────────────────────────────────────
+    {
+        name: "wp_get_categories",
+        title: "List categories",
+        description: "List WordPress categories.",
+        inputSchema: {
+            page: z.number().int().positive().optional(),
+            per_page: z.number().int().min(1).max(100).optional(),
+            search: z.string().optional(),
+            hide_empty: z.boolean().optional(),
+            parent: z.number().int().optional(),
+            orderby: z.enum(["id", "name", "slug", "count", "term_group"]).optional(),
+            order: z.enum(["asc", "desc"]).optional(),
+            _fields: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async (input) => {
+            const result = await wp.categories.list(input);
+            return { categories: result.data, total: result.total };
+        },
+    },
+    {
+        name: "wp_get_category",
+        title: "Get a category",
+        description: "Get a single category by ID.",
+        inputSchema: { id: z.number().int().positive() },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async (input) => wp.categories.get(input.id),
+    },
+    {
+        name: "wp_create_category",
+        title: "Create a category",
+        description: "Create a new category.",
+        inputSchema: {
+            name: z.string().min(1),
+            slug: z.string().optional(),
+            description: z.string().optional(),
+            parent: z.number().int().optional(),
+        },
+        annotations: { openWorldHint: true },
+        handler: async (input) => wp.categories.create(input),
+    },
+    {
+        name: "wp_update_category",
+        title: "Update a category",
+        description: "Update a category.",
+        inputSchema: {
+            id: z.number().int().positive(),
+            name: z.string().optional(),
+            slug: z.string().optional(),
+            description: z.string().optional(),
+            parent: z.number().int().optional(),
+        },
+        annotations: { openWorldHint: true },
+        handler: async (input) => {
+            const { id, ...data } = input;
+            return wp.categories.update(id, data);
+        },
+    },
+    {
+        name: "wp_delete_category",
+        title: "Delete a category",
+        description: "Delete a category. Categories cannot be trashed; force is required.",
+        inputSchema: {
+            id: z.number().int().positive(),
+            force: z.boolean().optional(),
+        },
+        annotations: { destructiveHint: true, openWorldHint: true },
+        handler: async (input) => {
+            const { id, force = true } = input;
+            return wp.categories.remove(id, force);
+        },
+    },
+    // ── TAGS ────────────────────────────────────────────────────────────────
+    {
+        name: "wp_get_tags",
+        title: "List tags",
+        description: "List WordPress tags.",
+        inputSchema: {
+            page: z.number().int().positive().optional(),
+            per_page: z.number().int().min(1).max(100).optional(),
+            search: z.string().optional(),
+            hide_empty: z.boolean().optional(),
+            orderby: z.enum(["id", "name", "slug", "count"]).optional(),
+            order: z.enum(["asc", "desc"]).optional(),
+            _fields: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async (input) => {
+            const result = await wp.tags.list(input);
+            return { tags: result.data, total: result.total };
+        },
+    },
+    {
+        name: "wp_get_tag",
+        title: "Get a tag",
+        description: "Get a single tag by ID.",
+        inputSchema: { id: z.number().int().positive() },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async (input) => wp.tags.get(input.id),
+    },
+    {
+        name: "wp_create_tag",
+        title: "Create a tag",
+        description: "Create a new tag.",
+        inputSchema: {
+            name: z.string().min(1),
+            slug: z.string().optional(),
+            description: z.string().optional(),
+        },
+        annotations: { openWorldHint: true },
+        handler: async (input) => wp.tags.create(input),
+    },
+    {
+        name: "wp_update_tag",
+        title: "Update a tag",
+        description: "Update a tag.",
+        inputSchema: {
+            id: z.number().int().positive(),
+            name: z.string().optional(),
+            slug: z.string().optional(),
+            description: z.string().optional(),
+        },
+        annotations: { openWorldHint: true },
+        handler: async (input) => {
+            const { id, ...data } = input;
+            return wp.tags.update(id, data);
+        },
+    },
+    {
+        name: "wp_delete_tag",
+        title: "Delete a tag",
+        description: "Delete a tag. Tags cannot be trashed; force is required.",
+        inputSchema: {
+            id: z.number().int().positive(),
+            force: z.boolean().optional(),
+        },
+        annotations: { destructiveHint: true, openWorldHint: true },
+        handler: async (input) => {
+            const { id, force = true } = input;
+            return wp.tags.remove(id, force);
+        },
+    },
+];
+//# sourceMappingURL=taxonomy.js.map

package/dist/tools/users.d.ts

@@ -0,0 +1,4 @@
+import { WordPressClient } from "../wordpress-client.js";
+import type { ToolDef } from "../types.js";
+export declare const userTools: (wp: WordPressClient) => ToolDef[];
+//# sourceMappingURL=users.d.ts.map

package/dist/tools/users.js

@@ -0,0 +1,99 @@
+import { z } from "zod";
+export const userTools = (wp) => [
+    {
+        name: "wp_get_users",
+        title: "List users",
+        description: "List WordPress users.",
+        inputSchema: {
+            page: z.number().int().positive().optional(),
+            per_page: z.number().int().min(1).max(100).optional(),
+            search: z.string().optional(),
+            roles: z.array(z.string()).optional(),
+            orderby: z
+                .enum(["id", "include", "name", "registered_date", "slug", "email", "url"])
+                .optional(),
+            order: z.enum(["asc", "desc"]).optional(),
+            _fields: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async (input) => {
+            const result = await wp.users.list(input);
+            return { users: result.data, total: result.total };
+        },
+    },
+    {
+        name: "wp_get_user",
+        title: "Get a user",
+        description: "Get a single user by ID.",
+        inputSchema: { id: z.number().int().positive() },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async (input) => wp.users.get(input.id),
+    },
+    {
+        name: "wp_get_current_user",
+        title: "Get current user",
+        description: "Get the currently authenticated user (the WP_USERNAME used to start this server).",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+        handler: async () => wp.users.me(),
+    },
+    {
+        name: "wp_create_user",
+        title: "Create a user",
+        description: "Create a new WordPress user. Requires the `create_users` capability.",
+        inputSchema: {
+            username: z.string().min(1),
+            email: z.string().email(),
+            password: z.string().min(8),
+            name: z.string().optional(),
+            first_name: z.string().optional(),
+            last_name: z.string().optional(),
+            url: z.string().url().optional(),
+            description: z.string().optional(),
+            roles: z.array(z.string()).optional(),
+        },
+        annotations: { openWorldHint: true },
+        handler: async (input) => wp.users.create(input),
+    },
+    {
+        name: "wp_update_user",
+        title: "Update a user",
+        description: "Update a user's profile or role.",
+        inputSchema: {
+            id: z.number().int().positive(),
+            email: z.string().email().optional(),
+            name: z.string().optional(),
+            first_name: z.string().optional(),
+            last_name: z.string().optional(),
+            url: z.string().url().optional(),
+            description: z.string().optional(),
+            roles: z.array(z.string()).optional(),
+            password: z.string().min(8).optional(),
+        },
+        annotations: { openWorldHint: true },
+        handler: async (input) => {
+            const { id, ...data } = input;
+            return wp.users.update(id, data);
+        },
+    },
+    {
+        name: "wp_delete_user",
+        title: "Delete a user",
+        description: "Permanently delete a user and reassign their content to another user. " +
+            "Always force-deletes (WP requirement).",
+        inputSchema: {
+            id: z.number().int().positive(),
+            reassign_to: z
+                .number()
+                .int()
+                .positive()
+                .describe("User ID to receive the deleted user's content."),
+        },
+        annotations: { destructiveHint: true, openWorldHint: true },
+        handler: async (input) => {
+            const { id, reassign_to } = input;
+            return wp.users.remove(id, reassign_to);
+        },
+    },
+];
+//# sourceMappingURL=users.js.map

package/dist/tools/woocommerce.d.ts

@@ -0,0 +1,4 @@
+import { WordPressClient } from "../wordpress-client.js";
+import type { ToolDef } from "../types.js";
+export declare const woocommerceTools: (wp: WordPressClient) => ToolDef[];
+//# sourceMappingURL=woocommerce.d.ts.map