mcp-github-learning-assistant 0.1.0__py3-none-any.whl

mcp_github_learning_assistant/__init__.py

@@ -0,0 +1,3 @@
+"""MCP GitHub Learning Assistant."""
+
+__version__ = "0.1.0"

mcp_github_learning_assistant/__main__.py

@@ -0,0 +1,8 @@
+"""Allow running the package with python -m."""
+
+import asyncio
+
+from .server import main
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_github_learning_assistant/analyzer.py

@@ -0,0 +1,125 @@
+"""Analysis logic: turn GitHub raw data into learning advice."""
+
+import base64
+
+from .github_client import github_client
+from .models.outputs import RepoAnalysis
+
+_PREREQ_MAP = {
+    "Java": ["Java basics", "Maven/Gradle", "IDE usage"],
+    "Python": ["Python basics", "pip/venv", "Data structures"],
+    "TypeScript": ["TypeScript basics", "npm/pnpm", "Node.js"],
+    "JavaScript": ["JavaScript basics", "npm", "DOM"],
+    "Go": ["Go basics", "go mod"],
+    "Rust": ["Rust basics", "cargo"],
+}
+
+
+def _score_doc_length(readme_len: int) -> str:
+    """Judge doc quality roughly by README length."""
+    if readme_len > 10000:
+        return "excellent"
+    elif readme_len > 3000:
+        return "good"
+    elif readme_len > 500:
+        return "fair"
+    return "poor"
+
+
+def _judge_difficulty(stars: int) -> str:
+    """Rough difficulty by repo size; can be refined later."""
+    if stars > 50000:
+        return "intermediate"
+    return "beginner"
+
+
+def _build_prerequisites(language: str) -> list[str]:
+    """Recommend prerequisites by main language."""
+    return _PREREQ_MAP.get(language, ["Basic programming"])
+
+
+def _build_path(doc_quality: str) -> list[str]:
+    """Build a suggested learning path."""
+    path = ["Read README to understand positioning"]
+    if doc_quality in ("good", "excellent"):
+        path.append("Follow official docs / quickstart with a minimal example")
+    path.extend([
+        "Browse repo structure, find core modules",
+        "Start reading code via a small issue or feature",
+    ])
+    return path
+
+
+async def analyze_repo(owner: str, repo: str) -> RepoAnalysis:
+    """Fetch data from GitHub API and produce analysis."""
+    async with await github_client() as client:
+        # 1. Basic repo info
+        repo_resp = await client.get(f"/repos/{owner}/{repo}")
+        repo_resp.raise_for_status()
+        repo_data = repo_resp.json()
+
+        # 2. Language breakdown
+        lang_resp = await client.get(f"/repos/{owner}/{repo}/languages")
+        lang_data = lang_resp.json()
+        main_language = next(iter(lang_data), repo_data.get("language") or "Unknown")
+
+        # 3. Recent commit activity
+        commit_resp = await client.get(
+            f"/repos/{owner}/{repo}/commits", params={"per_page": 1}
+        )
+        has_commits = commit_resp.status_code == 200 and len(commit_resp.json()) > 0
+
+        # 4. README quality
+        readme_resp = await client.get(f"/repos/{owner}/{repo}/readme")
+        readme_bytes = readme_resp.json().get("content", "")
+        readme_text = base64.b64decode(readme_bytes).decode("utf-8", errors="ignore")
+        doc_quality = _score_doc_length(len(readme_text))
+
+    stars = repo_data["stargazers_count"]
+    difficulty = _judge_difficulty(stars)
+    prerequisites = _build_prerequisites(main_language)
+    path = _build_path(doc_quality)
+
+    pros: list[str] = []
+    if stars > 10000:
+        pros.append(f"Large community ({stars} stars)")
+    if doc_quality in ("good", "excellent"):
+        pros.append("Well documented")
+    if has_commits:
+        pros.append("Actively maintained")
+
+    cons: list[str] = []
+    if stars > 50000:
+        cons.append("Large codebase, takes time to read")
+    if doc_quality == "poor":
+        cons.append("Weak docs, will rely on source code")
+
+    score = stars / 10000 + 3.0
+    if doc_quality in ("good", "excellent"):
+        score += 1.0
+    if not has_commits:
+        score -= 2.0
+    score = max(0.0, min(10.0, round(score, 1)))
+
+    active_text = "still maintained" if has_commits else "possibly unmaintained"
+    summary = (
+        f"{repo_data['full_name']} has {stars} stars, main language {main_language}. "
+        f"Doc quality is {doc_quality}, project is {active_text}. "
+        f"Overall difficulty: {difficulty}."
+    )
+
+    return RepoAnalysis(
+        repo_name=repo_data["full_name"],
+        stars=stars,
+        language=main_language,
+        difficulty=difficulty,
+        learning_score=score,
+        prerequisites=prerequisites,
+        pros=pros,
+        cons=cons,
+        suggested_path=path,
+        doc_quality=doc_quality,
+        active=has_commits,
+        summary=summary,
+    )
+

mcp_github_learning_assistant/comparer.py

