mcp-github-learning-assistant 0.1.0__tar.gz

mcp_github_learning_assistant-0.1.0/.env.example

@@ -0,0 +1,4 @@
+# GitHub Personal Access Token
+# 在 https://github.com/settings/tokens 创建
+# 不需要特殊权限，public_repo 即可
+GITHUB_TOKEN=your_github_token_here

mcp_github_learning_assistant-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install project and dev dependencies
+        run: pip install -e .[dev]
+
+      - name: Lint
+        run: ruff check src tests scripts
+
+      - name: Test
+        run: pytest -q

mcp_github_learning_assistant-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Environment
+.env
+
+# pytest
+.pytest_cache/

mcp_github_learning_assistant-0.1.0/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.

mcp_github_learning_assistant-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,75 @@
+# 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/docs/decisions.md

@@ -0,0 +1,156 @@
+# 决策记录
+
+## 2026-10-10：项目方向
+
+决定不做通用 GitHub MCP Server，因为 GitHub 官方已经做了很全的版本。
+我们选择「开源学习助手」这一细分方向，聚焦学习决策。
+
+## 2026-10-10：技术选型
+
+- 语言：Python 3.10+
+- 原因：MCP 官方 Python SDK 最成熟，上手快，适合快速验证
+- 分发方式：pip install（主要），Docker 后续可选
+- 依赖管理：pyproject.toml + pip
+- 用户实际环境：Python 3.12.10（Windows）
+- 测试客户端：Cherry Studio（国产开源，MCP 支持好）
+- 备选客户端：Cline（VS Code 插件）、LobeHub
+
+## 2026-10-10：GitHub API 选择
+
+使用 GitHub REST API v3，因为：
+- 文档完善
+- 无需复杂 GraphQL 查询
+- 覆盖我们需要的所有功能
+
+## 2026-10-10：部署策略
+
+优先 pip install，原因：
+- Python 项目安装最自然
+- 用户已有 Python 环境
+- 比 Docker 轻量
+- 开发和调试更方便
+
+Docker 作为第二阶段的可选方案。
+
+## 2026-10-10：测试客户端
+
+没有 Claude Desktop，选择国产客户端 Cherry Studio 进行测试。
+Cherry Studio 开源、支持 MCP、中文界面友好。
+
+---
+
+## 2026-10-11：MCP SDK API 版本适配
+
+mcp 2.3.0 的 Server 类没有 list_tools / call_tool 装饰器。
+改用高层 MCPServer，使用 @app.tool() 装饰器注册工具。
+决策：跟随已安装的 mcp 2.3.0 API，不回退旧版本。
+
+## 2026-10-11：添加 python -m 运行入口
+
+为了支持 `python -m mcp_github_learning_assistant`，
+新增 src/mcp_github_learning_assistant/__main__.py 作为包执行入口。
+
+## 2026-10-11：项目分层
+
+参考 Spring Boot 分层结构：
+- models/outputs.py  → DTO（数据结构）
+- analyzer.py        → Service（核心业务逻辑）
+- tools/analyze.py   → Controller（MCP 工具接入口）
+- server.py          → 启动类
+
+好处：逻辑独立、便于测试、面试讲得清楚。
+
+## 2026-10-11：GitHub Token 策略
+
+申请 fine-grained PAT：
+- Repository access: Public Repositories (read-only)
+- Permissions: 无
+- 目的：只提高 60 -> 5000 次每小时的请求额度
+- 传递方式：环境变量 GITHUB_TOKEN，不入库（.gitignore 排除 .env）
+
+## 2026-10-11：评分算法调整
+
+发现 learning_score 可能超过 10（stars 加分后再 + 文档分）。
+修复：min(10.0, ...) 挪到所有加减法之后统一封顶。
+评分函数是纯启发式，后续可以替换成更复杂的启发式或模型打分。
+
+## 2026-10-11：首次 Git 提交
+
+commit: d2ab733
+提交内容：项目骨架 + 2 个工具（get_server_info、analyze_repo_for_learning）+ 文档。
+其中 analyze_repo_for_learning 已实测成功（spring-projects/spring-boot）。
+
+## 2026-10-11：确认项目不含 FastAPI
+
+MCP 走 stdio 时不需要 HTTP 服务。
+后续若支持远程部署（SSE / streamable HTTP）再考虑引入 FastAPI。
+
+
+---
+
+## 2026-10-11：MCP Inspector 调试通过
+
+使用 MCP 官方 Inspector（npx @modelcontextprotocol/inspector）验证：
+- Server 进程启动正常（stdio 待命）
+- Connect 握手成功
+- Tools 标签列出 get_server_info 和 analyze_repo_for_learning
+- get_server_info Run 后正确返回
+
+结论：MCP 协议层、工具注册层全链路可用，可以进入新工具开发和真实客户端（Cherry Studio）集成阶段。
+
+## 2026-10-11：README 乱码修复
+
+原因：PowerShell 5.1 Set-Content -Encoding UTF8 带 BOM，且代码块语言标注被写入坏字节。
+修复：用 .NET [System.IO.File]::WriteAllText 配合 UTF8Encoding($false) 重写为 UTF-8 无 BOM。
+README 改为英文为主，后续考虑增加 README.zh-CN.md 双语版。
+
+
+---
+
+## 2026-10-11：MVP 全部工具实数据验证通过
+
+所有 7 个工具在真实 GitHub 数据下验证成功：
+- spring-boot analysis 评分/难度/路径
+- Spring Boot 仓库推荐（3 条）
+- vscode good-first-issues（10 条）
+- fastapi similar repos（aiohttp/starlette，语义正确）
+- spring-boot vs quarkus vs micronaut 排序
+- spring-boot roadmap（documentation → core → tests 顺序合理）
+
+### Issues 空列表诊断（spring-boot）
+
+连续三次为空，通过 debug_issues.py 三路交叉验证：
+- 无 label 基线 → 有数据（排除连通性）
+- labels=good first issue → []
+- Search API 同条件 → total_count: 0
+
+结论：spring-boot 确实当前 0 条 open good-first-issue（大数据项目常见），
+不是 bug。测试目标切到 microsoft/vscode 后正常返回 10 条。
+产品改进点（下一步）：空结果时返回引导文案而非空 JSON。
+
+### Roadmap 优化史
+
+第一版：按 API 返回顺序取前 10 个目录，充斥 .idea/antora/buildSrc 等噪音。
+第二版：加 _SKIP_PATTERNS 跳过工程目录，按关键词赋学习优先级。
+第三版：修复 "src in buildSrc" 子串误匹配（buildSrc 加入黑名单），
+documentation 通过 "doc" 关键词正确识别为高优先级。
+经验：目录名关键词匹配必须用词边界或黑名单双保险。
+
+### Similar 优化史
+
+第一版按 topic/language 搜索，fastapi 混入 public-apis（只是同为 Python）。
+第二版增加策略：优先非通用 topic，其次从 repo 名/描述提关键词，
+兜底 language-only + stars:>10000。fastapi 现在返回 aiohttp/starlette，语义正确。
+
+## 2026-10-11：整理截图文档
+
+docs/screenshots/README.md 是给开发者看的临时截图指引，对仓库访客没有价值。
+删除该子文档，截图使用说明并入主 README 的 Screenshots 部分。
+仓库内只保留主 README 一个入口，避免访客在截图目录看到重复说明。
+
+## 2026-10-11：新增 trending 工具
+
+GitHub API 没有官方 trending 接口，工具不再假装能直接取到榜单。
+改用 Search API 近似实现：按 language/topic、最低星数、创建时间和是否 fork/archived 过滤，
+再用 stars / age_days 作为趋势分排序。
+决策：输出明确的 stars_per_day 计算依据，让调用方知道这是可解释的近似，而非官方榜单。

