claude-mpm 5.6.1__py3-none-any.whl → 5.6.76__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-5.6.1
+5.6.76

claude_mpm/agents/PM_INSTRUCTIONS.md

@@ -294,6 +294,8 @@ If you're about to run ANY other command, stop and delegate instead.
 - Grep (>1), Glob (investigation) → Delegate to research
 - `mcp__mcp-ticketer__*` → Delegate to ticketing
 - `mcp__chrome-devtools__*` → Delegate to web-qa
+- `mcp__claude-in-chrome__*` → Delegate to web-qa
+- `mcp__playwright__*` → Delegate to web-qa
 
 ## Agent Deployment Architecture
 
@@ -358,7 +360,7 @@ These are EXAMPLES of routing, not an exhaustive list. **Default to delegation f
 | **Research** | Understanding codebase, investigating approaches, analyzing files | Grep, Glob, Read multiple files, WebSearch | Investigation tools |
 | **Engineer** | Writing/modifying code, implementing features, refactoring | Edit, Write, codebase knowledge, testing workflows | - |
 | **Ops** (local-ops) | Deploying apps, managing infrastructure, starting servers, port/process management | Environment config, deployment procedures | Use `local-ops` for localhost/PM2/docker |
-| **QA** (web-qa, api-qa) | Testing implementations, verifying deployments, regression tests, browser testing | Playwright (web), fetch (APIs), verification protocols | For browser: use **web-qa** (never use chrome-devtools directly) |
+| **QA** (web-qa, api-qa) | Testing implementations, verifying deployments, regression tests, browser testing | Playwright (web), fetch (APIs), verification protocols | For browser: use **web-qa** (never use chrome-devtools, claude-in-chrome, or playwright directly) |
 | **Documentation** | Creating/updating docs, README, API docs, guides | Style consistency, organization standards | - |
 | **Ticketing** | ALL ticket operations (CRUD, search, hierarchy, comments) | Direct mcp-ticketer access | PM never uses `mcp__mcp-ticketer__*` directly |
 | **Version Control** | Creating PRs, managing branches, complex git ops | PR workflows, branch management | Check git user for main branch access (bobmatnyc@users.noreply.github.com only) |