@@ -0,0 +1,71 @@
+"""Compare candidate repos and suggest which to learn first."""
+
+import base64
+
+from .github_client import github_client
+from .models.outputs import ComparisonResult
+
+
+def _score(data: dict, language: str, doc_quality: str) -> float:
+    """Weighted score: stars(0-4), docs(0-3), language-match(0-3)."""
+    stars = data.get("stargazers_count", 0)
+    stars_score = min(4.0, stars / 20000)
+    doc_score = {"excellent": 3.0, "good": 2.0, "fair": 1.0, "poor": 0.0}.get(doc_quality, 1.0)
+    lang_match = 3.0  # since filtered by language, assume high match
+    return round(stars_score + doc_score + lang_match, 1)
+
+
+def _doc_quality(readme_len: int) -> str:
+    if readme_len > 10000:
+        return "excellent"
+    elif readme_len > 3000:
+        return "good"
+    elif readme_len > 500:
+        return "fair"
+    return "poor"
+
+
+async def compare_repos(repos: list, user_level: str) -> ComparisonResult:
+    """Fetch each repo info and add score, then rank."""
+    async with await github_client() as client:
+        rows = []
+        for full in repos:
+            resp = await client.get(f"/repos/{full.strip()}")
+            if resp.status_code != 200:
+                rows.append({"repo": full, "error": f"not found ({resp.status_code})"})
+                continue
+            data = resp.json()
+            # doc-quality proxy
+            doc = "fair"
+            try:
+                rm = await client.get(f"/repos/{full.strip()}/readme")
+                rm.raise_for_status()
+                txt = base64.b64decode(rm.json().get("content", ""))
+                txt = txt.decode("utf-8", errors="ignore")
+                doc = _doc_quality(len(txt))
+            except Exception:
+                doc = "fair"
+            rows.append(
+                {
+                    "repo": data.get("full_name"),
+                    "stars": data.get("stargazers_count", 0),
+                    "language": data.get("language") or "Unknown",
+                    "description": data.get("description") or "",
+                    "updated_at": data.get("updated_at"),
+                    "doc_quality": doc,
+                    "score": _score(data, data.get("language"), doc),
+                }
+            )
+
+    success = [r for r in rows if "error" not in r]
+    success.sort(key=lambda x: x["score"], reverse=True)
+    best = success[0]["repo"] if success else None
+
+    return ComparisonResult(
+        comparison=rows,
+        best_for_learning=best,
+        user_level_note=(
+            f"Scored with a bias toward beginner-friendly docs because "
+            f"user level is '{user_level}'."
+        ),
+    )

mcp_github_learning_assistant/github_client.py

@@ -0,0 +1,24 @@
+"""GitHub API client."""
+
+import os
+
+import httpx
+
+GITHUB_API_BASE = "https://api.github.com"
+
+
+def get_github_token() -> str | None:
+    """Get GitHub token from environment."""
+    return os.environ.get("GITHUB_TOKEN")
+
+
+async def github_client() -> httpx.AsyncClient:
+    """Create an authenticated GitHub API client."""
+    token = get_github_token()
+    headers = {
+        "Accept": "application/vnd.github.v3+json",
+        "User-Agent": "mcp-github-learning-assistant",
+    }
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return httpx.AsyncClient(base_url=GITHUB_API_BASE, headers=headers, timeout=30.0)

mcp_github_learning_assistant/issuefind.py

@@ -0,0 +1,54 @@
+"""Find good first issues for newcomers."""
+
+import re
+
+from .github_client import github_client
+from .models.outputs import FirstIssueList
+
+_TAG_RE = re.compile(r"<[^>]+>")
+
+
+def _clean(text: str, limit: int = 200) -> str:
+    """Strip HTML tags and truncate text."""
+    return re.sub(_TAG_RE, "", text or "")[:limit].strip()
+
+
+async def find_first_issues(owner: str, repo: str, labels) -> FirstIssueList:
+    """Fetch open issues matching ANY of the starter-friendly labels (OR query).
+
+    We split multiple labels into separate requests because GitHub API's
+    `labels` param is AND semantics, which almost always yields no results
+    when passing multiple labels together.
+    """
+    label_list = [x.strip() for x in (labels[0] if labels else "").split(",") if x.strip()]
+    if not label_list:
+        label_list = ["good first issue"]
+
+    async with await github_client() as client:
+        all_issues: dict[int, dict] = {}
+        for label in label_list:
+            resp = await client.get(
+                f"/repos/{owner}/{repo}/issues",
+                params={"labels": label, "state": "open", "per_page": 10},
+            )
+            if resp.status_code != 200:
+                continue
+            for it in resp.json():
+                if "pull_request" in it:  # skip PRs
+                    continue
+                all_issues[it["number"]] = it  # dedupe by issue number
+
+    ordered = sorted(all_issues.values(), key=lambda x: x.get("number", 0), reverse=True)
+
+    issues = [
+        {
+            "number": it.get("number"),
+            "title": it.get("title"),
+            "url": it.get("html_url"),
+            "labels": [label.get("name") for label in it.get("labels", [])],
+            "preview": _clean(it.get("body") or ""),
+        }
+        for it in ordered[:10]
+    ]
+
+    return FirstIssueList(repo=f"{owner}/{repo}", issues=issues)

mcp_github_learning_assistant/models/__init__.py

@@ -0,0 +1 @@
+# Models package

mcp_github_learning_assistant/models/outputs.py

