fix(qa): SEO API Bridge fixes, transport type corrections, README improvements

- Fix SEO API Bridge branding, meta keys, route namespaces, GET auth
- Create WordPress.org-compatible readme.txt
- Fix transport types across all docs (streamableHttp/http, not sse)
- Add WordPress Plugin Requirements section to README

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
airano
2026-02-18 19:42:32 +03:30
parent 809dc264af
commit 91979ee18d
9 changed files with 178 additions and 55 deletions

View File

@@ -12,7 +12,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
cp env.example .env # Copy and fill in credentials cp env.example .env # Copy and fill in credentials
pip install -e ".[dev]" # Install with dev deps pip install -e ".[dev]" # Install with dev deps
python server.py # Run (stdio) or: python server.py # Run (stdio) or:
python server.py --transport sse --port 8000 # Run (HTTP) python server.py --transport streamable-http --port 8000 # Run (HTTP)
``` ```
## Build & Development Commands ## Build & Development Commands
@@ -24,8 +24,8 @@ pip install -e ".[dev]"
# Run server (stdio transport for Claude Desktop) # Run server (stdio transport for Claude Desktop)
python server.py python server.py
# Run server (SSE/HTTP transport for testing) # Run server (HTTP transport for testing)
python server.py --transport sse --port 8000 python server.py --transport streamable-http --port 8000
# Run all tests # Run all tests
pytest pytest

View File

@@ -20,7 +20,7 @@ pytest # Verify setup
```bash ```bash
python server.py # stdio (Claude Desktop) python server.py # stdio (Claude Desktop)
python server.py --transport sse --port 8000 # HTTP (testing) python server.py --transport streamable-http --port 8000 # HTTP (testing)
``` ```
### Code Style ### Code Style

View File

