mcphub/CHANGELOG.md

📝 Changelog

All notable changes to MCP Hub will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

---

[3.2.0] - 2026-02-24

claude.ai Protocol Compatibility & Social Login Consent

Adds full MCP Authorization Specification compliance for claude.ai Connectors, social login on the OAuth consent screen, and 15 bug fixes from comprehensive testing.

Added

• client_secret_basic Authentication (RFC 6749 §2.3.1): Token endpoint now accepts client credentials via Authorization: Basic header in addition to client_secret_post
• Token Revocation Endpoint (RFC 7009): POST /oauth/revoke for revoking access and refresh tokens, with client_secret_basic support
• resource Parameter (RFC 8707): Authorization and token requests accept the resource parameter; JWT access tokens include the aud claim binding tokens to the MCP server URL
• Social Login on OAuth Consent: OAuth authorize page detects dashboard sessions, allowing users logged in via GitHub/Google to authorize MCP clients without re-entering API keys
• Session-Based Consent: __session__ consent mode creates JWT tokens with sub: "admin:..." or sub: "user:..." claims based on session identity
• Social Login Return URL: mcp_auth_next cookie preserves OAuth flow state across social login redirects, with open redirect protection

Fixed

• get_system_info returned hardcoded version v2.6.0 instead of actual version
• Internal "phase": "X.3" debug field exposed in system info
• /dashboard/audit-logs caused redirect loop (removed from nav)
• Settings page used wrong sidebar layout
• Server mode displayed sse instead of streamable-http
• Plugin descriptions showed "No description" when description existed
• 404 page was unstyled plain text (now styled standalone page)
• OAuth flows failed without PUBLIC_URL env var
• Endpoint page showed wrong example tools per project
• Health check timestamps showed "None" for new projects
• Health checks missing auth_valid field causing dashboard errors
• ENCRYPTION_KEY not validated on startup (now fails fast with clear error)
• Stale JWT tokens caused 500 errors instead of 401
• Per-user MCP endpoint returned 500 ImportError on first request
• Copy button displayed Python repr() instead of clean JSON

Improved

• API key modal stays open until user clicks "Done" (was 0.5s auto-close)
• health_metric_recorded events filtered from project activity feed
• WooCommerce health checks use consumer_key/consumer_secret authentication

Tests

• Test suite expanded from 290 to 442 tests (+152)
• Added 23 Phase B OAuth protocol tests
• Added Phase C social login consent tests

---

[3.1.0] - 2026-02-23

Live Platform Foundation (Track E.1 - E.3)

Major release introducing the Live Platform architecture — SQLite database, OAuth social login, site management, and per-user MCP endpoints. All features are included in the Community Edition.

Added

• SQLite Database Backend (E.1): Async SQLite via aiosqlite, WAL mode, schema versioning with migrations framework, CRUD for users/sites/API keys/connection tokens
• Credential Encryption (E.1): AES-256-GCM with HKDF per-site key derivation, versioned wire format for future migration support
• OAuth Social Login (E.2): GitHub + Google OAuth 2.0, CSRF state tokens, JWT session management, dual session types (admin + oauth_user)
• Site Management API (E.3): Plugin credential definitions for all 9 plugins, connection validation, encrypted site CRUD, MAX_SITES_PER_USER=10
• User API Keys (E.3): bcrypt-hashed keys with mhu_ prefix, 8-char prefix for indexed lookup, 5-minute validation cache
• Per-User MCP Endpoints (E.3): Direct JSON-RPC handler at /u/{user_id}/{alias}/mcp, per-user rate limiting (30/min, 500/hr)
• Config Snippets (E.3): Auto-generated config for Claude Desktop, Claude Code, Cursor, VS Code, and ChatGPT
• Dashboard Pages: My Sites (list/add/test/delete), Connect (API keys + config snippets), Profile, OAuth Login
• Dark/Light Mode Toggle: Theme switcher across all dashboard pages
• RBAC: Role-based access control for dashboard
• Active Health Checks: Background health monitoring for connected services