@@ -0,0 +1,130 @@
+"""Pydantic models for tool outputs."""
+
+from pydantic import BaseModel
+
+
+class RepoAnalysis(BaseModel):
+    """Learning value analysis result."""
+
+    repo_name: str
+    stars: int
+    language: str
+    difficulty: str          # beginner / intermediate / advanced
+    learning_score: float    # 0-10
+    prerequisites: list[str]
+    pros: list[str]
+    cons: list[str]
+    suggested_path: list[str]
+    doc_quality: str         # poor / fair / good / excellent
+    active: bool
+    summary: str
+
+
+class RepoRecommendation(BaseModel):
+    """A single recommended repo."""
+
+    repo: str
+    stars: int
+    language: str
+    difficulty: str
+    match_score: float
+    why_recommended: str
+    estimated_time: str
+
+
+class RecommendationList(BaseModel):
+    """List of recommendations from recommend_learning_repos tool."""
+
+    recommendations: list[RepoRecommendation]
+    message: str
+
+
+class RoadmapModule(BaseModel):
+    """One module in a learning roadmap."""
+
+    name: str
+    hint: str
+    learning_order: int
+    path: str
+
+
+class RepoRoadmap(BaseModel):
+    """Learning roadmap derived from repo structure."""
+
+    repo: str
+    modules: list[RoadmapModule]
+    summary: str
+
+
+class SimilarRepo(BaseModel):
+    """One similar repo result."""
+
+    repo: str
+    stars: int
+    language: str
+    description: str
+    url: str
+
+
+class SimilarRepoList(BaseModel):
+    """List of similar repos."""
+
+    source_repo: str
+    similar: list[SimilarRepo]
+
+
+class TrendingRepo(BaseModel):
+    """One recently popular repo."""
+
+    repo: str
+    stars: int
+    stars_per_day: float
+    language: str
+    description: str
+    url: str
+
+
+class TrendingRepoList(BaseModel):
+    """List of trending repos for learning."""
+
+    language: str | None
+    topic: str | None
+    period_days: int
+    repos: list[TrendingRepo]
+
+
+class FirstIssue(BaseModel):
+    """One good-first-issue entry."""
+
+    number: int
+    title: str
+    url: str
+    labels: list[str]
+    preview: str
+
+
+class FirstIssueList(BaseModel):
+    """List of good first issues."""
+
+    repo: str
+    issues: list[FirstIssue]
+
+
+class ComparisonRow(BaseModel):
+    """One row in a repo comparison."""
+
+    repo: str
+    stars: int
+    language: str
+    description: str
+    updated_at: str | None = None
+    doc_quality: str = "fair"
+    score: float = 0.0
+
+
+class ComparisonResult(BaseModel):
+    """Comparison of multiple repos."""
+
+    comparison: list[ComparisonRow]
+    best_for_learning: str | None
+    user_level_note: str

mcp_github_learning_assistant/recommender.py

@@ -0,0 +1,119 @@
+"""Recommendation logic: match user profile to suitable GitHub repos."""
+
+import base64
+
+from .github_client import github_client
+from .models.outputs import RecommendationList, RepoRecommendation
+
+# Seed repos per tech (curated starting set; can be expanded or replaced by search later)
+_TECH_SEEDS = {
+    "spring boot": [
+        ("spring-projects/spring-boot", "Official Spring Boot repo"),
+        ("alibaba/fastjson2", "Popular Java JSON library with clean code"),
+        ("iluwatar/java-design-patterns", "Java design patterns, beginner-friendly docs"),
+    ],
+    "fastapi": [
+        ("fastapi/fastapi", "Official FastAPI repo"),
+        ("tiangolo/full-stack-fastapi-template", "Full-stack FastAPI template"),
+    ],
+    "vue": [
+        ("vuejs/core", "Vue 3 core"),
+        ("vuejs/pinia", "Official state management"),
+        ("vitejs/vite", "Build tool for Vue ecosystem"),
+    ],
+    "electron": [
+        ("electron/electron", "Electron framework"),
+    ],
+    "react": [
+        ("facebook/react", "React core"),
+    ],
+    "harmonyos": [
+        ("openharmony/docs", "OpenHarmony docs"),
+    ],
+}
+
+
+def _guess_seed_key(target_tech: str) -> str | None:
+    """Find a matching seed list key for the given target tech."""
+    tech_lower = (target_tech or "").lower()
+    for key in _TECH_SEEDS:
+        if key in tech_lower:
+            return key
+    return None
+
+
+def _score_for_level(stars: int, level: str) -> float:
+    """Quick heuristic: beginner-friendly repos should have good docs and not be gigantic."""
+    if level == "beginner":
+        return min(10.0, 5.0 + min(stars, 50000) / 10000)
+    return min(10.0, 4.0 + min(stars, 80000) / 10000)
+
+
+async def recommend_repos(role, target_tech, level, goal, count):
+    """Fetch repo data from GitHub and assemble recommendations."""
+    tech = _guess_seed_key(target_tech)
+    if not tech:
+        return RecommendationList(
+            recommendations=[],
+            message=(
+                f"No curated seeds for '{target_tech}'. Suggested: try Spring boot, "
+                "FastAPI, Vue, React, Electron, HarmonyOS."
+            ),
+        )
+
+    async with await github_client() as client:
+        recommendations: list[RepoRecommendation] = []
+        for full_name, note in _TECH_SEEDS[tech]:
+            try:
+                resp = await client.get(f"/repos/{full_name}")
+                resp.raise_for_status()
+                data = resp.json()
+            except Exception:
+                continue  # skip repos we can't fetch right now
+
+            stars = data.get("stargazers_count", 0)
+            difficulty = "beginner" if stars < 50000 else "intermediate"
+            recs_score = _score_for_level(stars, level)
+
+            # Fetch README length as doc-quality proxy
+            doc = "fair"
+            try:
+                rm = await client.get(f"/repos/{full_name}/readme")
+                rm.raise_for_status()
+                content = rm.json().get("content", "")
+                readme_len = len(base64.b64decode(content).decode("utf-8", errors="ignore"))
+                if readme_len > 10000:
+                    doc = "excellent"
+                elif readme_len > 3000:
+                    doc = "good"
+                elif readme_len > 500:
+                    doc = "fair"
+                else:
+                    doc = "poor"
+            except Exception:
+                doc = "fair"
+
+            why = f"{note}. Main language: {data.get('language')}, doc quality: {doc}."
+            if goal == "interview_prep":
+                why += " Useful for building a resume project."
+            elif goal == "open_source":
+                why += " Look at 'good first issue' labels to start contributing."
+
+            recommendations.append(
+                RepoRecommendation(
+                    repo=full_name,
+                    stars=stars,
+                    language=data.get("language") or "Unknown",
+                    difficulty=difficulty if level == "intermediate" else level,
+                    match_score=round(recs_score, 1),
+                    why_recommended=why,
+                    estimated_time="2-3 months" if difficulty == "intermediate" else "1-2 months",
+                )
+            )
+            if len(recommendations) >= count:
+                break
+
+    return RecommendationList(
+        recommendations=recommendations,
+        message=f"Found {len(recommendations)} repos for '{target_tech}'.",
+    )

