quickcall-integrations 0.1.8__py3-none-any.whl → 0.3.0__py3-none-any.whl

mcp_server/tools/github_tools.py

@@ -1,54 +1,110 @@
 """
 GitHub Tools - Pull requests and commits via GitHub API.
 
-These tools require authentication via QuickCall.
-Connect using connect_quickcall tool first.
+Authentication (in priority order):
+1. QuickCall GitHub App (preferred) - connect via connect_quickcall
+2. Personal Access Token (PAT) - set GITHUB_TOKEN env var or use .quickcall.env file
+
+PAT fallback is useful for:
+- Users at organizations that can't install the GitHub App
+- Personal repositories without app installation
+- Testing and development
 """
 
-from typing import Optional
+from typing import List, Optional, Tuple
 import logging
 
 from fastmcp import FastMCP
 from fastmcp.exceptions import ToolError
 from pydantic import Field
 
-from mcp_server.auth import get_credential_store, is_authenticated
+from mcp_server.auth import (
+    get_credential_store,
+    get_github_pat,
+    get_github_pat_username,
+)
 from mcp_server.api_clients.github_client import GitHubClient
 
 logger = logging.getLogger(__name__)
 
 
+# Track whether we're using PAT mode for status reporting
+_using_pat_mode: bool = False
+_pat_source: Optional[str] = None
+
+
 def _get_client() -> GitHubClient:
-    """Get the GitHub client, raising error if not configured."""
+    """
+    Get the GitHub client using the best available authentication method.
+
+    Authentication priority:
+    1. QuickCall GitHub App (if connected and working)
+    2. Personal Access Token from environment/config file
+
+    Raises:
+        ToolError: If no authentication method is available
+    """
+    global _using_pat_mode, _pat_source
+
     store = get_credential_store()
 
-    if not store.is_authenticated():
-        raise ToolError(
-            "Not connected to QuickCall. "
-            "Run connect_quickcall to authenticate and enable GitHub tools."
+    # Try QuickCall GitHub App first (preferred)
+    if store.is_authenticated():
+        creds = store.get_api_credentials()
+        if creds and creds.github_connected and creds.github_token:
+            _using_pat_mode = False
+            _pat_source = None
+            return GitHubClient(
+                token=creds.github_token,
+                default_owner=creds.github_username,
+                installation_id=creds.github_installation_id,
+            )
+
+    # Try PAT fallback
+    pat_token, pat_source = get_github_pat()
+    if pat_token:
+        _using_pat_mode = True
+        _pat_source = pat_source
+        pat_username = get_github_pat_username()
+        logger.info(f"Using GitHub PAT from {pat_source}")
+        return GitHubClient(
+            token=pat_token,
+            default_owner=pat_username,
+            installation_id=None,  # No installation ID for PAT
         )
 
-    # Fetch fresh credentials from API
-    creds = store.get_api_credentials()
+    # No authentication available - provide helpful error message
+    _using_pat_mode = False
+    _pat_source = None
 
-    if not creds or not creds.github_connected:
+    if store.is_authenticated():
+        # Connected to QuickCall but GitHub not connected
         raise ToolError(
-            "GitHub not connected. "
-            "Connect GitHub at quickcall.dev/assistant to enable GitHub tools."
+            "GitHub not connected. Options:\n"
+            "1. Connect GitHub App at quickcall.dev/assistant (recommended)\n"
+            "2. Run connect_github_via_pat with your Personal Access Token\n"
+            "3. Set GITHUB_TOKEN environment variable"
         )
-
-    if not creds.github_token:
+    else:
+        # Not connected to QuickCall at all
         raise ToolError(
-            "Could not fetch GitHub token. "
-            "Try reconnecting GitHub at quickcall.dev/assistant."
+            "GitHub authentication required. Options:\n"
+            "1. Run connect_quickcall to use QuickCall (full access to GitHub + Slack)\n"
+            "2. Run connect_github_via_pat with a Personal Access Token (GitHub only)\n"
+            "3. Set GITHUB_TOKEN environment variable\n\n"
+            "For PAT: Create token at https://github.com/settings/tokens\n"
+            "Required scopes: repo (private) or public_repo (public only)"
         )
 
-    # Create client with fresh token and installation ID
-    return GitHubClient(
-        token=creds.github_token,
-        default_owner=creds.github_username,
-        installation_id=creds.github_installation_id,
-    )
+
+def is_using_pat_mode() -> Tuple[bool, Optional[str]]:
+    """
+    Check if GitHub tools are using PAT mode.
+
+    Returns:
+        Tuple of (is_using_pat, source) where source is where the PAT was loaded from.
+    """
+    return (_using_pat_mode, _pat_source)
 
 
 def create_github_tools(mcp: FastMCP) -> None:
@@ -98,19 +154,34 @@ def create_github_tools(mcp: FastMCP) -> None:
             default=20,
             description="Maximum number of PRs to return (default: 20)",
         ),
