quickcall-integrations 0.3.1__tar.gz → 0.3.3__tar.gz

{quickcall_integrations-0.3.1 → quickcall_integrations-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickcall-integrations
-Version: 0.3.1
+Version: 0.3.3
 Summary: MCP server with developer integrations for Claude Code and Cursor
 Requires-Python: >=3.10
 Requires-Dist: fastmcp>=2.13.0

{quickcall_integrations-0.3.1 → quickcall_integrations-0.3.3}/mcp_server/tools/github_tools.py

@@ -164,10 +164,8 @@ def create_github_tools(mcp: FastMCP) -> None:
         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.
+        Use detail_level='summary' (default) to avoid context overflow.
+        Use get_prs() to fetch full details for specific PRs.
         """
         try:
             client = _get_client()
@@ -286,10 +284,8 @@ def create_github_tools(mcp: FastMCP) -> None:
         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.
+        Use detail_level='summary' (default) to avoid context overflow.
+        Use get_commit(sha) for full details on a specific commit.
         """
         try:
             client = _get_client()
@@ -393,84 +389,6 @@ def create_github_tools(mcp: FastMCP) -> None:
         except Exception as e:
             raise ToolError(f"Failed to list branches: {str(e)}")
 
-    @mcp.tool(tags={"github", "prs"})
-    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:
-        """
-        Search for merged pull requests by author within a time period.
-
-        NOTE: For appraisals/performance reviews, use prepare_appraisal_data instead!
-        It fetches all PRs with full stats in parallel and avoids context overflow.
-
-        This tool returns basic PR info without stats (additions, deletions).
-        Use detail_level='summary' (default) for large result sets.
-
-        Requires QuickCall authentication with GitHub connected.
-        """
-        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,
-            )
-
-            return {
-                "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)}")
-
     @mcp.tool(tags={"github", "prs", "appraisal"})
     def prepare_appraisal_data(
         author: Optional[str] = Field(
@@ -491,18 +409,17 @@ def create_github_tools(mcp: FastMCP) -> None:
         ),
     ) -> dict:
         """
-        Prepare appraisal data by fetching ALL merged PRs with full details.
-
-        USE THIS TOOL FOR APPRAISALS AND PERFORMANCE REVIEWS!
+        Fetch all merged PRs for appraisals/performance reviews.
 
-        This is the recommended tool for gathering contribution data because it:
-        1. Fetches ALL merged PRs with full stats (additions, deletions) in PARALLEL
-        2. Dumps everything to a local file (avoids context overflow)
-        3. Returns just PR titles for you to review
-        4. Then use get_appraisal_pr_details(file_path, pr_numbers) for selected PRs
+        Returns:
+        - file_path: temp file with full PR data (additions, deletions, files)
+        - pr_titles: list of {number, title, repo} for Claude to review
+        - count: total PRs found
 
-        DO NOT use search_merged_prs for appraisals - it doesn't include stats
-        and causes context overflow with large result sets.
+        Workflow:
+        1. Call this tool → get file_path and pr_titles
+        2. Review pr_titles, pick significant PRs
+        3. Call get_appraisal_pr_details(file_path, [pr_numbers]) for full details
         """
         import json
         import tempfile
@@ -611,13 +528,12 @@ def create_github_tools(mcp: FastMCP) -> None:
         ),
     ) -> dict:
         """
-        Get full PR details from the appraisal data dump.
+        Read full PR details from the appraisal data file.
 
-        This reads from the local file created by prepare_appraisal_data.
-        NO API CALLS are made - all data comes from the cached dump.
+        Call this after prepare_appraisal_data with selected PR numbers.
+        Reads from the cached file - no API calls made.
 
-        Use this after prepare_appraisal_data to get full details for specific PRs
-        that Claude has identified as important for the appraisal.
+        Returns: additions, deletions, files changed, body for selected PRs.
         """
         import json
 