Fixed

• CSRF middleware body consumption bug
• OAuth log noise and DCR crash on startup
• WordPress site connection validation (uses aiohttp to match plugin client)
• Tenant isolation enforced on all site queries

Security

• All bare except: replaced with except Exception: across 12 files
• Network error differentiation (DNS, SSL, timeout, connection refused)
• Retry with exponential backoff for transient errors only
• Auth/config errors never retried

Tests

• 452 total tests (up from 303), all passing
• New test suites: database (37), encryption (27), user_auth (32), site_api (17), user_keys (14), user_endpoints (12), config_snippets (10)

---

[2.9.0] - 2026-02-14

Project Revival - Dependency Updates & Documentation Sync

After 2-month hiatus (Dec 2025 - Feb 2026), updated all dependencies and verified compatibility.

Updated

• FastMCP: 2.12.4 → 2.14.5 (zero breaking changes for our codebase)
• MCP Protocol: 1.16.0 → 1.26.0
• cryptography: 46.0.2 → 46.0.5 (security patches)
• starlette: 0.48.0 → 0.52.1
• authlib: 1.6.5 → 1.6.7
• pydantic: 2.12.0 → 2.12.5
• PyJWT: installed (was missing from environment)

Fixed

• OAuth token timestamps: replaced datetime.utcnow() with datetime.now(timezone.utc) and time.time() for correct UTC timestamps in non-UTC timezones
• OAuth schemas: is_expired() now handles both naive and timezone-aware datetimes
• OAuth token reuse detection: get_refresh_token() now supports include_revoked parameter for proper reuse detection
• OAuth audit logging: fixed AuditLogger.log_event() call to use existing log_system_event() method
• All 54 tests now pass (previously 5 were failing)

Verified

• All 596 tools generate correctly
• Middleware API stable (Middleware, MiddlewareContext, get_http_headers)
• 30+ custom routes operational (dashboard + OAuth)
• Multi-endpoint architecture functional

Documentation

• Aligned version to 2.9.0 across all files (pyproject.toml was 1.3.0)
• Synchronized pyproject.toml dependencies with requirements.txt
• Updated ROADMAP.md and MASTER_CONTEXT.md dates

---

[1.3.0] - 2025-11-21

🎉 Phase E: Custom OAuth Authorization Page with Multi-language Support

Major Feature: Beautiful web-based OAuth authorization with English & Farsi support!

✨ Added

Web-Based Authorization UI:

• Beautiful HTML templates with Tailwind CSS and dark mode support
• Responsive design (mobile-friendly)
• User-friendly API Key input form with validation
• Smooth animations and transitions

Multi-language Support (i18n):

• Complete English (EN) & Persian/Farsi (FA) translations
• Automatic language detection from Accept-Language header
• RTL (Right-to-Left) layout support for Farsi
• 30+ translation keys covering all UI elements

Security Enhancements:

• CSRF Protection (core/oauth/csrf.py):
  • Cryptographically secure token generation (64 chars)
  • 10-minute token lifetime with automatic cleanup
  • One-time use tokens (consumed after validation)
• API Key validation at authorization time
• Permission inheritance from API Key to OAuth token
• Rate limiting infrastructure ready

Files Added:

• core/i18n.py - Internationalization utilities (200+ lines)
• core/oauth/csrf.py - CSRF token manager (150+ lines)
• templates/base.html - Base template with Tailwind CSS
• templates/oauth/authorize.html - Authorization form (170 lines)
• templates/oauth/error.html - Error page (90 lines)

Commits: c851c78, 7ec3b9d, b9b7dda, c60dd43

---

[1.2.0] - 2025-11-18

🎉 Phase D: WordPress Advanced Plugin Split

Plugin Separation: Advanced WordPress features moved to dedicated plugin!

Changed

Plugin Structure:

