mcp-github-learning-assistant 0.1.0__tar.gz → 0.1.1__tar.gz

{mcp_github_learning_assistant-0.1.0 → mcp_github_learning_assistant-0.1.1}/.github/workflows/ci.yml

@@ -28,3 +28,11 @@ jobs:
 
       - name: Test
         run: pytest -q
+
+      - name: Build distribution
+        run: pip install build && python -m build
+
+      - name: Verify distribution
+        run: |
+          pip install twine
+          twine check dist/*

{mcp_github_learning_assistant-0.1.0 → mcp_github_learning_assistant-0.1.1}/.gitignore

@@ -1,4 +1,4 @@
-# Python
+# Python
 __pycache__/
 *.py[cod]
 *.class
@@ -36,4 +36,12 @@ env/
 .env
 
 # pytest
-.pytest_cache/
+.pytest_cache/
+
+# AI coding tool artifacts
+.codex_patch
+*.codex_patch
+.codex/
+CLAUDE.md
+.aider*
+.continue/

{mcp_github_learning_assistant-0.1.0 → mcp_github_learning_assistant-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-github-learning-assistant
-Version: 0.1.0
+Version: 0.1.1
 Summary: An MCP server that helps developers discover and learn from GitHub open-source projects
 Author: iyiook333
 License: MIT
@@ -14,7 +14,7 @@ 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: mcp>=2.3.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: python-dotenv>=1.0.0
 Provides-Extra: dev
@@ -25,6 +25,9 @@ Description-Content-Type: text/markdown
 
 # MCP GitHub Learning Assistant
 
+[![PyPI version](https://img.shields.io/pypi/v/mcp-github-learning-assistant.svg)](https://pypi.org/project/mcp-github-learning-assistant/)
+[![CI](https://github.com/iyiook333/mcp-github-learning-assistant/actions/workflows/ci.yml/badge.svg)](https://github.com/iyiook333/mcp-github-learning-assistant/actions/workflows/ci.yml)
+
 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
@@ -56,6 +59,8 @@ Screenshots use dark-mode crops under 500KB each.
 pip install mcp-github-learning-assistant
 ```
 
+Requires Python 3.10+ and `mcp>=2.3.0`.
+
 ## Configuration
 
 Set your GitHub Personal Access Token:
@@ -71,21 +76,80 @@ export GITHUB_TOKEN=your_github_token
 ```
 
 Token scope: fine-grained PAT with no special permissions (public repo read-only) is enough.
+## Entry Point
+
+After `pip install mcp-github-learning-assistant`, the console command `mcp-github-learning` is available:
+
+```bash
+mcp-github-learning
+```
+
+This is equivalent to `python -m mcp_github_learning_assistant`.
 
 ## Usage in MCP Clients
 
 ### MCP Inspector (development)
 
 ```bash
-npx @modelcontextprotocol/inspector python -m mcp_github_learning_assistant
+npx @modelcontextprotocol/inspector mcp-github-learning
 ```
 
 ### Cherry Studio
 
 1. Open Cherry Studio, go to Settings -> MCP
-2. Add an MCP server with the command `python -m mcp_github_learning_assistant`
+2. Add an MCP server with the command `mcp-github-learning`
 3. Set the environment variable `GITHUB_TOKEN`
 
+### Claude Desktop
+
+Edit `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-github-learning": {
+      "command": "mcp-github-learning",
+      "env": {
+        "GITHUB_TOKEN": "your_github_token"
+      }
+    }
+  }
+}
+```
+
+> On Windows, if the command is not found, use the full path or fall back to `python -m mcp_github_learning_assistant`.
+
+### DSH / Dify
+
+Add an MCP server of type `stdio`:
+
+```yaml
+name: mcp-github-learning
+transport: stdio
+command: mcp-github-learning
+env:
+  GITHUB_TOKEN: your_github_token
+```
+
+If the client does not support custom `env`, set `GITHUB_TOKEN` at the system level before launching the client.
+
+## Current limitations
+
+These are known and intentional, not bugs. They are listed so the tool's output is not over-trusted.
+
+- **No AI/LLM layer.** Scoring is deterministic: star thresholds, README byte length, and directory-name
+  keyword matching. There are no embeddings and no model calls.
+- **`recommend_learning_repos` uses a curated seed list**, currently covering Spring Boot, FastAPI, Vue,
+  React, Electron and HarmonyOS. Any other stack returns an empty list rather than a bad guess.
+- **Only `get_trending_repos_for_learning` derives its ranking from data** — it computes
+  `stars / age_in_days` and re-sorts, since GitHub has no public trending API.
+- **No HTTP caching, retry, backoff, or pagination.** Unauthenticated GitHub allows 60 requests/hour, and
+  one `recommend_learning_repos` call can spend several of them. Always set `GITHUB_TOKEN`.
+- **Some parameters are accepted but not yet used** (`depth` in `get_repo_roadmap`, `user_level`
+  comparison weighting in `compare_learning_repos`). They are reserved for the next iteration.
+- **Test coverage is partial.** 9 tests cover `analyze`, `roadmap`, `trending` and `info`; the
+  `recommender`, `comparer`, `similar` and `issuefind` modules have none.
+
 ## Development
 
 ```bash

mcp_github_learning_assistant-0.1.1/README.md

@@ -0,0 +1,139 @@
+# MCP GitHub Learning Assistant
+
+[![PyPI version](https://img.shields.io/pypi/v/mcp-github-learning-assistant.svg)](https://pypi.org/project/mcp-github-learning-assistant/)
+[![CI](https://github.com/iyiook333/mcp-github-learning-assistant/actions/workflows/ci.yml/badge.svg)](https://github.com/iyiook333/mcp-github-learning-assistant/actions/workflows/ci.yml)
+
+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
+```
+
+Requires Python 3.10+ and `mcp>=2.3.0`.
+
+## 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.
+## Entry Point
+
+After `pip install mcp-github-learning-assistant`, the console command `mcp-github-learning` is available:
+
+```bash
+mcp-github-learning
+```
+
+This is equivalent to `python -m mcp_github_learning_assistant`.
+
+## Usage in MCP Clients
+
+### MCP Inspector (development)
+
+```bash
+npx @modelcontextprotocol/inspector mcp-github-learning
+```
+
+### Cherry Studio
+
+1. Open Cherry Studio, go to Settings -> MCP
+2. Add an MCP server with the command `mcp-github-learning`
+3. Set the environment variable `GITHUB_TOKEN`
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-github-learning": {
+      "command": "mcp-github-learning",
+      "env": {
+        "GITHUB_TOKEN": "your_github_token"
+      }
+    }
+  }
+}
+```
+
+> On Windows, if the command is not found, use the full path or fall back to `python -m mcp_github_learning_assistant`.
+
+### DSH / Dify
+
+Add an MCP server of type `stdio`:
+
+```yaml
+name: mcp-github-learning
+transport: stdio
+command: mcp-github-learning
+env:
+  GITHUB_TOKEN: your_github_token
+```
+
+If the client does not support custom `env`, set `GITHUB_TOKEN` at the system level before launching the client.
+
+## Current limitations
+
+These are known and intentional, not bugs. They are listed so the tool's output is not over-trusted.
+
+- **No AI/LLM layer.** Scoring is deterministic: star thresholds, README byte length, and directory-name
+  keyword matching. There are no embeddings and no model calls.
+- **`recommend_learning_repos` uses a curated seed list**, currently covering Spring Boot, FastAPI, Vue,
+  React, Electron and HarmonyOS. Any other stack returns an empty list rather than a bad guess.
+- **Only `get_trending_repos_for_learning` derives its ranking from data** — it computes
+  `stars / age_in_days` and re-sorts, since GitHub has no public trending API.
+- **No HTTP caching, retry, backoff, or pagination.** Unauthenticated GitHub allows 60 requests/hour, and
+  one `recommend_learning_repos` call can spend several of them. Always set `GITHUB_TOKEN`.
+- **Some parameters are accepted but not yet used** (`depth` in `get_repo_roadmap`, `user_level`
+  comparison weighting in `compare_learning_repos`). They are reserved for the next iteration.
+- **Test coverage is partial.** 9 tests cover `analyze`, `roadmap`, `trending` and `info`; the
+  `recommender`, `comparer`, `similar` and `issuefind` modules have none.
+
+## 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 → mcp_github_learning_assistant-0.1.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-github-learning-assistant"
-version = "0.1.0"
+version = "0.1.1"
 description = "An MCP server that helps developers discover and learn from GitHub open-source projects"
 authors = [{name = "iyiook333"}]
 license = {text = "MIT"}
@@ -16,7 +16,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
 ]
 dependencies = [
-    "mcp>=1.0.0",
+    "mcp>=2.3.0",
     "httpx>=0.27.0",
     "pydantic>=2.0.0",
     "python-dotenv>=1.0.0",
@@ -31,6 +31,7 @@ dev = [
 
 [project.scripts]
 mcp-github-learning-assistant = "mcp_github_learning_assistant.server:run"
+mcp-github-learning = "mcp_github_learning_assistant.server:run"
 
 [build-system]
 requires = ["hatchling"]

mcp_github_learning_assistant-0.1.1/src/mcp_github_learning_assistant/__init__.py

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

{mcp_github_learning_assistant-0.1.0 → mcp_github_learning_assistant-0.1.1}/src/mcp_github_learning_assistant/server.py

@@ -14,7 +14,7 @@ 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"
+    return "MCP GitHub Learning Assistant v0.1.1 - discover open-source projects worth learning"
 
 
 @app.tool()

mcp_github_learning_assistant-0.1.0/README.md

@@ -1,75 +0,0 @@
-# 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/src/mcp_github_learning_assistant/__init__.py

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