{quickcall_integrations-0.3.1 → quickcall_integrations-0.3.3}/plugins/quickcall/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "quickcall",
   "description": "Integrate quickcall into dev workflows - eliminate interruptions for developers. Ask about your work, get instant answers. No more context switching.",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "author": {
     "name": "Sagar Sarkale"
   }

{quickcall_integrations-0.3.1 → quickcall_integrations-0.3.3}/plugins/quickcall/commands/appraisal.md

@@ -16,30 +16,36 @@ Parse `$ARGUMENTS` for time period:
 
 ## Instructions
 
+**Two-step flow (avoids context overflow):**
+
+1. `prepare_appraisal_data` → fetches all PRs, dumps to file, returns titles + PR numbers
+2. `get_appraisal_pr_details` → Claude picks which PRs to get details for, reads from file
+
+---
+
 1. **Gather contribution data:**
 
-   **Option A - GitHub API (preferred if connected):**
-   - Use `search_merged_prs` tool with parsed days
-   - If user specifies an org, pass the `org` parameter
-   - If user specifies a repo, pass the `repo` parameter (format: "owner/repo")
-   - Default author is the authenticated user
+   **Option A - GitHub API (preferred):**
+   - Call `prepare_appraisal_data(days=X)` with the parsed time period
+   - This fetches ALL merged PRs with full stats in PARALLEL and dumps to a temp file
+   - Returns: `file_path` + `pr_titles` (number, title, repo for each PR)
+   - Optional: pass `org` or `repo` parameter to filter
 
-   **Option B - Local Git (fallback if not connected or for specific repo):**
+   **Option B - Local Git (fallback):**
    - Use `get_local_contributions` tool on the current directory
    - This parses local git history for commits by the user
-   - Extracts PR numbers from merge commit messages where available
 
-2. **Analyze and categorize each PR:**
-   Examine each PR's title, body, and labels to categorize:
+2. **Analyze and categorize PRs from the titles:**
+   Review the `pr_titles` list returned in step 1 and categorize:
    - **Features**: New functionality (feat:, add:, implement, new, create)
    - **Enhancements**: Improvements (improve:, update:, perf:, optimize, enhance)
    - **Bug fixes**: (fix:, bugfix:, hotfix:, resolve, patch)
    - **Chores**: Maintenance work (docs:, test:, ci:, chore:, refactor:, bump)
 
-3. **Identify top accomplishments:**
-   - Filter out chores for the highlights
-   - Sort features and enhancements by significance (based on title complexity, labels)
-   - For top 3-5 PRs, call `get_pr` to fetch detailed metrics (additions, deletions, files)
+3. **Get full details for selected PRs:**
+   - Based on the titles, pick the top 5-10 significant PRs worth highlighting
+   - Call `get_appraisal_pr_details(file_path, [pr_numbers])` with the selected PR numbers
+   - Returns: full details (additions, deletions, files, body) for those PRs only
 
 4. **Calculate summary metrics:**
    - Total PRs merged by category

