atlatl/mcphub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(release): publish preparation — fix docs, update badges, clean configs

Browse Source 
- Rewrite docs/getting-started.md (correct URLs, entry points, tool counts)
- Update README: badges (289 tests, 589 tools, CI), FastMCP note, fix links
- Add PyPI classifiers: License, OS Independent, Console
- Fix community sync false positives in test allowlist
- Clean docker-compose.yaml (remove internal phase references)
- Update tool counts: WordPress 65→67, total 587→589
- Update GitHub URLs to airano-ir/mcphub

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
airano
2026-02-17 10:52:16 +03:30
parent ac30087b57
commit 3707fef56c
13 changed files with 226 additions and 253 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.github/workflows/release.yml vendored
View File

@@ -86,8 +86,8 @@ jobs:
context: . context: .
push: true push: true
tags: | tags: |
mcphub/mcphub:latest airano/mcphub:latest
mcphub/mcphub:${{ steps.version.outputs.VERSION }} airano/mcphub:${{ steps.version.outputs.VERSION }}
platforms: linux/amd64,linux/arm64 platforms: linux/amd64,linux/arm64
github-release: github-release:

6
CHANGELOG.md
View File

@@ -30,7 +30,7 @@ After 2-month hiatus (Dec 2025 - Feb 2026), updated all dependencies and verifie
- All 54 tests now pass (previously 5 were failing) - All 54 tests now pass (previously 5 were failing)
#### Verified #### Verified
- All 587 tools generate correctly - All 589 tools generate correctly
- Middleware API stable (Middleware, MiddlewareContext, get_http_headers) - Middleware API stable (Middleware, MiddlewareContext, get_http_headers)
- 30+ custom routes operational (dashboard + OAuth) - 30+ custom routes operational (dashboard + OAuth)
- Multi-endpoint architecture functional - Multi-endpoint architecture functional
@@ -604,5 +604,5 @@ Initial implementation of WordPress management tools.
--- ---
[1.0.0]: https://github.com/mcphub/mcphub/releases/tag/v1.0.0 [1.0.0]: https://github.com/airano-ir/mcphub/releases/tag/v1.0.0
[Unreleased]: https://github.com/mcphub/mcphub/compare/v1.0.0...HEAD [Unreleased]: https://github.com/airano-ir/mcphub/compare/v1.0.0...HEAD

2
CLAUDE.md
View File

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview ## Project Overview
**MCP Hub** — a Python MCP (Model Context Protocol) server that manages multiple self-hosted projects through a unified plugin architecture. Supports 9 plugin types (WordPress, WooCommerce, WordPress Advanced, Gitea, n8n, Supabase, OpenPanel, Appwrite, Directus) with ~587 tools total. The tool count stays constant regardless of how many sites are configured. **MCP Hub** — a Python MCP (Model Context Protocol) server that manages multiple self-hosted projects through a unified plugin architecture. Supports 9 plugin types (WordPress, WooCommerce, WordPress Advanced, Gitea, n8n, Supabase, OpenPanel, Appwrite, Directus) with ~589 tools total. The tool count stays constant regardless of how many sites are configured.
## Quick Setup ## Quick Setup

2
CONTRIBUTING.md
View File

@@ -9,7 +9,7 @@ Thank you for your interest in contributing to MCP Hub!
**Prerequisites**: Python 3.11+, Docker (optional), Git **Prerequisites**: Python 3.11+, Docker (optional), Git
```bash ```bash
git clone https://github.com/mcphub/mcphub.git git clone https://github.com/airano-ir/mcphub.git
cd mcphub cd mcphub
cp env.example .env cp env.example .env
pip install -e ".[dev]" pip install -e ".[dev]"

29
README.md
View File