mcp_github_learning_assistant/roadmap.py

@@ -0,0 +1,77 @@
+"""Learning-roadmap logic based on repo top-level structure."""
+
+from .github_client import github_client
+from .models.outputs import RepoRoadmap
+
+# Directories to skip: not helpful for learning
+_SKIP_PATTERNS = {
+    ".github", ".idea", ".vscode", ".git", ".circleci", ".devcontainer",
+    "antora", "config", "buildpack", "gradle", "mvn", "scripts",
+    "distribution", "buildsrc", "build", "eclipse", "git", "ci",
+    "framework", "checkstyle", "etc",
+}
+
+# Ordered learning priority by directory-name keywords
+_HINTS = [
+    ("doc", "Read documentation first for concepts and setup", 1),
+    ("example", "Run sample examples to see usage", 2),
+    ("test", "Read tests to learn expected behavior", 5),
+    ("core", "Study core implementation module", 3),
+    ("src", "Study main source code", 3),
+    ("lib", "Review library internals", 4),
+    ("app", "Understand application entry points", 4),
+    ("web", "Front-end integration details", 4),
+    ("tools", "Look at build/dev tooling", 6),
+]
+
+# Lower `priority` = earlier in learning order
+_PRIORITY_DEFAULT = 5  # for unmatched dirs
+
+
+def _priority_for(name: str) -> tuple[int, str]:
+    """Return (priority, hint). Lower priority learns first."""
+    for kw, hint, prio in _HINTS:
+        if kw in name.lower():
+            return prio, hint
+    return _PRIORITY_DEFAULT, "Explore module to understand its purpose"
+
+
+def _skip(name: str) -> bool:
+    """Return True if this directory should not appear in roadmap."""
+    return name.lower() in _SKIP_PATTERNS or name.startswith(".")
+
+
+async def build_roadmap(owner: str, repo: str, depth: int) -> RepoRoadmap:
+    """Fetch top-level content and produce a clean, ordered learning roadmap."""
+    async with await github_client() as client:
+        resp = await client.get(f"/repos/{owner}/{repo}/contents")
+        resp.raise_for_status()
+        items = resp.json()
+
+    dirs = [item for item in items if item.get("type") == "dir" and not _skip(item.get("name", ""))]
+
+    # Sort by priority then name so ordering is deterministic
+    scored = []
+    for d in dirs:
+        prio, hint = _priority_for(d.get("name", ""))
+        scored.append((prio, d.get("name", ""), hint, d.get("path")))
+
+    scored.sort(key=lambda x: (x[0], x[1]))
+
+    modules = []
+    for i, (prio, name, hint, path) in enumerate(scored[:10], start=1):
+        modules.append(
+            {
+                "name": name,
+                "hint": hint,
+                "learning_order": i,
+                "path": path,
+            }
+        )
+
+    skipped = len([item for item in items if item.get("type") == "dir"]) - len(dirs)
+    summary = (
+        f"Generated learning sequence with {len(modules)} relevant modules "
+        f"from {owner}/{repo} top level (skipped {skipped} non-source directories)."
+    )
+    return RepoRoadmap(repo=f"{owner}/{repo}", modules=modules, summary=summary)

mcp_github_learning_assistant/server.py