@@ -728,7 +730,7 @@ Circuit breakers automatically detect and enforce delegation requirements. All c
 | 3 | Unverified Assertions | PM claiming status without agent evidence | Require verification evidence | [Details](#circuit-breaker-3-unverified-assertions) |
 | 4 | File Tracking | PM marking task complete without tracking new files | Run git tracking sequence | [Details](#circuit-breaker-4-file-tracking-enforcement) |
 | 5 | Delegation Chain | PM claiming completion without full workflow delegation | Execute missing phases | [Details](#circuit-breaker-5-delegation-chain) |
-| 6 | Forbidden Tool Usage | PM using ticketing/browser MCP tools directly | Delegate to specialist agent | [Details](#circuit-breaker-6-forbidden-tool-usage) |
+| 6 | Forbidden Tool Usage | PM using ticketing/browser MCP tools (ticketer, chrome-devtools, claude-in-chrome, playwright) directly | Delegate to specialist agent | [Details](#circuit-breaker-6-forbidden-tool-usage) |
 | 7 | Verification Commands | PM using curl/lsof/ps/wget/nc | Delegate to local-ops or QA | [Details](#circuit-breaker-7-verification-command-detection) |
 | 8 | QA Verification Gate | PM claiming work complete without QA delegation | BLOCK - Delegate to QA now | [Details](#circuit-breaker-8-qa-verification-gate) |
 | 9 | User Delegation | PM instructing user to run commands | Delegate to appropriate agent | [Details](#circuit-breaker-9-user-delegation-detection) |
@@ -747,6 +749,9 @@ Circuit breakers automatically detect and enforce delegation requirements. All c
 - "It works" / "It's deployed" → Circuit Breaker #3
 - Marks todo complete without `git status` → Circuit Breaker #4
 - Uses `mcp__mcp-ticketer__*` → Circuit Breaker #6
+- Uses `mcp__chrome-devtools__*` → Circuit Breaker #6
+- Uses `mcp__claude-in-chrome__*` → Circuit Breaker #6
+- Uses `mcp__playwright__*` → Circuit Breaker #6
 - Uses curl/lsof directly → Circuit Breaker #7
 - Claims complete without QA → Circuit Breaker #8
 - "You'll need to run..." → Circuit Breaker #9
@@ -782,7 +787,7 @@ When the user says "just do it" or "handle it", delegate to the full workflow pi
 
 When the user says "verify", "check", or "test", delegate to the QA agent with specific verification criteria.
 
-When the user mentions "browser", "screenshot", "click", "navigate", "DOM", "console errors", delegate to web-qa agent for browser testing (NEVER use chrome-devtools tools directly).
+When the user mentions "browser", "screenshot", "click", "navigate", "DOM", "console errors", "tabs", "window", delegate to web-qa agent for browser testing (NEVER use chrome-devtools, claude-in-chrome, or playwright tools directly).
 
 When the user mentions "localhost", "local server", or "PM2", delegate to **local-ops** as the primary choice for local development operations.
 

claude_mpm/auth/__init__.py

@@ -0,0 +1,35 @@
+"""OAuth authentication module for MCP services.
+
+This module provides secure OAuth token management and callback handling
+for authenticating with MCP services that require OAuth2 flows.
+
+Core Components:
+    - OAuthToken: Token data model with expiration handling
+    - TokenStorage: Secure encrypted token persistence
+    - OAuthCallbackServer: Local HTTP server for OAuth callbacks
+    - OAuthProvider: Abstract base class for OAuth providers
+    - GoogleOAuthProvider: Google OAuth2 implementation
+"""
+
+from claude_mpm.auth.callback_server import OAuthCallbackServer
+from claude_mpm.auth.models import (
+    OAuthToken,
+    StoredToken,
+    TokenMetadata,
+    TokenStatus,
+)
+from claude_mpm.auth.oauth_manager import OAuthManager
+from claude_mpm.auth.providers import GoogleOAuthProvider, OAuthProvider
+from claude_mpm.auth.token_storage import TokenStorage
+
+__all__ = [
+    "GoogleOAuthProvider",
+    "OAuthCallbackServer",
+    "OAuthManager",
+    "OAuthProvider",
+    "OAuthToken",
+    "StoredToken",
+    "TokenMetadata",
+    "TokenStatus",
+    "TokenStorage",
+]

claude_mpm/auth/callback_server.py

@@ -0,0 +1,328 @@
+"""OAuth callback server for handling authorization redirects.
+
+This module provides a local HTTP server that handles OAuth2 callback
+redirects, capturing authorization codes and tokens from OAuth providers.
+
+Security Features:
+    - Binds only to localhost (127.0.0.1)
+    - CSRF protection via state parameter validation
+    - Automatic server shutdown after callback received
+    - Configurable timeout for callback wait
+"""
+
+import asyncio
+import secrets
+from dataclasses import dataclass, field
+from typing import Optional
+
+from aiohttp import web
+
+# Default port for OAuth callback server
+DEFAULT_PORT = 8789
+
+# HTML response templates
+SUCCESS_HTML = """
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Authorization Successful</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            height: 100vh;
+            margin: 0;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        }
+        .container {
+            background: white;
+            padding: 40px 60px;
+            border-radius: 12px;
+            box-shadow: 0 10px 40px rgba(0,0,0,0.2);
+            text-align: center;
+        }
+        .success-icon {
+            font-size: 64px;
+            margin-bottom: 20px;
+        }
+        h1 { color: #22c55e; margin: 0 0 10px 0; }
+        p { color: #666; margin: 0; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="success-icon">&#10004;</div>
+        <h1>Authorization Successful</h1>
+        <p>You can close this window and return to Claude.</p>
+    </div>
+</body>
+</html>
+"""
+
+ERROR_HTML = """
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Authorization Failed</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            height: 100vh;
+            margin: 0;
+            background: linear-gradient(135deg, #f87171 0%, #dc2626 100%);
+        }
+        .container {
+            background: white;
+            padding: 40px 60px;
+            border-radius: 12px;
+            box-shadow: 0 10px 40px rgba(0,0,0,0.2);
+            text-align: center;
+        }
+        .error-icon {
+            font-size: 64px;
+            margin-bottom: 20px;
+        }
+        h1 { color: #dc2626; margin: 0 0 10px 0; }
+        p { color: #666; margin: 0; }
+        .error-detail {
+            color: #999;
+            font-size: 14px;
+            margin-top: 15px;
+            padding: 10px;
+            background: #f5f5f5;
+            border-radius: 6px;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="error-icon">&#10006;</div>
+        <h1>Authorization Failed</h1>
+        <p>An error occurred during authorization.</p>
+        <div class="error-detail">{error}</div>
+    </div>
+</body>
+</html>
+"""
+
+
+@dataclass
+class CallbackResult:
+    """Result from an OAuth callback.
+
+    Attributes:
+        success: Whether the callback was successful.
+        code: Authorization code if successful.
+        state: State parameter from the callback.
+        error: Error message if unsuccessful.
+        error_description: Detailed error description from provider.
+    """
+
+    success: bool
+    code: Optional[str] = None
+    state: Optional[str] = None
+    error: Optional[str] = None
+    error_description: Optional[str] = None
+
+
+@dataclass
+class OAuthCallbackServer:
+    """Local HTTP server for OAuth2 callback handling.
+
+    This server listens on localhost for OAuth redirect callbacks,
+    captures the authorization code or token, and provides it to
+    the calling code.
+
+    The server implements CSRF protection by generating a unique
+    state parameter that must be validated in the callback.
+
+    Attributes:
+        port: Port to listen on, defaults to 8789.
+        host: Host to bind to, always 127.0.0.1 for security.
+
+    Example:
+        ```python
+        server = OAuthCallbackServer()
+        state = server.generate_state()
+
+        # Use server.callback_url and state in OAuth authorization URL
+        auth_url = f"https://provider.com/oauth/authorize?redirect_uri={server.callback_url}&state={state}"
+
+        # Wait for callback (user completes auth in browser)
+        result = await server.wait_for_callback(expected_state=state, timeout=300)
+
+        if result.success:
+            print(f"Got authorization code: {result.code}")
+        else:
+            print(f"Error: {result.error}")
+        ```
+    """
+
+    port: int = DEFAULT_PORT
+    host: str = field(default="127.0.0.1", init=False)
+    _state: Optional[str] = field(default=None, init=False, repr=False)
+    _result: Optional[CallbackResult] = field(default=None, init=False, repr=False)
+    _callback_received: asyncio.Event = field(
+        default_factory=asyncio.Event, init=False, repr=False
+    )
+
+    @property
+    def callback_url(self) -> str:
+        """Get the callback URL for OAuth configuration.
+
+        Returns:
+            The full callback URL including host and port.
+        """
+        return f"http://{self.host}:{self.port}/callback"
+
+    def generate_state(self) -> str:
+        """Generate a cryptographically secure state parameter.
+
+        The state parameter is used for CSRF protection in the OAuth flow.
+        It should be included in the authorization request and validated
+        when the callback is received.
+
+        Returns:
+            A 32-character URL-safe random string.
+        """
+        self._state = secrets.token_urlsafe(24)
+        return self._state
+
+    async def _handle_callback(self, request: web.Request) -> web.Response:
+        """Handle the OAuth callback request.
+
+        Args:
+            request: The incoming HTTP request.
+
+        Returns:
+            HTML response indicating success or failure.
+        """
+        # Extract query parameters
+        code = request.query.get("code")
+        state = request.query.get("state")
+        error = request.query.get("error")
+        error_description = request.query.get("error_description", "")
+
+        # Check for error from provider
+        if error:
+            self._result = CallbackResult(
+                success=False,
+                state=state,
+                error=error,
+                error_description=error_description,
+            )
+            self._callback_received.set()
+            return web.Response(
+                text=ERROR_HTML.format(error=f"{error}: {error_description}"),
+                content_type="text/html",
+            )
+
+        # Validate state parameter (CSRF protection)
+        if self._state and state != self._state:
+            self._result = CallbackResult(
+                success=False,
+                state=state,
+                error="state_mismatch",
+                error_description="State parameter does not match. Possible CSRF attack.",
+            )
+            self._callback_received.set()
+            return web.Response(
+                text=ERROR_HTML.format(error="State mismatch - possible CSRF attack"),
+                content_type="text/html",
+            )
+
+        # Check for authorization code
+        if not code:
+            self._result = CallbackResult(
+                success=False,
+                state=state,
+                error="missing_code",
+                error_description="No authorization code received.",
+            )
+            self._callback_received.set()
+            return web.Response(
+                text=ERROR_HTML.format(error="No authorization code received"),
+                content_type="text/html",
+            )
+
+        # Success
+        self._result = CallbackResult(
+            success=True,
+            code=code,
+            state=state,
+        )
+        self._callback_received.set()
+        return web.Response(text=SUCCESS_HTML, content_type="text/html")
+
+    async def wait_for_callback(
+        self,
+        expected_state: Optional[str] = None,
+        timeout: float = 300.0,
+    ) -> CallbackResult:
+        """Start the server and wait for an OAuth callback.
+
+        This method starts the HTTP server, waits for a callback request,
+        validates the state parameter, and returns the result.
+
+        Args:
+            expected_state: State parameter to validate against.
+                If not provided, uses the last generated state.
+            timeout: Maximum time to wait for callback in seconds.
+                Defaults to 300 seconds (5 minutes).
+
+        Returns:
+            CallbackResult containing the authorization code or error.
+
+        Raises:
+            asyncio.TimeoutError: If no callback received within timeout.
+        """
+        # Set expected state
+        if expected_state:
+            self._state = expected_state
+
+        # Reset state for new wait
+        self._result = None
+        self._callback_received.clear()
+
+        # Create aiohttp app and routes
+        app = web.Application()
+        app.router.add_get("/callback", self._handle_callback)
+
+        # Create and start runner
+        runner = web.AppRunner(app)
+        await runner.setup()
+
+        site = web.TCPSite(runner, self.host, self.port)
+        await site.start()
+
+        try:
+            # Wait for callback with timeout
+            await asyncio.wait_for(
+                self._callback_received.wait(),
+                timeout=timeout,
+            )
+
+            if self._result is None:
+                return CallbackResult(
+                    success=False,
+                    error="unknown_error",
+                    error_description="Callback received but no result set.",
+                )
+
+            return self._result
+
+        except asyncio.TimeoutError:
+            return CallbackResult(
+                success=False,
+                error="timeout",
+                error_description=f"No callback received within {timeout} seconds.",
+            )
+
+        finally:
+            # Clean up server
+            await runner.cleanup()

claude_mpm/auth/models.py

@@ -0,0 +1,104 @@
+"""OAuth data models for token management.
+
+This module defines Pydantic models for OAuth tokens and their metadata,
+providing type-safe token handling with automatic validation.
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class TokenStatus(str, Enum):
+    """Status of an OAuth token."""
+
+    VALID = "valid"
+    EXPIRED = "expired"
+    MISSING = "missing"
+    INVALID = "invalid"
+
+
+class OAuthToken(BaseModel):
+    """OAuth2 token data.
+
+    Represents the token response from an OAuth provider with
+    expiration tracking and scope management.
+
+    Attributes:
+        access_token: The access token string for API authentication.
+        refresh_token: Optional refresh token for token renewal.
+        expires_at: UTC timestamp when the access token expires.
+        scopes: List of granted OAuth scopes.
+        token_type: Token type, typically "Bearer".
+    """
+
+    access_token: str = Field(..., description="OAuth access token")
+    refresh_token: Optional[str] = Field(
+        default=None, description="OAuth refresh token for renewal"
+    )
+    expires_at: datetime = Field(..., description="Token expiration timestamp (UTC)")
+    scopes: list[str] = Field(default_factory=list, description="Granted OAuth scopes")
+    token_type: str = Field(default="Bearer", description="Token type")
+
+    def is_expired(self, buffer_seconds: int = 60) -> bool:
+        """Check if the token is expired or about to expire.
+
+        Args:
+            buffer_seconds: Number of seconds before actual expiration
+                to consider the token expired. Defaults to 60 seconds
+                to allow time for token refresh.
+
+        Returns:
+            True if the token is expired or will expire within the buffer period.
+        """
+        now = datetime.now(timezone.utc)
+        # Ensure expires_at is timezone-aware
+        expires_at = self.expires_at
+        if expires_at.tzinfo is None:
+            expires_at = expires_at.replace(tzinfo=timezone.utc)
+
+        from datetime import timedelta
+
+        return now >= (expires_at - timedelta(seconds=buffer_seconds))
+
+
+class TokenMetadata(BaseModel):
+    """Metadata about a stored OAuth token.
+
+    Tracks service information and timestamps for token lifecycle management.
+
+    Attributes:
+        service_name: Name of the MCP service this token authenticates.
+        provider: OAuth provider identifier (e.g., "github", "google").
+        created_at: When the token was first stored.
+        last_refreshed: When the token was last refreshed, if applicable.
+    """
+
+    service_name: str = Field(..., description="MCP service name")
+    provider: str = Field(..., description="OAuth provider identifier")
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="Token creation timestamp",
+    )
+    last_refreshed: Optional[datetime] = Field(
+        default=None, description="Last token refresh timestamp"
+    )
+
+
+class StoredToken(BaseModel):
+    """Complete stored token with metadata and versioning.
+
+    This is the top-level structure persisted to storage, containing
+    both the token data and metadata needed for management.
+
+    Attributes:
+        version: Schema version for future migration support.
+        metadata: Token metadata including service and provider info.
+        token: The actual OAuth token data.
+    """
+
+    version: int = Field(default=1, description="Schema version for migrations")
+    metadata: TokenMetadata = Field(..., description="Token metadata")
+    token: OAuthToken = Field(..., description="OAuth token data")