@pkagentic/mcp 1.4.0

package/README.md

@@ -0,0 +1,68 @@
+# PK Agent MCP Server Installation
+
+This MCP server provides tools for AI agents (like Claude Desktop) to interact with the **PK Agentic** WordPress plugin via its External Agent API.
+
+**Compatible with PK Agentic 1.8+**
+
+## Prerequisites
+
+1.  **Node.js** (v18 or newer recommended).
+2.  **PK Agentic Plugin** installed and configured on your WordPress site.
+3.  **Agent API Enabled** in WordPress (**PK Agentic -> Settings -> Agent API**).
+4.  **API Key Generated** in same settings page (**PK Agentic -> Settings -> Agent API**).
+5.  **Agent Email** known (the email address assigned to the key during generation).
+
+> **Note:** The API Key and Email are required for the MCP server to authenticate with your WordPress site.
+
+## Setup Instructions
+
+### 1. Install Dependencies
+
+Navigate to the `pk-mcp` directory and install dependencies:
+
+```bash
+cd pk-mcp
+npm install
+```
+
+### 2. Add to Claude Desktop (or other MCP Client)
+
+To use this with Claude Desktop, edit your `claude_desktop_config.json`:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+Add the following configuration, making sure to provide your actual WordPress site details in the `env` section:
+
+```json
+{
+  "mcpServers": {
+    "pk-agent": {
+      "command": "node",
+      "args": [
+        "/Users/YOUR_USER/path/to/pk-agentic/pk-mcp/dist/index.js"
+      ],
+      "env": {
+        "PK_AGENT_API_URL": "https://your-wordpress-site.com/wp-json/pk-agentic/v1/agent/",
+        "PK_AGENT_KEY": "pk_agent_your_generated_key_here",
+        "PK_AGENT_EMAIL": "your-email@example.com",
+        "GEMINI_API_KEY": "your_gemini_api_key_here",
+        "GEMINI_MODEL": "gemini-3-pro-image-preview"
+      }
+    }
+  }
+}
+```
+
+> **Note:** Make sure to use the absolute path to `dist/index.js`. After updating the config, restart Claude Desktop to activate the tools.
+
+## Configuration Parameters
+
+When configuring this MCP server in your AI agent, you will need the following parameters from your WordPress site:
+
+| Parameter | Environment Variable | Description |
+|-----------|----------------------|-------------|
+| **API URL** | `PK_AGENT_API_URL` | The URL of the PK Agentic API (e.g., `https://example.com/wp-json/pk-agentic/v1/agent/`). |
+| **Agent Key** | `PK_AGENT_KEY` | The secret key generated in **PK Agentic -> Security -> Agent Keys**. Starts with `pk_agent_`. |
+| **Agent Email** | `PK_AGENT_EMAIL` | The email address associated with the Agent Key. Required for authentication. |
+| **Gemini API Key** | `GEMINI_API_KEY` | **Optional.** Required for the `generate_image` tool. Get one at [aistudio.google.com](https://aistudio.google.com/). |
+| **Gemini Model** | `GEMINI_MODEL` | **Optional.** The model ID to use for image generation. Defaults to `gemini-3-pro-image-preview`. |

package/dist/handlers/image-generation.d.ts

@@ -0,0 +1,14 @@
+import { GenerateImageArgs } from "../types.js";
+export declare class ImageGenerationApi {
+    private client;
+    private modelId;
+    constructor(apiKey?: string, modelId?: string);
+    generateImage(args: GenerateImageArgs): Promise<{
+        success: boolean;
+        message: string;
+        file_path: string;
+        image_name: string;
+        page_name: string;
+        model: string;
+    }>;
+}

package/dist/handlers/image-generation.js

@@ -0,0 +1,77 @@
+import fs from "fs";
+import path from "path";
+import { GoogleGenAI } from "@google/genai";
+export class ImageGenerationApi {
+    client;
+    modelId;
+    constructor(apiKey, modelId) {
+        this.modelId = modelId || "gemini-3-pro-image-preview";
+        if (apiKey) {
+            this.client = new GoogleGenAI({ apiKey, apiVersion: "v1beta" });
+        }
+    }
+    async generateImage(args) {
+        if (!this.client) {
+            throw new Error("GEMINI_API_KEY is not set. Please set it in your MCP configuration (e.g., in claude_desktop_config.json or .env file) and restart the server.");
+        }
+        const { prompt_path, image_name, page_name, aspect_ratio = "1:1" } = args;
+        // 1. Read prompt from file
+        if (!fs.existsSync(prompt_path)) {
+            throw new Error(`Prompt file not found at ${prompt_path}. Please create it first.`);
+        }
+        const prompt = fs.readFileSync(prompt_path, "utf-8").trim();
+        try {
+            // 2. Call Gemini SDK (Nano Banana Pro)
+            // Gemini 3 models support native image generation via generateContent
+            const response = await this.client.models.generateContent({
+                model: this.modelId,
+                contents: prompt,
+                config: {
+                    imageConfig: { aspectRatio: aspect_ratio },
+                    responseModalities: ["IMAGE"]
+                }
+            });
+            if (!response.candidates || response.candidates.length === 0) {
+                throw new Error("No candidates returned from Gemini API.");
+            }
+            const parts = response.candidates[0].content?.parts;
+            if (!parts) {
+                throw new Error("No parts found in the response. The model might have been blocked by safety filters.");
+            }
+            let base64Data;
+            let mimeType = "image/png";
+            for (const part of parts) {
+                if (part.inlineData) {
+                    base64Data = part.inlineData.data;
+                    mimeType = part.inlineData.mimeType || "image/png";
+                    break;
+                }
+            }
+            if (!base64Data) {
+                throw new Error("No image data found in the response parts. The model might have returned text instead.");
+            }
+            const extension = mimeType.split("/")[1] || "png";
+            // 3. Save image to folder
+            const outputDir = path.join("workspace", "generated-images");
+            if (!fs.existsSync(outputDir)) {
+                fs.mkdirSync(outputDir, { recursive: true });
+            }
+            const fileName = `${image_name}.${extension}`;
+            const outputPath = path.join(outputDir, fileName);
+            fs.writeFileSync(outputPath, Buffer.from(base64Data, "base64"));
+            return {
+                success: true,
+                message: `Image generated using Nano Banana Pro and saved to ${outputPath}`,
+                file_path: outputPath,
+                image_name: fileName,
+                page_name: page_name,
+                model: this.modelId
+            };
+        }
+        catch (error) {
+            const errorMessage = error.message || "Unknown error occurred during image generation.";
+            throw new Error(`Gemini SDK Error: ${errorMessage}`);
+        }
+    }
+}
+//# sourceMappingURL=image-generation.js.map

package/dist/handlers/image-generation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-generation.js","sourceRoot":"","sources":["../../src/handlers/image-generation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,MAAM,OAAO,kBAAkB;IACrB,MAAM,CAA0B;IAChC,OAAO,CAAS;IAExB,YAAY,MAAe,EAAE,OAAgB;QAC3C,IAAI,CAAC,OAAO,GAAG,OAAO,IAAI,4BAA4B,CAAC;QACvD,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,MAAM,GAAG,IAAI,WAAW,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC;QAClE,CAAC;IACH,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,IAAuB;QACzC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,+IAA+I,CAAC,CAAC;QACnK,CAAC;QAED,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,GAAG,KAAK,EAAE,GAAG,IAAI,CAAC;QAE1E,2BAA2B;QAC3B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,4BAA4B,WAAW,2BAA2B,CAAC,CAAC;QACtF,CAAC;QACD,MAAM,MAAM,GAAG,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QAE5D,IAAI,CAAC;YACH,uCAAuC;YACvC,sEAAsE;YACtE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC;gBACxD,KAAK,EAAE,IAAI,CAAC,OAAO;gBACnB,QAAQ,EAAE,MAAM;gBAChB,MAAM,EAAE;oBACN,WAAW,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE;oBAC1C,kBAAkB,EAAE,CAAC,OAAO,CAAC;iBAC9B;aACF,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,UAAU,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC7D,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;YAC7D,CAAC;YAED,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC;YACpD,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CAAC,sFAAsF,CAAC,CAAC;YAC1G,CAAC;YAED,IAAI,UAA8B,CAAC;YACnC,IAAI,QAAQ,GAAG,WAAW,CAAC;YAE3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;oBACpB,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;oBAClC,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,QAAQ,IAAI,WAAW,CAAC;oBACnD,MAAM;gBACR,CAAC;YACH,CAAC;YAED,IAAI,CAAC,UAAU,EAAE,CAAC;gBAChB,MAAM,IAAI,KAAK,CAAC,wFAAwF,CAAC,CAAC;YAC5G,CAAC;YAED,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;YAElD,0BAA0B;YAC1B,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,kBAAkB,CAAC,CAAC;YAC7D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC9B,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/C,CAAC;YAED,MAAM,QAAQ,GAAG,GAAG,UAAU,IAAI,SAAS,EAAE,CAAC;YAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YAElD,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;YAEhE,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,sDAAsD,UAAU,EAAE;gBAC3E,SAAS,EAAE,UAAU;gBACrB,UAAU,EAAE,QAAQ;gBACpB,SAAS,EAAE,SAAS;gBACpB,KAAK,EAAE,IAAI,CAAC,OAAO;aACpB,CAAC;QACJ,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,IAAI,iDAAiD,CAAC;YACxF,MAAM,IAAI,KAAK,CAAC,qBAAqB,YAAY,EAAE,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;CACF"}

package/dist/handlers/index.d.ts

@@ -0,0 +1,5 @@
+export { PKAgentApi } from "./pk-agent.js";
+export { UtilityApi } from "./utility.js";
+export { WebCrawlerApi } from "./web-crawler.js";
+export { ImageGenerationApi } from "./image-generation.js";
+export { TailwindApi } from "./tailwind.js";

package/dist/handlers/index.js

@@ -0,0 +1,6 @@
+export { PKAgentApi } from "./pk-agent.js";
+export { UtilityApi } from "./utility.js";
+export { WebCrawlerApi } from "./web-crawler.js";
+export { ImageGenerationApi } from "./image-generation.js";
+export { TailwindApi } from "./tailwind.js";
+//# sourceMappingURL=index.js.map

package/dist/handlers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/handlers/pk-agent.d.ts

@@ -0,0 +1,156 @@
+import { SyncArgs, GetFileArgs, GetFilesBatchArgs, SaveItemArgs, PublishItemArgs, CreateItemArgs, ToggleItemArgs, UpdateConditionsArgs, UpdateMetadataArgs, DeleteItemArgs, GetRevisionsArgs, RestoreRevisionArgs, SearchContentsArgs, MarkContentEditArgs, SearchMediaArgs, UploadMediaArgs, GetImageSrcsetArgs, ListLibrariesArgs, CreateLibraryArgs, UpdateLibraryArgs, DeleteLibraryArgs, SearchLibrariesArgs, GetLibraryArgs, CdnDownloadLibraryArgs, SaveLibraryFilesArgs, RestoreLibraryBackupArgs, UpdateLibraryConditionsArgs, ToggleLibraryArgs, ToggleLibraryLockArgs } from "../types.js";
+export declare class PKAgentApi {
+    private axiosInstance;
+    constructor(baseURL: string, key: string, email: string);
+    /**
+     * Ensure a directory exists and write JSON content to a file.
+     */
+    private writeJsonFile;
+    /**
+     * Write downloaded code fields (html/css/js) from an API item to the
+     * correct workspace sub-directory derived from the item's virtual_path.
+     *
+     * Layout:
+     *   template → workspace/templates/{slug}/{slug}.php  .css  .js
+     *   script   → workspace/scripts/{slug}/{slug}.php    .css  .js
+     *   content  → workspace/contents/{vp_parts}/{slug}.html .css .js
+     *
+     * Returns relative paths of every file that was written.
+     */
+    private writeItemFiles;
+    private readFileContent;
+    getSiteInfo(): Promise<{
+        success: boolean;
+        message: string;
+        file_written: string;
+        summary: {
+            site_name: any;
+            site_url: any;
+            plugin_version: any;
+            wordpress_version: any;
+            php_version: any;
+            batch_file_limit: any;
+            css_framework: any;
+            timezone: any;
+            language: any;
+            theme: any;
+            permissions: any;
+            menu_locations: any;
+        };
+    }>;
+    syncItems(args: SyncArgs): Promise<{
+        success: boolean;
+        message: string;
+        file_written: string;
+        summary: {
+            page: any;
+            per_page: any;
+            total_items: any;
+            total_pages: any;
+            has_more: any;
+            items_on_page: {
+                templates: any;
+                scripts: any;
+                content: any;
+            };
+        };
+    }>;
+    getFile(args: GetFileArgs): Promise<{
+        success: boolean;
+        partial_download: boolean;
+        message: string;
+        metadata: {
+            id: any;
+            type: any;
+            slug: any;
+            virtual_path: any;
+            download_type: any;
+            total_lines: any;
+            line_range: any;
+            is_locked?: undefined;
+            status?: undefined;
+            description?: undefined;
+            document_content?: undefined;
+        };
+        content: {
+            js?: any;
+            css?: any;
+            html?: any;
+        };
+        files_written?: undefined;
+        files_count?: undefined;
+    } | {
+        success: boolean;
+        message: string;
+        files_written: string[];
+        files_count: number;
+        metadata: {
+            id: any;
+            type: any;
+            slug: any;
+            virtual_path: any;
+            is_locked: any;
+            status: any;
+            download_type: any;
+            total_lines: any;
+            description: any;
+            document_content: any;
+            line_range?: undefined;
+        };
+        partial_download?: undefined;
+        content?: undefined;
+    }>;
+    getFilesBatch(args: GetFilesBatchArgs): Promise<{
+        success: boolean;
+        message: string;
+        items_downloaded: number;
+        total_files_written: number;
+        items: any[];
+    }>;
+    getTemplateInfo(id: number): Promise<any>;
+    getScriptInfo(id: number): Promise<any>;
+    getContentInfo(id: number): Promise<any>;
+    saveItem(args: SaveItemArgs): Promise<any>;
+    publishItem(args: PublishItemArgs): Promise<any>;
+    createItem(args: CreateItemArgs): Promise<any>;
+    toggleItem(args: ToggleItemArgs): Promise<any>;
+    updateConditions(args: UpdateConditionsArgs): Promise<any>;
+    updateMetadata(args: UpdateMetadataArgs): Promise<any>;
+    deleteItem(args: DeleteItemArgs): Promise<any>;
+    getRevisions(args: GetRevisionsArgs): Promise<any>;
+    restoreRevision(args: RestoreRevisionArgs): Promise<any>;
+    searchContents(args: SearchContentsArgs): Promise<any>;
+    markContentEdit(args: MarkContentEditArgs): Promise<any>;
+    searchMedia(args: SearchMediaArgs): Promise<any>;
+    uploadMedia(args: UploadMediaArgs): Promise<any>;
+    getImageSrcset(args: GetImageSrcsetArgs): Promise<any>;
+    getAgentGuide(guide: string): Promise<{
+        success: boolean;
+        message: string;
+        guide: string;
+        version: string;
+        file_written: string;
+        absolute_path: string;
+    }>;
+    getRoles(): Promise<any>;
+    getTailwindConfig(): Promise<any>;
+    updateTailwindConfig(args: any): Promise<any>;
+    listLibraries(args: ListLibrariesArgs): Promise<{
+        success: boolean;
+        message: string;
+        file_written: string;
+        data: any;
+        pagination: any;
+    }>;
+    createLibrary(args: CreateLibraryArgs): Promise<any>;
+    updateLibrary(args: UpdateLibraryArgs): Promise<any>;
+    deleteLibrary(args: DeleteLibraryArgs): Promise<any>;
+    searchLibraries(args: SearchLibrariesArgs): Promise<any>;
+    getLibrary(args: GetLibraryArgs): Promise<any>;
+    cdnDownloadLibrary(args: CdnDownloadLibraryArgs): Promise<any>;
+    saveLibraryFiles(args: SaveLibraryFilesArgs): Promise<any>;
+    restoreLibraryBackup(args: RestoreLibraryBackupArgs): Promise<any>;
+    updateLibraryConditions(args: UpdateLibraryConditionsArgs): Promise<any>;
+    toggleLibrary(args: ToggleLibraryArgs): Promise<any>;
+    toggleLibraryLock(args: ToggleLibraryLockArgs): Promise<any>;
+}