+        detail_level: str = Field(
+            default="summary",
+            description="'summary' for minimal fields (~200 bytes/PR: number, title, state, author, merged_at, html_url), "
+            "'full' for all fields (~2KB/PR). Use 'summary' for large result sets, 'full' for detailed analysis.",
+        ),
     ) -> dict:
         """
         List pull requests for a GitHub repository.
 
         Returns PRs sorted by last updated.
         Requires QuickCall authentication with GitHub connected.
+
+        Use detail_level='summary' (default) to avoid context overflow with large result sets.
+        Use get_pr(number) to get full details for specific PRs when needed.
         """
         try:
             client = _get_client()
-            prs = client.list_prs(owner=owner, repo=repo, state=state, limit=limit)
+            prs = client.list_prs(
+                owner=owner,
+                repo=repo,
+                state=state,
+                limit=limit,
+                detail_level=detail_level,
+            )
 
             return {
                 "count": len(prs),
+                "detail_level": detail_level,
                 "prs": [pr.model_dump() for pr in prs],
             }
         except ToolError:
@@ -185,12 +256,20 @@ def create_github_tools(mcp: FastMCP) -> None:
             default=20,
             description="Maximum number of commits to return (default: 20)",
         ),
+        detail_level: str = Field(
+            default="summary",
+            description="'summary' for minimal fields (short sha, message title, author, date, url), "
+            "'full' for all fields including full commit message. Use 'summary' for large result sets.",
+        ),
     ) -> dict:
         """
         List commits for a GitHub repository.
 
         Returns commits sorted by date (newest first).
         Requires QuickCall authentication with GitHub connected.
+
+        Use detail_level='summary' (default) to avoid context overflow with large result sets.
+        Use get_commit(sha) to get full details for specific commits when needed.
         """
         try:
             client = _get_client()
@@ -201,10 +280,12 @@ def create_github_tools(mcp: FastMCP) -> None:
                 author=author,
                 since=since,
                 limit=limit,
+                detail_level=detail_level,
             )
 
             return {
                 "count": len(commits),
+                "detail_level": detail_level,
                 "commits": [commit.model_dump() for commit in commits],
             }
         except ToolError:
@@ -292,44 +373,334 @@ def create_github_tools(mcp: FastMCP) -> None:
         except Exception as e:
             raise ToolError(f"Failed to list branches: {str(e)}")
 
-    @mcp.tool(tags={"github", "status"})
-    def check_github_connection() -> dict:
+    @mcp.tool(tags={"github", "prs", "appraisal"})
+    def search_merged_prs(
+        author: Optional[str] = Field(
+            default=None,
+            description="GitHub username to filter by. Defaults to authenticated user if not specified.",
+        ),
+        days: int = Field(
+            default=180,
+            description="Number of days to look back (default: 180 for ~6 months)",
+        ),
+        org: Optional[str] = Field(
+            default=None,
+            description="GitHub org to search within. If not specified, searches all accessible repos.",
+        ),
+        repo: Optional[str] = Field(
+            default=None,
+            description="Specific repo in 'owner/repo' format (e.g., 'revolving-org/supabase'). Overrides org if specified.",
+        ),
+        limit: int = Field(
+            default=100,
+            description="Maximum PRs to return (default: 100)",
+        ),
+        detail_level: str = Field(
+            default="summary",
+            description="'summary' for minimal fields (number, title, merged_at, repo, owner, html_url, author), "
+            "'full' adds body and labels. Use 'summary' for large result sets.",
+        ),
+    ) -> dict:
         """
-        Check if GitHub is connected and working.
+        Search for merged pull requests by author within a time period.
 
-        Tests the GitHub connection by fetching your account info.
-        Use this to verify your GitHub integration is working.
+        USE FOR APPRAISALS: This tool is ideal for gathering contribution data
+        for performance reviews. Returns basic PR info - use get_pr for full
+        details (additions, deletions, files) on specific PRs.
+
+        Claude should analyze the returned PRs to:
+
+        1. CATEGORIZE by type (look at PR title/labels):
+           - Features: "feat:", "add:", "implement", "new", "create"
+           - Enhancements: "improve:", "update:", "perf:", "optimize", "enhance"
+           - Bug fixes: "fix:", "bugfix:", "hotfix:", "resolve", "patch"
+           - Chores: "chore:", "docs:", "test:", "ci:", "refactor:", "bump"
+
+        2. IDENTIFY top PRs worth highlighting (call get_pr for detailed metrics)
+
+        3. SUMMARIZE for appraisal with accomplishments grouped by category
+
+        Use detail_level='summary' (default) to avoid context overflow with large result sets.
+        Use get_pr(number) to get full details for specific PRs when needed.
+
+        Requires QuickCall authentication with GitHub connected.
         """