@@ -0,0 +1,155 @@
+"""MCP server entry point."""
+
+import asyncio
+import sys
+
+from dotenv import load_dotenv
+from mcp.server import MCPServer
+
+from .tools import analyze, compare, issues, recommend, roadmap, similar, trending
+
+app = MCPServer("mcp-github-learning-assistant")
+
+
+@app.tool()
+async def get_server_info() -> str:
+    """Return basic server info to verify the MCP connection works."""
+    return "MCP GitHub Learning Assistant v0.1.0 - discover open-source projects worth learning"
+
+
+@app.tool()
+async def analyze_repo_for_learning(owner: str, repo: str) -> str:
+    """Analyze a GitHub repo to see if it is worth learning.
+
+    Returns score, difficulty, prerequisites, pros/cons and a suggested
+    learning path as a JSON string.
+
+    Args:
+        owner: GitHub user or org name, e.g. spring-projects
+        repo: Repository name, e.g. spring-boot
+    """
+    results = await analyze.analyze_repo_tool({"owner": owner, "repo": repo})
+    return results[0].text
+
+
+@app.tool()
+async def recommend_learning_repos(
+    role: str,
+    target_tech: str,
+    experience_level: str,
+    goal: str,
+    count: int = 5,
+) -> str:
+    """Recommend GitHub repos to learn, based on the user's profile.
+
+    Args:
+        role: user role, e.g. student, backend_dev, frontend_dev, mobile_dev
+        target_tech: tech to learn, e.g. Spring Boot, FastAPI, Vue
+        experience_level: beginner, intermediate, or advanced
+        goal: interview_prep, skill_upgrade, open_source, project_practice
+        count: max recommendation count (default 5)
+    """
+    arguments = {
+        "role": role,
+        "target_tech": target_tech,
+        "experience_level": experience_level,
+        "goal": goal,
+        "count": count,
+    }
+    results = await recommend.recommend_repos_tool(arguments)
+    return results[0].text
+
+
+@app.tool()
+async def get_repo_roadmap(owner: str, repo: str, depth: int = 2) -> str:
+    """Generate a learning roadmap from a repo's top-level structure.
+
+    Args:
+        owner: GitHub user or org name
+        repo: Repository name
+        depth: how deep to explore (reserved; currently uses top level)
+    """
+    results = await roadmap.roadmap_tool({"owner": owner, "repo": repo, "depth": depth})
+    return results[0].text
+
+
+@app.tool()
+async def find_similar_repos(owner: str, repo: str, count: int = 3) -> str:
+    """Find similar repositories (same language/topic) for comparison.
+
+    Args:
+        owner: GitHub user or org name
+        repo: Repository name
+        count: max similar repos to return
+    """
+    results = await similar.similar_tool({"owner": owner, "repo": repo, "count": count})
+    return results[0].text
+
+
+@app.tool()
+async def find_good_first_issues(owner: str, repo: str) -> str:
+    """Find beginner-friendly (good first issue / help wanted) open issues.
+
+    Args:
+        owner: GitHub user or org name
+        repo: Repository name
+    """
+    results = await issues.issues_tool({"owner": owner, "repo": repo})
+    return results[0].text
+
+
+@app.tool()
+async def compare_learning_repos(repos: list[str], user_level: str = "intermediate") -> str:
+    """Compare 2+ repos and suggest which to learn first.
+
+    Args:
+        repos: list of full repo names like ["spring-projects/spring-boot", "quarkusio/quarkus"]
+        user_level: beginner / intermediate / advanced
+    """
+    results = await compare.compare_tool({"repos": repos, "user_level": user_level})
+    return results[0].text
+
+
+@app.tool()
+async def get_trending_repos_for_learning(
+    language: str = "",
+    topic: str = "",
+    count: int = 5,
+    min_stars: int = 100,
+    period_days: int = 90,
+) -> str:
+    """Find recently popular repositories suitable for learning.
+
+    Args:
+        language: programming language filter, e.g. Python
+        topic: GitHub topic filter, e.g. fastapi
+        count: maximum repos to return (1-10)
+        min_stars: minimum lifetime stars (default 100)
+        period_days: look-back window in days (1-365)
+    """
+    results = await trending.trending_tool(
+        {
+            "language": language,
+            "topic": topic,
+            "count": count,
+            "min_stars": min_stars,
+            "period_days": period_days,
+        }
+    )
+    return results[0].text
+
+
+async def main():
+    """Run the MCP server."""
+    load_dotenv()  # auto-load .env file if present
+    print("MCP Server starting...", file=sys.stderr, flush=True)
+    await app.run_stdio_async()
+
+
+def run():
+    """Run the MCP server from a console script entry point."""
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_github_learning_assistant/similar.py

@@ -0,0 +1,86 @@
+"""Find similar repos using GitHub search.
+
+Strategy (in order of specificity):
+1. Search by the source repo's primary topic + language
+2. If no topics, use descriptive keywords from repo name/description + language
+3. Fall back to language-only query with framework-ish qualifier
+"""
+
+from .github_client import github_client
+from .models.outputs import SimilarRepoList
+
+# Very generic topics that give bad results if used alone
+_GENERIC_TOPICS = {
+    "python", "javascript", "typescript", "java", "go", "rust",
+    "api", "library", "framework", "http", "server", "cli", "json",
+    "hacktoberfest",
+}
+
+
+def _pick_topic(topics: list) -> str | None:
+    """Pick the most topic-meaningful label."""
+    for t in topics:
+        if t.lower() not in _GENERIC_TOPICS:
+            return t
+    return None
+
+
+def _keywords_from_name_desc(repo_name: str, desc: str) -> str:
+    """Extract a short query from repo name or description."""
+    # Try name first, take main word
+    base = repo_name.split("/")[-1].lower()
+    if len(base) > 3:
+        return base
+    # Fall back to first few words of description
+    words = (desc or "").split()
+    return " ".join(words[:3]) if words else ""
+
+
+async def find_similar(owner: str, repo: str, count: int) -> SimilarRepoList:
+    """Search GitHub for thematically similar repos (not merely same language)."""
+    async with await github_client() as client:
+        base_resp = await client.get(f"/repos/{owner}/{repo}")
+        base_resp.raise_for_status()
+        base = base_resp.json()
+
+        language = base.get("language") or "Unknown"
+        topics = base.get("topics") or []
+        description = base.get("description") or ""
+
+        topic = _pick_topic(topics) if topics else None
+        if topic:
+            q = f"topic:{topic} language:{language}"
+        else:
+            kw = _keywords_from_name_desc(repo, description)
+            # Exclude generic keyword to avoid joining unrelated top-repos
+            if kw and len(kw) > 3:
+                q = f"{kw} language:{language} stars:>1000"
+            else:
+                q = f"language:{language} stars:>10000"  # last resort
+
+        search_resp = await client.get(
+            "/search/repositories",
+            params={"q": q, "sort": "stars", "order": "desc", "per_page": 20},
+        )
+        search_resp.raise_for_status()
+        items = search_resp.json().get("items", [])
+
+    full = f"{owner}/{repo}"
+    results = []
+    for item in items:
+        name = item.get("full_name")
+        if name == full:
+            continue
+        results.append(
+            {
+                "repo": name,
+                "stars": item.get("stargazers_count", 0),
+                "language": item.get("language") or "Unknown",
+                "description": item.get("description") or "",
+                "url": item.get("html_url") or "",
+            }
+        )
+        if len(results) >= count:
+            break
+
+    return SimilarRepoList(source_repo=full, similar=results)

mcp_github_learning_assistant/tools/__init__.py

@@ -0,0 +1 @@
+# Tools package

mcp_github_learning_assistant/tools/analyze.py

