github-talent-mcp 0.1.0__py3-none-any.whl

github_talent_mcp/__main__.py

@@ -0,0 +1,3 @@
+from github_talent_mcp.server import main
+
+main()

github_talent_mcp/github_client.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Any
+
+import httpx
+
+GITHUB_API = "https://api.github.com"
+PERMISSIVE_LICENSES = frozenset({
+    "mit", "apache-2.0", "bsd-2-clause", "bsd-3-clause", "isc", "unlicense",
+})
+
+log = logging.getLogger("github-talent-mcp")
+
+
+class GitHubClient:
+    def __init__(self, token: str | None = None):
+        self._token = token or os.environ.get("GITHUB_TOKEN", "")
+        self._cache: dict[str, tuple[float, Any]] = {}
+        self._cache_ttl = 300  # 5 minutes
+        headers: dict[str, str] = {
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        self._client = httpx.AsyncClient(
+            base_url=GITHUB_API,
+            headers=headers,
+            timeout=30.0,
+        )
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    # -- Cache helpers --
+
+    def _cache_get(self, key: str) -> Any | None:
+        if key in self._cache:
+            ts, data = self._cache[key]
+            if time.monotonic() - ts < self._cache_ttl:
+                return data
+            del self._cache[key]
+        return None
+
+    def _cache_set(self, key: str, data: Any) -> None:
+        self._cache[key] = (time.monotonic(), data)
+
+    def _check_rate_limit(self, resp: httpx.Response) -> None:
+        remaining = resp.headers.get("X-RateLimit-Remaining")
+        if remaining and int(remaining) < 100:
+            reset = resp.headers.get("X-RateLimit-Reset", "unknown")
+            log.warning(f"Rate limit low: {remaining} remaining, resets at {reset}")
+
+    # -- API methods --
+
+    async def search_users(
+        self,
+        *,
+        languages: list[str] | None = None,
+        location: str | None = None,
+        min_followers: int | None = None,
+        min_repos: int | None = None,
+        per_page: int = 30,
+        page: int = 1,
+    ) -> dict:
+        parts: list[str] = ["type:user"]
+        if languages:
+            for lang in languages:
+                parts.append(f"language:{lang}")
+        if location:
+            parts.append(f"location:{location}")
+        if min_followers is not None:
+            parts.append(f"followers:>={min_followers}")
+        if min_repos is not None:
+            parts.append(f"repos:>={min_repos}")
+        # Note: pushed:> is NOT a valid qualifier for /search/users — it silently
+        # returns 0 results. Use created:> for account age filtering instead.
+        # Recent activity should be verified via get_developer_profile.
+
+        q = " ".join(parts)
+        resp = await self._client.get(
+            "/search/users",
+            params={"q": q, "per_page": per_page, "page": page, "sort": "followers", "order": "desc"},
+        )
+        self._check_rate_limit(resp)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def get_repo_info(self, owner: str, repo: str) -> dict:
+        cache_key = f"repo:{owner}/{repo}"
+        cached = self._cache_get(cache_key)
+        if cached is not None:
+            return cached
+        resp = await self._client.get(f"/repos/{owner}/{repo}")
+        self._check_rate_limit(resp)
+        resp.raise_for_status()
+        data = resp.json()
+        self._cache_set(cache_key, data)
+        return data
+
+    async def get_user(self, username: str) -> dict:
+        cache_key = f"user:{username}"
+        cached = self._cache_get(cache_key)
+        if cached is not None:
+            return cached
+        resp = await self._client.get(f"/users/{username}")
+        self._check_rate_limit(resp)
+        resp.raise_for_status()
+        data = resp.json()
+        self._cache_set(cache_key, data)
+        return data
+
+    async def get_user_repos(self, username: str, per_page: int = 100) -> list[dict]:
+        cache_key = f"repos:{username}"
+        cached = self._cache_get(cache_key)
+        if cached is not None:
+            return cached
+        resp = await self._client.get(
+            f"/users/{username}/repos",
+            params={"per_page": per_page, "sort": "pushed", "direction": "desc", "type": "owner"},
+        )
+        self._check_rate_limit(resp)
+        resp.raise_for_status()
+        data = resp.json()
+        self._cache_set(cache_key, data)
+        return data
+
+    async def get_repo_languages(self, owner: str, repo: str) -> dict[str, int]:
+        cache_key = f"langs:{owner}/{repo}"
+        cached = self._cache_get(cache_key)
+        if cached is not None:
+            return cached
+        resp = await self._client.get(f"/repos/{owner}/{repo}/languages")
+        self._check_rate_limit(resp)
+        resp.raise_for_status()
+        data = resp.json()
+        self._cache_set(cache_key, data)
+        return data
+
+    async def get_user_events(self, username: str, max_pages: int = 3) -> list[dict]:
+        cache_key = f"events:{username}"
+        cached = self._cache_get(cache_key)
+        if cached is not None:
+            return cached
+        all_events: list[dict] = []
+        for page in range(1, max_pages + 1):
+            resp = await self._client.get(
+                f"/users/{username}/events/public",
+                params={"per_page": 100, "page": page},
+            )
+            self._check_rate_limit(resp)
+            resp.raise_for_status()
+            events = resp.json()
+            if not events:
+                break
+            all_events.extend(events)
+        self._cache_set(cache_key, all_events)
+        return all_events
+
+    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(
+                f"/repos/{username}/{username}/readme",
+                headers={"Accept": "application/vnd.github.raw+json"},
+            )
+            if resp.status_code == 200:
+                content = resp.text[:3000]
+                self._cache_set(cache_key, content)
+                return content
+        except httpx.HTTPError:
+            pass
+        self._cache_set(cache_key, None)
+        return None
+
+    async def get_repo_contributors(
+        self, owner: str, repo: str, per_page: int = 30,
+    ) -> list[dict]:
+        resp = await self._client.get(
+            f"/repos/{owner}/{repo}/contributors",
+            params={"per_page": per_page},
+        )
+        self._check_rate_limit(resp)
+        resp.raise_for_status()
+        return resp.json()

github_talent_mcp/models.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class DeveloperSearchResult(BaseModel):
+    login: str
+    name: str | None = None
+    avatar_url: str
+    html_url: str
+    type: str = "User"
+
+
+class NotableRepo(BaseModel):
+    name: str
+    description: str | None = None
+    stars: int = 0
+    forks: int = 0
+    language: str | None = None
+    license: str | None = None
+    topics: list[str] = Field(default_factory=list)
+    last_updated: str | None = None
+
+
+class DeveloperProfile(BaseModel):
+    login: str
+    name: str | None = None
+    bio: str | None = None
+    location: str | None = None
+    email: str | None = None
+    blog: str | None = None
+    company: str | None = None
+    twitter_username: str | None = None
+    hireable: bool | None = None
+    followers: int = 0
+    following: int = 0
+    public_repos: int = 0
+    account_age_days: int = 0
+    avatar_url: str = ""
+    html_url: str = ""
+
+    # Profile README
+    has_profile_readme: bool = False
+    profile_readme_length: int = 0
+    profile_readme_summary: str | None = None
+
+    # Language analysis
+    top_languages: list[str] = Field(default_factory=list)
+    language_breakdown: dict[str, float] = Field(default_factory=dict)
+
+    # Repo metrics
+    total_stars_received: int = 0
+    total_forks_received: int = 0
+    notable_repos: list[NotableRepo] = Field(default_factory=list)
+    repos_with_description_ratio: float = 0.0
+
+    # License analysis
+    open_source_license_ratio: float = 0.0
+    license_breakdown: dict[str, int] = Field(default_factory=dict)
+    has_permissive_license_repos: bool = False
+
+    # Activity
+    commits_last_30_days: int = 0
+    commits_last_90_days: int = 0
+    prs_opened_last_30_days: int = 0
+    prs_opened_last_90_days: int = 0
+    contributed_repo_stars: int = 0
+    last_active: str | None = None
+
+    # OSS contributions
+    contributes_to_major_oss: bool = False
+    major_oss_contributions: list[str] = Field(default_factory=list)
+
+    # Linked profiles
+    linked_profiles: dict[str, str | None] = Field(default_factory=dict)
+
+    # Scoring
+    activity_score: int = 0
+    activity_score_breakdown: dict[str, int] = Field(default_factory=dict)
+
+
+class RankedCandidate(BaseModel):
+    rank: int
+    username: str
+    score: float
+    reasoning: str
+    strengths: list[str] = Field(default_factory=list)
+    gaps: list[str] = Field(default_factory=list)
+    profile_url: str
+
+
+class RepoContributor(BaseModel):
+    login: str
+    contributions: int
+    html_url: str
+    avatar_url: str = ""

github_talent_mcp/scoring.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+PERMISSIVE_LICENSES = frozenset({
+    "mit", "apache-2.0", "bsd-2-clause", "bsd-3-clause", "isc", "unlicense",
+})
+
+
+def _compute_reputation_floor(followers: int, stars: int, account_age_days: int) -> int:
+    """Compute a minimum score floor based on cumulative reputation.
+
+    Prevents well-known developers from scoring low just because their
+    recent GitHub activity doesn't match behavioral scoring expectations
+    (e.g., Torvalds works via mailing lists, not GitHub PRs).
+    """
+    if followers >= 10_000 or stars >= 50_000:
+        return 150
+    if followers >= 1_000 or stars >= 5_000:
+        return 120
+    if followers >= 500 or stars >= 1_000:
+        return 100
+    if followers >= 100 or stars >= 200:
+        return 80
+    return 0
+
+
+def compute_activity_score(profile: dict[str, Any]) -> tuple[int, dict[str, int]]:
+    """Compute activity score with per-dimension breakdown.
+
+    The score combines behavioral signals (recent commits, PRs, OSS contributions)
+    with a reputation floor (followers, stars) so that well-known developers
+    aren't penalized for workflows that don't produce GitHub events.
+
+    Returns (total_score, breakdown_dict).
+    """
+    breakdown: dict[str, int] = {}
+
+    commits_90d = profile.get("commits_last_90_days", 0)
+    breakdown["commits_last_90_days"] = min(commits_90d * 3, 60)
+
+    breakdown["has_profile_readme"] = 20 if profile.get("has_profile_readme") else 0
+
+    stars = profile.get("total_stars_received", 0)
+    breakdown["stars_on_own_repos"] = min(stars * 2, 40)
+
+    followers = profile.get("followers", 0)
+    breakdown["followers"] = min(followers, 20)
+
+    desc_ratio = profile.get("repos_with_description_ratio", 0.0)
+    breakdown["repos_with_description"] = int(desc_ratio * 20)
+
+    breakdown["permissive_license_repos"] = 15 if profile.get("has_permissive_license_repos") else 0
+
+    oss = profile.get("major_oss_contributions", [])
+    breakdown["major_oss_contributions"] = min(len(oss) * 10, 30)
+
+    behavioral_score = sum(breakdown.values())
+
+    # Apply reputation floor — cumulative impact shouldn't be erased by a quiet quarter
+    account_age_days = profile.get("account_age_days", 0)
+    reputation_floor = _compute_reputation_floor(followers, stars, account_age_days)
+    total = max(behavioral_score, reputation_floor)
+
+    if reputation_floor > behavioral_score:
+        breakdown["reputation_floor"] = reputation_floor
+
+    return total, breakdown
+
+
+def extract_keywords(job_description: str) -> list[str]:
+    """Extract meaningful keywords from a job description."""
+    noise = {
+        "the", "a", "an", "and", "or", "is", "are", "was", "were", "be", "been",
+        "with", "for", "to", "of", "in", "on", "at", "by", "from", "as", "we",
+        "you", "our", "your", "this", "that", "will", "can", "should", "must",
+        "have", "has", "had", "do", "does", "did", "not", "but", "if", "about",
+        "experience", "team", "work", "working", "looking", "join", "role",
+        "ability", "strong", "plus", "years", "knowledge", "skills", "required",
+        "preferred", "etc", "including", "such", "also", "may", "would", "could",
+    }
+    words = re.findall(r"[a-zA-Z#+.]+", job_description.lower())
+    seen: set[str] = set()
+    keywords: list[str] = []
+    for w in words:
+        if len(w) >= 2 and w not in noise and w not in seen:
+            seen.add(w)
+            keywords.append(w)
+    return keywords
+
+
+def compute_relevance_score(profile: dict[str, Any], job_keywords: list[str]) -> int:
+    """Score 0-100 based on keyword overlap between profile and job description."""
+    if not job_keywords:
+        return 50
+
+    searchable_parts = [
+        profile.get("bio") or "",
+        " ".join(profile.get("top_languages", [])),
+        " ".join(profile.get("major_oss_contributions", [])),
+        profile.get("profile_readme_summary") or "",
+        profile.get("company") or "",
+    ]
+    for repo in profile.get("notable_repos", []):
+        if isinstance(repo, dict):
+            searchable_parts.append(repo.get("description") or "")
+            searchable_parts.extend(repo.get("topics") or [])
+            searchable_parts.append(repo.get("language") or "")
+
+    searchable = " ".join(searchable_parts).lower()
+
+    matches = sum(1 for kw in job_keywords if kw in searchable)
+    return min(int((matches / len(job_keywords)) * 100), 100)
+
+
+def generate_strengths_gaps(profile: dict[str, Any]) -> tuple[list[str], list[str]]:
+    """Generate human-readable strengths and gaps from profile data."""
+    strengths: list[str] = []
+    gaps: list[str] = []
+
+    commits_90d = profile.get("commits_last_90_days", 0)
+    prs_90d = profile.get("prs_opened_last_90_days", 0)
+    if commits_90d > 20 or prs_90d > 10:
+        parts = []
+        if commits_90d > 0:
+            parts.append(f"{commits_90d} commits")
+        if prs_90d > 0:
+            parts.append(f"{prs_90d} PRs opened")
+        strengths.append(f"Active contributor: {', '.join(parts)} in last 90 days")
+    elif commits_90d == 0 and prs_90d == 0:
+        gaps.append("No recent public commit or PR activity")
+
+    contributed_stars = profile.get("contributed_repo_stars", 0)
+    if contributed_stars > 1000:
+        strengths.append(f"Contributes to repos with {contributed_stars:,} combined stars")
+
+    if profile.get("has_profile_readme"):
+        strengths.append("Maintains a profile README")
+
+    stars = profile.get("total_stars_received", 0)
+    if stars > 50:
+        strengths.append(f"Popular open source work: {stars} total stars received")
+    elif stars == 0:
+        gaps.append("No starred repositories")
+
+    oss = profile.get("major_oss_contributions", [])
+    if oss:
+        strengths.append(f"Contributes to {len(oss)} external OSS project(s): {', '.join(oss[:3])}")
+
+    if not profile.get("has_permissive_license_repos"):
+        gaps.append("No repos with permissive open-source licenses")
+
+    followers = profile.get("followers", 0)
+    if followers >= 10_000:
+        strengths.append(f"Exceptional community presence: {followers:,} followers")
+    elif followers >= 1_000:
+        strengths.append(f"Strong community presence: {followers:,} followers")
+    elif followers > 100:
+        strengths.append(f"Notable community presence: {followers:,} followers")
+
+    if profile.get("hireable"):
+        strengths.append("Marked as hireable on GitHub")
+
+    langs = profile.get("top_languages", [])
+    if langs:
+        strengths.append(f"Primary languages: {', '.join(langs[:5])}")
+
+    return strengths, gaps

github_talent_mcp/server.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+
+from github_talent_mcp.github_client import GitHubClient
+from github_talent_mcp.tools.search import search_developers as _search
+from github_talent_mcp.tools.profile import get_developer_profile as _profile
+from github_talent_mcp.tools.rank import rank_candidates as _rank
+from github_talent_mcp.tools.contributors import get_repo_contributors as _contributors
+
+load_dotenv()
+
+logging.basicConfig(level=logging.INFO, stream=sys.stderr)
+
+mcp = FastMCP("github-talent")
+
+_client: GitHubClient | None = None
+
+
+def _get_client() -> GitHubClient:
+    global _client
+    if _client is None:
+        token = os.environ.get("GITHUB_TOKEN", "")
+        if not token:
+            logging.warning("GITHUB_TOKEN not set — API requests limited to 60/hr")
+        _client = GitHubClient(token=token)
+    return _client
+
+
+@mcp.tool()
+async def search_developers(
+    languages: list[str] | None = None,
+    location: str | None = None,
+    min_followers: int | None = None,
+    min_repos: int | None = None,
+    limit: int = 20,
+) -> str:
+    """Search GitHub developers by technical and geographic filters.
+
+    Returns a list of matching usernames sorted by followers. Use
+    get_developer_profile on interesting candidates for full enrichment
+    and to verify recent activity.
+
+    For topic-based sourcing (e.g. "LLM", "inference"), use get_repo_contributors
+    on relevant repos instead — GitHub user search doesn't support topic/bio search.
+
+    Args:
+        languages: Filter by programming languages, e.g. ["python", "rust"]
+        location: Filter by location, e.g. "San Francisco" or "Germany"
+        min_followers: Minimum follower count
+        min_repos: Minimum public repo count
+        limit: Max results to return (default 20, max 100)
+    """
+    return await _search(
+        _get_client(),
+        languages=languages,
+        location=location,
+        min_followers=min_followers,
+        min_repos=min_repos,
+        limit=limit,
+    )
+
+
+@mcp.tool()
+async def get_developer_profile(username: str) -> str:
+    """Get enriched GitHub developer profile with activity scoring.
+
+    Returns languages, stars, commit activity, OSS contributions, profile README,
+    license breakdown, and a 0-205 activity score with per-dimension breakdown.
+
+    Args:
+        username: GitHub username to analyze
+    """
+    return await _profile(_get_client(), username)
+
+
+@mcp.tool()
+async def rank_candidates(
+    usernames: list[str],
+    job_description: str,
+    top_n: int = 10,
+) -> str:
+    """Rank GitHub users against a job description.
+
+    Enriches each profile, scores activity + relevance, and returns candidates
+    sorted by combined score with strengths, gaps, and reasoning.
+
+    Args:
+        usernames: GitHub usernames to evaluate
+        job_description: The role description to rank candidates against
+        top_n: Number of top candidates to return (default 10)
+    """
+    return await _rank(
+        _get_client(),
+        usernames=usernames,
+        job_description=job_description,
+        top_n=top_n,
+    )
+
+
+@mcp.tool()
+async def get_repo_contributors(
+    repo: str,
+    limit: int = 25,
+) -> str:
+    """Get top contributors for a GitHub repository as candidate leads.
+
+    Accepts 'owner/repo' format or full GitHub URL.
+
+    Args:
+        repo: Repository in 'owner/repo' format or GitHub URL
+        limit: Max contributors to return (default 25)
+    """
+    return await _contributors(_get_client(), repo=repo, limit=limit)
+
+
+def main():
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

github_talent_mcp/tools/contributors.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import json
+from urllib.parse import urlparse
+
+from github_talent_mcp.github_client import GitHubClient
+
+
+def parse_repo_string(repo: str) -> tuple[str, str]:
+    """Parse 'owner/repo', 'https://github.com/owner/repo', or 'github.com/owner/repo' into (owner, repo)."""
+    repo = repo.strip().rstrip("/")
+
+    # Handle URLs
+    if "github.com" in repo:
+        parsed = urlparse(repo if "://" in repo else f"https://{repo}")
+        parts = [p for p in parsed.path.strip("/").split("/") if p]
+        if len(parts) >= 2:
+            return parts[0], parts[1]
+        raise ValueError(f"Could not parse owner/repo from URL: {repo}")
+
+    # Handle owner/repo
+    if "/" in repo:
+        parts = repo.split("/")
+        if len(parts) == 2 and parts[0] and parts[1]:
+            return parts[0], parts[1]
+
+    raise ValueError(f"Expected 'owner/repo' or GitHub URL, got: {repo}")
+
+
+async def get_repo_contributors(
+    client: GitHubClient,
+    *,
+    repo: str,
+    limit: int = 25,
+) -> str:
+    try:
+        owner, repo_name = parse_repo_string(repo)
+    except ValueError as e:
+        return json.dumps({"error": str(e)})
+
+    try:
+        data = await client.get_repo_contributors(owner, repo_name, per_page=min(limit, 100))
+    except Exception as e:
+        return json.dumps({"error": f"GitHub API error: {e}"})
+
+    contributors = []
+    for c in data[:limit]:
+        if c.get("type") != "User":
+            continue
+        contributors.append({
+            "login": c["login"],
+            "contributions": c["contributions"],
+            "html_url": f"https://github.com/{c['login']}",
+            "avatar_url": c.get("avatar_url", ""),
+        })
+
+    return json.dumps({
+        "repo": f"{owner}/{repo_name}",
+        "total_returned": len(contributors),
+        "contributors": contributors,
+    }, indent=2)

github_talent_mcp/tools/profile.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+
+from github_talent_mcp.github_client import GitHubClient, PERMISSIVE_LICENSES
+from github_talent_mcp.models import DeveloperProfile, NotableRepo
+from github_talent_mcp.scoring import compute_activity_score
+
+
+async def get_developer_profile(client: GitHubClient, username: str) -> str:
+    try:
+        return await _build_profile(client, username)
+    except Exception as e:
+        return json.dumps({"error": f"Failed to build profile for {username}: {e}"})
+
+
+async def _build_profile(client: GitHubClient, username: str) -> str:
+    # 1. Base user data
+    user = await client.get_user(username)
+    now = datetime.now(timezone.utc)
+
+    created_at = user.get("created_at", "")
+    account_age_days = 0
+    if created_at:
+        created = datetime.fromisoformat(created_at.replace("Z", "+00:00"))
+        account_age_days = (now - created).days
+
+    # 2. Repos (owner's non-fork repos for analysis)
+    all_repos = await client.get_user_repos(username)
+    owned_repos = [r for r in all_repos if not r.get("fork")]
+
+    # 3. Language breakdown from top 10 repos by stars
+    sorted_by_stars = sorted(owned_repos, key=lambda r: r.get("stargazers_count", 0), reverse=True)
+    lang_totals: dict[str, int] = {}
+    for repo in sorted_by_stars[:10]:
+        langs = await client.get_repo_languages(username, repo["name"])
+        for lang, byte_count in langs.items():
+            lang_totals[lang] = lang_totals.get(lang, 0) + byte_count
+
+    total_bytes = sum(lang_totals.values()) or 1
+    language_breakdown = {
+        lang: round(bytes_ / total_bytes, 3)
+        for lang, bytes_ in sorted(lang_totals.items(), key=lambda x: x[1], reverse=True)
+    }
+    top_languages = list(language_breakdown.keys())[:10]
+
+    # 4. Stars and forks
+    total_stars = sum(r.get("stargazers_count", 0) for r in owned_repos)
+    total_forks = sum(r.get("forks_count", 0) for r in owned_repos)
+
+    # 5. Description ratio
+    if owned_repos:
+        with_desc = sum(1 for r in owned_repos if r.get("description"))
+        desc_ratio = round(with_desc / len(owned_repos), 2)
+    else:
+        desc_ratio = 0.0
+
+    # 6. License analysis
+    license_counts: dict[str, int] = {}
+    for repo in owned_repos:
+        lic = repo.get("license")
+        spdx = lic.get("spdx_id", "NOASSERTION") if lic else "none"
+        license_counts[spdx] = license_counts.get(spdx, 0) + 1
+
+    has_permissive = any(
+        spdx.lower() in PERMISSIVE_LICENSES for spdx in license_counts
+    )
+    licensed_repos = sum(v for k, v in license_counts.items() if k not in ("none", "NOASSERTION"))
+    license_ratio = round(licensed_repos / len(owned_repos), 2) if owned_repos else 0.0
+
+    # 7. Events: commits, PRs, and OSS contributions
+    events = await client.get_user_events(username)
+    commits_30d = 0
+    commits_90d = 0
+    prs_opened_30d = 0
+    prs_opened_90d = 0
+    last_active: str | None = None
+    oss_contributions: set[str] = set()
+
+    for event in events:
+        created_str = event.get("created_at", "")
+        if not created_str:
+            continue
+        created = datetime.fromisoformat(created_str.replace("Z", "+00:00"))
+        age_days = (now - created).days
+
+        if last_active is None:
+            last_active = created_str
+
+        if event["type"] == "PushEvent":
+            num_commits = len(event.get("payload", {}).get("commits", []))
+            if age_days <= 30:
+                commits_30d += num_commits
+            if age_days <= 90:
+                commits_90d += num_commits
+
+        # Count PR opens as activity (catches PR-based workflows that PushEvents miss)
+        if event["type"] == "PullRequestEvent":
+            action = event.get("payload", {}).get("action", "")
+            if action == "opened":
+                if age_days <= 30:
+                    prs_opened_30d += 1
+                if age_days <= 90:
+                    prs_opened_90d += 1
+
+        if event["type"] in ("PullRequestEvent", "PushEvent", "IssuesEvent", "IssueCommentEvent"):
+            repo_name = event.get("repo", {}).get("name", "")
+            if repo_name and not repo_name.lower().startswith(f"{username.lower()}/"):
+                oss_contributions.add(repo_name)
+
+    # 7b. Fetch star counts for contributed repos (captures org repo impact)
+    contributed_stars = 0
+    for contrib_repo in sorted(oss_contributions)[:5]:  # cap at 5 to limit API calls
+        parts = contrib_repo.split("/")
+        if len(parts) == 2:
+            try:
+                repo_info = await client.get_repo_info(parts[0], parts[1])
+                contributed_stars += repo_info.get("stargazers_count", 0)
+            except Exception as e:
+                logging.getLogger("github-talent-mcp").debug(
+                    "Failed to fetch repo info for %s: %s", contrib_repo, e,
+                )
+
+    # 8. Profile README
+    readme_content = await client.get_profile_readme(username)
+    has_readme = readme_content is not None
+    readme_length = len(readme_content) if readme_content else 0
+    readme_summary = None
+    if readme_content:
+        # Take first ~500 chars as summary (the calling LLM can summarize further)
+        readme_summary = readme_content[:500].strip()
+        if len(readme_content) > 500:
+            readme_summary += "..."
+
+    # 9. Notable repos
+    notable_repos = []
+    for repo in sorted_by_stars[:5]:
+        lic = repo.get("license")
+        notable_repos.append(NotableRepo(
+            name=repo["name"],
+            description=repo.get("description"),
+            stars=repo.get("stargazers_count", 0),
+            forks=repo.get("forks_count", 0),
+            language=repo.get("language"),
+            license=lic.get("spdx_id") if lic else None,
+            topics=repo.get("topics", []),
+            last_updated=repo.get("pushed_at"),
+        ))
+
+    # 10. Linked profiles
+    linked_profiles = {
+        "twitter": user.get("twitter_username"),
+        "personal_site": user.get("blog") or None,
+    }
+
+    # 11. Activity score
+    # Combine push commits + PR opens for total activity signal
+    # PRs weighted x3 (each PR represents more effort than a single commit)
+    total_activity_90d = commits_90d + (prs_opened_90d * 3)
+    # Combine personal repo stars + contributed repo stars
+    combined_stars = total_stars + contributed_stars
+
+    score_input = {
+        "commits_last_90_days": total_activity_90d,
+        "has_profile_readme": has_readme,
+        "total_stars_received": combined_stars,
+        "followers": user.get("followers", 0),
+        "repos_with_description_ratio": desc_ratio,
+        "has_permissive_license_repos": has_permissive,
+        "major_oss_contributions": sorted(oss_contributions),
+        "account_age_days": account_age_days,
+    }
+    activity_score, score_breakdown = compute_activity_score(score_input)
+
+    # 12. Build the full profile
+    profile = DeveloperProfile(
+        login=user["login"],
+        name=user.get("name"),
+        bio=user.get("bio"),
+        location=user.get("location"),
+        email=user.get("email"),
+        blog=user.get("blog"),
+        company=user.get("company"),
+        twitter_username=user.get("twitter_username"),
+        hireable=user.get("hireable"),
+        followers=user.get("followers", 0),
+        following=user.get("following", 0),
+        public_repos=user.get("public_repos", 0),
+        account_age_days=account_age_days,
+        avatar_url=user.get("avatar_url", ""),
+        html_url=user.get("html_url", f"https://github.com/{username}"),
+        has_profile_readme=has_readme,
+        profile_readme_length=readme_length,
+        profile_readme_summary=readme_summary,
+        top_languages=top_languages,
+        language_breakdown=language_breakdown,
+        total_stars_received=total_stars,
+        total_forks_received=total_forks,
+        notable_repos=notable_repos,
+        repos_with_description_ratio=desc_ratio,
+        open_source_license_ratio=license_ratio,
+        license_breakdown=license_counts,
+        has_permissive_license_repos=has_permissive,
+        commits_last_30_days=commits_30d,
+        commits_last_90_days=commits_90d,
+        prs_opened_last_30_days=prs_opened_30d,
+        prs_opened_last_90_days=prs_opened_90d,
+        contributed_repo_stars=contributed_stars,
+        last_active=last_active,
+        contributes_to_major_oss=bool(oss_contributions),
+        major_oss_contributions=sorted(oss_contributions),
+        linked_profiles=linked_profiles,
+        activity_score=activity_score,
+        activity_score_breakdown=score_breakdown,
+    )
+
+    return json.dumps(profile.model_dump(), indent=2)

github_talent_mcp/tools/rank.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import json
+
+from github_talent_mcp.github_client import GitHubClient
+from github_talent_mcp.scoring import (
+    compute_relevance_score,
+    extract_keywords,
+    generate_strengths_gaps,
+)
+from github_talent_mcp.tools.profile import get_developer_profile
+
+
+async def rank_candidates(
+    client: GitHubClient,
+    *,
+    usernames: list[str],
+    job_description: str,
+    top_n: int = 10,
+) -> str:
+    keywords = extract_keywords(job_description)
+    candidates = []
+
+    for username in usernames:
+        profile_json = await get_developer_profile(client, username)
+        profile = json.loads(profile_json)
+
+        if "error" in profile:
+            candidates.append({
+                "rank": 0,
+                "username": username,
+                "score": 0,
+                "reasoning": f"Could not fetch profile: {profile['error']}",
+                "strengths": [],
+                "gaps": ["Profile unavailable"],
+                "profile_url": f"https://github.com/{username}",
+            })
+            continue
+
+        activity = profile.get("activity_score", 0)
+        relevance = compute_relevance_score(profile, keywords)
+
+        # Weighted combination: relevance matters more than raw activity
+        combined = activity * 0.4 + relevance * 0.6
+
+        strengths, gaps = generate_strengths_gaps(profile)
+
+        # Build reasoning sentence
+        parts = []
+        if activity >= 120:
+            parts.append("exceptional GitHub activity")
+        elif activity >= 80:
+            parts.append("strong GitHub activity")
+        elif activity >= 40:
+            parts.append("moderate GitHub activity")
+        else:
+            parts.append("limited public activity")
+
+        if relevance >= 70:
+            parts.append("high keyword match with job description")
+        elif relevance >= 40:
+            parts.append("partial keyword match")
+        else:
+            parts.append("low keyword overlap with job description")
+
+        top_langs = profile.get("top_languages", [])[:3]
+        if top_langs:
+            parts.append(f"primary languages: {', '.join(top_langs)}")
+
+        reasoning = ". ".join(p.capitalize() for p in parts) + "."
+
+        candidates.append({
+            "rank": 0,
+            "username": username,
+            "score": round(combined, 1),
+            "reasoning": reasoning,
+            "strengths": strengths,
+            "gaps": gaps,
+            "profile_url": profile.get("html_url", f"https://github.com/{username}"),
+        })
+
+    # Sort by score descending and assign ranks
+    candidates.sort(key=lambda c: c["score"], reverse=True)
+    for i, c in enumerate(candidates[:top_n], 1):
+        c["rank"] = i
+
+    return json.dumps({
+        "job_keywords_extracted": keywords[:20],
+        "total_evaluated": len(candidates),
+        "candidates": candidates[:top_n],
+    }, indent=2)

github_talent_mcp/tools/search.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import json
+
+from github_talent_mcp.github_client import GitHubClient
+
+
+async def search_developers(
+    client: GitHubClient,
+    *,
+    languages: list[str] | None = None,
+    location: str | None = None,
+    min_followers: int | None = None,
+    min_repos: int | None = None,
+    limit: int = 20,
+) -> str:
+    per_page = min(limit, 100)
+
+    try:
+        data = await client.search_users(
+            languages=languages,
+            location=location,
+            min_followers=min_followers,
+            min_repos=min_repos,
+            per_page=per_page,
+        )
+    except Exception as e:
+        return json.dumps({"error": f"GitHub API error: {e}"})
+
+    results = []
+    for item in data.get("items", [])[:limit]:
+        results.append({
+            "login": item["login"],
+            "avatar_url": item.get("avatar_url", ""),
+            "html_url": item.get("html_url", f"https://github.com/{item['login']}"),
+        })
+
+    return json.dumps({
+        "total_count": data.get("total_count", 0),
+        "returned": len(results),
+        "note": "Use get_developer_profile on candidates for full enrichment with activity scoring.",
+        "developers": results,
+    }, indent=2)

github_talent_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: github-talent-mcp
+Version: 0.1.0
+Summary: MCP server for searching, scoring, and ranking GitHub developers for technical recruiting
+Author: Carolina Cherry
+License: MIT
+Project-URL: Homepage, https://github.com/carolinacherry/github-talent-mcp
+Project-URL: Repository, https://github.com/carolinacherry/github-talent-mcp
+Project-URL: Issues, https://github.com/carolinacherry/github-talent-mcp/issues
+Keywords: mcp,github,recruiting,developer-tools,claude
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+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
+Dynamic: license-file
+
+# github-talent-mcp
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![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 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.
+
+## Demo
+
+https://github.com/user-attachments/assets/2dfd82b4-3eb5-4f2b-bc0a-2580b95043e4
+
+### Profile deep dive
+
+> Get the full developer profile and activity score for torvalds on GitHub
+
+Claude calls `get_developer_profile("torvalds")` and returns:
+
+| Field | Value |
+|---|---|
+| **Activity Score** | **150** (reputation floor applied) |
+| Location | Portland, OR |
+| Followers | 293,321 |
+| Stars Received | 235,068 |
+| Primary Language | C (98.1%) |
+| Commits (90d) | 0 |
+| PRs (90d) | 0 |
+| Notable Repos | linux (183K stars), libdc-for-dirk, subsurface-for-dirk, uemacs, pesern-resolve |
+| Profile README | No |
+| Hireable | No |
+
+Torvalds has zero recent GitHub activity because kernel development flows through mailing lists, not GitHub PRs. The **reputation floor** (293K followers) overrides the behavioral score and sets it to 150.
+
+### Repo contributor ranking
+
+> Get the top contributors to huggingface/transformers and rank them for a founding ML engineer role at an AI startup
+
+Claude calls `get_repo_contributors("huggingface/transformers")` → `rank_candidates` on the top 24 contributors:
+
+| Rank | Developer | Combined Score | Activity | Relevance | Strengths |
+|---|---|---|---|---|---|
+| 1 | stas00 | 83.4 | 150 | 72 | 4,553 stars, contributes to major OSS, MIT-licensed repos |
+| 2 | cyyever | 80.8 | 120 | 64 | 1,217 followers, active contributor, profile README |
+| 3 | Cyrilvallez | 77.2 | 120 | 56 | Active: 13 commits + 57 PRs in 90 days, strong OSS presence |
+| 4 | ArthurZucker | 74.4 | 120 | 48 | 37 PRs in 90 days, contributes to huggingface/transformers |
+| 5 | ydshieh | 72.0 | 120 | 40 | Active: 9 commits + 40 PRs in 90 days |
+
+Combined score = activity × 0.4 + relevance × 0.6. Relevance is keyword overlap with the job description (ML, AI, startup, engineer, etc.).
+
+## Installation
+
+### 1. Clone and install
+
+```bash
+git clone https://github.com/carolinacherry/github-talent-mcp.git
+cd github-talent-mcp
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+### 2. Create a GitHub personal access token
+
+Go to [github.com/settings/tokens](https://github.com/settings/tokens) and create a **fine-grained** or **classic** token with these scopes:
+
+| Scope | Why |
+|---|---|
+| `read:user` | Read user profiles and search users |
+| `public_repo` | Read public repo data, languages, contributors |
+
+Create a `.env` file in the project root:
+
+```
+GITHUB_TOKEN=ghp_xxxxxxxxxxxx
+```
+
+### 3. Connect to Claude
+
+#### Claude Code (CLI)
+
+One command:
+
+```bash
+claude mcp add github-talent -- /path/to/github-talent-mcp/.venv/bin/python3 -m github_talent_mcp
+```
+
+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`.
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "github-talent": {
+      "command": "/path/to/github-talent-mcp/.venv/bin/python3",
+      "args": ["-m", "github_talent_mcp"],
+      "cwd": "/path/to/github-talent-mcp",
+      "env": {
+        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The tools will appear in the toolbox icon.
+
+## Try It
+
+Once installed, paste these prompts to verify everything works:
+
+**Basic search:**
+> Find Python developers in Raleigh active in the last 60 days
+
+**Profile deep dive:**
+> Get the full developer profile and activity score for torvalds on GitHub
+
+**Full workflow:**
+> Find 10 ML engineers in San Francisco active in the last 30 days, then rank them for a senior LLM inference engineer role
+
+**Repo contributors:**
+> Get the top contributors to huggingface/transformers and rank them for a founding ML engineer role at an AI startup
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `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. |
+| `get_repo_contributors` | Top contributors for any repo. Accepts `owner/repo` or full URL. The fastest way to source for a specific domain. |
+
+## Scoring
+
+The activity score combines two layers: **behavioral signals** (what you did recently) and a **reputation floor** (what you've built over time).
+
+### Behavioral Score (0-205)
+
+| Signal | Max Points | How |
+|---|---|---|
+| Commits + PRs (last 90 days) | 60 | Push commits + PR opens (PRs weighted x3). Captures both push-based and PR-based workflows. |
+| Stars on repos | 40 | Personal repo stars + stars on repos you contribute to. Org repo maintainers get credit. |
+| Profile README | 20 | Presence of a profile README (github.com/username/username). |
+| Followers | 20 | Capped at 20. |
+| Repos with descriptions | 20 | Ratio of repos that have descriptions. Signal of care and polish. |
+| Permissive license repos | 15 | Has at least one repo with MIT, Apache-2.0, BSD, ISC, or Unlicense. |
+| Major OSS contributions | 30 | PRs, pushes, or issues on repos you don't own. Capped at 3 repos (10 pts each). |
+
+### Reputation Floor
+
+The behavioral score alone penalizes developers whose work doesn't produce GitHub events — Torvalds works through mailing lists, senior maintainers merge via org bots, and many engineers work in private repos.
+
+The reputation floor ensures cumulative impact isn't erased by a quiet quarter:
+
+| Threshold | Floor |
+|---|---|
+| 10K+ followers **or** 50K+ stars | 150 |
+| 1K+ followers **or** 5K+ stars | 120 |
+| 500+ followers **or** 1K+ stars | 100 |
+| 100+ followers **or** 200+ stars | 80 |
+
+The final score is `max(behavioral_score, reputation_floor)`. If the floor is applied, the breakdown includes a `reputation_floor` field so you know.
+
+### Score Tiers
+
+- **150+** — exceptional (top OSS maintainers, well-known engineers)
+- **120-149** — strong signal, worth reaching out
+- **80-119** — solid developer with meaningful public work
+- **40-79** — active but limited public signal
+- **<40** — low signal (likely private work or junior)
+
+### Ranking
+
+`rank_candidates` combines the activity score with a **relevance score** (0-100) based on keyword overlap between the job description and the candidate's profile (bio, languages, repo topics, README). The combined score weights relevance at 60% and activity at 40% — a high-activity developer with no overlap to the job shouldn't outrank a relevant one.
+
+## Rate Limits
+
+GitHub REST API: 5,000 requests/hour with token. A typical workflow (search + enrich 5 candidates + rank) uses ~60-100 API calls. Profile results are cached within a session to avoid redundant calls during ranking.
+
+## License
+
+MIT

github_talent_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+github_talent_mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+github_talent_mcp/__main__.py,sha256=xboib-GsIoLb6gAKr_J8Ez58m2bVEtcIylTIEX6hMmM,50
+github_talent_mcp/github_client.py,sha256=At7Q1KWXkDwp75rfN8KRc-jT7fQlNlBt03HRWOPgHw8,6614
+github_talent_mcp/models.py,sha256=fc1erOnkw-E5qRgHCNcbctf9wJQTpWphf0RmEtrjsqc,2545
+github_talent_mcp/scoring.py,sha256=ruM2cYGl_ZXJcsTWaWQI3STVDyd9ifdQatN4z0esxSo,6592
+github_talent_mcp/server.py,sha256=rf9pq1wtxV3_uZGHCOpj-DE6uy_mNGpcb3n7j5XXAnU,3691
+github_talent_mcp/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+github_talent_mcp/tools/contributors.py,sha256=Oy4lKEg31dczj0wE3crILYmscBDamUN6DZrEwirlbjQ,1859
+github_talent_mcp/tools/profile.py,sha256=u7UHgj6j7NQXutgBwJPp-RXkd_xms6PnLdXtzdqO-58,8683
+github_talent_mcp/tools/rank.py,sha256=_Msx_Req2YqPq__UHj9UtJLRomwS11c6_23HMx3RO9c,2897
+github_talent_mcp/tools/search.py,sha256=HLJ2BkleuQPGNnGqAW9xn5aYl6AJHpia0f6yf2aEAfY,1234
+github_talent_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=fvdAvsHztUyLfy24J6KGQxObupndrkyC7loArb9nSa4,1072
+github_talent_mcp-0.1.0.dist-info/METADATA,sha256=3qZuPS5nGplWCbc3Qs1hVXeyAP9YUQJXEGTIrfjt5ro,8943
+github_talent_mcp-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+github_talent_mcp-0.1.0.dist-info/entry_points.txt,sha256=mbH4DQjPoKjMoCuaeYMKULS1thXzBHCk0bTwVrY9gJc,68
+github_talent_mcp-0.1.0.dist-info/top_level.txt,sha256=s6U6EATNZhgMhH4K9fGZFBq63L9nOeHtTBFUbfchKjY,18
+github_talent_mcp-0.1.0.dist-info/RECORD,,

github_talent_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

github_talent_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+github-talent-mcp = github_talent_mcp.server:main

github_talent_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carolina Cherry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

github_talent_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+github_talent_mcp