mcp_github_learning_assistant-0.1.0/docs/plan.md

@@ -0,0 +1,61 @@
+# 项目规划
+
+## 产品定位
+
+帮助开发者（尤其是初学者和转行者）根据自身水平和目标，发现适合学习的 GitHub 开源项目。
+
+区别于 GitHub 官方 MCP Server（侧重仓库操作），我们聚焦「学习决策」。
+
+## 目标用户
+
+- 编程初学者
+- 转行开发者
+- 面试准备者
+- 想参与开源的人
+- 进阶学习者
+
+## 核心功能
+
+### Tools
+1. recommend_learning_repos：根据定位推荐项目
+2. analyze_repo_for_learning：深度分析项目学习价值
+3. get_repo_roadmap：生成学习路线
+4. find_similar_repos：查找相似项目
+5. compare_learning_repos：对比多个项目
+6. find_good_first_issues：找适合新手的 issue
+7. get_trending_repos_for_learning：发现热门学习项目
+
+## 技术栈
+
+- Python 3.10+
+- MCP 官方 SDK
+- httpx
+- pydantic
+- pytest
+- ruff
+- pip / uv
+
+## 开发阶段
+
+### Week 1：项目骨架 + recommend tool
+- 搭建项目结构
+- 封装 GitHub API 客户端
+- 实现第一个 Tool：recommend_learning_repos
+- 在 Cherry Studio 中测试
+
+### Week 2：核心分析工具
+- analyze_repo_for_learning
+- get_repo_roadmap
+- find_similar_repos
+
+### Week 3：高级工具 + Prompts
+- compare_learning_repos
+- find_good_first_issues
+- get_trending_repos_for_learning
+- 添加 MCP Prompts
+
+### Week 4：测试 + 发布 + 文档
+- 补充 pytest 测试
+- GitHub Actions CI
+- 发布到 PyPI
+- 完善 README 和使用教程