-        store = get_credential_store()
+        try:
+            client = _get_client()
+
+            # Calculate since_date from days
+            from datetime import datetime, timedelta, timezone
+
+            since_date = (datetime.now(timezone.utc) - timedelta(days=days)).strftime(
+                "%Y-%m-%d"
+            )
+
+            # Use authenticated user if author not specified
+            if not author:
+                creds = get_credential_store().get_api_credentials()
+                if creds and creds.github_username:
+                    author = creds.github_username
+
+            prs = client.search_merged_prs(
+                author=author,
+                since_date=since_date,
+                org=org,
+                repo=repo,
+                limit=limit,
+                detail_level=detail_level,
+            )
 
-        if not store.is_authenticated():
             return {
-                "connected": False,
-                "error": "Not connected to QuickCall. Run connect_quickcall first.",
+                "count": len(prs),
+                "detail_level": detail_level,
+                "period": f"Last {days} days",
+                "author": author,
+                "org": org,
+                "repo": repo,
+                "prs": prs,
             }
+        except ToolError:
+            raise
+        except Exception as e:
+            raise ToolError(f"Failed to search merged PRs: {str(e)}")
 
-        creds = store.get_api_credentials()
+    @mcp.tool(tags={"github", "prs", "appraisal"})
+    def prepare_appraisal_data(
+        author: Optional[str] = Field(
+            default=None,
+            description="GitHub username. Defaults to authenticated user.",
+        ),
+        days: int = Field(
+            default=180,
+            description="Number of days to look back (default: 180 for ~6 months)",
+        ),
+        org: Optional[str] = Field(
+            default=None,
+            description="GitHub org to search within.",
+        ),
+        repo: Optional[str] = Field(
+            default=None,
+            description="Specific repo in 'owner/repo' format.",
+        ),
+    ) -> dict:
+        """
+        Prepare appraisal data by fetching ALL merged PRs with full details.
+
+        This tool:
+        1. Searches for all merged PRs by the author
+        2. Fetches FULL details (additions, deletions, files) for each PR IN PARALLEL
+        3. Dumps everything to a JSON file for later queries
+        4. Returns the file path + list of PR titles for Claude to review
+
+        USE THIS for appraisals instead of search_merged_prs + multiple get_pr calls.
+        After calling this, use get_appraisal_pr_details to get full info for specific PRs.
+        """
+        import json
+        import tempfile
+        from datetime import datetime, timedelta, timezone
+
+        try:
+            client = _get_client()
+
+            since_date = (datetime.now(timezone.utc) - timedelta(days=days)).strftime(
+                "%Y-%m-%d"
+            )
+
+            # Use authenticated user if author not specified
+            if not author:
+                creds = get_credential_store().get_api_credentials()
+                if creds and creds.github_username:
+                    author = creds.github_username
+
+            # Step 1: Get list of merged PRs
+            pr_list = client.search_merged_prs(
+                author=author,
+                since_date=since_date,
+                org=org,
+                repo=repo,
+                limit=100,
+                detail_level="full",  # Get body/labels from search
+            )
+
+            if not pr_list:
+                return {
+                    "count": 0,
+                    "message": "No merged PRs found for the specified criteria",
+                    "author": author,
+                    "period": f"Last {days} days",
+                }
+
+            # Step 2: Prepare refs for parallel fetch
+            pr_refs = [
+                {"owner": pr["owner"], "repo": pr["repo"], "number": pr["number"]}
+                for pr in pr_list
+            ]
+
+            # Step 3: Fetch full details in parallel
+            full_prs = client.fetch_prs_parallel(pr_refs, max_workers=10)
+
+            # Step 4: Merge search data with full PR data
+            # (search has body/labels, full PR has additions/deletions/files)
+            pr_lookup = {(pr["owner"], pr["repo"], pr["number"]): pr for pr in pr_list}
+            for pr in full_prs:
+                key = (pr["owner"], pr["repo"], pr["number"])
+                if key in pr_lookup:
+                    # Add labels from search (not in PyGithub response for some reason)
+                    search_pr = pr_lookup[key]
+                    if "labels" in search_pr:
+                        pr["labels"] = search_pr["labels"]
+
+            # Step 5: Dump to file
+            dump_data = {
+                "author": author,
+                "period": f"Last {days} days",
+                "org": org,
+                "repo": repo,
+                "fetched_at": datetime.now(timezone.utc).isoformat(),
+                "count": len(full_prs),
+                "prs": full_prs,
+            }
+
+            # Create temp file that persists
+            fd, file_path = tempfile.mkstemp(suffix=".json", prefix="appraisal_")
+            with open(file_path, "w") as f:
+                json.dump(dump_data, f, indent=2, default=str)
+
+            # Step 6: Return file path + just titles for Claude to scan
+            pr_titles = [
+                {
+                    "number": pr["number"],
+                    "title": pr["title"],
+                    "repo": f"{pr['owner']}/{pr['repo']}",
+                }
+                for pr in full_prs
+            ]
 
