mcphub-server 3.0.4__tar.gz → 3.3.0__tar.gz

{mcphub_server-3.0.4/mcphub_server.egg-info → mcphub_server-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcphub-server
-Version: 3.0.4
+Version: 3.3.0
 Summary: AI-native management hub for WordPress, WooCommerce, and self-hosted services via Model Context Protocol (MCP)
 Author-email: MCP Hub <contact@mcphub.dev>
 License-Expression: MIT
@@ -33,7 +33,9 @@ Requires-Dist: docker>=7.0.0
 Requires-Dist: authlib>=1.5.0
 Requires-Dist: PyJWT>=2.8.0
 Requires-Dist: cryptography>=46.0.0
+Requires-Dist: aiosqlite>=0.20.0
 Requires-Dist: jinja2>=3.1.2
+Requires-Dist: bcrypt>=4.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.4.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
@@ -45,6 +47,8 @@ Requires-Dist: mypy>=1.7.0; extra == "dev"
 Requires-Dist: pre-commit>=3.5.0; extra == "dev"
 Dynamic: license-file
 
+<!-- mcp-name: io.github.airano-ir/mcphub -->
+
 # MCP Hub
 
 <div align="center">
@@ -58,7 +62,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/)
 [![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)
-[![Tests: 290 passing](https://img.shields.io/badge/tests-290%20passing-brightgreen.svg)]()
+[![Tests: 481 passing](https://img.shields.io/badge/tests-481%20passing-brightgreen.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)
 
@@ -153,7 +157,20 @@ curl http://localhost:8000/health
 
 Open the **web dashboard** in your browser: **http://localhost:8000/dashboard**
 
-You should see the login page. Use your `MASTER_API_KEY` to log in.
+You should see the login page. Log in with your `MASTER_API_KEY` or via **GitHub/Google OAuth** (if configured).
+
+### Try It Now (No Setup Required)
+
+**Don't want to self-host?** Try the demo instance at **[mcp.palebluedot.live](https://mcp.palebluedot.live)**:
+
+1. Log in with **GitHub** or **Google**
+2. Add your sites via the dashboard (My Sites → Add Service)
+3. Go to **Connect** page — generate config for your AI client
+4. Copy-paste the config into Claude Desktop, VS Code, or Claude Code
+
+Your personal MCP endpoint: `https://mcp.palebluedot.live/u/{your-user-id}/{alias}/mcp`
+
+---
 
 ### Configure Your Sites
 
@@ -342,12 +359,14 @@ MCP Hub supports **Open Dynamic Client Registration** (RFC 7591). ChatGPT can au
 /appwrite/mcp               → Appwrite tools (100 tools)
 /directus/mcp               → Directus tools (100 tools)
 /project/{alias}/mcp        → Per-project endpoint (auto-injects site)
+/u/{user_id}/{alias}/mcp    → Per-user endpoint (hosted/OAuth users)
 ```
 
 **Recommendation**: Use plugin-specific endpoints instead of `/mcp` (596 tools) to minimize token usage.
 
 | Endpoint | Use Case | Tools |
 |----------|----------|------:|
+| `/u/{user_id}/{alias}/mcp` | Hosted users (OAuth login) | 22-100 |
 | `/project/{alias}/mcp` | Single-site workflow (recommended) | 22-100 |
 | `/{plugin}/mcp` | Multi-site management | 23-101 |
 | `/mcp` | Admin & discovery only | 596 |
@@ -368,7 +387,7 @@ 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/) ([Download ZIP](wordpress-plugin/seo-api-bridge.zip)) + Rank Math or Yoast SEO |
+| SEO tools (`wordpress_get_post_seo`, etc.) | [Airano MCP SEO Bridge](https://wordpress.org/plugins/airano-mcp-seo-bridge/) ([GitHub](wordpress-plugin/airano-mcp-seo-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 |
 | OpenPanel analytics integration | [OpenPanel Self-Hosted](wordpress-plugin/openpanel-self-hosted/) ([Download ZIP](wordpress-plugin/openpanel-self-hosted.zip)) |
@@ -408,7 +427,7 @@ Without Docker socket, WP-CLI tools return "not available" but all REST API tool
 # Install with dev dependencies
 pip install -e ".[dev]"
 
-# Run tests (290 tests)
+# Run tests (481 tests)
 pytest
 
 # Format and lint

{mcphub_server-3.0.4 → mcphub_server-3.3.0}/README.md

@@ -1,3 +1,5 @@
+<!-- mcp-name: io.github.airano-ir/mcphub -->
+
 # MCP Hub
 
 <div align="center">
@@ -11,7 +13,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/)
 [![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)
-[![Tests: 290 passing](https://img.shields.io/badge/tests-290%20passing-brightgreen.svg)]()
+[![Tests: 481 passing](https://img.shields.io/badge/tests-481%20passing-brightgreen.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)
 
@@ -106,7 +108,20 @@ curl http://localhost:8000/health
 
 Open the **web dashboard** in your browser: **http://localhost:8000/dashboard**
 
-You should see the login page. Use your `MASTER_API_KEY` to log in.
+You should see the login page. Log in with your `MASTER_API_KEY` or via **GitHub/Google OAuth** (if configured).
+
+### Try It Now (No Setup Required)
+
+**Don't want to self-host?** Try the demo instance at **[mcp.palebluedot.live](https://mcp.palebluedot.live)**:
+
+1. Log in with **GitHub** or **Google**
+2. Add your sites via the dashboard (My Sites → Add Service)
+3. Go to **Connect** page — generate config for your AI client
+4. Copy-paste the config into Claude Desktop, VS Code, or Claude Code
+
+Your personal MCP endpoint: `https://mcp.palebluedot.live/u/{your-user-id}/{alias}/mcp`
+
+---
 
 ### Configure Your Sites
 
@@ -295,12 +310,14 @@ MCP Hub supports **Open Dynamic Client Registration** (RFC 7591). ChatGPT can au
 /appwrite/mcp               → Appwrite tools (100 tools)
 /directus/mcp               → Directus tools (100 tools)
 /project/{alias}/mcp        → Per-project endpoint (auto-injects site)
+/u/{user_id}/{alias}/mcp    → Per-user endpoint (hosted/OAuth users)
 ```
 
 **Recommendation**: Use plugin-specific endpoints instead of `/mcp` (596 tools) to minimize token usage.
 
 | Endpoint | Use Case | Tools |
 |----------|----------|------:|
+| `/u/{user_id}/{alias}/mcp` | Hosted users (OAuth login) | 22-100 |
 | `/project/{alias}/mcp` | Single-site workflow (recommended) | 22-100 |
 | `/{plugin}/mcp` | Multi-site management | 23-101 |
 | `/mcp` | Admin & discovery only | 596 |
@@ -321,7 +338,7 @@ 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/) ([Download ZIP](wordpress-plugin/seo-api-bridge.zip)) + Rank Math or Yoast SEO |
+| SEO tools (`wordpress_get_post_seo`, etc.) | [Airano MCP SEO Bridge](https://wordpress.org/plugins/airano-mcp-seo-bridge/) ([GitHub](wordpress-plugin/airano-mcp-seo-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 |
 | OpenPanel analytics integration | [OpenPanel Self-Hosted](wordpress-plugin/openpanel-self-hosted/) ([Download ZIP](wordpress-plugin/openpanel-self-hosted.zip)) |
@@ -361,7 +378,7 @@ Without Docker socket, WP-CLI tools return "not available" but all REST API tool
 # Install with dev dependencies
 pip install -e ".[dev]"
 
-# Run tests (290 tests)
+# Run tests (481 tests)
 pytest
 
 # Format and lint

{mcphub_server-3.0.4 → mcphub_server-3.3.0}/core/__init__.py

@@ -45,12 +45,10 @@ from core.rate_limiter import RateLimitConfig, RateLimiter, get_rate_limiter
 from core.site_manager import SiteConfig, SiteManager, get_site_manager
 
 # Legacy (kept for backward compatibility, will be removed in v2.0)
-from core.site_registry import SiteInfo, SiteRegistry, get_site_registry
 from core.tool_generator import ToolGenerator
 
 # Tool Management (Option B architecture)
 from core.tool_registry import ToolDefinition, ToolRegistry, get_tool_registry
-from core.unified_tools import UnifiedToolGenerator
 
 __all__ = [
     # Authentication
@@ -64,11 +62,6 @@ __all__ = [
     "SiteManager",
     "SiteConfig",
     "get_site_manager",
-    # Legacy (deprecated)
-    "SiteRegistry",
-    "SiteInfo",
-    "get_site_registry",
-    "UnifiedToolGenerator",
     # Tool Management
     "ToolRegistry",
     "ToolDefinition",

mcphub_server-3.3.0/core/admin_utils.py

@@ -0,0 +1,27 @@
+"""Admin utility functions for role determination.
+
+Centralizes admin email checking so it can be used in OAuth callback,
+dashboard auth, and future admin/user panel unification (F.5+).
+"""
+
+import os
+
+
+def is_admin_email(email: str | None) -> bool:
+    """Check if an email is in the ADMIN_EMAILS env var list.
+
+    Args:
+        email: Email address to check.
+
+    Returns:
+        True if email matches an admin email (case-insensitive).
+    """
+    if not email:
+        return False
+
+    admin_emails_raw = os.environ.get("ADMIN_EMAILS", "")
+    if not admin_emails_raw.strip():
+        return False
+
+    admin_emails = {e.strip().lower() for e in admin_emails_raw.split(",") if e.strip()}
+    return email.strip().lower() in admin_emails

{mcphub_server-3.0.4 → mcphub_server-3.3.0}/core/api_keys.py

@@ -14,6 +14,8 @@ from dataclasses import asdict, dataclass
 from datetime import datetime, timedelta
 from pathlib import Path
 
+import bcrypt
+
 logger = logging.getLogger(__name__)
 
 
@@ -79,7 +81,7 @@ class APIKey:
     """
 
     key_id: str
-    key_hash: str
+    key_hash: str  # bcrypt hash (new keys) or SHA-256 hex (legacy)
     project_id: str
     scope: Scope
     created_at: str
@@ -180,8 +182,16 @@ class APIKeyManager:
             logger.error(f"Failed to save keys: {e}")
 
     def _hash_key(self, api_key: str) -> str:
-        """Hash API key for storage."""
-        return hashlib.sha256(api_key.encode()).hexdigest()
+        """Hash API key for storage using bcrypt."""
+        return bcrypt.hashpw(api_key.encode(), bcrypt.gensalt()).decode()
+
+    def _verify_key(self, api_key: str, key_hash: str) -> bool:
+        """Verify API key against stored hash (supports bcrypt and legacy SHA-256)."""
+        if key_hash.startswith("$2"):
+            # bcrypt hash
+            return bcrypt.checkpw(api_key.encode(), key_hash.encode())
+        # Legacy SHA-256 fallback
+        return hashlib.sha256(api_key.encode()).hexdigest() == key_hash
 
     def create_key(
         self,
@@ -269,11 +279,9 @@ class APIKeyManager:
         Returns:
             Optional[str]: key_id if valid, None otherwise
         """
-        key_hash = self._hash_key(api_key)
-
-        # Find key by hash
+        # Find key by verifying against stored hash (bcrypt or legacy SHA-256)
         for key_id, key in self.keys.items():
-            if key.key_hash != key_hash:
+            if not self._verify_key(api_key, key.key_hash):
                 continue
 
             # Check if valid (not revoked, not expired)
@@ -341,10 +349,8 @@ class APIKeyManager:
         Returns:
             Optional[APIKey]: The APIKey object if found, None otherwise
         """
-        key_hash = self._hash_key(api_key)
-
         for key_id, key in self.keys.items():
-            if key.key_hash == key_hash:
+            if self._verify_key(api_key, key.key_hash):
                 logger.debug(f"Found API key {key_id} by token")
                 return key
 

{mcphub_server-3.0.4 → mcphub_server-3.3.0}/core/auth.py

@@ -51,10 +51,13 @@ class AuthManager:
         Returns:
             bool: True if valid
         """
-        is_valid = secrets.compare_digest(api_key, self.master_api_key)
+        if not self.master_api_key:
+            return False
+
+        is_valid = secrets.compare_digest(api_key.strip(), self.master_api_key.strip())
 
         if not is_valid:
-            logger.warning("Invalid API key attempt")
+            logger.debug("Master key validation failed for provided token")
 
         return is_valid
 

mcphub_server-3.3.0/core/config_snippets.py

@@ -0,0 +1,128 @@
+"""MCP client configuration snippet generation (Track E.3).
+
+Generates copy-paste configuration snippets for connecting AI clients
+(Claude Desktop, Claude Code, Cursor, VS Code, ChatGPT) to per-user
+MCP endpoints.
+
+Usage:
+    from core.config_snippets import generate_config, get_supported_clients
+
+    snippet = generate_config(
+        base_url="https://mcp.example.com",
+        user_id="abc123",
+        alias="myblog",
+        api_key="mhu_...",
+        client_type="claude_desktop",
+    )
+"""
+
+import json
+
+# Supported MCP client types
+SUPPORTED_CLIENTS = [
+    {
+        "id": "claude_connectors",
+        "label": "Claude.ai Connectors",
+        "description": "claude.ai/customize/connectors",
+    },
+    {
+        "id": "claude_desktop",
+        "label": "Claude Desktop",
+        "description": "Anthropic's desktop app for Claude",
+    },
+    {
+        "id": "claude_code",
+        "label": "Claude Code",
+        "description": "Anthropic's CLI for Claude",
+    },
+    {
+        "id": "cursor",
+        "label": "Cursor",
+        "description": "AI-first code editor",
+    },
+    {
+        "id": "vscode",
+        "label": "VS Code",
+        "description": "Visual Studio Code with MCP extension",
+    },
+    {
+        "id": "chatgpt",
+        "label": "ChatGPT",
+        "description": "OpenAI ChatGPT (URL-based)",
+    },
+]
+
+# Clients that only need a URL (no JSON config snippet, no transport Note)
+WEB_CLIENTS = {"claude_connectors", "chatgpt"}
+
+
+def get_supported_clients() -> list[dict[str, str]]:
+    """Return the list of supported MCP client types."""
+    return SUPPORTED_CLIENTS
+
+
+def generate_config(
+    base_url: str,
+    user_id: str,
+    alias: str,
+    api_key: str,
+    client_type: str,
+) -> str:
+    """Generate a configuration snippet for the given MCP client.
+
+    Args:
+        base_url: Public URL of the MCP Hub instance (no trailing slash).
+        user_id: User UUID.
+        alias: Site alias.
+        api_key: User API key (``mhu_...``).
+        client_type: One of the supported client type IDs.
+
+    Returns:
+        JSON configuration string ready for copy-paste.
+
+    Raises:
+        ValueError: If client_type is not supported.
+    """
+    base_url = base_url.rstrip("/")
+    endpoint_url = f"{base_url}/u/{user_id}/{alias}/mcp"
+    server_name = f"mcphub-{alias}"
+
+    # Claude Desktop uses streamableHttp; Claude Code, VS Code, Cursor use http
+    transport_type = "streamableHttp" if client_type == "claude_desktop" else "http"
+
+    if client_type in ("claude_desktop", "claude_code"):
+        config = {
+            "mcpServers": {
+                server_name: {
+                    "type": transport_type,
+                    "url": endpoint_url,
+                    "headers": {
+                        "Authorization": f"Bearer {api_key}",
+                    },
+                }
+            }
+        }
+        return json.dumps(config, indent=2)
+
+    elif client_type in ("cursor", "vscode"):
+        config = {
+            "mcp": {
+                "servers": {
+                    server_name: {
+                        "type": transport_type,
+                        "url": endpoint_url,
+                        "headers": {
+                            "Authorization": f"Bearer {api_key}",
+                        },
+                    }
+                }
+            }
+        }
+        return json.dumps(config, indent=2)
+
+    elif client_type in ("claude_connectors", "chatgpt"):
+        return endpoint_url
+
+    else:
+        valid = [c["id"] for c in SUPPORTED_CLIENTS]
+        raise ValueError(f"Unsupported client type '{client_type}'. Valid: {valid}")

{mcphub_server-3.0.4 → mcphub_server-3.3.0}/core/dashboard/auth.py

@@ -89,19 +89,30 @@ class DashboardAuth:
         if not api_key:
             return False, "", None
 
+        api_key_clean = api_key.strip()
+        # Check if master key dashboard login is disabled
+        master_login_disabled = (
+            os.environ.get("DISABLE_MASTER_KEY_LOGIN", "false").lower() == "true"
+        )
+
         # Check master API key (from env var)
-        if self.master_api_key and secrets.compare_digest(api_key, self.master_api_key):
+        if (
+            not master_login_disabled
+            and self.master_api_key
+            and secrets.compare_digest(api_key_clean, self.master_api_key.strip())
+        ):
             return True, "master", None
 
         # Check AuthManager's master key (covers auto-generated temp keys)
-        try:
-            from core.auth import get_auth_manager
+        if not master_login_disabled:
+            try:
+                from core.auth import get_auth_manager
 
-            auth_mgr = get_auth_manager()
-            if auth_mgr.validate_master_key(api_key):
-                return True, "master", None
-        except Exception as e:
-            logger.debug(f"AuthManager check skipped: {e}")
+                auth_mgr = get_auth_manager()
+                if auth_mgr.validate_master_key(api_key):
+                    return True, "master", None
+            except Exception as e:
+                logger.debug(f"AuthManager check skipped: {e}")
 
         # Check project API keys with admin scope
         try:
@@ -202,6 +213,9 @@ class DashboardAuth:
                 user_type=payload["type"],
                 key_id=payload.get("kid"),
             )
+        except KeyError as e:
+            logger.debug(f"Invalid dashboard session payload (missing key): {e}")
+            return None
         except jwt.ExpiredSignatureError:
             logger.debug("Dashboard session expired")
             return None
@@ -224,6 +238,27 @@ class DashboardAuth:
             return None
         return self.validate_session(token)
 
+    def get_user_session_from_request(self, request: Request) -> dict | None:
+        """Extract and validate an OAuth user session from request.
+
+        Args:
+            request: Starlette request object.
+
+        Returns:
+            User session dict (user_id, email, name, role, type)
+            or None.
+        """
+        token = request.cookies.get(self.COOKIE_NAME)
+        if not token:
+            return None
+        try:
+            from core.user_auth import get_user_auth
+
+            user_auth = get_user_auth()
+            return user_auth.validate_user_session(token)
+        except (RuntimeError, Exception):
+            return None
+
     def set_session_cookie(self, response: Response, token: str) -> Response:
         """
         Set session cookie on response.
@@ -273,13 +308,15 @@ class DashboardAuth:
             RedirectResponse to login page if not authenticated, None if OK.
         """
         session = self.get_session_from_request(request)
-        if not session:
+        user_session = self.get_user_session_from_request(request)
+
+        if not session and not user_session:
             # Store original URL for redirect after login
             next_url = str(request.url.path)
             if request.url.query:
                 next_url += f"?{request.url.query}"
             return RedirectResponse(
-                url=f"/dashboard/login?next={next_url}",
+                url=f"/auth/login?next={next_url}",
                 status_code=303,
             )
         return None
@@ -291,3 +328,58 @@ def get_dashboard_auth() -> DashboardAuth:
     if _dashboard_auth is None:
         _dashboard_auth = DashboardAuth()
     return _dashboard_auth
+
+
+# ── Role-checking helpers ──────────────────────────────────────
+
+
+def is_admin_session(session) -> bool:
+    """Check if session is admin (master key or API key with admin scope).
+
+    Args:
+        session: DashboardSession or OAuth user dict.
+
+    Returns:
+        True if admin session.
+    """
+    if isinstance(session, DashboardSession):
+        return session.user_type in ("master", "api_key")
+    if isinstance(session, dict):
+        return session.get("type") == "master" or session.get("role") == "admin"
+    return False
+
+
+def get_session_display_info(session) -> dict:
+    """Get display info for header/UI.
+
+    Args:
+        session: DashboardSession or OAuth user dict.
+
+    Returns:
+        Dict with name, type, email, avatar keys.
+    """
+    if isinstance(session, DashboardSession):
+        return {"name": "Admin", "type": "admin", "email": None, "avatar": None}
+    if isinstance(session, dict):
+        session_type = "admin" if session.get("role") == "admin" else "user"
+        return {
+            "name": session.get("name") or session.get("email", "User"),
+            "type": session_type,
+            "email": session.get("email"),
+            "avatar": None,
+        }
+    return {"name": "Unknown", "type": "unknown", "email": None, "avatar": None}
+
+
+def get_session_user_id(session) -> str | None:
+    """Get user_id for OAuth sessions, None for admin.
+
+    Args:
+        session: DashboardSession or OAuth user dict.
+
+    Returns:
+        User UUID string or None.
+    """
+    if isinstance(session, dict):
+        return session.get("user_id")
+    return None