@@ -10,7 +10,7 @@ Connect your sites, stores, repos, and databases — manage them all through Cla
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-3776ab.svg)](https://www.python.org/) [![Python 3.11+](https://img.shields.io/badge/python-3.11+-3776ab.svg)](https://www.python.org/)
[![PyPI](https://img.shields.io/pypi/v/mcphub-server.svg)](https://pypi.org/project/mcphub-server/) [![PyPI](https://img.shields.io/pypi/v/mcphub-server.svg)](https://pypi.org/project/mcphub-server/)
[![Docker](https://img.shields.io/docker/v/airano/mcphub?label=docker)](https://hub.docker.com/r/airano/mcphub) [![Docker](https://img.shields.io/docker/v/airano/mcphub?label=docker)](https://hub.docker.com/r/airano/mcphub)
[![Tests: 289 passing](https://img.shields.io/badge/tests-289%20passing-brightgreen.svg)]() [![Tests: 290 passing](https://img.shields.io/badge/tests-290%20passing-brightgreen.svg)]()
[![Tools: 596](https://img.shields.io/badge/tools-596-orange.svg)]() [![Tools: 596](https://img.shields.io/badge/tools-596-orange.svg)]()
[![CI](https://github.com/airano-ir/mcphub/actions/workflows/ci.yml/badge.svg)](https://github.com/airano-ir/mcphub/actions/workflows/ci.yml) [![CI](https://github.com/airano-ir/mcphub/actions/workflows/ci.yml/badge.svg)](https://github.com/airano-ir/mcphub/actions/workflows/ci.yml)
@@ -91,7 +91,7 @@ cd mcphub
pip install -e . pip install -e .
cp env.example .env cp env.example .env
# Edit .env with your site credentials # Edit .env with your site credentials
python server.py --transport sse --port 8000 python server.py --transport streamable-http --port 8000
``` ```
### Verify It Works ### Verify It Works
@@ -112,7 +112,7 @@ You should see the login page. Use your `MASTER_API_KEY` to log in.
Add site credentials to `.env`: Add site credentials to `.env`:
```bash ```bash
# Master API Key (required) # Master API Key (recommended — auto-generates temp key if omitted)
MASTER_API_KEY=your-secure-key-here MASTER_API_KEY=your-secure-key-here
# WordPress Site # WordPress Site
@@ -135,6 +135,10 @@ GITEA_REPO1_ALIAS=mygitea
### Connect Your AI Client ### Connect Your AI Client
All MCP clients use **Bearer token** authentication: `Authorization: Bearer YOUR_API_KEY`
> Use a plugin-specific endpoint (e.g., `/wordpress/mcp`) instead of `/mcp` to reduce tool count and save tokens. See [Architecture](#architecture) below.
<details> <details>
<summary><b>Claude Desktop</b></summary> <summary><b>Claude Desktop</b></summary>
@@ -143,10 +147,11 @@ Add to `claude_desktop_config.json`:
```json ```json
{ {
"mcpServers": { "mcpServers": {
"mcphub": { "mcphub-wordpress": {
"url": "https://your-server:8000/mcp", "type": "streamableHttp",
"url": "http://your-server:8000/wordpress/mcp",
"headers": { "headers": {
"Authorization": "Bearer YOUR_MASTER_API_KEY" "Authorization": "Bearer YOUR_API_KEY"
} }
} }
} }
@@ -163,11 +168,11 @@ Add to `.mcp.json` in your project:
```json ```json
{ {
"mcpServers": { "mcpServers": {
"mcphub": { "mcphub-wordpress": {
"type": "sse", "type": "http",
"url": "https://your-server:8000/mcp", "url": "http://your-server:8000/wordpress/mcp",
"headers": { "headers": {
"Authorization": "Bearer YOUR_MASTER_API_KEY" "Authorization": "Bearer YOUR_API_KEY"
} }
} }
} }
@@ -181,9 +186,9 @@ Add to `.mcp.json` in your project:
Go to **Settings > MCP Servers > Add Server**: Go to **Settings > MCP Servers > Add Server**:
- **Name**: MCP Hub - **Name**: MCP Hub WordPress
- **URL**: `https://your-server:8000/mcp` - **URL**: `http://your-server:8000/wordpress/mcp`
- **Headers**: `Authorization: Bearer YOUR_MASTER_API_KEY` - **Headers**: `Authorization: Bearer YOUR_API_KEY`
</details> </details>
@@ -195,11 +200,11 @@ Add to `.vscode/mcp.json`:
```json ```json
{ {
"servers": { "servers": {
"mcphub": { "mcphub-wordpress": {
"type": "sse", "type": "http",
"url": "https://your-server:8000/mcp", "url": "http://your-server:8000/wordpress/mcp",
"headers": { "headers": {
"Authorization": "Bearer YOUR_MASTER_API_KEY" "Authorization": "Bearer YOUR_API_KEY"
} }
} }
} }
@@ -219,6 +224,8 @@ MCP Hub supports **Open Dynamic Client Registration** (RFC 7591). ChatGPT can au
</details> </details>
> **Transport types**: Use `"type": "streamableHttp"` for Claude Desktop and `"type": "http"` for VS Code/Claude Code. Using `"type": "sse"` will cause `400 Bad Request` errors.
--- ---
## Architecture ## Architecture
@@ -237,7 +244,13 @@ MCP Hub supports **Open Dynamic Client Registration** (RFC 7591). ChatGPT can au
/project/{alias}/mcp → Per-project endpoint (auto-injects site) /project/{alias}/mcp → Per-project endpoint (auto-injects site)
``` ```
**Multi-endpoint architecture**: Give each team member or AI agent access to only the tools they need. **Recommendation**: Use plugin-specific endpoints instead of `/mcp` (596 tools) to minimize token usage.
| Endpoint | Use Case | Tools |
|----------|----------|------:|
| `/project/{alias}/mcp` | Single-site workflow (recommended) | 22-100 |
| `/{plugin}/mcp` | Multi-site management | 23-101 |
| `/mcp` | Admin & discovery only | 596 |
### Security ### Security
@@ -249,6 +262,28 @@ MCP Hub supports **Open Dynamic Client Registration** (RFC 7591). ChatGPT can au
> **Compatibility Note**: MCP Hub requires FastMCP 2.x (`>=2.14.0,<3.0.0`). FastMCP 3.0 introduced breaking changes and is not yet supported. If you install dependencies manually, ensure you don't upgrade to FastMCP 3.x. > **Compatibility Note**: MCP Hub requires FastMCP 2.x (`>=2.14.0,<3.0.0`). FastMCP 3.0 introduced breaking changes and is not yet supported. If you install dependencies manually, ensure you don't upgrade to FastMCP 3.x.
### WordPress Plugin Requirements
Some MCP Hub tools require companion WordPress plugins:
| Tools | Requirement |
|-------|-------------|
| SEO tools (`wordpress_get_post_seo`, etc.) | [SEO API Bridge](wordpress-plugin/seo-api-bridge/) + Rank Math or Yoast SEO |
| WP-CLI tools (15 tools: `wp_cache_*`, `wp_db_*`, etc.) | Docker socket + `CONTAINER` env var |
| WordPress Advanced database/system tools | Docker socket + `CONTAINER` env var |
| WooCommerce tools | WooCommerce plugin (separate `WOOCOMMERCE_` config) |
**Docker socket** is needed for WP-CLI and WordPress Advanced system tools. Add to your docker-compose:
```yaml
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
WORDPRESS_SITE1_CONTAINER: your-wp-container-name
```
Without Docker socket, WP-CLI tools return "not available" but all REST API tools work normally.
--- ---
## Documentation ## Documentation
@@ -272,14 +307,14 @@ MCP Hub supports **Open Dynamic Client Registration** (RFC 7591). ChatGPT can au
# Install with dev dependencies # Install with dev dependencies
pip install -e ".[dev]" pip install -e ".[dev]"
# Run tests (289 tests) # Run tests (290 tests)
pytest pytest
# Format and lint # Format and lint
black . && ruff check --fix . black . && ruff check --fix .
# Run server locally # Run server locally
python server.py --transport sse --port 8000 python server.py --transport streamable-http --port 8000
``` ```
--- ---

View File

@@ -70,7 +70,7 @@ cd mcphub
pip install -e . pip install -e .
cp env.example .env cp env.example .env
# Edit .env with your site credentials # Edit .env with your site credentials
python server.py --transport sse --port 8000 python server.py --transport streamable-http --port 8000
``` ```
### Option 4: Automated Setup Scripts ### Option 4: Automated Setup Scripts
@@ -305,7 +305,7 @@ DIRECTUS_SITE1_ALIAS=my-directus # Recommended
### SSE Transport (for remote AI clients) ### SSE Transport (for remote AI clients)
```bash ```bash
python server.py --transport sse --port 8000 python server.py --transport streamable-http --port 8000
``` ```
### Stdio Transport (for Claude Desktop local) ### Stdio Transport (for Claude Desktop local)

View File

@@ -9,8 +9,8 @@ Usage:
# With stdio transport (Claude Desktop) # With stdio transport (Claude Desktop)
python server.py python server.py
# With SSE transport (HTTP server) # With HTTP transport (Streamable HTTP server)
python server.py --transport sse --port 8000 python server.py --transport streamable-http --port 8000
Environment Variables: Environment Variables:
MASTER_API_KEY: Master API key for authentication MASTER_API_KEY: Master API key for authentication

View File

@@ -19,7 +19,7 @@ Benefits:
- Scalable architecture - Scalable architecture
Usage: Usage:
python server_multi.py --transport sse --port 8000 python server_multi.py --transport streamable-http --port 8000
""" """
import inspect import inspect

View File

@@ -31,7 +31,7 @@ SEO API Bridge is a comprehensive WordPress plugin that exposes Rank Math SEO an
#### Core Fields #### Core Fields
- `rank_math_focus_keyword` - Focus keyword - `rank_math_focus_keyword` - Focus keyword
- `rank_math_seo_title` - Meta title - `rank_math_title` - Meta title
- `rank_math_description` - Meta description - `rank_math_description` - Meta description
- `rank_math_additional_keywords` - Additional keywords - `rank_math_additional_keywords` - Additional keywords
@@ -94,7 +94,7 @@ SEO API Bridge is a comprehensive WordPress plugin that exposes Rank Math SEO an
2. Go to WordPress Admin → Plugins 2. Go to WordPress Admin → Plugins
3. Find "SEO API Bridge" and click "Activate" 3. Find "SEO API Bridge" and click "Activate"
### Method 3: WP-CLI (Recommended for Coolify) ### Method 3: WP-CLI
```bash ```bash
# Via SSH to your WordPress container # Via SSH to your WordPress container
@@ -107,48 +107,48 @@ wp plugin activate seo-api-bridge
### Status Endpoint ### Status Endpoint
**GET** `/wp-json/seo-bridge/v1/status` **GET** `/wp-json/seo-api-bridge/v1/status`
Check plugin status and detected SEO plugins. Check plugin status and detected SEO plugins.
```bash ```bash
curl https://yoursite.com/wp-json/seo-bridge/v1/status curl https://yoursite.com/wp-json/seo-api-bridge/v1/status
``` ```
### Post SEO Endpoints ### Post SEO Endpoints
**GET** `/wp-json/seo-bridge/v1/posts/{id}/seo` **GET** `/wp-json/seo-api-bridge/v1/posts/{id}/seo`
Get SEO metadata for a post. Get SEO metadata for a post.
**POST** `/wp-json/seo-bridge/v1/posts/{id}/seo` **POST** `/wp-json/seo-api-bridge/v1/posts/{id}/seo`
Update SEO metadata for a post. Update SEO metadata for a post.
```bash ```bash
curl -X POST https://yoursite.com/wp-json/seo-bridge/v1/posts/123/seo \ curl -X POST https://yoursite.com/wp-json/seo-api-bridge/v1/posts/123/seo \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"focus_keyword": "wordpress", "seo_title": "My Title"}' -d '{"focus_keyword": "wordpress", "seo_title": "My Title"}'
``` ```
### Page SEO Endpoints ### Page SEO Endpoints
**GET** `/wp-json/seo-bridge/v1/pages/{id}/seo` **GET** `/wp-json/seo-api-bridge/v1/pages/{id}/seo`
**POST** `/wp-json/seo-bridge/v1/pages/{id}/seo` **POST** `/wp-json/seo-api-bridge/v1/pages/{id}/seo`
### Product SEO Endpoints (WooCommerce) ### Product SEO Endpoints (WooCommerce)
**GET** `/wp-json/seo-bridge/v1/products/{id}/seo` **GET** `/wp-json/seo-api-bridge/v1/products/{id}/seo`
Get SEO metadata for a WooCommerce product. Get SEO metadata for a WooCommerce product.
**POST** `/wp-json/seo-bridge/v1/products/{id}/seo` **POST** `/wp-json/seo-api-bridge/v1/products/{id}/seo`
Update SEO metadata for a WooCommerce product. Update SEO metadata for a WooCommerce product.
```bash ```bash
curl -X POST https://yoursite.com/wp-json/seo-bridge/v1/products/1217/seo \ curl -X POST https://yoursite.com/wp-json/seo-api-bridge/v1/products/1217/seo \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"focus_keyword": "product keyword", "seo_title": "Product Title"}' -d '{"focus_keyword": "product keyword", "seo_title": "Product Title"}'
``` ```
@@ -190,7 +190,7 @@ await mcp.wordpress_update_product_seo({
"title": {"rendered": "My Post"}, "title": {"rendered": "My Post"},
"meta": { "meta": {
"rank_math_focus_keyword": "wordpress seo", "rank_math_focus_keyword": "wordpress seo",
"rank_math_seo_title": "Complete SEO Guide", "rank_math_title": "Complete SEO Guide",
"rank_math_description": "Learn WordPress SEO best practices..." "rank_math_description": "Learn WordPress SEO best practices..."
} }
} }
@@ -210,7 +210,7 @@ GET /wp-json/wp/v2/posts/{id}
"title": {"rendered": "My Post"}, "title": {"rendered": "My Post"},
"meta": { "meta": {
"rank_math_focus_keyword": "wordpress seo", "rank_math_focus_keyword": "wordpress seo",
"rank_math_seo_title": "Complete WordPress SEO Guide", "rank_math_title": "Complete WordPress SEO Guide",
"rank_math_description": "Learn how to optimize your WordPress site...", "rank_math_description": "Learn how to optimize your WordPress site...",
"rank_math_facebook_title": "SEO Guide for Facebook", "rank_math_facebook_title": "SEO Guide for Facebook",
"rank_math_twitter_card_type": "summary_large_image" "rank_math_twitter_card_type": "summary_large_image"
@@ -229,7 +229,7 @@ Content-Type: application/json
{ {
"meta": { "meta": {
"rank_math_focus_keyword": "wordpress optimization", "rank_math_focus_keyword": "wordpress optimization",
"rank_math_seo_title": "WordPress Optimization Tips", "rank_math_title": "WordPress Optimization Tips",
"rank_math_description": "Discover the best practices for WordPress optimization" "rank_math_description": "Discover the best practices for WordPress optimization"
} }
} }
@@ -255,7 +255,7 @@ POST /wp-json/wp/v2/products/{id}
## Usage with MCP Server ## Usage with MCP Server
This plugin is designed to work with the [Coolify Projects MCP Server](https://github.com/your-repo/mcphub). This plugin is designed to work with the [MCP Hub](https://github.com/airano-ir/mcphub).
### Example MCP Tool Usage ### Example MCP Tool Usage
@@ -397,8 +397,8 @@ curl -X GET "https://your-site.com/wp-json/wp/v2/posts/1" \
## Support ## Support
For issues related to: For issues related to:
- **This plugin:** [GitHub Issues](https://github.com/your-repo/mcphub/issues) - **This plugin:** [GitHub Issues](https://github.com/airano-ir/mcphub/issues)
- **MCP Server:** [MCP Server Documentation](https://github.com/your-repo/mcphub) - **MCP Server:** [MCP Server Documentation](https://github.com/airano-ir/mcphub)
- **Rank Math SEO:** [Rank Math Support](https://rankmath.com/support/) - **Rank Math SEO:** [Rank Math Support](https://rankmath.com/support/)
- **Yoast SEO:** [Yoast Support](https://yoast.com/help/) - **Yoast SEO:** [Yoast Support](https://yoast.com/help/)
@@ -425,4 +425,4 @@ MIT License - See LICENSE file for details
## Credits ## Credits
Developed for use with Coolify Projects MCP Server to enable AI-powered SEO content management. Developed for use with MCP Hub to enable AI-powered SEO content management.

View File

@@ -0,0 +1,82 @@
=== SEO API Bridge ===
Contributors: airano
Tags: seo, rest-api, rank-math, yoast, mcp
Requires at least: 5.0
Tested up to: 6.7
Requires PHP: 7.4
Stable tag: 1.3.0
License: MIT
License URI: https://opensource.org/licenses/MIT
Exposes Rank Math SEO and Yoast SEO meta fields via WordPress REST API for use with MCP servers and AI agents.
== Description ==
SEO API Bridge is a WordPress plugin that exposes Rank Math SEO and Yoast SEO meta fields via dedicated REST API endpoints. This enables MCP servers, AI agents, and other applications to read and write SEO metadata programmatically for posts, pages, and WooCommerce products.
**Features:**
* **Rank Math SEO Support** — Full access to all Rank Math meta fields
* **Yoast SEO Support** — Full access to all Yoast SEO meta fields
* **WooCommerce Compatible** — Works with product post types
* **Secure** — Requires WordPress Application Password and edit_posts capability
* **Auto-Detection** — Automatically detects which SEO plugin is active
* **Status Endpoint** — Dedicated API endpoint for plugin and SEO detection
* **Zero Configuration** — Works out of the box after activation
**REST API Endpoints:**
* `GET/POST /wp-json/seo-api-bridge/v1/posts/{id}/seo` — Post SEO data
* `GET/POST /wp-json/seo-api-bridge/v1/pages/{id}/seo` — Page SEO data
* `GET/POST /wp-json/seo-api-bridge/v1/products/{id}/seo` — Product SEO data (WooCommerce)
* `GET /wp-json/seo-api-bridge/v1/status` — Plugin status and SEO detection
**Designed for [MCP Hub](https://github.com/airano-ir/mcphub)** — the AI-native management hub for WordPress and self-hosted services.
== Installation ==
1. Upload the `seo-api-bridge` folder to `/wp-content/plugins/`
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Ensure either Rank Math SEO or Yoast SEO is active
4. The REST API endpoints are now available
== Frequently Asked Questions ==
= Which SEO plugins are supported? =
Rank Math SEO and Yoast SEO. The plugin auto-detects which one is active.
= Does it work with WooCommerce? =
Yes. Product SEO endpoints are available when WooCommerce is active.
= How is authentication handled? =
All endpoints require WordPress Application Password authentication and the `edit_posts` capability. POST requests require the same capability.
= Can I use this without MCP Hub? =
Yes. The REST API endpoints work with any application that can make HTTP requests with proper WordPress authentication.
== Changelog ==
= 1.3.0 =
* Added REST API endpoints for posts, pages, and products (GET/POST operations)
* Added authentication requirement for all endpoints
* Fixed rank_math_title meta key registration
= 1.2.0 =
* Enhanced WooCommerce product support
* Improved MariaDB compatibility
= 1.1.0 =
* Added status endpoint for plugin detection
* Improved error handling
= 1.0.0 =
* Initial release with Rank Math and Yoast SEO support
== Upgrade Notice ==
= 1.3.0 =
GET endpoints now require authentication (edit_posts capability). Update your API clients if needed.

View File

@@ -1,11 +1,11 @@
<?php <?php
/** /**
* Plugin Name: SEO API Bridge * Plugin Name: SEO API Bridge
* Plugin URI: https://github.com/your-repo/seo-api-bridge * Plugin URI: https://github.com/airano-ir/mcphub
* Description: Exposes Rank Math SEO and Yoast SEO meta fields via WordPress REST API for use with MCP servers and AI agents. Supports posts, pages, and WooCommerce products with full CRUD operations. * Description: Exposes Rank Math SEO and Yoast SEO meta fields via WordPress REST API for use with MCP servers and AI agents. Supports posts, pages, and WooCommerce products with full CRUD operations.
* Version: 1.3.0 * Version: 1.3.0
* Author: MCP Coolify Projects * Author: MCP Hub
* Author URI: https://github.com/your-repo * Author URI: https://github.com/airano-ir
* License: MIT * License: MIT
* Requires at least: 5.0 * Requires at least: 5.0
* Requires PHP: 7.4 * Requires PHP: 7.4
@@ -70,7 +70,9 @@ class SEO_API_Bridge {
[ [
'methods' => 'GET', 'methods' => 'GET',
'callback' => [$this, 'get_post_seo'], 'callback' => [$this, 'get_post_seo'],
'permission_callback' => '__return_true', 'permission_callback' => function() {
return current_user_can('edit_posts');
},
'args' => [ 'args' => [
'id' => [ 'id' => [
'validate_callback' => function($param) { 'validate_callback' => function($param) {
@@ -100,7 +102,9 @@ class SEO_API_Bridge {
[ [
'methods' => 'GET', 'methods' => 'GET',
'callback' => [$this, 'get_page_seo'], 'callback' => [$this, 'get_page_seo'],
'permission_callback' => '__return_true', 'permission_callback' => function() {
return current_user_can('edit_posts');
},
'args' => [ 'args' => [
'id' => [ 'id' => [
'validate_callback' => function($param) { 'validate_callback' => function($param) {
@@ -130,7 +134,9 @@ class SEO_API_Bridge {
[ [
'methods' => 'GET', 'methods' => 'GET',
'callback' => [$this, 'get_product_seo'], 'callback' => [$this, 'get_product_seo'],
'permission_callback' => '__return_true', 'permission_callback' => function() {
return current_user_can('edit_posts');
},
'args' => [ 'args' => [
'id' => [ 'id' => [
'validate_callback' => function($param) { 'validate_callback' => function($param) {
@@ -246,7 +252,7 @@ class SEO_API_Bridge {
'description' => 'Rank Math focus keyword', 'description' => 'Rank Math focus keyword',
'single' => true, 'single' => true,
], ],
'rank_math_seo_title' => [ 'rank_math_title' => [
'type' => 'string', 'type' => 'string',
'description' => 'Rank Math SEO title (meta title)', 'description' => 'Rank Math SEO title (meta title)',
'single' => true, 'single' => true,