{quickcall_integrations-0.3.1 → quickcall_integrations-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quickcall-integrations"
-version = "0.3.1"
+version = "0.3.3"
 description = "MCP server with developer integrations for Claude Code and Cursor"
 readme = "README.md"
 requires-python = ">=3.10"

quickcall_integrations-0.3.3/tests/test_appraisal_integration.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""
+Integration test for appraisal tools.
+
+Tests the actual MCP tool functions with real GitHub API calls.
+
+Usage:
+    uv run python tests/test_appraisal_integration.py
+"""
+
+import json
+import os
+import sys
+
+# Add parent dir to path for imports
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+def test_prepare_appraisal_data_tool():
+    """Test prepare_appraisal_data MCP tool with real API."""
+    print("\n=== Integration Test: prepare_appraisal_data ===")
+
+    from mcp_server.auth import get_github_pat, get_credential_store
+    from mcp_server.api_clients.github_client import GitHubClient
+
+    # Check auth
+    pat_token, source = get_github_pat()
+    store = get_credential_store()
+
+    if not pat_token and not store.is_authenticated():
+        print("⚠️  No GitHub auth available, skipping integration test")
+        return None
+
+    # Get client
+    if pat_token:
+        client = GitHubClient(token=pat_token)
+        author = client.get_authenticated_user()
+        print(f"✅ Using PAT ({source}), user: {author}")
+    else:
+        creds = store.get_api_credentials()
+        client = GitHubClient(
+            token=creds.github_token,
+            default_owner=creds.github_username,
+            installation_id=creds.github_installation_id,
+        )
+        author = creds.github_username
+        print(f"✅ Using GitHub App, user: {author}")
+
+    # Step 1: Search merged PRs
+    print("\n[Step 1] Searching merged PRs (last 30 days, limit 10)...")
+    from datetime import datetime, timedelta, timezone
+
+    since_date = (datetime.now(timezone.utc) - timedelta(days=30)).strftime("%Y-%m-%d")
+
+    pr_list = client.search_merged_prs(
+        author=author,
+        since_date=since_date,
+        limit=10,
+        detail_level="full",
+    )
+
+    if not pr_list:
+        print("⚠️  No merged PRs found in last 30 days")
+        return None
+
+    print(f"✅ Found {len(pr_list)} PRs")
+    for pr in pr_list[:3]:
+        print(f"   - #{pr['number']}: {pr['title'][:50]}")
+
+    # Step 2: Fetch full details in parallel
+    print("\n[Step 2] Fetching full PR details in parallel...")
+    pr_refs = [
+        {"owner": pr["owner"], "repo": pr["repo"], "number": pr["number"]}
+        for pr in pr_list
+    ]
+
+    full_prs = client.fetch_prs_parallel(pr_refs, max_workers=5)
+    print(f"✅ Fetched {len(full_prs)} PRs with full details")
+
+    if full_prs:
+        pr = full_prs[0]
+        print(
+            f"   Sample: #{pr['number']} - +{pr.get('additions', 0)}/-{pr.get('deletions', 0)}"
+        )
+
+    # Step 3: Dump to file
+    print("\n[Step 3] Dumping to file...")
+    import tempfile
+
+    dump_data = {
+        "author": author,
+        "period": "Last 30 days",
+        "fetched_at": datetime.now(timezone.utc).isoformat(),
+        "count": len(full_prs),
+        "prs": full_prs,
+    }
+
+    fd, file_path = tempfile.mkstemp(suffix=".json", prefix="appraisal_integration_")
+    with open(file_path, "w") as f:
+        json.dump(dump_data, f, indent=2, default=str)
+
+    file_size = os.path.getsize(file_path)
+    print(f"✅ Dumped to: {file_path}")
+    print(f"   Size: {file_size / 1024:.1f} KB")
+
+    # Step 4: Generate titles (what tool returns)
+    print("\n[Step 4] Generating PR titles for Claude...")
+    pr_titles = [
+        {
+            "number": pr["number"],
+            "title": pr["title"],
+            "repo": f"{pr.get('owner', '')}/{pr.get('repo', '')}",
+        }
+        for pr in full_prs
+    ]
+
+    print(f"✅ Generated {len(pr_titles)} titles")
+    for t in pr_titles[:5]:
+        print(f"   - #{t['number']}: {t['title'][:50]}")
+
+    # Step 5: Test get_appraisal_pr_details
+    print("\n[Step 5] Testing get_appraisal_pr_details...")
+    if len(full_prs) >= 2:
+        selected_numbers = [full_prs[0]["number"], full_prs[1]["number"]]
+
+        with open(file_path) as f:
+            data = json.load(f)
+
+        pr_numbers_set = set(selected_numbers)
+        selected_prs = [
+            pr for pr in data.get("prs", []) if pr["number"] in pr_numbers_set
+        ]
+
+        print(f"✅ Retrieved {len(selected_prs)} selected PRs from dump")
+        for pr in selected_prs:
+            print(
+                f"   - #{pr['number']}: {pr['title'][:40]} (+{pr.get('additions', 0)}/-{pr.get('deletions', 0)})"
+            )
+
+    # Cleanup
+    os.unlink(file_path)
+    print("\n✅ Integration test passed!")
+    return True
+
+
+def test_response_size():
+    """Test that response sizes are reasonable."""
+    print("\n=== Test: Response sizes ===")
+
+    # Simulate 100 PRs
+    mock_pr_titles = [
+        {
+            "number": i,
+            "title": f"PR title for #{i} - some description here",
+            "repo": "org/repo",
+        }
+        for i in range(1, 101)
+    ]
+
+    # Calculate size of titles-only response
+    titles_response = {
+        "file_path": "/tmp/appraisal_xxx.json",
+        "count": 100,
+        "author": "testuser",
+        "period": "Last 180 days",
+        "pr_titles": mock_pr_titles,
+        "next_step": "Call get_appraisal_pr_details...",
+    }
+
+    titles_size = len(json.dumps(titles_response))
+    print(f"✅ Titles-only response for 100 PRs: {titles_size / 1024:.1f} KB")
+
+    # Compare to full response (old way)
+    mock_full_prs = [
+        {
+            "number": i,
+            "title": f"PR title for #{i} - some description here",
+            "body": "This is a longer description " * 10,
+            "owner": "org",
+            "repo": "repo",
+            "additions": 100,
+            "deletions": 50,
+            "changed_files": 10,
+            "labels": ["bug", "feature"],
+            "merged_at": "2024-01-01T00:00:00Z",
+            "html_url": f"https://github.com/org/repo/pull/{i}",
+        }
+        for i in range(1, 101)
+    ]
+
+    full_response = {
+        "count": 100,
+        "prs": mock_full_prs,
+    }
+
+    full_size = len(json.dumps(full_response))
+    print(f"✅ Full response for 100 PRs: {full_size / 1024:.1f} KB")
+    print(f"✅ Reduction: {(1 - titles_size / full_size) * 100:.0f}%")
+
+    assert titles_size < full_size / 2, "Titles response should be <50% of full"
+    print("✅ Test passed!\n")
+    return True
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("Appraisal Tools - Integration Tests")
+    print("=" * 60)
+
+    results = []
+
+    # Test response sizes first (no auth needed)
+    try:
+        results.append(("Response sizes", test_response_size()))
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+        results.append(("Response sizes", False))
+
+    # Test actual tool flow
+    try:
+        result = test_prepare_appraisal_data_tool()
+        results.append(("prepare_appraisal_data", result))
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+        import traceback
+
+        traceback.print_exc()
+        results.append(("prepare_appraisal_data", False))
+
+    print("\n" + "=" * 60)
+    print("Results:")
+    for name, passed in results:
+        status = "✅ PASS" if passed else ("⚠️ SKIP" if passed is None else "❌ FAIL")
+        print(f"  {name}: {status}")
+    print("=" * 60)

quickcall_integrations-0.3.3/tests/test_appraisal_tools.py

@@ -0,0 +1,416 @@
+#!/usr/bin/env python3
+"""
+Test appraisal tools locally.
+
+Tests:
+1. prepare_appraisal_data - fetches PRs in parallel, dumps to file, returns titles
+2. get_appraisal_pr_details - reads from dump file
+
+Usage:
+    uv run python tests/test_appraisal_tools.py
+"""
+
+import json
+import os
+import tempfile
+from datetime import datetime, timezone
+from unittest.mock import MagicMock, patch
+
+# Test the core logic without MCP server
+
+
+def test_prepare_appraisal_data_dumps_to_file():
+    """Test that prepare_appraisal_data creates a file with PR data."""
+    print("\n=== Test 1: prepare_appraisal_data dumps to file ===")
+
+    # Mock data - simulating full PR details from parallel fetch
+    mock_full_prs = [
+        {
+            "number": 1,
+            "title": "feat: add login",
+            "owner": "test-org",
+            "repo": "test-repo",
+            "additions": 100,
+            "deletions": 20,
+            "body": "Added login feature",
+        },
+        {
+            "number": 2,
+            "title": "fix: bug in auth",
+            "owner": "test-org",
+            "repo": "test-repo",
+            "additions": 10,
+            "deletions": 5,
+            "body": "Fixed auth bug",
+        },
+        {
+            "number": 3,
+            "title": "chore: update deps",
+            "owner": "test-org",
+            "repo": "test-repo",
+            "additions": 50,
+            "deletions": 50,
+            "body": "Updated dependencies",
+        },
+    ]
+
+    # Simulate what prepare_appraisal_data does
+    dump_data = {
+        "author": "testuser",
+        "period": "Last 180 days",
+        "org": None,
+        "repo": None,
+        "fetched_at": datetime.now(timezone.utc).isoformat(),
+        "count": len(mock_full_prs),
+        "prs": mock_full_prs,
+    }
+
+    # Create temp file
+    fd, file_path = tempfile.mkstemp(suffix=".json", prefix="appraisal_test_")
+    with open(file_path, "w") as f:
+        json.dump(dump_data, f, indent=2, default=str)
+
+    # Verify file exists and has correct structure
+    assert os.path.exists(file_path), "File should be created"
+
+    with open(file_path) as f:
+        loaded = json.load(f)
+
+    assert loaded["count"] == 3, f"Expected 3 PRs, got {loaded['count']}"
+    assert len(loaded["prs"]) == 3, "Should have 3 PRs in data"
+    assert loaded["prs"][0]["title"] == "feat: add login", "First PR title should match"
+
+    # Generate titles (what prepare_appraisal_data returns)
+    pr_titles = [
+        {
+            "number": pr["number"],
+            "title": pr["title"],
+            "repo": f"{pr['owner']}/{pr['repo']}",
+        }
+        for pr in mock_full_prs
+    ]
+
+    result = {
+        "file_path": file_path,
+        "count": len(mock_full_prs),
+        "author": "testuser",
+        "period": "Last 180 days",
+        "pr_titles": pr_titles,
+        "next_step": "Call get_appraisal_pr_details...",
+    }
+
+    print(f"✅ File created: {file_path}")
+    print(f"✅ PR count: {result['count']}")
+    print(f"✅ PR titles returned: {len(result['pr_titles'])}")
+    for t in result["pr_titles"]:
+        print(f"   - #{t['number']}: {t['title']}")
+
+    # Cleanup
+    os.unlink(file_path)
+    print("✅ Test passed!\n")
+    return True
+
+
+def test_get_appraisal_pr_details_reads_from_file():
+    """Test that get_appraisal_pr_details reads selected PRs from dump."""
+    print("\n=== Test 2: get_appraisal_pr_details reads from file ===")
+
+    # Create a dump file
+    mock_prs = [
+        {
+            "number": 1,
+            "title": "feat: add login",
+            "owner": "test-org",
+            "repo": "test-repo",
+            "additions": 100,
+            "deletions": 20,
+            "body": "Added login feature",
+        },
+        {
+            "number": 2,
+            "title": "fix: bug in auth",
+            "owner": "test-org",
+            "repo": "test-repo",
+            "additions": 10,
+            "deletions": 5,
+            "body": "Fixed auth bug",
+        },
+        {
+            "number": 3,
+            "title": "chore: update deps",
+            "owner": "test-org",
+            "repo": "test-repo",
+            "additions": 50,
+            "deletions": 50,
+            "body": "Updated dependencies",
+        },
+        {
+            "number": 4,
+            "title": "feat: add logout",
+            "owner": "test-org",
+            "repo": "test-repo",
+            "additions": 80,
+            "deletions": 10,
+            "body": "Added logout",
+        },
+        {
+            "number": 5,
+            "title": "docs: update readme",
+            "owner": "test-org",
+            "repo": "test-repo",
+            "additions": 20,
+            "deletions": 5,
+            "body": "Updated docs",
+        },
+    ]
+
+    dump_data = {
+        "author": "testuser",
+        "period": "Last 180 days",
+        "prs": mock_prs,
+    }
+
+    fd, file_path = tempfile.mkstemp(suffix=".json", prefix="appraisal_test_")
+    with open(file_path, "w") as f:
+        json.dump(dump_data, f)
+
+    # Simulate get_appraisal_pr_details - select only PRs 1 and 4
+    selected_numbers = [1, 4]
+    pr_numbers_set = set(selected_numbers)
+
+    with open(file_path) as f:
+        data = json.load(f)
+
+    selected_prs = [pr for pr in data.get("prs", []) if pr["number"] in pr_numbers_set]
+
+    result = {
+        "count": len(selected_prs),
+        "requested": len(selected_numbers),
+        "prs": selected_prs,
+    }
+
+    assert result["count"] == 2, f"Expected 2 PRs, got {result['count']}"
+    assert result["prs"][0]["number"] == 1, "First PR should be #1"
+    assert result["prs"][1]["number"] == 4, "Second PR should be #4"
+    assert result["prs"][0]["additions"] == 100, "Should have full PR details"
+
+    print(f"✅ Requested PRs: {selected_numbers}")
+    print(f"✅ Retrieved {result['count']} PRs from dump")
+    for pr in result["prs"]:
+        print(
+            f"   - #{pr['number']}: {pr['title']} (+{pr['additions']}/-{pr['deletions']})"
+        )
+
+    # Cleanup
+    os.unlink(file_path)
+    print("✅ Test passed!\n")
+    return True
+
+
+def test_parallel_fetch_simulation():
+    """Test that parallel fetching logic works."""
+    print("\n=== Test 3: Parallel fetch simulation ===")
+
+    from concurrent.futures import ThreadPoolExecutor, as_completed
+    import time
+
+    # Simulate fetching PR details
+    def fetch_pr(pr_ref):
+        # Simulate API latency
+        time.sleep(0.1)
+        return {
+            "number": pr_ref["number"],
+            "title": f"PR #{pr_ref['number']}",
+            "owner": pr_ref["owner"],
+            "repo": pr_ref["repo"],
+            "additions": pr_ref["number"] * 10,
+            "deletions": pr_ref["number"] * 2,
+        }
+
+    pr_refs = [
+        {"owner": "test", "repo": "repo", "number": i}
+        for i in range(1, 11)  # 10 PRs
+    ]
+
+    start = time.time()
+
+    # Sequential (for comparison)
+    # sequential_results = [fetch_pr(ref) for ref in pr_refs]
+    # sequential_time = time.time() - start
+
+    # Parallel
+    start = time.time()
+    results = []
+    with ThreadPoolExecutor(max_workers=10) as executor:
+        futures = {executor.submit(fetch_pr, ref): ref for ref in pr_refs}
+        for future in as_completed(futures):
+            result = future.result()
+            if result:
+                results.append(result)
+
+    parallel_time = time.time() - start
+
+    assert len(results) == 10, f"Expected 10 results, got {len(results)}"
+    print(f"✅ Fetched {len(results)} PRs in parallel")
+    print(f"✅ Time: {parallel_time:.2f}s (vs ~1s sequential)")
+    print("✅ Test passed!\n")
+    return True
+
+
+def test_full_flow_with_mock_client():
+    """Test the full appraisal flow with mocked GitHub client."""
+    print("\n=== Test 4: Full flow with mock client ===")
+
+    from mcp_server.api_clients.github_client import GitHubClient
+
+    # Create a mock client
+    with patch.object(GitHubClient, "__init__", lambda self, **kwargs: None):
+        client = GitHubClient(token="fake")
+        client.token = "fake"
+        client._is_pat_mode = True
+        client.default_owner = "testuser"
+
+        # Mock search_merged_prs
+        mock_search_results = [
+            {
+                "number": 1,
+                "title": "feat: add feature",
+                "owner": "org",
+                "repo": "repo",
+                "merged_at": "2024-01-01",
+                "body": "",
+                "labels": [],
+            },
+            {
+                "number": 2,
+                "title": "fix: bug fix",
+                "owner": "org",
+                "repo": "repo",
+                "merged_at": "2024-01-02",
+                "body": "",
+                "labels": [],
+            },
+        ]
+
+        # Mock get_pr to return full details
+        class MockPR:
+            def __init__(self, num):
+                self.number = num
+                self.title = f"PR #{num}"
+                self.body = f"Body for PR #{num}"
+                self.state = "closed"
+                self.additions = num * 100
+                self.deletions = num * 10
+                self.changed_files = num * 5
+                self.commits = num
+                self.draft = False
+                self.mergeable = True
+                self.labels = []
+                self.reviewers = []
+                self.created_at = datetime.now()
+                self.updated_at = datetime.now()
+                self.merged_at = datetime.now()
+                self.html_url = f"https://github.com/org/repo/pull/{num}"
+                self.head_branch = "feature"
+                self.base_branch = "main"
+                self.user = MagicMock(login="testuser")
+
+            def model_dump(self):
+                return {
+                    "number": self.number,
+                    "title": self.title,
+                    "body": self.body,
+                    "additions": self.additions,
+                    "deletions": self.deletions,
+                }
+
+        client.search_merged_prs = MagicMock(return_value=mock_search_results)
+        client.get_pr = MagicMock(side_effect=lambda num, **kw: MockPR(num))
+
+        # Test search
+        search_result = client.search_merged_prs(
+            author="testuser", since_date="2024-01-01"
+        )
+        assert len(search_result) == 2, "Should get 2 PRs from search"
+        print(f"✅ Search returned {len(search_result)} PRs")
+
+        # Test get_pr
+        pr = client.get_pr(1)
+        assert pr.number == 1, "Should get PR #1"
+        assert pr.additions == 100, "Should have additions"
+        print(
+            f"✅ get_pr returned PR #{pr.number} with +{pr.additions}/-{pr.deletions}"
+        )
+
+    print("✅ Test passed!\n")
+    return True
+
+
+def test_actual_github_client():
+    """Test actual GitHub client if credentials available."""
+    print("\n=== Test 5: Actual GitHub client (optional) ===")
+
+    from mcp_server.auth import get_github_pat
+
+    pat_token, source = get_github_pat()
+    if not pat_token:
+        print("⚠️  No GitHub PAT found, skipping live test")
+        print("   Set GITHUB_TOKEN env var to enable this test")
+        return True
+
+    from mcp_server.api_clients.github_client import GitHubClient
+
+    client = GitHubClient(token=pat_token)
+
+    # Test search (limited)
+    print(f"✅ Using PAT from {source}")
+
+    try:
+        prs = client.search_merged_prs(
+            author=client.get_authenticated_user(),
+            since_date="2024-12-01",
+            limit=5,
+            detail_level="summary",
+        )
+        print(f"✅ Found {len(prs)} merged PRs in last month")
+        for pr in prs[:3]:
+            print(f"   - #{pr['number']}: {pr['title'][:50]}")
+    except Exception as e:
+        print(f"⚠️  Search failed: {e}")
+
+    print("✅ Test passed!\n")
+    return True
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("Testing Appraisal Tools")
+    print("=" * 60)
+
+    tests = [
+        test_prepare_appraisal_data_dumps_to_file,
+        test_get_appraisal_pr_details_reads_from_file,
+        test_parallel_fetch_simulation,
+        test_full_flow_with_mock_client,
+        test_actual_github_client,
+    ]
+
+    passed = 0
+    failed = 0
+
+    for test in tests:
+        try:
+            if test():
+                passed += 1
+            else:
+                failed += 1
+        except Exception as e:
+            print(f"❌ Test failed with exception: {e}")
+            import traceback
+
+            traceback.print_exc()
+            failed += 1
+
+    print("=" * 60)
+    print(f"Results: {passed} passed, {failed} failed")
+    print("=" * 60)