• Split WordPress plugin into two modules:
  • plugins/wordpress/ - Core features (92 tools)
  • plugins/wordpress_advanced/ - Advanced features (22 tools)

WordPress Advanced Plugin (plugins/wordpress_advanced/):

• Database Operations (7 tools): export, import, size, tables, search, query, repair
• Bulk Operations (8 tools): parallel batch processing with semaphore control
• System Operations (7 tools): system info, cron, cache, error logs

Benefits:

• Better tool visibility (basic users see only 92 tools)
• Improved security (sensitive features in separate plugin)
• Granular access control (separate API keys per plugin)
• Reduced complexity for regular users

Documentation:

• Complete README.md in plugins/wordpress_advanced/
• Environment configuration examples
• Conditional initialization guide

Tool Count: Remains 114 total (92 core + 22 advanced split)

Commits: 2df7f31, fc97c85, 475dd73

---

[1.1.0] - 2025-11-19

🎉 Phase C: Gitea Plugin Implementation

New Plugin: Complete Gitea repository management with 55 tools!

✨ Added

Gitea Plugin (plugins/gitea/):

Features:

• Repository Management (15 tools): CRUD, branches, tags, files
• Issue Tracking (12 tools): issues, labels, milestones, comments
• Pull Requests (15 tools): PRs, reviews, merges, comments
• User & Organization (8 tools): users, orgs, teams, search
• Webhooks (5 tools): webhook management

Architecture (Option B Clean Architecture):

• Pydantic Schemas (6 files, ~1,100 lines):
  • common.py - Site, Pagination, User models
  • repository.py - Repository, Branch, Tag, File models
  • issue.py - Issue, Label, Milestone, Comment models
  • pull_request.py - PR, Review, Commit, File models
  • user.py - User, Organization, Team models
  • webhook.py - Webhook configuration models
• Gitea API Client (client.py - 406 lines):
  • OAuth 2.1 integration
  • Full REST API methods
  • Error handling and logging
• Handler Modules (5 files, ~2,900 lines):
  • repositories.py, issues.py, pull_requests.py
  • users.py, webhooks.py
• Main Plugin (plugin.py - 177 lines):
  • Dynamic method delegation with __getattr__
  • get_tool_specifications() static method
  • Health check integration

Bug Fixes:

• Plugin registration integration (a30b444)
• Tool registration enabled (61b8280)
• Dynamic method delegation fix (bb251c0)
• Pydantic V2 compatibility (8bc4eb6)
• Schema validation - JSON strings (dbd3234)

Documentation:

• Complete usage guide (docs/GITEA_GUIDE.md - 724 lines)
• Environment configuration in .env.example

Tool Count: 136 → 191 tools (+55 Gitea tools)

Commits: a30b444, 61b8280, bb251c0, 8bc4eb6, dbd3234

---

1.0.0 - 2025-11-18

🎉 Phase B: OAuth 2.1 Infrastructure

Major Feature: Production-ready OAuth 2.1 server with RFC compliance!

✨ Added

OAuth 2.1 Server (core/oauth/server.py - ~450 lines):

• RFC 8414: Authorization Server Metadata
• RFC 7591: Dynamic Client Registration (Protected)
• RFC 7636: PKCE (S256 mandatory)
• RFC 8705: Protected Resource Metadata

Core Components:

• core/oauth/schemas.py - Pydantic models (OAuthClient, tokens)
• core/oauth/pkce.py - PKCE implementation (S256)
• core/oauth/storage.py - JSON-based token storage with auto-cleanup
• core/oauth/client_registry.py - OAuth client management
• core/oauth/token_manager.py - JWT generation/validation

OAuth Endpoints (4 endpoints):

• GET /.well-known/oauth-authorization-server (discovery)
• GET /.well-known/oauth-protected-resource (RFC 8705)
• POST /oauth/register (protected - Master API Key required)
• GET /oauth/authorize - Authorization endpoint (API Key required)
• POST /oauth/token - Token exchange (all grant types)

Security Features:

• Protected client registration (Master API Key required)
• API Key authorization mode (OAUTH_AUTH_MODE=required)
• Refresh token rotation (prevents reuse)
• Authorization code single-use (prevents replay)
• PKCE mandatory (prevents CSRF)
• API Key permission inheritance

OAuth Tools (3 new tools):

• oauth_register_client - Register new OAuth clients
• oauth_list_clients - List all registered clients
• oauth_revoke_client - Revoke client access

ChatGPT Integration:

• OAuth (manual) mode support
• Admin registers client with Master API Key
• Users authorize with their own API Keys
• Enhanced security - no open registration

Documentation:

• Complete OAuth guide (docs/OAUTH_GUIDE.md - ~650 lines)
• Environment configuration examples
• Security model documentation

Tool Count: 133 → 136 tools (+3 OAuth tools)

Commits: Multiple commits (2025-11-18, updated 2025-11-19)

---

Unreleased - 2025-11-11

🔄 Architecture Refactoring (Option A)

BREAKING CHANGE: Removed per-site tools to prevent tool explosion.

Changed

• Architecture: Migrated from Hybrid to Unified-Only architecture
• Tool Count: Reduced from 390 to ~105 tools (constant regardless of site count)
• Scalability: Now supports unlimited sites without tool explosion
  • 1 site: 105 tools (was 200)
  • 10 sites: 105 tools (was 1055)
  • 100 sites: 105 tools (was 9600+)

Technical Details

• Per-site tools (e.g., wordpress_site1_get_post) are no longer registered
• Only unified tools (e.g., wordpress_get_post(site="site1")) are exposed
• Plugin infrastructure remains intact for internal use
• Site aliases continue to work seamlessly

Migration

• Non-breaking for new users: Use unified tools from the start
• For existing integrations: Update tool calls to use site parameter
  • Before: wordpress_site1_get_post(post_id=123)
  • After: wordpress_get_post(site="site1", post_id=123)

Files Modified:

• server.py: Removed per-site tool registration
• MASTER_CONTEXT.md: Updated architecture documentation
• README.md: Updated tool count and features

Next Steps: Option B (complete architectural cleanup) planned for separate branch.

---

1.0.0 - 2025-11-11 (Planned)

🎉 Initial Public Release

This will be the first stable release of MCP Hub, featuring comprehensive WordPress and WooCommerce management through MCP protocol.

✨ Added

Core Features

• ~105 MCP Tools with unified architecture (constant tool count!)
• Unified Architecture: Context-based tools for efficient scaling
• Site Registry: Friendly aliases for projects (e.g., "plantup" → site2)
• Multi-language Support: Full bilingual documentation (English/Persian)

WordPress Management (Phase 1-3)

• Posts Management: Create, read, update, delete posts
• Pages Management: Full CRUD operations for pages
• Media Library: Upload, manage, and delete media files
• Comments: Moderate and manage comments
• Categories & Tags: Taxonomy management
• Users: User information and authentication
• Plugins & Themes: List and inspect installed plugins/themes
• Site Settings: Read WordPress configuration
• Site Health: Check WordPress accessibility

Commits:

• 9881838: feat(wordpress): implement core WordPress tools (Phase 1)
• ad26cdc: feat(wordpress): add media, comments, and taxonomy tools (Phase 2)
• e7ac72d: feat(wordpress): complete users, plugins, themes, and settings (Phase 3)

WooCommerce Integration (Phase 4-5)

• Products: Full product lifecycle management
• Product Variations: Variable product support
• Product Categories & Tags: Product taxonomy management
• Product Attributes: Global attributes for variations
• Coupons: Discount code management
• Orders: Order processing and status updates
• Customers: Customer data management
• Reports: Sales, top sellers, and customer analytics

Commits:

• cda10fb: feat(woocommerce): implement products, categories, and coupons (Phase 4)
• 0ffe5ad: feat(woocommerce): add orders, customers, and reports (Phase 5)