mcp_github_learning_assistant-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "mcp-github-learning-assistant"
+version = "0.1.0"
+description = "An MCP server that helps developers discover and learn from GitHub open-source projects"
+authors = [{name = "iyiook333"}]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.6.0",
+]
+
+[project.scripts]
+mcp-github-learning-assistant = "mcp_github_learning_assistant.server:run"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

mcp_github_learning_assistant-0.1.0/scripts/debug_issues.py

@@ -0,0 +1,47 @@
+"""Debug why issue queries return empty."""
+
+import asyncio
+
+from dotenv import load_dotenv
+
+from mcp_github_learning_assistant.github_client import github_client
+
+
+async def main():
+    """Print raw responses for label queries."""
+    load_dotenv()
+    owner, repo = "spring-projects", "spring-boot"
+
+    async with await github_client() as client:
+        # No-label baseline
+        r0 = await client.get(
+            f"/repos/{owner}/{repo}/issues",
+            params={"state": "open", "per_page": 3},
+        )
+        print("no-label status:", r0.status_code)
+        if r0.status_code == 200:
+            items = r0.json()
+            print("  got", len(items), "issues (any labels)")
+            for it in items:
+                print("   -", it.get("number"), it.get("title"))
+
+        # Label query
+        r1 = await client.get(
+            f"/repos/{owner}/{repo}/issues",
+            params={"labels": "good first issue", "state": "open", "per_page": 3},
+        )
+        print("good-first-issue status:", r1.status_code)
+        print("  body[:300]:", r1.text[:300])
+
+        # Search API alternative (OR across labels)
+        q = f"repo:{owner}/{repo} is:issue is:open label:'good first issue',label:'help wanted'"
+        r2 = await client.get("/search/issues", params={"q": q, "per_page": 5})
+        print("search-api status:", r2.status_code)
+        if r2.status_code == 200:
+            data = r2.json()
+            print("  total_count:", data.get("total_count"))
+            for it in data.get("items", [])[:5]:
+                print("   -", it.get("number"), it.get("title"))
+
+
+asyncio.run(main())

mcp_github_learning_assistant-0.1.0/scripts/test_analyze.py

@@ -0,0 +1,15 @@
+"""Direct test for the analyzer logic (no MCP involved)."""
+
+import asyncio
+
+from mcp_github_learning_assistant.analyzer import analyze_repo
+
+
+async def main():
+    """Analyze spring-projects/spring-boot and print JSON."""
+    result = await analyze_repo("spring-projects", "spring-boot")
+    print(result.model_dump_json(indent=2))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_github_learning_assistant-0.1.0/scripts/test_client.py

@@ -0,0 +1,32 @@
+"""Simple MCP client to test the server locally."""
+
+import asyncio
+import sys
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+
+async def main():
+    """Connect to the MCP server and call get_server_info."""
+    server_params = StdioServerParameters(
+        command=sys.executable,
+        args=["-m", "mcp_github_learning_assistant"],
+        env=None,
+    )
+
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            tools = await session.list_tools()
+            print("Available tools:", [tool.name for tool in tools.tools])
+
+            result = await session.call_tool("get_server_info", {})
+            print("Tool result:")
+            for content in result.content:
+                print(content.text)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

mcp_github_learning_assistant-0.1.0/scripts/test_compare.py

@@ -0,0 +1,17 @@
+import asyncio
+
+from mcp_github_learning_assistant.comparer import compare_repos
+
+
+async def main():
+    r = await compare_repos(
+        repos=[
+            "spring-projects/spring-boot",
+            "quarkusio/quarkus",
+            "micronaut-projects/micronaut-core",
+        ],
+        user_level="beginner",
+    )
+    print(r.model_dump_json(indent=2))
+
+asyncio.run(main())

mcp_github_learning_assistant-0.1.0/scripts/test_issues.py

@@ -0,0 +1,14 @@
+"""Direct test for find_first_issues (no MCP involved)."""
+
+import asyncio
+
+from mcp_github_learning_assistant.issuefind import find_first_issues
+
+
+async def main():
+    """vscode reliably has many good first issues."""
+    r = await find_first_issues("microsoft", "vscode", ["good first issue"])
+    print(r.model_dump_json(indent=2))
+
+
+asyncio.run(main())