quickcall-integrations 0.1.8__py3-none-any.whl → 0.2.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 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:
@@ -292,44 +348,155 @@ 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)",
+        ),
+    ) -> 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
+
+        Returns: number, title, body, merged_at, labels, repo, owner, html_url, author.
+        For full stats (additions, deletions, files), call get_pr on specific PRs.
+
+        Requires QuickCall authentication with GitHub connected.
         """
-        store = get_credential_store()
+        try:
+            client = _get_client()
 
-        if not store.is_authenticated():
-            return {
-                "connected": False,
-                "error": "Not connected to QuickCall. Run connect_quickcall first.",
-            }
+            # Calculate since_date from days
+            from datetime import datetime, timedelta
 
-        creds = store.get_api_credentials()
+            since_date = (datetime.utcnow() - timedelta(days=days)).strftime("%Y-%m-%d")
 
-        if not creds:
-            return {
-                "connected": False,
-                "error": "Could not fetch credentials from QuickCall.",
-            }
+            # 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,
+            )
 
-        if not creds.github_connected:
             return {
-                "connected": False,
-                "error": "GitHub not connected. Connect at quickcall.dev/assistant.",
+                "count": len(prs),
+                "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)}")
 
+    @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 {

{quickcall_integrations-0.1.8.dist-info → quickcall_integrations-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickcall-integrations
-Version: 0.1.8
+Version: 0.2.0
 Summary: MCP server with developer integrations for Claude Code and Cursor
 Requires-Python: >=3.10
 Requires-Dist: fastmcp>=2.13.0
@@ -26,8 +26,9 @@ Description-Content-Type: text/markdown
 </p>
 
 <p align="center">
-  <a href="#integrations">Integrations</a> |
   <a href="#install">Install</a> |
+  <a href="#capabilities">Capabilities</a> |
+  <a href="#integrations">Integrations</a> |
   <a href="#authentication">Authentication</a> |
   <a href="#commands">Commands</a> |
   <a href="#troubleshooting">Troubleshooting</a>
@@ -35,6 +36,42 @@ Description-Content-Type: text/markdown
 
 ---
 
+## Install
+
+### Claude Code
+
+**In your terminal:**
+```bash
+claude mcp add quickcall -- uvx quickcall-integrations
+```
+
+**In Claude Code:**
+```
+/plugin marketplace add quickcall-dev/quickcall-integrations
+```
+```
+/plugin enable quickcall
+```
+
+**Restart Claude Code**, then verify with `/mcp` and `/plugin list`.
+
+### Cursor / Other IDEs
+
+Add to MCP config (`~/.cursor/mcp.json` or `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "quickcall": {
+      "command": "uvx",
+      "args": ["quickcall-integrations"]
+    }
+  }
+}
+```
+
+> Works with any IDE that supports MCP servers.
+
 ## Capabilities
 
 - **Get standup updates** from git history (commits, diffs, stats)
@@ -99,56 +136,10 @@ Description-Content-Type: text/markdown
 
 </details>
 
-## Install
-
-### Claude Code
-
-```
-/plugin marketplace add quickcall-dev/quickcall-integrations
-/plugin install quickcall@quickcall-integrations
-```
-
-<details>
-<summary>MCP only (without plugin)</summary>
-
-```bash
-claude mcp add quickcall -- uvx quickcall-integrations
-```
-</details>
-
-<details>
-<summary>Update to latest version</summary>
-
-```
-/plugin marketplace update quickcall-integrations
-/plugin uninstall quickcall
-/plugin install quickcall@quickcall-integrations
-```
-
-After updating, restart Claude Code or open a new terminal.
-</details>
-
-### Cursor
-
-Add to your Cursor MCP config (`~/.cursor/mcp.json` for global, or `.cursor/mcp.json` for project):
-
-```json
-{
-  "mcpServers": {
-    "quickcall": {
-      "command": "uvx",
-      "args": ["quickcall-integrations"]
-    }
-  }
-}
-```
-
-Then restart Cursor.
-
-> Also works with [Antigravity](https://antigravity.dev) and any other IDE that supports MCP servers.
-
 ## Authentication
 
+### Option 1: QuickCall (Recommended)
+
 To use GitHub and Slack integrations, connect your QuickCall account:
 
 ```
@@ -162,6 +153,30 @@ This will guide you through:
 
 Credentials are stored locally in `~/.quickcall/credentials.json`.
 
+### Option 2: GitHub PAT (For Enterprise Users)
+
+If your organization can't install the QuickCall GitHub App (common at enterprises with strict app policies), you can use a Personal Access Token instead:
+
+**Environment Variable:**
+```bash
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
+```
+
+**Or config file** (create `.quickcall.env` in your project root or home directory):
+```bash
+# .quickcall.env
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
+GITHUB_USERNAME=your-username  # Optional: for better UX
+```
+
+**Create a PAT at:** https://github.com/settings/tokens
+
+**Required scopes:**
+- `repo` - Full access to private repositories
+- `public_repo` - Access to public repositories only (if you don't need private repos)
+
+**Note:** PAT mode provides access to GitHub tools only. For Slack integration, use QuickCall authentication.
+
 ## Commands
 
 ### Claude Code
@@ -214,27 +229,22 @@ What did I work on this week? Send summary to #standup
 
 ## Troubleshooting
 
-### Plugin Not Updating?
+### Clean Reinstall
 
-If new commands don't appear after updating, clear the cache:
+If commands don't appear or aren't updating:
 
 ```bash
+# Remove everything
 rm -rf ~/.claude/plugins/cache/quickcall-integrations
 rm -rf ~/.claude/plugins/marketplaces/quickcall-integrations
+claude mcp remove quickcall
 ```
 
-Then restart Claude Code and reinstall:
-
-```
-/plugin marketplace add quickcall-dev/quickcall-integrations
-/plugin install quickcall@quickcall-integrations
-```
+Then follow the [install steps](#claude-code) again.
 
 ### Commands Not Showing?
 
-Type `/quickcall:` - you should see `connect`, `status`, `updates`.
-
-If only `updates` shows, run the cleanup above and reinstall.
+Type `/quickcall:` - you should see `connect`, `status`, `updates`. If not, do a clean reinstall above.
 
 ---
 

{quickcall_integrations-0.1.8.dist-info → quickcall_integrations-0.2.0.dist-info}/RECORD

@@ -1,20 +1,20 @@
 mcp_server/__init__.py,sha256=UJBr5BLG_aU2S4s2fEbRBZYd7GUWDVejxBpqezNBo8Q,98
 mcp_server/server.py,sha256=zGrrYwp7H24pJAAGAVkHDk7Y6IydOR_wo5hIL-e6_50,3001
 mcp_server/api_clients/__init__.py,sha256=kOG5_sxIVpAx_tvf1nq_P0QCkqojAVidRE-wenLS-Wc,207
-mcp_server/api_clients/github_client.py,sha256=KnF0hZ8ThBSmUVF9sgviMk5hrUe6GAgmQXY-EkOPwsM,14474
+mcp_server/api_clients/github_client.py,sha256=Ddnekr2Jz4_dOpf1lmgdhBHB2Kr5WjC67-W_j2AZkK0,20772
 mcp_server/api_clients/slack_client.py,sha256=w3rcGghttfYw8Ird2beNo2LEYLc3rCTbUKMH4X7QQuQ,16447
-mcp_server/auth/__init__.py,sha256=YQpDPH5itIaBuEm0AtwNCHxTX4L5dLutTximVamsItw,552
-mcp_server/auth/credentials.py,sha256=OCPs_4DcQ1zHEBgkcPDNCHVFFO36Xe6_QBx_5Jn2xgk,9379
+mcp_server/auth/__init__.py,sha256=D-JS0Qe7FkeJjYx92u_AqPx8ZRoB3dKMowzzJXlX6cc,780
+mcp_server/auth/credentials.py,sha256=1e1FpiaPPVc5hVdLlvIU2JbhbdHbXH9pzYBDPsUr0hI,20003
 mcp_server/auth/device_flow.py,sha256=NXNWHzd-CA4dlhEVCgUhwfpe9TpMKpLSJuyFCh70xKs,8371
 mcp_server/resources/__init__.py,sha256=JrMa3Kf-DmeCB4GwVNfmfw9OGnxF9pJJxCw9Y7u7ujQ,35
 mcp_server/resources/slack_resources.py,sha256=b_CPxAicwkF3PsBXIat4QoLbDUHM2g_iPzgzvVpwjaw,1687
 mcp_server/tools/__init__.py,sha256=vIR2ujAaTXm2DgpTsVNz3brI4G34p-Jeg44Qe0uvWc0,405
-mcp_server/tools/auth_tools.py,sha256=yev9UZi-i842JPx_9IgGf7pWChEQzSXRiICsHo46s9Q,17853
-mcp_server/tools/git_tools.py,sha256=5cZfngkP1wHNYUvGtLFcMjS7bhrFzxAC_TPz0h3CUB0,7691
-mcp_server/tools/github_tools.py,sha256=GomR88SByAbdi4VHk1vaUNp29hwWEIY6cX1t9QoMDOU,10972
+mcp_server/tools/auth_tools.py,sha256=kCPjPC1jrVz0XaRAwPea-ue8ybjLLTxyILplBDJ9Mv4,24477
+mcp_server/tools/git_tools.py,sha256=jyCTQR2eSzUFXMt0Y8x66758-VY8YCY14DDUJt7GY2U,13957
+mcp_server/tools/github_tools.py,sha256=r5HgYQIxdV8KQO5G5lAR3z3XK9moyrQgA84IH0hJKI4,17727
 mcp_server/tools/slack_tools.py,sha256=-HVE_x3Z1KMeYGi1xhyppEwz5ZF-I-ZD0-Up8yBeoYE,11796
 mcp_server/tools/utility_tools.py,sha256=1WiOpJivu6Ug9OLajm77lzsmFfBPgWHs8e1hNCEX_Aw,3359
-quickcall_integrations-0.1.8.dist-info/METADATA,sha256=MK4ehZKL17rzpQs5Rmun3y-KN8L5FNu8c9w-Cde06wo,6576
-quickcall_integrations-0.1.8.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-quickcall_integrations-0.1.8.dist-info/entry_points.txt,sha256=kkcunmJUzncYvQ1rOR35V2LPm2HcFTKzdI2l3n7NwiM,66
-quickcall_integrations-0.1.8.dist-info/RECORD,,
+quickcall_integrations-0.2.0.dist-info/METADATA,sha256=y_LgEAseZRBLdxQGRiIl9kjlfDe6rtSY5SmEtnV6VCU,7043
+quickcall_integrations-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+quickcall_integrations-0.2.0.dist-info/entry_points.txt,sha256=kkcunmJUzncYvQ1rOR35V2LPm2HcFTKzdI2l3n7NwiM,66
+quickcall_integrations-0.2.0.dist-info/RECORD,,