-        if not creds:
             return {
-                "connected": False,
-                "error": "Could not fetch credentials from QuickCall.",
+                "file_path": file_path,
+                "count": len(full_prs),
+                "author": author,
+                "period": f"Last {days} days",
+                "pr_titles": pr_titles,
+                "next_step": "Review titles above, then call "
+                "get_appraisal_pr_details(file_path, pr_numbers) for full details on selected PRs.",
             }
 
-        if not creds.github_connected:
+        except ToolError:
+            raise
+        except Exception as e:
+            raise ToolError(f"Failed to prepare appraisal data: {str(e)}")
+
+    @mcp.tool(tags={"github", "prs", "appraisal"})
+    def get_appraisal_pr_details(
+        file_path: str = Field(
+            ...,
+            description="Path to the appraisal data file from prepare_appraisal_data",
+        ),
+        pr_numbers: List[int] = Field(
+            ..., description="List of PR numbers to get full details for"
+        ),
+    ) -> dict:
+        """
+        Get full PR details from the appraisal data dump.
+
+        This reads from the local file created by prepare_appraisal_data.
+        NO API CALLS are made - all data comes from the cached dump.
+
+        Use this after prepare_appraisal_data to get full details for specific PRs
+        that Claude has identified as important for the appraisal.
+        """
+        import json
+
+        try:
+            with open(file_path) as f:
+                data = json.load(f)
+
+            pr_numbers_set = set(pr_numbers)
+            selected_prs = [
+                pr for pr in data.get("prs", []) if pr["number"] in pr_numbers_set
+            ]
+
             return {
-                "connected": False,
-                "error": "GitHub not connected. Connect at quickcall.dev/assistant.",
+                "count": len(selected_prs),
+                "requested": len(pr_numbers),
+                "prs": selected_prs,
             }
 
+        except FileNotFoundError:
+            raise ToolError(f"Appraisal data file not found: {file_path}")
+        except json.JSONDecodeError:
+            raise ToolError(f"Invalid JSON in appraisal data file: {file_path}")
+        except Exception as e:
+            raise ToolError(f"Failed to read appraisal data: {str(e)}")
+
+    @mcp.tool(tags={"github", "status"})
+    def check_github_connection() -> dict:
+        """
+        Check if GitHub is connected and working.
+
+        Tests the GitHub connection by fetching your account info.
+        Shows whether using QuickCall GitHub App or PAT fallback.
+        Use this to verify your GitHub integration is working.
+        """
+        store = get_credential_store()
+
+        # First, try to get a working client (this handles both QuickCall and PAT)
         try:
             client = _get_client()
-            username = client.get_authenticated_user()
+            using_pat, pat_source = is_using_pat_mode()
+
+            # Try to get username to verify connection works
+            try:
+                username = client.get_authenticated_user()
+            except Exception:
+                username = None
+
+            if using_pat:
+                return {
+                    "connected": True,
+                    "mode": "pat",
+                    "pat_source": pat_source,
+                    "username": username or get_github_pat_username(),
+                    "note": "Using Personal Access Token (PAT) mode. "
+                    "Some features like list_repos may have limited access.",
+                }
+            else:
+                creds = store.get_api_credentials()
+                return {
+                    "connected": True,
+                    "mode": "github_app",
+                    "username": username or (creds.github_username if creds else None),
+                    "installation_id": creds.github_installation_id if creds else None,
+                }
+        except ToolError as e:
+            # No authentication available
+            pat_token, _ = get_github_pat()
+            if pat_token:
+                # PAT exists but failed to work
+                return {
+                    "connected": False,
+                    "error": "PAT authentication failed. Token may be invalid or expired.",
+                    "suggestion": "Check your GITHUB_TOKEN or .quickcall.env file.",
+                }
+
+            # Check QuickCall status for helpful error
+            if store.is_authenticated():
+                creds = store.get_api_credentials()
+                if creds and not creds.github_connected:
+                    return {
+                        "connected": False,
+                        "error": "GitHub not connected via QuickCall.",
+                        "suggestions": [
+                            "Connect GitHub App at quickcall.dev/assistant",
+                            "Or set GITHUB_TOKEN environment variable",
+                            "Or create .quickcall.env with GITHUB_TOKEN=ghp_xxx",
+                        ],
+                    }
 
             return {
-                "connected": True,
-                "username": username,
-                "installation_id": creds.github_installation_id,
+                "connected": False,
+                "error": str(e),
             }
         except Exception as e:
             return {