WP-CLI & SEO Tools (Phase 6)

• Cache Management: Flush object cache, check cache type
• Transients: List and delete transients
• Database: Health checks, optimization, export
• Plugin Management: List, verify checksums, update plugins
• Theme Management: List, verify, update themes
• Core Management: Verify and update WordPress core
• Search & Replace: Dry-run database migrations
• SEO Metadata: Rank Math & Yoast SEO integration
• Navigation Menus: Menu and menu item management
• Custom Post Types: List and manage custom post types
• Custom Taxonomies: Taxonomy term management

Commits:

• e5aaa97: feat(wp-cli): implement WP-CLI integration (Phase 6)
• e5aaa97: feat(seo): add SEO metadata management tools (Phase 6)

Hybrid Architecture (Phase 7.0)

• Site Registry System: Central site configuration management
• Unified Tool Generator: Context-based tools with site parameter
• Per-Site Tools: Backward-compatible legacy tools
• Tool Aliases: Support for friendly project names
• Plugin Architecture: Extensible plugin system

Commit: b638d4a: feat(architecture): implement hybrid dual-tool architecture (Phase 7.0)

Security & Monitoring (Phase 7.1-7.3)

• Audit Logging (Phase 7.1):

  • GDPR-compliant structured logging
  • Sensitive data filtering (passwords, API keys)
  • JSON format for easy parsing
  • Automatic log rotation

• Health Monitoring (Phase 7.2):

  • Real-time system metrics
  • Response time tracking
  • Error rate monitoring
  • Historical metrics (1-24 hours)
  • Alert thresholds
  • Export functionality

• Rate Limiting (Phase 7.3):

  • Token bucket algorithm
  • 60 req/min, 1000 req/hour, 10000 req/day
  • Per-client tracking
  • Automatic throttling
  • Statistics and monitoring

Commits:

• 003ee0f: feat(audit): implement GDPR-compliant audit logging (Phase 7.1)
• 796c8e0: feat(health): implement enhanced health monitoring (Phase 7.2)
• 9297f20: feat(rate-limiting): implement rate limiting & throttling (Phase 7.3)

Documentation

• README.md: Bilingual project introduction
• CONTRIBUTING.md: Simplified contribution guide
• SECURITY.md: Security policy with OWASP compliance
• MASTER_CONTEXT.md: Comprehensive project reference
• Development Documentation: Architecture and deployment guides

🔒 Security

• API key authentication for WordPress and WooCommerce
• Password filtering in logs
• Input validation and schema checking
• Docker security hardening
• OWASP Top 10 2025 compliance
• Regular dependency updates

🏗️ Infrastructure

• Docker Support: Production-ready Docker Compose setup
• Coolify Integration: One-click deployment support
• Environment Variables: Secure configuration management
• Health Checks: Automated container health monitoring
• Log Management: Structured logging with rotation

🧪 Testing

• 40 Tests: Comprehensive test suite
• 75%+ Coverage: Unit, integration, and E2E tests
• pytest Framework: Modern Python testing
• Mock Support: Isolated testing with pytest-mock
• Async Testing: Full async/await test support

📊 Statistics

• 390 Total Tools: 285 per-site + 95 unified + 10 system
• 3 WordPress Sites: Configured and tested
• 8 Development Phases: From inception to production
• 19 Commits: Clean development history

🔧 Technical Details

• Python 3.11+: Modern async/await support
• FastMCP Framework: MCP protocol implementation
• httpx: Async HTTP client
• Docker Compose: Container orchestration
• pytest: Testing framework

---

Development History

Phase 7.3 - Rate Limiting & Throttling

Date: 2025-11-11 Status: ✅ Complete

Added rate limiting system with token bucket algorithm to prevent API abuse.

Changes:

• Implemented RateLimiter class with token bucket algorithm
• Added per-client request tracking
• Configurable limits (per-minute, per-hour, per-day)
• Rate limit statistics endpoint
• Rate limit reset functionality
• Integration with all tool handlers
• Comprehensive testing