@@ -8,8 +8,9 @@ Connect your sites, stores, repos, and databases — manage them all through Cla
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![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/)
[![Tests: 164 passing](https://img.shields.io/badge/tests-164%20passing-brightgreen.svg)]() [![Tests: 289 passing](https://img.shields.io/badge/tests-289%20passing-brightgreen.svg)]()
[![Tools: 587](https://img.shields.io/badge/tools-587-orange.svg)]() [![Tools: 589](https://img.shields.io/badge/tools-589-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)
</div> </div>
@@ -19,7 +20,7 @@ Connect your sites, stores, repos, and databases — manage them all through Cla
WordPress powers 43% of the web. WooCommerce runs 36% of online stores. Yet **no MCP server existed** for managing them through AI — until now. WordPress powers 43% of the web. WooCommerce runs 36% of online stores. Yet **no MCP server existed** for managing them through AI — until now.
MCP Hub is the first and only MCP server that lets you manage WordPress, WooCommerce, and 7 other self-hosted services through any AI assistant. Instead of clicking through dashboards, just tell your AI what to do: MCP Hub is the first MCP server that lets you manage WordPress, WooCommerce, and 7 other self-hosted services through any AI assistant. Instead of clicking through dashboards, just tell your AI what to do:
> *"Update the SEO meta description for all WooCommerce products that don't have one"* > *"Update the SEO meta description for all WooCommerce products that don't have one"*
> >
@@ -33,7 +34,7 @@ MCP Hub is the first and only MCP server that lets you manage WordPress, WooComm
|---------|----------|--------|---------------------|-------------| |---------|----------|--------|---------------------|-------------|
| Multi-site management | Yes | Yes | No | **Yes** | | Multi-site management | Yes | Yes | No | **Yes** |
| AI agent integration | No | No | No | **Native (MCP)** | | AI agent integration | No | No | No | **Native (MCP)** |
| Full WordPress API | Dashboard | Dashboard | Content only | **65 tools** | | Full WordPress API | Dashboard | Dashboard | Content only | **67 tools** |
| WooCommerce management | No | Limited | No | **28 tools** | | WooCommerce management | No | Limited | No | **28 tools** |
| Git/CI management | No | No | No | **56 tools (Gitea)** | | Git/CI management | No | No | No | **56 tools (Gitea)** |
| Automation workflows | No | No | No | **56 tools (n8n)** | | Automation workflows | No | No | No | **56 tools (n8n)** |
@@ -43,11 +44,11 @@ MCP Hub is the first and only MCP server that lets you manage WordPress, WooComm
--- ---
## 587 Tools Across 9 Plugins ## 589 Tools Across 9 Plugins
| Plugin | Tools | What You Can Do | | Plugin | Tools | What You Can Do |
|--------|-------|-----------------| |--------|-------|-----------------|
| **WordPress** | 65 | Posts, pages, media, users, menus, taxonomies, SEO (Rank Math/Yoast) | | **WordPress** | 67 | Posts, pages, media, users, menus, taxonomies, SEO (Rank Math/Yoast) |
| **WooCommerce** | 28 | Products, orders, customers, coupons, reports, shipping | | **WooCommerce** | 28 | Products, orders, customers, coupons, reports, shipping |
| **WordPress Advanced** | 22 | Database ops, bulk operations, WP-CLI, system management | | **WordPress Advanced** | 22 | Database ops, bulk operations, WP-CLI, system management |
| **Gitea** | 56 | Repos, issues, pull requests, releases, webhooks, organizations | | **Gitea** | 56 | Repos, issues, pull requests, releases, webhooks, organizations |
@@ -57,7 +58,7 @@ MCP Hub is the first and only MCP server that lets you manage WordPress, WooComm
| **Appwrite** | 100 | Databases, auth, storage, functions, teams, messaging | | **Appwrite** | 100 | Databases, auth, storage, functions, teams, messaging |
| **Directus** | 100 | Collections, items, users, files, flows, permissions | | **Directus** | 100 | Collections, items, users, files, flows, permissions |
| **System** | 17 | Health monitoring, API keys, project discovery | | **System** | 17 | Health monitoring, API keys, project discovery |
| **Total** | **587** | Constant count — scales to unlimited sites | | **Total** | **589** | Constant count — scales to unlimited sites |
--- ---
@@ -66,7 +67,7 @@ MCP Hub is the first and only MCP server that lets you manage WordPress, WooComm
### Option 1: Docker (Recommended) ### Option 1: Docker (Recommended)
```bash ```bash
git clone https://github.com/mcphub/mcphub.git git clone https://github.com/airano-ir/mcphub.git
cd mcphub cd mcphub
cp env.example .env cp env.example .env
# Edit .env with your site credentials # Edit .env with your site credentials
@@ -76,7 +77,7 @@ docker compose up -d
### Option 2: Python ### Option 2: Python
```bash ```bash
git clone https://github.com/mcphub/mcphub.git git clone https://github.com/airano-ir/mcphub.git
cd mcphub cd mcphub
pip install -e . pip install -e .
cp env.example .env cp env.example .env
@@ -201,9 +202,9 @@ MCP Hub supports **Open Dynamic Client Registration** (RFC 7591). ChatGPT can au
## Architecture ## Architecture
``` ```
/mcp → Admin endpoint (all 587 tools) /mcp → Admin endpoint (all 589 tools)
/system/mcp → System tools only (17 tools) /system/mcp → System tools only (17 tools)
/wordpress/mcp → WordPress tools (65 tools) /wordpress/mcp → WordPress tools (67 tools)
/woocommerce/mcp → WooCommerce tools (28 tools) /woocommerce/mcp → WooCommerce tools (28 tools)
/gitea/mcp → Gitea tools (56 tools) /gitea/mcp → Gitea tools (56 tools)
/n8n/mcp → n8n tools (56 tools) /n8n/mcp → n8n tools (56 tools)
@@ -224,6 +225,8 @@ MCP Hub supports **Open Dynamic Client Registration** (RFC 7591). ChatGPT can au
- **GDPR-compliant audit logging** with automatic sensitive data filtering - **GDPR-compliant audit logging** with automatic sensitive data filtering
- **Web dashboard** with real-time health monitoring (8 pages, EN/FA i18n) - **Web dashboard** with real-time health monitoring (8 pages, EN/FA i18n)
> **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.
--- ---
## Documentation ## Documentation
@@ -235,7 +238,7 @@ MCP Hub supports **Open Dynamic Client Registration** (RFC 7591). ChatGPT can au
| [API Keys Guide](docs/API_KEYS_GUIDE.md) | Per-project API key management | | [API Keys Guide](docs/API_KEYS_GUIDE.md) | Per-project API key management |
| [OAuth Guide](docs/OAUTH_GUIDE.md) | OAuth 2.1 setup for Claude/ChatGPT | | [OAuth Guide](docs/OAUTH_GUIDE.md) | OAuth 2.1 setup for Claude/ChatGPT |
| [Gitea Guide](docs/GITEA_GUIDE.md) | Gitea plugin configuration | | [Gitea Guide](docs/GITEA_GUIDE.md) | Gitea plugin configuration |
| [Deployment Guide](DEPLOYMENT_GUIDE.md) | Docker and Coolify deployment | | [Deployment Guide](docs/DEPLOYMENT_GUIDE.md) | Docker and Coolify deployment |
| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions | | [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
| [Plugin Development](docs/PLUGIN_DEVELOPMENT.md) | Build your own plugin | | [Plugin Development](docs/PLUGIN_DEVELOPMENT.md) | Build your own plugin |
@@ -247,7 +250,7 @@ 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 (164 tests) # Run tests (289 tests)
pytest pytest
# Format and lint # Format and lint

14
docker-compose.yaml
View File

@@ -1,6 +1,5 @@
# =================================== # ===================================
# Coolify Projects MCP Server # MCP Hub — Docker Compose Configuration
# Docker Compose Configuration
# =================================== # ===================================
# #
# Build Pack: Docker Compose # Build Pack: Docker Compose
@@ -35,7 +34,7 @@ services:
- LOG_LEVEL=${LOG_LEVEL:-INFO} - LOG_LEVEL=${LOG_LEVEL:-INFO}
- PYTHONUNBUFFERED=1 - PYTHONUNBUFFERED=1
# === OAuth 2.1 Configuration (Phase B) === # === OAuth 2.1 Configuration ===
# Required for OAuth authentication # Required for OAuth authentication
- OAUTH_JWT_SECRET_KEY=${OAUTH_JWT_SECRET_KEY} - OAUTH_JWT_SECRET_KEY=${OAUTH_JWT_SECRET_KEY}
- OAUTH_JWT_ALGORITHM=${OAUTH_JWT_ALGORITHM:-HS256} - OAUTH_JWT_ALGORITHM=${OAUTH_JWT_ALGORITHM:-HS256}
@@ -67,9 +66,10 @@ services:
# ⚠️ DO NOT add example values here - configure in Coolify! # ⚠️ DO NOT add example values here - configure in Coolify!
# The server will auto-discover all WORDPRESS_* variables at startup. # The server will auto-discover all WORDPRESS_* variables at startup.
# === Future Plugins === # === Other Plugins ===
# Gitea, Supabase, and other plugins will auto-discover # Gitea, n8n, Supabase, OpenPanel, Appwrite, and Directus plugins
# their environment variables when implemented. # auto-discover their environment variables at startup.
# Format: {PLUGIN_TYPE}_{SITE_ID}_{CONFIG_KEY}
# No need to pre-define them here. # No need to pre-define them here.
# Health check # Health check
@@ -80,7 +80,7 @@ services:
retries: 3 retries: 3
start_period: 40s start_period: 40s
# Docker socket access for WP-CLI tools (Phase 5+) # Docker socket access for WP-CLI tools
# Required for: wp_cache_flush, wp_cache_type, wp_transient_*, etc. # Required for: wp_cache_flush, wp_cache_type, wp_transient_*, etc.
volumes: volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro - /var/run/docker.sock:/var/run/docker.sock:ro

391
docs/getting-started.md
View File

@@ -1,4 +1,4 @@
# 🚀 Getting Started with MCP Hub # Getting Started with MCP Hub
--- ---
@@ -8,7 +8,7 @@
2. [Installation](#installation) 2. [Installation](#installation)
3. [Configuration](#configuration) 3. [Configuration](#configuration)
4. [Running the Server](#running-the-server) 4. [Running the Server](#running-the-server)
5. [Testing Your Setup](#testing-your-setup) 5. [Connect Your AI Client](#connect-your-ai-client)
6. [Using MCP Tools](#using-mcp-tools) 6. [Using MCP Tools](#using-mcp-tools)
7. [Docker Deployment](#docker-deployment) 7. [Docker Deployment](#docker-deployment)
8. [Coolify Deployment](#coolify-deployment) 8. [Coolify Deployment](#coolify-deployment)
@@ -18,8 +18,6 @@
## Prerequisites ## Prerequisites
Before you begin, ensure you have the following installed:
### Required ### Required
- **Python 3.11+**: [Download Python](https://www.python.org/downloads/) - **Python 3.11+**: [Download Python](https://www.python.org/downloads/)
@@ -44,16 +42,34 @@ For each WordPress site you want to manage:
## Installation ## Installation
### Option 1: Automated Setup (Recommended) ### Option 1: Docker (Recommended)
```bash
git clone https://github.com/airano-ir/mcphub.git
cd mcphub
cp env.example .env
# Edit .env with your site credentials
docker compose up -d
```
### Option 2: Python (pip)
```bash
git clone https://github.com/airano-ir/mcphub.git
cd mcphub
pip install -e .
cp env.example .env
# Edit .env with your site credentials
python server.py --transport sse --port 8000
```
### Option 3: Automated Setup Scripts
#### Linux/Mac #### Linux/Mac
```bash ```bash
# Clone the repository git clone https://github.com/airano-ir/mcphub.git
git clone https://github.com/mcphub/mcphub.git
cd mcphub cd mcphub
# Run setup script
chmod +x scripts/setup.sh chmod +x scripts/setup.sh
./scripts/setup.sh ./scripts/setup.sh
``` ```
@@ -61,39 +77,12 @@ chmod +x scripts/setup.sh
#### Windows (PowerShell) #### Windows (PowerShell)
```powershell ```powershell
# Clone the repository git clone https://github.com/airano-ir/mcphub.git
git clone https://github.com/mcphub/mcphub.git
cd mcphub cd mcphub
# Run setup script
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
.\scripts\setup.ps1 .\scripts\setup.ps1
``` ```
### Option 2: Manual Setup
```bash
# 1. Clone repository
git clone https://github.com/mcphub/mcphub.git
cd mcphub
# 2. Create virtual environment
python3 -m venv venv
# 3. Activate virtual environment
# Linux/Mac:
source venv/bin/activate
# Windows:
.\venv\Scripts\Activate.ps1
# 4. Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
# 5. Copy environment template
cp .env.example .env
```
--- ---
## Configuration ## Configuration
@@ -103,9 +92,9 @@ cp .env.example .env
For each WordPress site: For each WordPress site:
1. Log in to WordPress admin 1. Log in to WordPress admin
2. Navigate to: **Users → Your Profile** 2. Navigate to: **Users > Your Profile**
3. Scroll to **Application Passwords** section 3. Scroll to **Application Passwords** section
4. Enter name: `MCP Server` 4. Enter name: `MCP Hub`
5. Click **Add New Application Password** 5. Click **Add New Application Password**
6. Copy the generated password (format: `xxxx xxxx xxxx xxxx xxxx xxxx`) 6. Copy the generated password (format: `xxxx xxxx xxxx xxxx xxxx xxxx`)
@@ -115,10 +104,10 @@ For each WordPress site:
If using WooCommerce tools: If using WooCommerce tools:
1. Go to: **WooCommerce → Settings → Advanced → REST API** 1. Go to: **WooCommerce > Settings > Advanced > REST API**
2. Click **Add Key** 2. Click **Add Key**
3. Fill in: 3. Fill in:
- **Description**: `MCP Server` - **Description**: `MCP Hub`
- **User**: Select admin user - **User**: Select admin user
- **Permissions**: `Read/Write` - **Permissions**: `Read/Write`
4. Click **Generate API Key** 4. Click **Generate API Key**
@@ -126,48 +115,56 @@ If using WooCommerce tools:
### Step 3: Configure Environment Variables ### Step 3: Configure Environment Variables
Edit `.env` file: Edit the `.env` file with your credentials:
```bash ```bash
# Basic Configuration # ============================================
MCP_SERVER_NAME=mcphub # Required
MCP_SERVER_VERSION=1.0.0 # ============================================
MASTER_API_KEY=your-secure-key-here
# Site 1 - Main WordPress Site # ============================================
WORDPRESS_SITE1_URL=https://example.com # WordPress Site
# ============================================
WORDPRESS_SITE1_URL=https://myblog.com
WORDPRESS_SITE1_USERNAME=admin WORDPRESS_SITE1_USERNAME=admin
WORDPRESS_SITE1_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx WORDPRESS_SITE1_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
WORDPRESS_SITE1_WC_CONSUMER_KEY=ck_xxxxxxxxxxxxx WORDPRESS_SITE1_ALIAS=myblog
WORDPRESS_SITE1_WC_CONSUMER_SECRET=cs_xxxxxxxxxxxxx
WORDPRESS_SITE1_ALIAS=mainsite
# Site 2 - E-commerce Site (Optional) # ============================================
WORDPRESS_SITE2_URL=https://shop.example.com # WooCommerce Store (separate plugin)
WORDPRESS_SITE2_USERNAME=admin # ============================================
WORDPRESS_SITE2_APP_PASSWORD=yyyy yyyy yyyy yyyy yyyy yyyy WOOCOMMERCE_STORE1_URL=https://mystore.com
WORDPRESS_SITE2_WC_CONSUMER_KEY=ck_yyyyyyyyyyyyy WOOCOMMERCE_STORE1_CONSUMER_KEY=ck_xxxxx
WORDPRESS_SITE2_WC_CONSUMER_SECRET=cs_yyyyyyyyyyyyy WOOCOMMERCE_STORE1_CONSUMER_SECRET=cs_xxxxx
WORDPRESS_SITE2_ALIAS=shop WOOCOMMERCE_STORE1_ALIAS=mystore
# Site 3 - Blog Site (Optional) # ============================================
WORDPRESS_SITE3_URL=https://blog.example.com # Gitea Instance (optional)
WORDPRESS_SITE3_USERNAME=admin # ============================================
WORDPRESS_SITE3_APP_PASSWORD=zzzz zzzz zzzz zzzz zzzz zzzz GITEA_REPO1_URL=https://git.example.com
WORDPRESS_SITE3_ALIAS=blog GITEA_REPO1_TOKEN=your_gitea_token
GITEA_REPO1_ALIAS=mygitea
# Rate Limiting (Optional) # ============================================
# OAuth (required for Claude/ChatGPT auto-registration)
# ============================================
OAUTH_JWT_SECRET_KEY=your-jwt-secret
OAUTH_BASE_URL=https://your-server:8000
# ============================================
# Optional
# ============================================
LOG_LEVEL=INFO
RATE_LIMIT_PER_MINUTE=60 RATE_LIMIT_PER_MINUTE=60
RATE_LIMIT_PER_HOUR=1000 RATE_LIMIT_PER_HOUR=1000
RATE_LIMIT_PER_DAY=10000 RATE_LIMIT_PER_DAY=10000
# Logging (Optional)
LOG_LEVEL=INFO
``` ```
### Configuration Tips ### Configuration Tips
- **Site Aliases**: Use friendly names like `mainsite`, `shop`, or `blog` - **Site Aliases**: Use friendly names like `myblog`, `mystore`, or `mygitea`
- **Minimal WooCommerce**: Only configure WooCommerce keys if you need e-commerce tools - **Separate plugins**: WordPress and WooCommerce are separate plugins with separate env var prefixes
- **Testing**: Start with one site, verify it works, then add more - **Testing**: Start with one site, verify it works, then add more
- **Security**: Never commit `.env` file to git - **Security**: Never commit `.env` file to git
@@ -175,18 +172,16 @@ LOG_LEVEL=INFO
## Running the Server ## Running the Server
### Development Mode ### SSE Transport (for remote AI clients)
```bash ```bash
# Activate virtual environment (if not already active) python server.py --transport sse --port 8000
source venv/bin/activate # Linux/Mac ```
.\venv\Scripts\Activate.ps1 # Windows
# Run server ### Stdio Transport (for Claude Desktop local)
python src/main.py
# Or use the dev script ```bash
./scripts/dev.sh # Linux/Mac python server.py
``` ```
### Verify Server is Running ### Verify Server is Running
@@ -194,119 +189,133 @@ python src/main.py
Check logs for: Check logs for:
``` ```
INFO: MCP Server initialized INFO: MCP Hub initialized
INFO: Registered 390 tools INFO: Registered 589 tools
INFO: Server ready INFO: Server ready
``` ```
Or test the health endpoint:
```bash
curl http://localhost:8000/health
```
--- ---
## Testing Your Setup ## Connect Your AI Client
### Quick Health Check ### Claude Desktop
Run the test script: Add to `claude_desktop_config.json`:
```bash ```json
./scripts/test.sh quick {
"mcpServers": {
"mcphub": {
"url": "https://your-server:8000/mcp",
"headers": {
"Authorization": "Bearer YOUR_MASTER_API_KEY"
}
}
}
}
``` ```
### Manual Testing ### Claude Code
```bash Add to `.mcp.json` in your project:
# Run all tests
pytest
# Run with coverage ```json
pytest --cov {
"mcpServers": {
# Run specific test "mcphub": {
pytest tests/test_wordpress_plugin.py "type": "sse",
"url": "https://your-server:8000/mcp",
"headers": {
"Authorization": "Bearer YOUR_MASTER_API_KEY"
}
}
}
}
``` ```
### Verify Tool Registration ### Cursor
Check that tools are registered: Go to **Settings > MCP Servers > Add Server**:
```bash - **Name**: MCP Hub
python -c " - **URL**: `https://your-server:8000/mcp`
from src.main import app - **Headers**: `Authorization: Bearer YOUR_MASTER_API_KEY`
tools = app.list_tools()
print(f'Total tools: {len(tools)}') ### VS Code + Copilot
"
Add to `.vscode/mcp.json`:
```json
{
"servers": {
"mcphub": {
"type": "sse",
"url": "https://your-server:8000/mcp",
"headers": {
"Authorization": "Bearer YOUR_MASTER_API_KEY"
}
}
}
}
``` ```
Expected output: `Total tools: 390` (for 3 configured sites) ### ChatGPT (Remote MCP)
MCP Hub supports **Open Dynamic Client Registration** (RFC 7591). ChatGPT can auto-register as an OAuth client:
1. Deploy MCP Hub with `OAUTH_BASE_URL` set
2. In ChatGPT, add MCP server: `https://your-server:8000/mcp`
3. ChatGPT auto-discovers OAuth metadata and registers
--- ---
## Using MCP Tools ## Using MCP Tools
### Tool Naming Convention ### 589 Tools Across 9 Plugins
#### Per-Site Tools (Legacy) | Plugin | Tools | Env Prefix |
``` |--------|-------|------------|
wordpress_{site}_action | WordPress | 67 | `WORDPRESS_` |
``` | WooCommerce | 28 | `WOOCOMMERCE_` |
Examples: | WordPress Advanced | 22 | `WORDPRESS_` (same sites, advanced ops) |
- `wordpress_site1_list_posts` | Gitea | 56 | `GITEA_` |
- `wordpress_site2_get_product` | n8n | 56 | `N8N_` |
- `wordpress_site3_create_page` | Supabase | 70 | `SUPABASE_` |
| OpenPanel | 73 | `OPENPANEL_` |
| Appwrite | 100 | `APPWRITE_` |
| Directus | 100 | `DIRECTUS_` |
| System | 17 | (no config needed) |
#### Unified Tools (Recommended) ### Unified Tool Pattern
```
wordpress_action(site="site_id", ...)
```
Examples:
- `wordpress_list_posts(site="site1")`
- `wordpress_get_product(site="shop", product_id=123)`
- `wordpress_create_page(site="blog", title="Hello", content="...")`
### Using Site Aliases All tools use a `site` parameter to select which site to operate on:
If you configured `WORDPRESS_SITE2_ALIAS=shop`:
```python ```python
# Both work the same wordpress_list_posts(site="myblog", per_page=10, status="publish")
wordpress_list_products(site="site2") wordpress_create_post(site="myblog", title="Hello", content="World")
wordpress_list_products(site="shop") woocommerce_list_products(site="mystore")
gitea_list_repos(site="mygitea")
``` ```
### Example: List Posts The `site` parameter accepts either a **site_id** (e.g., `site1`) or an **alias** (e.g., `myblog`).
### Multi-Endpoint Architecture
Use specific endpoints to limit tool access:
**Using Per-Site Tools**:
```python
result = wordpress_site1_list_posts(per_page=10, status="publish")
``` ```
/mcp → All 589 tools (Master API Key)
**Using Unified Tools**: /system/mcp → System tools only (17 tools)
```python /wordpress/mcp → WordPress tools (67 tools)
result = wordpress_list_posts(site="mainsite", per_page=10, status="publish") /woocommerce/mcp → WooCommerce tools (28 tools)
``` /gitea/mcp → Gitea tools (56 tools)
/project/{alias}/mcp → Per-project (auto-injects site)
### Example: Create Product
```python
result = wordpress_create_product(
site="shop",
name="New Product",
type="simple",
regular_price="29.99",
description="Product description",
status="publish"
)
```
### Example: Update Page
```python
result = wordpress_update_page(
site="blog",
page_id=42,
title="Updated Title",
content="<p>Updated content</p>",
status="publish"
)
``` ```
--- ---
@@ -316,10 +325,6 @@ result = wordpress_update_page(
### Quick Start ### Quick Start
```bash ```bash
# Deploy with Docker
./scripts/deploy.sh
# Or manually
docker compose up -d docker compose up -d
``` ```
@@ -356,11 +361,6 @@ curl http://localhost:8000/health
## Coolify Deployment ## Coolify Deployment
### Prerequisites
- Coolify instance running
- Docker registry access (optional)
### Step 1: Create New Resource ### Step 1: Create New Resource
1. Log in to Coolify dashboard 1. Log in to Coolify dashboard
@@ -369,21 +369,25 @@ curl http://localhost:8000/health
### Step 2: Configure Repository ### Step 2: Configure Repository
1. **Git Repository**: `https://github.com/mcphub/mcphub.git` 1. **Git Repository**: `https://github.com/airano-ir/mcphub.git`
2. **Branch**: `main` 2. **Branch**: `main`
3. **Build Pack**: `Docker Compose` 3. **Build Pack**: `Docker Compose`
### Step 3: Configure Environment Variables ### Step 3: Configure Environment Variables
Add all required environment variables from `.env.example`: Add all required environment variables in Coolify's environment variable UI:
``` ```
MASTER_API_KEY=your-secure-key-here
OAUTH_JWT_SECRET_KEY=your-jwt-secret
OAUTH_BASE_URL=https://your-domain.com
WORDPRESS_SITE1_URL=https://example.com WORDPRESS_SITE1_URL=https://example.com
WORDPRESS_SITE1_USERNAME=admin WORDPRESS_SITE1_USERNAME=admin
WORDPRESS_SITE1_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx WORDPRESS_SITE1_APP_PASSWORD=xxxx xxxx xxxx xxxx
...
``` ```
The server auto-discovers all `WORDPRESS_*`, `WOOCOMMERCE_*`, `GITEA_*`, and other plugin environment variables at startup.
### Step 4: Configure Health Check ### Step 4: Configure Health Check
- **Path**: `/health` - **Path**: `/health`
@@ -398,51 +402,14 @@ WORDPRESS_SITE1_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
2. Wait for build to complete 2. Wait for build to complete
3. Check logs for successful startup 3. Check logs for successful startup
### Coolify-Specific Configuration
Add to `docker-compose.yml` if needed:
```yaml
services:
mcp-server:
labels:
- "coolify.managed=true"
- "coolify.port=8000"
- "coolify.health_check=/health"
```
--- ---
## Next Steps ## Next Steps
### 1. Explore Available Tools 1. **Explore the full tool list**: See the [README](../README.md) for all 589 tools
2. **Set up API keys**: [API Keys Guide](API_KEYS_GUIDE.md) for per-project access control
Check the [README](../README.md) for complete tool listing. 3. **Configure OAuth**: [OAuth Guide](OAUTH_GUIDE.md) for Claude/ChatGPT auto-registration
4. **Monitor health**: Use `check_all_projects_health` tool or visit the web dashboard
### 2. Configure Monitoring 5. **Troubleshoot issues**: [Troubleshooting Guide](troubleshooting.md)
- View health metrics: Use `check_all_projects_health` tool
- Check rate limits: Use `get_rate_limit_stats` tool
- Review audit logs: `tail -f logs/audit.log`
### 3. Customize Configuration
- Adjust rate limits in `.env`
- Configure log levels
- Add more WordPress sites
### 4. Read Documentation
- [Troubleshooting Guide](troubleshooting.md)
- [Security Policy](../SECURITY.md)
- [Contributing Guide](../CONTRIBUTING.md)
### 5. Join Community
- **Repository**: [github.com/mcphub/mcphub](https://github.com/mcphub/mcphub)
- **Contact**: hello@mcphub.dev
- **Website**: [mcphub.dev](https://mcphub.dev)
---
--- ---

4
plugins/wordpress/plugin.py
View File

@@ -30,7 +30,7 @@ class WordPressPlugin(BasePlugin):
- Internal link analysis - Internal link analysis
Note: WooCommerce functionality moved to separate woocommerce plugin (Phase D.1) Note: WooCommerce functionality moved to separate woocommerce plugin (Phase D.1)
Total: 65 tools Total: 67 tools
""" """
@staticmethod @staticmethod
@@ -96,7 +96,7 @@ class WordPressPlugin(BasePlugin):
with site parameter routing. with site parameter routing.
Returns: Returns:
List of tool specification dictionaries (65 tools) List of tool specification dictionaries (67 tools)
""" """
specs = [] specs = []

13
pyproject.toml
View File

@@ -15,6 +15,9 @@ keywords = [
] ]
classifiers = [ classifiers = [
"Development Status :: 4 - Beta", "Development Status :: 4 - Beta",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
"Environment :: Console",
"Intended Audience :: Developers", "Intended Audience :: Developers",
"Intended Audience :: System Administrators", "Intended Audience :: System Administrators",
"Programming Language :: Python :: 3", "Programming Language :: Python :: 3",
@@ -54,11 +57,11 @@ dev = [
mcphub = "server:main" mcphub = "server:main"
[project.urls] [project.urls]
Homepage = "https://github.com/mcphub/mcphub" Homepage = "https://github.com/airano-ir/mcphub"
Repository = "https://github.com/mcphub/mcphub" Repository = "https://github.com/airano-ir/mcphub"
Documentation = "https://github.com/mcphub/mcphub#readme" Documentation = "https://github.com/airano-ir/mcphub#readme"
Issues = "https://github.com/mcphub/mcphub/issues" Issues = "https://github.com/airano-ir/mcphub/issues"
Changelog = "https://github.com/mcphub/mcphub/releases" Changelog = "https://github.com/airano-ir/mcphub/releases"
[build-system] [build-system]
requires = ["setuptools>=68.0", "wheel"] requires = ["setuptools>=68.0", "wheel"]

2
scripts/setup.ps1
View File

@@ -178,7 +178,7 @@ function Main {
Write-Host " pytest --cov" -ForegroundColor Blue Write-Host " pytest --cov" -ForegroundColor Blue
Write-Host "" Write-Host ""
Write-Host "For more information, visit:" Write-Host "For more information, visit:"
Write-Host "https://github.com/mcphub/mcphub" -ForegroundColor Blue Write-Host "https://github.com/airano-ir/mcphub" -ForegroundColor Blue
Write-Host "" Write-Host ""
} }

2
scripts/setup.sh
View File

@@ -173,7 +173,7 @@ main() {
echo -e " ${BLUE}pytest --cov${NC}" echo -e " ${BLUE}pytest --cov${NC}"
echo "" echo ""
echo "For more information, visit:" echo "For more information, visit:"
echo -e "${BLUE}https://github.com/mcphub/mcphub${NC}" echo -e "${BLUE}https://github.com/airano-ir/mcphub${NC}"
echo "" echo ""
} }

6
server.py
View File

@@ -4173,9 +4173,9 @@ def create_multi_endpoint_app(transport: str = "streamable-http"):
logger.info("=" * 60) logger.info("=" * 60)
logger.info("Dashboard: /dashboard") # Phase K logger.info("Dashboard: /dashboard") # Phase K
logger.info("Endpoints:") logger.info("Endpoints:")
logger.info(" /mcp - Admin (all 587 tools)") logger.info(" /mcp - Admin (all 589 tools)")
logger.info(" /system/mcp - System (17 tools)") # Phase X.3 logger.info(" /system/mcp - System (17 tools)")
logger.info(" /wordpress/mcp - WordPress Core (65 tools)") logger.info(" /wordpress/mcp - WordPress Core (67 tools)")
logger.info(" /woocommerce/mcp - WooCommerce (28 tools)") # Phase D.1 logger.info(" /woocommerce/mcp - WooCommerce (28 tools)") # Phase D.1
logger.info(" /wordpress-advanced/mcp - WordPress Advanced (22 tools)") logger.info(" /wordpress-advanced/mcp - WordPress Advanced (22 tools)")
logger.info(" /gitea/mcp - Gitea (56 tools)") logger.info(" /gitea/mcp - Gitea (56 tools)")

4
tests/test_community_build.py
View File

@@ -209,7 +209,7 @@ class TestBrandingTransform:
def test_replaces_repo_urls(self): def test_replaces_repo_urls(self):
content = "https://gitea.airano.ir/dev/coolify-mcp-hub" content = "https://gitea.airano.ir/dev/coolify-mcp-hub"
transformed, changed = apply_branding_transform(content) transformed, changed = apply_branding_transform(content)
assert "github.com/mcphub/mcphub" in transformed assert "github.com/airano-ir/mcphub" in transformed
def test_replaces_email(self): def test_replaces_email(self):
content = "Contact: gitea@airano.ir" content = "Contact: gitea@airano.ir"
@@ -224,7 +224,7 @@ class TestBrandingTransform:
assert "line3" in transformed assert "line3" in transformed
def test_no_changes_returns_false(self): def test_no_changes_returns_false(self):
content = "clean content with no markers" content = "clean content with no markers\n"
transformed, changed = apply_branding_transform(content) transformed, changed = apply_branding_transform(content)
assert changed is False assert changed is False