@@ -0,0 +1,25 @@
+"""MCP tool: analyze repo for learning."""
+
+from mcp.types import TextContent
+
+from ..analyzer import analyze_repo
+
+
+async def analyze_repo_tool(arguments: dict) -> list[TextContent]:
+    """Entry point called by AI.
+
+    Args:
+        arguments: dict with keys `owner` and `repo`.
+    """
+    try:
+        owner = arguments["owner"]
+        repo = arguments["repo"]
+    except KeyError as e:
+        return [TextContent(type="text", text=f"Missing required argument: {e}")]
+
+    try:
+        result = await analyze_repo(owner, repo)
+    except Exception as e:
+        return [TextContent(type="text", text=f"Analysis failed: {e}")]
+
+    return [TextContent(type="text", text=result.model_dump_json(indent=2))]

mcp_github_learning_assistant/tools/compare.py

@@ -0,0 +1,22 @@
+"""MCP tool: compare candidate repos for learning."""
+
+from mcp.types import TextContent
+
+from ..comparer import compare_repos
+
+
+async def compare_tool(arguments: dict) -> list[TextContent]:
+    """Entry point: expects `repos` (list of full names) and optional user_level."""
+    repos = arguments.get("repos") or []
+    if not isinstance(repos, list) or len(repos) < 2:
+        return [TextContent(
+            type="text",
+            text="Please provide at least 2 repos as list of 'owner/repo'.",
+        )]
+    level = arguments.get("user_level", "intermediate")
+
+    try:
+        result = await compare_repos(repos, level)
+    except Exception as e:
+        return [TextContent(type="text", text=f"Comparison failed: {e}")]
+    return [TextContent(type="text", text=result.model_dump_json(indent=2))]

mcp_github_learning_assistant/tools/info.py

@@ -0,0 +1,16 @@
+"""Simple info tool for testing."""
+
+from mcp.types import TextContent
+
+
+async def get_server_info() -> list[TextContent]:
+    """Return server information."""
+    return [
+        TextContent(
+            type="text",
+            text=(
+                "MCP GitHub Learning Assistant v0.1.0 - "
+                "discover open-source projects worth learning"
+            ),
+        )
+    ]

mcp_github_learning_assistant/tools/issues.py

@@ -0,0 +1,21 @@
+"""MCP tool: find good first issues."""
+
+from mcp.types import TextContent
+
+from ..issuefind import find_first_issues
+
+
+async def issues_tool(arguments: dict) -> list[TextContent]:
+    """Entry point: expects owner, repo(optional labels)."""
+    try:
+        owner = arguments["owner"]
+        repo = arguments["repo"]
+    except KeyError as e:
+        return [TextContent(type="text", text=f"Missing required argument: {e}")]
+    labels = arguments.get("labels", "good first issue,help wanted")
+
+    try:
+        result = await find_first_issues(owner, repo, [labels])
+    except Exception as e:
+        return [TextContent(type="text", text=f"Issue-finding failed: {e}")]
+    return [TextContent(type="text", text=result.model_dump_json(indent=2))]

mcp_github_learning_assistant/tools/recommend.py

@@ -0,0 +1,33 @@
+"""MCP tool: recommend learning repositories based on user profile."""
+
+from mcp.types import TextContent
+
+from ..recommender import recommend_repos
+
+
+async def recommend_repos_tool(arguments: dict) -> list[TextContent]:
+    """Entry point called by AI.
+
+    Expected argument keys:
+        role: student / backend_dev / frontend_dev / mobile_dev / ai_dev
+        target_tech: e.g. Spring Boot, FastAPI, Vue 3
+        experience_level: beginner / intermediate / advanced
+        goal: interview_prep / skill_upgrade / open_source / project_practice
+        count: max recommendations to return
+    """
+    role = arguments.get("role", "student")
+    tech = arguments.get("target_tech", "")
+    level = arguments.get("experience_level", "beginner")
+    goal = arguments.get("goal", "skill_upgrade")
+    count = arguments.get("count", 5)
+    try:
+        count = max(1, min(int(count), 10))
+    except (TypeError, ValueError):
+        count = 5
+
+    try:
+        recs = await recommend_repos(role, tech, level, goal, count)
+    except Exception as e:
+        return [TextContent(type="text", text=f"Recommendation failed: {e}")]
+
+    return [TextContent(type="text", text=recs.model_dump_json(indent=2))]

mcp_github_learning_assistant/tools/roadmap.py

@@ -0,0 +1,22 @@
+"""MCP tool: generate learning roadmap from repo structure."""
+
+from mcp.types import TextContent
+
+from ..roadmap import build_roadmap
+
+
+async def roadmap_tool(arguments: dict) -> list[TextContent]:
+    """Entry point: expects owner, repo, depth(optional)."""
+    try:
+        owner = arguments["owner"]
+        repo = arguments["repo"]
+    except KeyError as e:
+        return [TextContent(type="text", text=f"Missing required argument: {e}")]
+    depth = int(arguments.get("depth", 2))
+    depth = max(1, min(depth, 3))
+
+    try:
+        result = await build_roadmap(owner, repo, depth)
+    except Exception as e:
+        return [TextContent(type="text", text=f"Roadmap failed: {e}")]
+    return [TextContent(type="text", text=result.model_dump_json(indent=2))]

mcp_github_learning_assistant/tools/similar.py

@@ -0,0 +1,22 @@
+"""MCP tool: find similar repositories by language & topic."""
+
+from mcp.types import TextContent
+
+from ..similar import find_similar
+
+
+async def similar_tool(arguments: dict) -> list[TextContent]:
+    """Entry point: expects owner, repo, count(optional)."""
+    try:
+        owner = arguments["owner"]
+        repo = arguments["repo"]
+    except KeyError as e:
+        return [TextContent(type="text", text=f"Missing required argument: {e}")]
+    count = int(arguments.get("count", 3))
+    count = max(1, min(count, 10))
+
+    try:
+        result = await find_similar(owner, repo, count)
+    except Exception as e:
+        return [TextContent(type="text", text=f"Similar-repos failed: {e}")]
+    return [TextContent(type="text", text=result.model_dump_json(indent=2))]

