github-talent-mcp 0.1.0__tar.gz → 0.3.0__tar.gz

{github_talent_mcp-0.1.0/src/github_talent_mcp.egg-info → github_talent_mcp-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-talent-mcp
-Version: 0.1.0
+Version: 0.3.0
 Summary: MCP server for searching, scoring, and ranking GitHub developers for technical recruiting
 Author: Carolina Cherry
 License: MIT
@@ -21,10 +21,10 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mcp>=1.0.0
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: mcp<2,>=1.0.0
+Requires-Dist: httpx<1,>=0.27.0
+Requires-Dist: pydantic<3,>=2.0.0
+Requires-Dist: python-dotenv<2,>=1.0.0
 Dynamic: license-file
 
 # github-talent-mcp
@@ -33,12 +33,19 @@ Dynamic: license-file
 [![Python 3.14+](https://img.shields.io/badge/Python-3.14+-blue.svg)](https://www.python.org)
 [![MCP](https://img.shields.io/badge/MCP-Model_Context_Protocol-8A2BE2)](https://modelcontextprotocol.io)
 [![Claude](https://img.shields.io/badge/Built_for-Claude_by_Anthropic-d4a373)](https://claude.ai)
+[![GitHub Copilot](https://img.shields.io/badge/Works_with-GitHub_Copilot-8957E5?logo=githubcopilot&logoColor=white)](https://github.com/features/copilot)
 [![GitHub API](https://img.shields.io/badge/GitHub-REST_API_v3-181717?logo=github)](https://docs.github.com/en/rest)
 
 MCP server that searches, scores, and ranks GitHub developers for technical recruiting.
 
+Works with **Claude** (Code & Desktop) and **GitHub Copilot** (CLI & desktop app) — any MCP client that speaks stdio.
+
 ## Demo
 
+https://github.com/user-attachments/assets/b2dbe9e0-26ee-4849-861a-4b5cb268facc
+
+Sourcing candidates for a real Anthropic JD, live in Claude Cowork.
+
 https://github.com/user-attachments/assets/2dfd82b4-3eb5-4f2b-bc0a-2580b95043e4
 
 ### Profile deep dive
@@ -118,7 +125,7 @@ Then set the token as an environment variable. Either:
 - Export it in your shell: `export GITHUB_TOKEN=ghp_xxxxxxxxxxxx`
 - Or keep it in the `.env` file — the server reads it via `python-dotenv` on startup
 
-Restart Claude Code to pick up the new server. Verify with `/mcp` — you should see 4 tools under `github-talent`.
+Restart Claude Code to pick up the new server. Verify with `/mcp` — you should see 8 tools under `github-talent`.
 
 #### Claude Desktop
 
@@ -141,6 +148,32 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 Restart Claude Desktop. The tools will appear in the toolbox icon.
 
+#### GitHub Copilot (CLI & desktop app)
+
+The [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli) and the [GitHub Copilot app](https://github.com/features/ai/github-app) share one MCP config, so a single setup covers both.
+
+Add it to `~/.copilot/mcp-config.json` (global), or commit a `.copilot/mcp-config.json` in your repo — the Copilot app picks that up automatically:
+
+```json
+{
+  "mcpServers": {
+    "github-talent": {
+      "type": "local",
+      "command": "uvx",
+      "args": ["github-talent-mcp"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      },
+      "tools": ["*"]
+    }
+  }
+}
+```
+
+Export your token first (`export GITHUB_TOKEN=ghp_xxxxxxxxxxxx`) — Copilot only inherits `PATH`, so the `${GITHUB_TOKEN}` reference reads it from your shell. If `uvx` isn't on your `PATH`, use its absolute path as `command`.
+
+The **Copilot app** reads this same config and also lets you add servers under Settings → MCP. In a Copilot CLI session, run `/mcp add` to register interactively or `/mcp show` to verify — you should see 8 tools under `github-talent`.
+
 ## Try It
 
 Once installed, paste these prompts to verify everything works:
@@ -157,6 +190,18 @@ Once installed, paste these prompts to verify everything works:
 **Repo contributors:**
 > Get the top contributors to huggingface/transformers and rank them for a founding ML engineer role at an AI startup
 
+**JD scoring:**
+> Score these candidates against this job description: [paste JD]. Candidates: tiangolo, karpathy, hwchase17
+
+**Compare candidates:**
+> Compare tiangolo and hwchase17 for a Senior Python AI Engineer role
+
+**Bulk scoring:**
+> Score these 10 GitHub usernames and give me a ranked table: [paste list]
+
+**Outreach:**
+> Generate a casual recruiter message for tiangolo about a Senior Python role at Acme. My name is Daniel.
+
 ## Tools
 
 | Tool | Description |
@@ -164,6 +209,10 @@ Once installed, paste these prompts to verify everything works:
 | `search_developers` | Search GitHub users by language, location, activity, followers. For topic-based sourcing, use `get_repo_contributors` on relevant repos instead. |
 | `get_developer_profile` | Deep profile enrichment: languages, stars, commits + PRs, OSS contributions, license breakdown, profile README, and activity score with breakdown. |
 | `rank_candidates` | Rank usernames against a job description. Returns sorted candidates with combined score, strengths, gaps, and reasoning. |
+| `score_against_jd` | Score candidates against a JD with per-dimension breakdown (tech stack, experience level, OSS signal, leadership). Returns gaps and personalized interview questions. |
+| `compare_candidates` | Side-by-side comparison of 2-5 candidates. Shows dimension winners and a recommendation. Optionally scored against a JD. |
+| `bulk_score` | Score up to 100 GitHub usernames in one call. Returns a ranked markdown table or CSV. Supports optional JD matching. |
+| `generate_outreach` | Generate personalized recruiter messages (short/medium/detailed) that reference the candidate's actual repos and contributions. Requires your company name and sender name. Casual or formal tone. |
 | `get_repo_contributors` | Top contributors for any repo. Accepts `owner/repo` or full URL. The fastest way to source for a specific domain. |
 
 ## Scoring

{github_talent_mcp-0.1.0 → github_talent_mcp-0.3.0}/README.md

@@ -4,12 +4,19 @@
 [![Python 3.14+](https://img.shields.io/badge/Python-3.14+-blue.svg)](https://www.python.org)
 [![MCP](https://img.shields.io/badge/MCP-Model_Context_Protocol-8A2BE2)](https://modelcontextprotocol.io)
 [![Claude](https://img.shields.io/badge/Built_for-Claude_by_Anthropic-d4a373)](https://claude.ai)
+[![GitHub Copilot](https://img.shields.io/badge/Works_with-GitHub_Copilot-8957E5?logo=githubcopilot&logoColor=white)](https://github.com/features/copilot)
 [![GitHub API](https://img.shields.io/badge/GitHub-REST_API_v3-181717?logo=github)](https://docs.github.com/en/rest)
 
 MCP server that searches, scores, and ranks GitHub developers for technical recruiting.
 
+Works with **Claude** (Code & Desktop) and **GitHub Copilot** (CLI & desktop app) — any MCP client that speaks stdio.
+
 ## Demo
 
+https://github.com/user-attachments/assets/b2dbe9e0-26ee-4849-861a-4b5cb268facc
+
+Sourcing candidates for a real Anthropic JD, live in Claude Cowork.
+
 https://github.com/user-attachments/assets/2dfd82b4-3eb5-4f2b-bc0a-2580b95043e4
 
 ### Profile deep dive
@@ -89,7 +96,7 @@ Then set the token as an environment variable. Either:
 - Export it in your shell: `export GITHUB_TOKEN=ghp_xxxxxxxxxxxx`
 - Or keep it in the `.env` file — the server reads it via `python-dotenv` on startup
 
-Restart Claude Code to pick up the new server. Verify with `/mcp` — you should see 4 tools under `github-talent`.
+Restart Claude Code to pick up the new server. Verify with `/mcp` — you should see 8 tools under `github-talent`.
 
 #### Claude Desktop
 
@@ -112,6 +119,32 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 Restart Claude Desktop. The tools will appear in the toolbox icon.
 
+#### GitHub Copilot (CLI & desktop app)
+
+The [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli) and the [GitHub Copilot app](https://github.com/features/ai/github-app) share one MCP config, so a single setup covers both.
+
+Add it to `~/.copilot/mcp-config.json` (global), or commit a `.copilot/mcp-config.json` in your repo — the Copilot app picks that up automatically:
+
+```json
+{
+  "mcpServers": {
+    "github-talent": {
+      "type": "local",
+      "command": "uvx",
+      "args": ["github-talent-mcp"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      },
+      "tools": ["*"]
+    }
+  }
+}
+```
+
+Export your token first (`export GITHUB_TOKEN=ghp_xxxxxxxxxxxx`) — Copilot only inherits `PATH`, so the `${GITHUB_TOKEN}` reference reads it from your shell. If `uvx` isn't on your `PATH`, use its absolute path as `command`.
+
+The **Copilot app** reads this same config and also lets you add servers under Settings → MCP. In a Copilot CLI session, run `/mcp add` to register interactively or `/mcp show` to verify — you should see 8 tools under `github-talent`.
+
 ## Try It
 
 Once installed, paste these prompts to verify everything works:
@@ -128,6 +161,18 @@ Once installed, paste these prompts to verify everything works:
 **Repo contributors:**
 > Get the top contributors to huggingface/transformers and rank them for a founding ML engineer role at an AI startup
 
+**JD scoring:**
+> Score these candidates against this job description: [paste JD]. Candidates: tiangolo, karpathy, hwchase17
+
+**Compare candidates:**
+> Compare tiangolo and hwchase17 for a Senior Python AI Engineer role
+
+**Bulk scoring:**
+> Score these 10 GitHub usernames and give me a ranked table: [paste list]
+
+**Outreach:**
+> Generate a casual recruiter message for tiangolo about a Senior Python role at Acme. My name is Daniel.
+
 ## Tools
 
 | Tool | Description |
@@ -135,6 +180,10 @@ Once installed, paste these prompts to verify everything works:
 | `search_developers` | Search GitHub users by language, location, activity, followers. For topic-based sourcing, use `get_repo_contributors` on relevant repos instead. |
 | `get_developer_profile` | Deep profile enrichment: languages, stars, commits + PRs, OSS contributions, license breakdown, profile README, and activity score with breakdown. |
 | `rank_candidates` | Rank usernames against a job description. Returns sorted candidates with combined score, strengths, gaps, and reasoning. |
+| `score_against_jd` | Score candidates against a JD with per-dimension breakdown (tech stack, experience level, OSS signal, leadership). Returns gaps and personalized interview questions. |
+| `compare_candidates` | Side-by-side comparison of 2-5 candidates. Shows dimension winners and a recommendation. Optionally scored against a JD. |
+| `bulk_score` | Score up to 100 GitHub usernames in one call. Returns a ranked markdown table or CSV. Supports optional JD matching. |
+| `generate_outreach` | Generate personalized recruiter messages (short/medium/detailed) that reference the candidate's actual repos and contributions. Requires your company name and sender name. Casual or formal tone. |
 | `get_repo_contributors` | Top contributors for any repo. Accepts `owner/repo` or full URL. The fastest way to source for a specific domain. |
 
 ## Scoring

{github_talent_mcp-0.1.0 → github_talent_mcp-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "github-talent-mcp"
-version = "0.1.0"
+version = "0.3.0"
 description = "MCP server for searching, scoring, and ranking GitHub developers for technical recruiting"
 readme = "README.md"
 license = {text = "MIT"}
@@ -26,10 +26,10 @@ classifiers = [
     "Topic :: Software Development :: Libraries",
 ]
 dependencies = [
-    "mcp>=1.0.0",
-    "httpx>=0.27.0",
-    "pydantic>=2.0.0",
-    "python-dotenv>=1.0.0",
+    "mcp>=1.0.0,<2",
+    "httpx>=0.27.0,<1",
+    "pydantic>=2.0.0,<3",
+    "python-dotenv>=1.0.0,<2",
 ]
 
 [project.urls]

{github_talent_mcp-0.1.0 → github_talent_mcp-0.3.0}/src/github_talent_mcp/github_client.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 import logging
 import os
 import time
@@ -54,6 +55,59 @@ class GitHubClient:
             reset = resp.headers.get("X-RateLimit-Reset", "unknown")
             log.warning(f"Rate limit low: {remaining} remaining, resets at {reset}")
 
+    # -- Request wrapper with rate-limit backoff --
+
+    async def _get(
+        self,
+        url: str,
+        *,
+        params: dict | None = None,
+        headers: dict | None = None,
+        max_retries: int = 3,
+    ) -> httpx.Response:
+        """GET with backoff on GitHub rate limits (primary + secondary) and 5xx.
+
+        Respects Retry-After and X-RateLimit-Reset so a broad sourcing run paces
+        itself instead of erroring out mid-job. Each wait is capped (60s) so an
+        exhausted hourly quota fails fast rather than hanging the session.
+        """
+        resp = await self._client.get(url, params=params, headers=headers)
+        for attempt in range(max_retries):
+            if not self._should_retry(resp):
+                return resp
+            delay = self._retry_after_seconds(resp, attempt)
+            log.warning(
+                f"GitHub {resp.status_code} on {url} — backing off {delay:.0f}s "
+                f"(retry {attempt + 1}/{max_retries})"
+            )
+            await asyncio.sleep(delay)
+            resp = await self._client.get(url, params=params, headers=headers)
+        return resp
+
+    @staticmethod
+    def _should_retry(resp: httpx.Response) -> bool:
+        if resp.status_code >= 500:
+            return True
+        if resp.status_code in (403, 429):
+            # Secondary limit sends Retry-After; primary limit zeroes Remaining.
+            if resp.headers.get("Retry-After"):
+                return True
+            if resp.headers.get("X-RateLimit-Remaining") == "0":
+                return True
+        return False
+
+    @staticmethod
+    def _retry_after_seconds(resp: httpx.Response, attempt: int) -> float:
+        retry_after = resp.headers.get("Retry-After", "")
+        if retry_after.isdigit():
+            return min(float(retry_after), 60.0)
+        if resp.headers.get("X-RateLimit-Remaining") == "0":
+            reset = resp.headers.get("X-RateLimit-Reset", "")
+            if reset.isdigit():
+                wait = float(reset) - time.time()
+                return min(max(wait, 0.0), 60.0) + 1.0
+        return min(2.0 ** attempt, 30.0)
+
     # -- API methods --
 
     async def search_users(
@@ -71,7 +125,7 @@ class GitHubClient:
             for lang in languages:
                 parts.append(f"language:{lang}")
         if location:
-            parts.append(f"location:{location}")
+            parts.append(f'location:"{location}"')
         if min_followers is not None:
             parts.append(f"followers:>={min_followers}")
         if min_repos is not None:
@@ -81,7 +135,7 @@ class GitHubClient:
         # Recent activity should be verified via get_developer_profile.
 
         q = " ".join(parts)
-        resp = await self._client.get(
+        resp = await self._get(
             "/search/users",
             params={"q": q, "per_page": per_page, "page": page, "sort": "followers", "order": "desc"},
         )
@@ -94,7 +148,7 @@ class GitHubClient:
         cached = self._cache_get(cache_key)
         if cached is not None:
             return cached
-        resp = await self._client.get(f"/repos/{owner}/{repo}")
+        resp = await self._get(f"/repos/{owner}/{repo}")
         self._check_rate_limit(resp)
         resp.raise_for_status()
         data = resp.json()
@@ -106,7 +160,7 @@ class GitHubClient:
         cached = self._cache_get(cache_key)
         if cached is not None:
             return cached
-        resp = await self._client.get(f"/users/{username}")
+        resp = await self._get(f"/users/{username}")
         self._check_rate_limit(resp)
         resp.raise_for_status()
         data = resp.json()
@@ -118,7 +172,7 @@ class GitHubClient:
         cached = self._cache_get(cache_key)
         if cached is not None:
             return cached
-        resp = await self._client.get(
+        resp = await self._get(
             f"/users/{username}/repos",
             params={"per_page": per_page, "sort": "pushed", "direction": "desc", "type": "owner"},
         )
@@ -133,7 +187,7 @@ class GitHubClient:
         cached = self._cache_get(cache_key)
         if cached is not None:
             return cached
-        resp = await self._client.get(f"/repos/{owner}/{repo}/languages")
+        resp = await self._get(f"/repos/{owner}/{repo}/languages")
         self._check_rate_limit(resp)
         resp.raise_for_status()
         data = resp.json()
@@ -147,7 +201,7 @@ class GitHubClient:
             return cached
         all_events: list[dict] = []
         for page in range(1, max_pages + 1):
-            resp = await self._client.get(
+            resp = await self._get(
                 f"/users/{username}/events/public",
                 params={"per_page": 100, "page": page},
             )
@@ -160,13 +214,55 @@ class GitHubClient:
         self._cache_set(cache_key, all_events)
         return all_events
 
+    async def search_commit_count(self, username: str, since_date: str) -> int:
+        """Count commits by username since a date using the Search API.
+
+        More accurate than Events API for users whose commits don't
+        surface as PushEvents (e.g. Torvalds' kernel merges).
+        """
+        cache_key = f"commit_count:{username}:{since_date}"
+        cached = self._cache_get(cache_key)
+        if cached is not None:
+            return cached
+        resp = await self._get(
+            "/search/commits",
+            params={
+                "q": f"author:{username} user:{username} committer-date:>={since_date}",
+                "per_page": 1,
+            },
+        )
+        self._check_rate_limit(resp)
+        resp.raise_for_status()
+        count = resp.json().get("total_count", 0)
+        self._cache_set(cache_key, count)
+        return count
+
+    async def search_pr_count(self, username: str, since_date: str) -> int:
+        """Count PRs opened by username since a date using the Search API."""
+        cache_key = f"pr_count:{username}:{since_date}"
+        cached = self._cache_get(cache_key)
+        if cached is not None:
+            return cached
+        resp = await self._get(
+            "/search/issues",
+            params={
+                "q": f"author:{username} type:pr created:>={since_date}",
+                "per_page": 1,
+            },
+        )
+        self._check_rate_limit(resp)
+        resp.raise_for_status()
+        count = resp.json().get("total_count", 0)
+        self._cache_set(cache_key, count)
+        return count
+
     async def get_profile_readme(self, username: str) -> str | None:
         cache_key = f"readme:{username}"
         cached = self._cache_get(cache_key)
         if cached is not None:
             return cached
         try:
-            resp = await self._client.get(
+            resp = await self._get(
                 f"/repos/{username}/{username}/readme",
                 headers={"Accept": "application/vnd.github.raw+json"},
             )
@@ -182,7 +278,7 @@ class GitHubClient:
     async def get_repo_contributors(
         self, owner: str, repo: str, per_page: int = 30,
     ) -> list[dict]:
-        resp = await self._client.get(
+        resp = await self._get(
             f"/repos/{owner}/{repo}/contributors",
             params={"per_page": per_page},
         )