Tools Added: 2 (get_rate_limit_stats, reset_rate_limit)

Phase 7.2 - Enhanced Health Monitoring

Date: 2025-11-10 Status: ✅ Complete

Enhanced health monitoring system with detailed metrics and historical tracking.

Changes:

• Response time tracking per project
• Error rate calculation
• Historical metrics storage (up to 24 hours)
• Alert threshold system
• Health metrics export
• System-wide statistics
• Project-specific health endpoints

Tools Added: 5 (check_all_projects_health, get_project_health, get_system_metrics, get_system_uptime, get_project_metrics, export_health_metrics)

Phase 7.1 - Audit Logging

Date: 2025-11-09 Status: ✅ Complete

Implemented GDPR-compliant audit logging system with sensitive data filtering.

Changes:

• Structured JSON logging
• GDPR compliance (PII filtering)
• Password and API key filtering
• Log rotation configuration
• User action tracking
• Security event logging
• Timezone-aware timestamps

Phase 7.0 - Hybrid Architecture

Date: 2025-11-08 Status: ✅ Complete

Major architectural refactor introducing dual tool system.

Changes:

• Site Registry system
• Unified tool generator
• Plugin architecture
• Per-site tool preservation (backward compatibility)
• Site alias support
• Dynamic tool registration

Tools Added: 95 unified tools (matching per-site tools)

Phase 6 - WP-CLI & Advanced Features

Date: 2025-11-05 Status: ✅ Complete

Added WP-CLI integration and advanced WordPress features.

Changes:

• Cache management (flush, type)
• Transient management
• Database operations (check, optimize, export)
• Plugin checksums verification
• Core file verification
• Search & replace (dry-run only)
• Plugin/theme/core updates (with dry-run mode)
• SEO metadata management (Rank Math & Yoast)
• Navigation menu management
• Custom post types support
• Custom taxonomies support

Tools Added per Site: 19

Phase 5 - WooCommerce Orders & Customers

Date: 2025-11-03 Status: ✅ Complete

Extended WooCommerce support with order and customer management.

Changes:

• Order listing with filters
• Order details retrieval
• Order status updates
• Order creation
• Order deletion
• Customer listing
• Customer details
• Customer creation/updates

Tools Added per Site: 8

Phase 4 - WooCommerce Products & Reports

Date: 2025-11-02 Status: ✅ Complete

Added comprehensive WooCommerce product management and reporting.

Changes:

• Product CRUD operations
• Product categories and tags
• Product attributes
• Product variations
• Coupon management
• Sales reports
• Top sellers analytics
• Customer statistics

Tools Added per Site: 20

Phase 3 - WordPress Extended Features

Date: 2025-11-01 Status: ✅ Complete

Completed core WordPress functionality.

Changes:

• User management
• Plugin listing
• Theme management
• Site settings access
• Site health checks

Tools Added per Site: 5

Phase 2 - WordPress Media & Taxonomy

Date: 2025-10-31 Status: ✅ Complete

Extended WordPress tools with media and taxonomy support.

Changes:

• Media library management
• Media upload from URL
• Media metadata updates
• Comment moderation
• Category management
• Tag management

Tools Added per Site: 6

Phase 1 - Core WordPress Tools

Date: 2025-10-30 Status: ✅ Complete

Initial implementation of WordPress management tools.

Changes:

• Post management (CRUD)
• Page management (CRUD)
• Basic MCP server setup
• Environment configuration
• Docker Compose setup

Tools Added per Site: 6

---

---

Unreleased

🔮 Planned for Phase 2

Gitea Integration (Priority)

• Repository management
• Issue tracking
• Pull request operations
• Webhook management
• User and team management

Supabase Integration

• Database operations
• Authentication management
• Storage management
• Real-time subscriptions
• Edge functions

Migration Tools

• WordPress to Supabase migration
• Data export/import utilities
• Schema generation

---