mcp_github_learning_assistant/tools/trending.py

@@ -0,0 +1,35 @@
+"""MCP tool: find recent popular repositories."""
+
+from mcp.types import TextContent
+
+from ..trending import get_trending_repos
+
+
+async def trending_tool(arguments: dict) -> list[TextContent]:
+    """Entry point: expects language and/or topic with search options."""
+    language = str(arguments.get("language", "")).strip()
+    topic = str(arguments.get("topic", "")).strip()
+    if not language and not topic:
+        return [TextContent(type="text", text="Provide a language and/or topic.")]
+
+    try:
+        count = max(1, min(int(arguments.get("count", 5)), 10))
+        min_stars = max(0, int(arguments.get("min_stars", 100)))
+        period_days = max(1, min(int(arguments.get("period_days", 90)), 365))
+    except (TypeError, ValueError):
+        count = 5
+        min_stars = 100
+        period_days = 90
+
+    try:
+        result = await get_trending_repos(
+            language=language.lower(),
+            topic=topic.lower(),
+            count=count,
+            min_stars=min_stars,
+            period_days=period_days,
+        )
+    except Exception as error:
+        return [TextContent(type="text", text=f"Trending lookup failed: {error}")]
+
+    return [TextContent(type="text", text=result.model_dump_json(indent=2))]

mcp_github_learning_assistant/trending.py

@@ -0,0 +1,82 @@
+"""Find recently popular repositories using GitHub search."""
+
+from datetime import datetime, timedelta, timezone
+
+from .github_client import github_client
+from .models.outputs import TrendingRepo, TrendingRepoList
+
+
+def _build_query(language: str, topic: str, min_stars: int, created_after: str) -> str:
+    """Build a GitHub repository search query."""
+    terms = [
+        f"language:{language}" if language else "",
+        f"topic:{topic}" if topic else "",
+        f"stars:>={min_stars}",
+        f"created:>{created_after}",
+        "archived:false",
+        "fork:false",
+    ]
+    return " ".join(term for term in terms if term)
+
+
+def _parse_created_at(value: str) -> datetime | None:
+    """Parse an ISO-8601 GitHub timestamp safely."""
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except (AttributeError, TypeError, ValueError):
+        return None
+
+
+async def get_trending_repos(
+    language: str,
+    topic: str,
+    count: int,
+    min_stars: int,
+    period_days: int,
+) -> TrendingRepoList:
+    """Find high-star repositories created within the requested period."""
+    language = language.strip().lower()
+    topic = topic.strip().lower()
+    period_ended = datetime.now(timezone.utc)
+    period_started = period_ended - timedelta(days=period_days)
+    created_after = period_started.date().isoformat()
+    search_query = _build_query(language, topic, min_stars, created_after)
+
+    async with await github_client() as client:
+        response = await client.get(
+            "/search/repositories",
+            params={
+                "q": search_query,
+                "sort": "stars",
+                "order": "desc",
+                "per_page": count,
+            },
+        )
+        response.raise_for_status()
+        items = response.json().get("items", [])
+
+    repos: list[TrendingRepo] = []
+    for item in items:
+        created_at = _parse_created_at(item.get("created_at"))
+        age_days = max(
+            1, (period_ended - created_at).days if created_at else period_days
+        )
+        stars = item.get("stargazers_count", 0)
+        repos.append(
+            TrendingRepo(
+                repo=item.get("full_name") or "",
+                stars=stars,
+                stars_per_day=round(stars / age_days, 1),
+                language=item.get("language") or "Unknown",
+                description=item.get("description") or "",
+                url=item.get("html_url") or "",
+            )
+        )
+
+    repos.sort(key=lambda repo: repo.stars_per_day, reverse=True)
+    return TrendingRepoList(
+        language=language or None,
+        topic=topic or None,
+        period_days=period_days,
+        repos=repos,
+    )

