@wplaunchify/ml-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 1WD LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,220 @@
+# ML MCP Server
+
+**Universal Model Context Protocol (MCP) Server for WordPress and Fluent Suite**
+
+Connect AI assistants like Claude and Cursor directly to your WordPress site with 145 powerful tools for managing content, e-commerce, CRM, community, and more.
+
+---
+
+## 🚀 Features
+
+### **WordPress Core (37 tools)**
+- Content management (posts, pages, custom post types)
+- Taxonomy management (categories, tags, custom taxonomies)
+- User management
+- Media library
+- Comments
+- Plugin management
+
+### **Fluent Suite (79 tools)**
+- **FluentCommunity** (29 tools) - Spaces, posts, members, design, layout
+- **FluentCart** (31 tools) - Products, orders, customers, subscriptions, coupons
+- **FluentCRM** (19 tools) - Contacts, lists, campaigns, tags
+
+### **MinuteLaunch Plugins (29 tools)**
+- **ML Canvas Block** (3 tools) - Surgical HTML editing
+- **ML Image Editor** (8 tools) - AI image generation and editing
+- **ML Media Hub** (18 tools) - Google Images search, Noun Project icons, advanced filters
+
+---
+
+## 📦 Installation
+
+### **Prerequisites**
+- Node.js 18 or higher
+- WordPress site with one of the following plugins:
+  - `ml-mcp` (MinuteLaunch - full feature set)
+  - `fluent-mcp` (FluentMCP - Community/Cart/CRM only)
+
+### **Install via npx (Recommended)**
+
+Add to your MCP client configuration (e.g., Cursor's `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "npx",
+      "args": ["-y", "@wplaunchify/ml-mcp-server"],
+      "env": {
+        "WORDPRESS_API_URL": "https://your-site.com",
+        "WORDPRESS_USERNAME": "your-username",
+        "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
+      }
+    }
+  }
+}
+```
+
+### **Install Globally**
+
+```bash
+npm install -g @wplaunchify/ml-mcp-server
+```
+
+---
+
+## 🔧 Configuration
+
+### **1. WordPress Application Password**
+
+1. Go to **WordPress Admin → Users → Profile**
+2. Scroll to **Application Passwords**
+3. Enter name: "MCP Server"
+4. Click **Add New Application Password**
+5. Copy the generated password (format: `xxxx xxxx xxxx xxxx xxxx xxxx`)
+
+### **2. Environment Variables**
+
+Create a `.env` file or set in your MCP client config:
+
+```bash
+WORDPRESS_API_URL=https://your-site.com
+WORDPRESS_USERNAME=your-username
+WORDPRESS_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
+```
+
+### **3. WordPress Plugin**
+
+Install one of these plugins on your WordPress site:
+
+- **ml-mcp.php** - Full feature set (MinuteLaunch subscribers)
+- **fluent-mcp.php** - Core features only (FluentMCP customers)
+
+The plugin exposes REST API endpoints that the MCP server connects to.
+
+---
+
+## 🛠️ Development
+
+### **Build from Source**
+
+```bash
+git clone https://github.com/wplaunchify/ml-mcp-server.git
+cd ml-mcp-server
+npm install
+npm run build
+```
+
+### **Run in Development Mode**
+
+```bash
+npm run dev
+```
+
+### **Run Tests**
+
+```bash
+npm test
+```
+
+---
+
+## 📖 Usage Examples
+
+### **Create a FluentCommunity Post**
+
+```javascript
+// AI assistant can now do this:
+"Create a post in the General space titled 'Welcome' with content 'Hello everyone!'"
+```
+
+### **Manage FluentCart Products**
+
+```javascript
+// AI assistant can now do this:
+"List all products, then update the price of 'Premium Plan' to $99"
+```
+
+### **Search and Import Images**
+
+```javascript
+// AI assistant can now do this:
+"Search Google Images for 'sunset beach' with large size and creative commons license, then import the first result"
+```
+
+---
+
+## 🏗️ Architecture
+
+```
+AI Assistant (Claude/Cursor)
+         ↓
+   MCP Server (this package)
+         ↓
+   WordPress REST API
+         ↓
+   WordPress Plugin (ml-mcp or fluent-mcp)
+         ↓
+   WordPress Site + Fluent Plugins
+```
+
+The MCP server acts as a bridge, translating AI requests into WordPress REST API calls.
+
+---
+
+## 📋 Tool Categories
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **Content** | 8 | Posts, pages, custom post types |
+| **Taxonomies** | 8 | Categories, tags, custom taxonomies |
+| **Users** | 5 | User management and roles |
+| **Media** | 4 | Media library management |
+| **Comments** | 5 | Comment moderation |
+| **Plugins** | 7 | Plugin management and repository search |
+| **FluentCommunity** | 29 | Social network features |
+| **FluentCart** | 31 | E-commerce management |
+| **FluentCRM** | 19 | Contact and campaign management |
+| **ML Canvas** | 3 | HTML editing |
+| **ML Image Editor** | 8 | AI image generation |
+| **ML Media Hub** | 18 | Image/icon search and import |
+
+---
+
+## 🔐 Security
+
+- Uses WordPress Application Passwords (no plain passwords)
+- REST API authentication via HTTP Basic Auth
+- License validation enforced by WordPress plugin
+- No credentials stored in MCP server
+
+---
+
+## 📄 License
+
+MIT License - Copyright (c) 2025 1WD LLC
+
+---
+
+## 🆘 Support
+
+- **Documentation**: [GitHub Wiki](https://github.com/wplaunchify/ml-mcp-server/wiki)
+- **Issues**: [GitHub Issues](https://github.com/wplaunchify/ml-mcp-server/issues)
+- **Website**: [MinuteLaunch.com](https://minutelaunch.com) | [FluentMCP.com](https://fluentmcp.com)
+
+---
+
+## 🎯 Products
+
+This MCP server powers two products:
+
+- **MinuteLaunch MCP** - Full feature set with ML plugins (recurring subscription)
+- **FluentMCP** - Core WordPress + Fluent Suite only (one-time purchase)
+
+Both use the same MCP server - the WordPress plugin determines which features are available.
+
+---
+
+**Built with ❤️ by 1WD LLC**
+

package/build/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/cli.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// src/cli.ts
+import * as path from 'path';
+import * as fs from 'fs';
+import { spawn } from 'child_process';
+// Function to check if required environment variables are set
+function checkEnvironmentVariables() {
+    const requiredVars = ['WORDPRESS_API_URL', 'WORDPRESS_USERNAME', 'WORDPRESS_APP_PASSWORD'];
+    const missingVars = requiredVars.filter(varName => !process.env[varName]);
+    if (missingVars.length > 0) {
+        console.error(`Missing required environment variables: ${missingVars.join(', ')}`);
+        console.error('Please set these variables in your .env file or environment');
+        process.exit(1);
+    }
+}
+// Main function to run the MCP server
+async function main() {
+    console.log('Starting WordPress MCP Server...');
+    // Check for .env file in current directory
+    const envPath = path.join(process.cwd(), '.env');
+    if (!fs.existsSync(envPath)) {
+        console.warn('No .env file found in current directory.');
+        console.warn('Make sure your WordPress credentials are set in your environment variables.');
+    }
+    checkEnvironmentVariables();
+    // Start the server
+    const serverPath = path.join(__dirname, 'server.js');
+    const serverProcess = spawn('node', [serverPath], {
+        stdio: 'inherit',
+        env: process.env
+    });
+    // Handle server process events
+    serverProcess.on('close', (code) => {
+        if (code !== 0) {
+            console.error(`Server process exited with code ${code}`);
+            process.exit(code || 1);
+        }
+        process.exit(0);
+    });
+    // Forward termination signals to the child process
+    ['SIGINT', 'SIGTERM'].forEach(signal => {
+        process.on(signal, () => {
+            // Fix: Convert string signal to number for kill method
+            serverProcess.kill();
+        });
+    });
+}
+// Run the main function
+main().catch(error => {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+});

package/build/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/server.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// src/server.ts
+import * as dotenv from 'dotenv';
+dotenv.config(); // Load environment variables from .env first
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { allTools, toolHandlers } from './tools/index.js';
+import { z } from 'zod';
+// Create MCP server instance
+const server = new McpServer({
+    name: "wordpress",
+    version: "0.0.1"
+}, {
+    capabilities: {
+        tools: allTools.reduce((acc, tool) => {
+            acc[tool.name] = tool;
+            return acc;
+        }, {})
+    }
+});
+// Register each tool from our tools list with its corresponding handler
+let registeredCount = 0;
+for (const tool of allTools) {
+    const handler = toolHandlers[tool.name];
+    if (!handler) {
+        console.error(`⚠️  No handler for tool: ${tool.name}`);
+        continue;
+    }
+    const wrappedHandler = async (args) => {
+        // The handler functions are already typed with their specific parameter types
+        const result = await handler(args);
+        return {
+            content: result.toolResult.content.map((item) => ({
+                ...item,
+                type: "text"
+            })),
+            isError: result.toolResult.isError
+        };
+    };
+    // console.log(`Registering tool: ${tool.name}`);
+    // console.log(`Input schema: ${JSON.stringify(tool.inputSchema)}`);
+    // const zodSchema = z.any().optional();
+    // const jsonSchema = zodToJsonSchema(z.object(tool.inputSchema.properties as z.ZodRawShape));
+    // const schema = z.object(tool.inputSchema as z.ZodRawShape).catchall(z.unknown());
+    // The inputSchema is already in JSON Schema format with properties
+    // server.tool(tool.name, tool.inputSchema.shape, wrappedHandler);
+    // const zodSchema = z.any().optional();
+    // const jsonSchema = zodToJsonSchema(z.object(tool.inputSchema.properties as z.ZodRawShape));
+    // const parsedSchema = z.any().optional().parse(jsonSchema);
+    const zodSchema = z.object(tool.inputSchema.properties);
+    server.tool(tool.name, zodSchema.shape, wrappedHandler);
+    registeredCount++;
+}
+console.error(`✅ Registered ${registeredCount} of ${allTools.length} tools`);
+async function main() {
+    const { logToFile } = await import('./wordpress.js');
+    logToFile('Starting WordPress MCP server...');
+    if (!process.env.WORDPRESS_API_URL) {
+        logToFile('Missing required environment variables. Please check your .env file.');
+        process.exit(1);
+    }
+    try {
+        logToFile('Initializing WordPress client...');
+        const { initWordPress } = await import('./wordpress.js');
+        await initWordPress();
+        logToFile('WordPress client initialized successfully.');
+        logToFile('Setting up server transport...');
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        logToFile('WordPress MCP Server running on stdio');
+    }
+    catch (error) {
+        logToFile(`Failed to initialize server: ${error}`);
+        process.exit(1);
+    }
+}
+// Handle process signals and errors
+process.on('SIGTERM', () => {
+    console.log('Received SIGTERM signal, shutting down...');
+    process.exit(0);
+});
+process.on('SIGINT', () => {
+    console.log('Received SIGINT signal, shutting down...');
+    process.exit(0);
+});
+process.on('uncaughtException', (error) => {
+    console.error('Uncaught exception:', error);
+    process.exit(1);
+});
+process.on('unhandledRejection', (error) => {
+    console.error('Unhandled rejection:', error);
+    process.exit(1);
+});
+main().catch((error) => {
+    console.error('Startup error:', error);
+    process.exit(1);
+});

package/build/tools/comments.d.ts

@@ -0,0 +1,212 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+declare const listCommentsSchema: z.ZodObject<{
+    page: z.ZodOptional<z.ZodNumber>;
+    per_page: z.ZodOptional<z.ZodNumber>;
+    search: z.ZodOptional<z.ZodString>;
+    after: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodArray<z.ZodNumber, "many">]>>;
+    author_email: z.ZodOptional<z.ZodString>;
+    author_exclude: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    post: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodOptional<z.ZodEnum<["approve", "hold", "spam", "trash"]>>;
+    type: z.ZodOptional<z.ZodString>;
+    orderby: z.ZodOptional<z.ZodEnum<["date", "date_gmt", "id", "include", "post", "parent", "type"]>>;
+    order: z.ZodOptional<z.ZodEnum<["asc", "desc"]>>;
+}, "strip", z.ZodTypeAny, {
+    post?: number | undefined;
+    page?: number | undefined;
+    per_page?: number | undefined;
+    search?: string | undefined;
+    status?: "approve" | "hold" | "spam" | "trash" | undefined;
+    type?: string | undefined;
+    author?: number | number[] | undefined;
+    orderby?: "post" | "type" | "date" | "parent" | "id" | "include" | "date_gmt" | undefined;
+    order?: "asc" | "desc" | undefined;
+    after?: string | undefined;
+    author_email?: string | undefined;
+    author_exclude?: number[] | undefined;
+}, {
+    post?: number | undefined;
+    page?: number | undefined;
+    per_page?: number | undefined;
+    search?: string | undefined;
+    status?: "approve" | "hold" | "spam" | "trash" | undefined;
+    type?: string | undefined;
+    author?: number | number[] | undefined;
+    orderby?: "post" | "type" | "date" | "parent" | "id" | "include" | "date_gmt" | undefined;
+    order?: "asc" | "desc" | undefined;
+    after?: string | undefined;
+    author_email?: string | undefined;
+    author_exclude?: number[] | undefined;
+}>;
+declare const getCommentSchema: z.ZodObject<{
+    id: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    id: number;
+}, {
+    id: number;
+}>;
+declare const createCommentSchema: z.ZodObject<{
+    post: z.ZodNumber;
+    author: z.ZodOptional<z.ZodNumber>;
+    author_name: z.ZodOptional<z.ZodString>;
+    author_email: z.ZodOptional<z.ZodString>;
+    author_url: z.ZodOptional<z.ZodString>;
+    content: z.ZodString;
+    parent: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodOptional<z.ZodEnum<["approve", "hold"]>>;
+}, "strict", z.ZodTypeAny, {
+    post: number;
+    content: string;
+    status?: "approve" | "hold" | undefined;
+    author?: number | undefined;
+    parent?: number | undefined;
+    author_email?: string | undefined;
+    author_name?: string | undefined;
+    author_url?: string | undefined;
+}, {
+    post: number;
+    content: string;
+    status?: "approve" | "hold" | undefined;
+    author?: number | undefined;
+    parent?: number | undefined;
+    author_email?: string | undefined;
+    author_name?: string | undefined;
+    author_url?: string | undefined;
+}>;
+declare const updateCommentSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    post: z.ZodOptional<z.ZodNumber>;
+    author: z.ZodOptional<z.ZodNumber>;
+    author_name: z.ZodOptional<z.ZodString>;
+    author_email: z.ZodOptional<z.ZodString>;
+    author_url: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodString>;
+    parent: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodOptional<z.ZodEnum<["approve", "hold", "spam", "trash"]>>;
+}, "strict", z.ZodTypeAny, {
+    id: number;
+    post?: number | undefined;
+    status?: "approve" | "hold" | "spam" | "trash" | undefined;
+    author?: number | undefined;
+    parent?: number | undefined;
+    content?: string | undefined;
+    author_email?: string | undefined;
+    author_name?: string | undefined;
+    author_url?: string | undefined;
+}, {
+    id: number;
+    post?: number | undefined;
+    status?: "approve" | "hold" | "spam" | "trash" | undefined;
+    author?: number | undefined;
+    parent?: number | undefined;
+    content?: string | undefined;
+    author_email?: string | undefined;
+    author_name?: string | undefined;
+    author_url?: string | undefined;
+}>;
+declare const deleteCommentSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    force: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    id: number;
+    force?: boolean | undefined;
+}, {
+    id: number;
+    force?: boolean | undefined;
+}>;
+type ListCommentsParams = z.infer<typeof listCommentsSchema>;
+type GetCommentParams = z.infer<typeof getCommentSchema>;
+type CreateCommentParams = z.infer<typeof createCommentSchema>;
+type UpdateCommentParams = z.infer<typeof updateCommentSchema>;
+type DeleteCommentParams = z.infer<typeof deleteCommentSchema>;
+export declare const commentTools: Tool[];
+export declare const commentHandlers: {
+    list_comments: (params: ListCommentsParams) => Promise<{
+        toolResult: {
+            content: {
+                type: string;
+                text: string;
+            }[];
+            isError?: undefined;
+        };
+    } | {
+        toolResult: {
+            isError: boolean;
+            content: {
+                type: string;
+                text: string;
+            }[];
+        };
+    }>;
+    get_comment: (params: GetCommentParams) => Promise<{
+        toolResult: {
+            content: {
+                type: string;
+                text: string;
+            }[];
+            isError?: undefined;
+        };
+    } | {
+        toolResult: {
+            isError: boolean;
+            content: {
+                type: string;
+                text: string;
+            }[];
+        };
+    }>;
+    create_comment: (params: CreateCommentParams) => Promise<{
+        toolResult: {
+            content: {
+                type: string;
+                text: string;
+            }[];
+            isError?: undefined;
+        };
+    } | {
+        toolResult: {
+            isError: boolean;
+            content: {
+                type: string;
+                text: string;
+            }[];
+        };
+    }>;
+    update_comment: (params: UpdateCommentParams) => Promise<{
+        toolResult: {
+            content: {
+                type: string;
+                text: string;
+            }[];
+            isError?: undefined;
+        };
+    } | {
+        toolResult: {
+            isError: boolean;
+            content: {
+                type: string;
+                text: string;
+            }[];
+        };
+    }>;
+    delete_comment: (params: DeleteCommentParams) => Promise<{
+        toolResult: {
+            content: {
+                type: string;
+                text: string;
+            }[];
+            isError?: undefined;
+        };
+    } | {
+        toolResult: {
+            isError: boolean;
+            content: {
+                type: string;
+                text: string;
+            }[];
+        };
+    }>;
+};
+export {};