@websamurai/mcp-wp-remote 1.0.1

package/README.md

@@ -0,0 +1,173 @@
+# @samuraiwp/mcp-wp-remote
+
+A STDIO bridge for connecting to WordPress sites via the Model Context Protocol (MCP). This package enables communication between MCP clients and WordPress installations running the SamuraiWP plugin.
+
+## Overview
+
+`mcp-wp-remote` acts as a bridge between MCP clients and WordPress REST API endpoints. It reads JSON-RPC requests from STDIN, forwards them to a WordPress site's MCP endpoint, and returns responses via STDOUT.
+
+## Installation
+
+```bash
+npm install -g @samuraiwp/mcp-wp-remote
+```
+
+Or use directly with npx:
+
+```bash
+npx @samuraiwp/mcp-wp-remote <url> <api-key>
+```
+
+## Requirements
+
+- Node.js (ES modules support required)
+- WordPress site with SamuraiWP plugin installed
+- Valid API key from your WordPress installation
+
+## Usage
+
+### Command Line
+
+```bash
+mcp-wp-remote <url> <api-key>
+```
+
+**Parameters:**
+- `<url>` - Your WordPress site URL (e.g., `https://example.com`)
+- `<api-key>` - API key for authentication (Bearer token)
+
+The endpoint path `/wp-json/samur-ai/v1/mcp` is automatically appended to the URL if not present.
+
+### Example
+
+```bash
+mcp-wp-remote https://mysite.com my-secret-api-key
+```
+
+Or with the full endpoint:
+
+```bash
+mcp-wp-remote https://mysite.com/wp-json/samur-ai/v1/mcp my-secret-api-key
+```
+
+### As MCP Server Configuration
+
+Add to your MCP client configuration (e.g., Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "mcp-wp-remote",
+      "args": ["https://yoursite.com", "your-api-key"]
+    }
+  }
+}
+```
+
+## How It Works
+
+1. Accepts JSON-RPC 2.0 formatted messages via STDIN
+2. Authenticates with WordPress using Bearer token authorization
+3. Forwards requests to the WordPress MCP endpoint
+4. Returns responses via STDOUT in JSON-RPC 2.0 format
+
+### Communication Flow
+
+```
+MCP Client → STDIN → mcp-wp-remote → WordPress REST API
+           ← STDOUT ←              ←
+```
+
+## JSON-RPC Protocol
+
+The bridge expects and returns JSON-RPC 2.0 formatted messages:
+
+**Request:**
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "method_name",
+  "params": {},
+  "id": 1
+}
+```
+
+**Response (Success):**
+```json
+{
+  "jsonrpc": "2.0",
+  "result": {},
+  "id": 1
+}
+```
+
+**Response (Error):**
+```json
+{
+  "jsonrpc": "2.0",
+  "error": {
+    "code": -32000,
+    "message": "Error description"
+  },
+  "id": 1
+}
+```
+
+## Error Handling
+
+The bridge handles various error scenarios:
+
+- **Invalid URL**: Exits with code 1 if URL is malformed
+- **HTTP Errors**: Returns JSON-RPC error with HTTP status code
+- **Network Errors**: Returns JSON-RPC error with code -32000
+- **Invalid Arguments**: Shows usage message and exits
+
+## Features
+
+- Automatic endpoint path normalization
+- Bearer token authentication
+- Multi-line JSON input support
+- Graceful shutdown handling (SIGINT, SIGTERM)
+- JSON-RPC 2.0 compliant error responses
+
+## WordPress Setup
+
+1. Install the SamuraiWP plugin on your WordPress site
+2. Generate an API key in the plugin settings
+3. Ensure the REST API endpoint is accessible at `/wp-json/samur-ai/v1/mcp`
+
+## Development
+
+```bash
+# Clone repository
+git clone <repository-url>
+
+# Install dependencies (if any)
+npm install
+
+# Run locally
+node index.js https://example.com your-api-key
+```
+
+## License
+
+MIT
+
+## Keywords
+
+- MCP (Model Context Protocol)
+- WordPress
+- JSON-RPC
+- STDIO Bridge
+- REST API
+
+## Author
+
+SamuraiWP Team
+
+## Support
+
+For issues and questions:
+- WordPress Plugin: [SamuraiWP](https://samuraiwp.com)
+- GitHub Issues: Report issues in the repository

package/index.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+import { createInterface } from 'readline';
+
+// Parse command line arguments
+const args = process.argv.slice( 2 );
+
+if ( args.length < 2 ) {
+	console.error( 'Usage: mcp-wp-remote <url> <api-key>' );
+	process.exit( 1 );
+}
+
+let url = args[ 0 ];
+const apiKey = args[ 1 ];
+if( args[ 2 ] ) {
+	/// use the third argument as api key if provided to create a tunnel for remote access to dev/internal sites
+	remoteapi = args[ 2 ];
+}
+
+// Add the endpoint path if not present
+const endpoint = '/wp-json/samur-ai/v1/mcp';
+if ( ! url.endsWith( endpoint ) ) {
+	url = url.replace( /\/$/, '' ) + endpoint;
+}
+
+// Validate URL
+try {
+	new URL( url );
+} catch ( error ) {
+	console.error( 'Invalid URL provided:', url );
+	process.exit( 1 );
+}
+
+// Create readline interface for STDIO
+const rl = createInterface( {
+	input: process.stdin,
+	output: process.stdout,
+	terminal: false
+} );
+
+// Buffer for accumulating input lines
+let inputBuffer = '';
+console.log( JSON.stringify( {
+	jsonrpc: "2.0",
+	method: "notifications/message",
+	params: {
+		level: "info",
+		logger: "stdio",
+		data: {
+			message: "Welcome to the SamuraiWP MCP Remote Client!",
+		}
+	}
+} ) );
+
+// Process each line from STDIN
+rl.on( 'line', async ( line ) => {
+	inputBuffer += line;
+
+	// Try to parse as JSON
+	try {
+		const jsonInput = JSON.parse( inputBuffer );
+		inputBuffer = ''; // Reset buffer on successful parse
+
+		// Send JSON-RPC request to endpoint
+		try {
+			let body = {
+				jsonrpc: '2.0',
+				method: jsonInput.method,
+				params: jsonInput.params || {},
+			};
+			const response = await fetch( url, {
+				method: 'POST',
+				headers: {
+					'Content-Type': 'application/json',
+					'Authorization': `Bearer ${ apiKey }`
+				},
+				body: JSON.stringify( body )
+			} );
+
+			if ( ! response.ok ) {
+				const errorText = await response.text();
+				console.error( JSON.stringify( {
+					jsonrpc: '2.0',
+					error: {
+						code: response.status,
+						message: `HTTP ${ response.status }: ${ errorText }`
+					},
+					id: jsonInput.id
+				} ) );
+				return;
+			}
+
+			const result = await response.json();
+			if( result && result.jsonrpc && result.result ) {
+				let out = {
+					jsonrpc: '2.0',
+					result: result.result,
+					id: jsonInput.id
+				}
+				console.log( JSON.stringify( out ) );
+			} else {
+				const errorText = await response.text();
+				console.error( JSON.stringify( {
+					jsonrpc: '2.0',
+					error: {
+						code: response.status,
+						message: `HTTP ${ response.status }: ${ errorText }`
+					},
+					id: jsonInput.id
+				} ) );
+				return;
+			}
+
+		} catch ( fetchError ) {
+			console.error( JSON.stringify( {
+				jsonrpc: '2.0',
+				error: {
+					code: -32000,
+					message: `Network error: ${ fetchError.message }`
+				},
+				id: jsonInput.id
+			} ) );
+		}
+
+	} catch ( parseError ) {
+		// Not valid JSON yet, continue accumulating
+		// This allows for multi-line JSON input
+	}
+} );
+
+rl.on( 'close', () => {
+	process.exit( 0 );
+} );
+
+// Handle process termination
+process.on( 'SIGINT', () => {
+	process.exit( 0 );
+} );
+
+process.on( 'SIGTERM', () => {
+	process.exit( 0 );
+} );

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@websamurai/mcp-wp-remote",
+  "version": "1.0.1",
+  "description": "STDIO to WordPress JSON-RPC bridge for MCP protocol",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "bin": {
+    "mcp-wp-remote": "index.js"
+  },
+  "keywords": [
+    "mcp",
+    "wordpress",
+    "json-rpc",
+    "stdio"
+  ],
+  "author": "Kiera Howe",
+  "license": "MIT",
+  "devDependencies": {},
+  "dependencies": {}
+}