mcp_github_learning_assistant-0.1.0.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.5
+Name: mcp-github-learning-assistant
+Version: 0.1.0
+Summary: An MCP server that helps developers discover and learn from GitHub open-source projects
+Author: iyiook333
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+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
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MCP GitHub Learning Assistant
+
+An MCP (Model Context Protocol) server that helps developers discover and learn from open-source projects on GitHub, based on their skill level and goals.
+
+## Features
+
+8 tools to support every stage of open-source learning:
+
+| Tool | Description |
+|------|-------------|
+| `analyze_repo_for_learning` | Score a repo: stars, doc quality, difficulty, prerequisites, suggested learning path |
+| `recommend_learning_repos` | Curated recommendations per tech stack (Spring Boot, FastAPI, Vue, React, Electron, HarmonyOS) |
+| `get_repo_roadmap` | Generate a step-by-step learning roadmap from a repo's directory structure |
+| `find_similar_repos` | Find thematically similar repos (same language/topic) for comparison |
+| `find_good_first_issues` | Find beginner-friendly open issues (good first issue / help wanted) |
+| `compare_learning_repos` | Compare 2+ candidate repos and suggest which to learn first |
+| `get_trending_repos_for_learning` | Find breakout repos created recently by language/topic |
+| `get_server_info` | Verify the MCP server connection |
+
+## Screenshots
+
+| MCP Inspector - Tools list | MCP Inspector - analyze_repo_for_learning result |
+|:---:|:---:|
+| ![Inspector Tools](https://raw.githubusercontent.com/iyiook333/mcp-github-learning-assistant/master/docs/screenshots/inspector-tools.jpg) | ![Inspector Analyze](https://raw.githubusercontent.com/iyiook333/mcp-github-learning-assistant/master/docs/screenshots/inspector-analyze.jpg) |
+
+Screenshots use dark-mode crops under 500KB each.
+
+## Installation
+
+```bash
+pip install mcp-github-learning-assistant
+```
+
+## Configuration
+
+Set your GitHub Personal Access Token:
+
+```powershell
+# Windows PowerShell
+$env:GITHUB_TOKEN = "your_github_token"
+```
+
+```bash
+# Linux / macOS
+export GITHUB_TOKEN=your_github_token
+```
+
+Token scope: fine-grained PAT with no special permissions (public repo read-only) is enough.
+
+## Usage in MCP Clients
+
+### MCP Inspector (development)
+
+```bash
+npx @modelcontextprotocol/inspector python -m mcp_github_learning_assistant
+```
+
+### Cherry Studio
+
+1. Open Cherry Studio, go to Settings -> MCP
+2. Add an MCP server with the command `python -m mcp_github_learning_assistant`
+3. Set the environment variable `GITHUB_TOKEN`
+
+## Development
+
+```bash
+git clone https://github.com/iyiook333/mcp-github-learning-assistant.git
+cd mcp-github-learning-assistant
+pip install -e .[dev]
+pytest
+```
+
+## License
+
+MIT

mcp_github_learning_assistant-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+mcp_github_learning_assistant/__init__.py,sha256=iYC6R6V4fgqkeCQ-NxBLKxF86ojy1ooAxdkxs3lCKxE,64
+mcp_github_learning_assistant/__main__.py,sha256=pmJap3GHEmTMV2nvIFa4tifa9-10Ow4Gl_LFmAp1Tls,142
+mcp_github_learning_assistant/analyzer.py,sha256=__Wi8zDlmdfyM-LAltHd9j_GpyTw184Ry9P_CAGhmos,4160
+mcp_github_learning_assistant/comparer.py,sha256=743KIizbw0BVSptMPfiEDp7sM8AI7BuIEAWwwtHOc2s,2615
+mcp_github_learning_assistant/github_client.py,sha256=eg98xpGu6aL1O6xCkTSc98qUeYwEkjiogq8Z2Pms-c4,641
+mcp_github_learning_assistant/issuefind.py,sha256=lAKFUjvQ2_Z3J3Ijo7VYC9bQt_-k82HXZ2OXzW1UCms,1875
+mcp_github_learning_assistant/recommender.py,sha256=9J24b3gY5skxLhnBOnb2w0eruqG6A7obIHaTjvt2kJk,4454
+mcp_github_learning_assistant/roadmap.py,sha256=k8kMcd2F6VdsN58DLt6dombciSQxdRL5xQXvWZnHmUo,2872
+mcp_github_learning_assistant/server.py,sha256=lkeaDL0gyQf3uuOdArk8S6cBBELs9UKfBnJbUwLpZ-w,4580
+mcp_github_learning_assistant/similar.py,sha256=mZSThh1rrSFEhqZqKy8y0evClNFgvqGUif4y5AQe9Yw,2990
+mcp_github_learning_assistant/trending.py,sha256=tUn2_we94a-uRIvY0miL7CizBDlQwlwswdlSmDnYIF8,2701
+mcp_github_learning_assistant/models/__init__.py,sha256=Bvq5w7Vj873u7FT9HKvKci2iD-CdRKOii12xgWdfGTE,21
+mcp_github_learning_assistant/models/outputs.py,sha256=_aZF2CvoxI6-DEUOQ68GqlGaWV8GfyZQxPu9_hIscco,2487
+mcp_github_learning_assistant/tools/__init__.py,sha256=CQ-dDaKhiwoYYQnvkb3RDi5XgXnnW8YGHE6JSzuWSDg,20
+mcp_github_learning_assistant/tools/analyze.py,sha256=bAHh_t6dkUGXJPc5gxLpF4xRt_WdLjbDog3e705e9kI,715
+mcp_github_learning_assistant/tools/compare.py,sha256=biIrrM05lvuq4qXy_9eyFT4LkY17KO9oIykezmVDO3M,808
+mcp_github_learning_assistant/tools/info.py,sha256=f448pXWRh_yaqChnwmtxQjznx-hr0rPm9dO1RWNUw2A,390
+mcp_github_learning_assistant/tools/issues.py,sha256=lOIlw8TXLUvtTYwanmSGOhIjnEbs1AgijD7nWQGt_ms,751
+mcp_github_learning_assistant/tools/recommend.py,sha256=oZISqHeeSucggbR8UInYgMHON_jFO5IVlySzl2lLEW0,1207
+mcp_github_learning_assistant/tools/roadmap.py,sha256=_iFv_COY7xZi9UEXkvnSwFSyuv0SNC0izBYZIMFo2tM,764
+mcp_github_learning_assistant/tools/similar.py,sha256=EuRTnUo7Tw0FPyxt9LGOTrNLFL0fwNBkxcuUBnVdfpo,769
+mcp_github_learning_assistant/tools/trending.py,sha256=pn1plw83E68Nw7yGuj7wCsnbpPDcLNSk9h4NsuvpkH0,1237
+mcp_github_learning_assistant-0.1.0.dist-info/METADATA,sha256=_xc4ycc5NvF3G4_PkJt6ArhKi9mGS2iYMLavsuqJbII,3343
+mcp_github_learning_assistant-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+mcp_github_learning_assistant-0.1.0.dist-info/entry_points.txt,sha256=z1J-_9Ur83GR0UplkNp9gxWFB3wz7xAL0TfnOwUDgfw,91
+mcp_github_learning_assistant-0.1.0.dist-info/licenses/LICENSE,sha256=7tb57gjQnuCyKGlquv4Aim6NrFaR0lueq0wxqGTTGqw,1062
+mcp_github_learning_assistant-0.1.0.dist-info/RECORD,,

mcp_github_learning_assistant-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_github_learning_assistant-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-github-learning-assistant = mcp_github_learning_assistant.server:run

mcp_github_learning_assistant-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iyiook333
+
+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.