Initial commit

Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.9-slim
+
+WORKDIR /code
+
+COPY ./requirements.txt /code/requirements.txt
+RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
+
+COPY ./ /code/
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"] 

README.md

@@ -1,14 +1,139 @@
----
-title: Github Mcp Pr
-emoji: 🌖
-colorFrom: gray
-colorTo: green
-sdk: gradio
-sdk_version: 5.33.1
-app_file: app.py
-pinned: false
-license: mit
-short_description: It can helps users find potential PR opportunity
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: MCP GitHub PR Opportunity Server
+emoji: 🔍
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+sdk_version: 5.33.1
+app_file: app.py
+pinned: false
+tag: mcp-server-track
+license: mit
+---
+
+# MCP GitHub PR Opportunity Server
+
+A Gradio-based MCP server that searches GitHub repositories for possible PR opportunities (open issues labeled 'good first issue' or 'help wanted'), supporting search by keyword and topic, with authentication.
+
+## Features
+- Search GitHub repos by keyword and topic
+- Find open issues labeled 'good first issue' or 'help wanted'
+- Supports GitHub authentication via token
+- Gradio MCP server for LLM integration
+- Interactive web interface
+- Compatible with n8n workflows
+
+## Local Setup
+
+1. **Clone the repo and install dependencies:**
+    ```bash
+    cd mcp_github_server
+    pip install -r requirements.txt
+    ```
+
+2. **Configure GitHub Token:**
+    - Set `GITHUB_TOKEN` in your environment variables, or
+    - Enter the token in the web interface
+
+3. **Run the server:**
+    ```bash
+    python app.py
+    ```
+
+## Hugging Face Spaces Deployment
+
+1. **Create a new Space:**
+   - Go to [Hugging Face Spaces](https://huggingface.co/spaces)
+   - Click "Create new Space"
+   - Choose "Gradio" as the SDK
+   - Name your space (e.g., "mcp-github-pr-server")
+
+2. **Configure Environment Variables:**
+   - In your Space settings, add `GITHUB_TOKEN` as a secret
+   - Set your GitHub token as the value
+
+3. **Deploy:**
+   - Push your code to the Space repository
+   - Hugging Face will automatically build and deploy your application
+
+## Using with MCP Clients
+
+Add this configuration to your MCP client (e.g., Claude Desktop, Cursor, or Cline):
+
+```json
+{
+  "mcpServers": {
+    "github-pr-finder": {
+      "url": "https://akinyemiar-mcp-github-pr-server.hf.space/gradio_api/mcp/sse"
+    }
+  }
+}
+```
+
+## Using with n8n
+
+1. **Add HTTP Request Node:**
+   - In your n8n workflow, add an "HTTP Request" node
+   - Set the URL to your Hugging Face Space URL (e.g., `https://akinyemiar-mcp-github-pr-server.hf.space/api/predict`)
+   - Set Method to POST
+   - Add Headers:
+     ```
+     Content-Type: application/json
+     ```
+   - Set Body to JSON:
+     ```json
+     {
+       "data": [
+         "fastapi",
+         "python",
+         5,
+         1,
+         "YOUR_GITHUB_TOKEN"
+       ]
+     }
+     ```
+
+2. **Process Response:**
+   - The response will contain opportunities and total_count
+   - Use n8n's "Set" node to process the response data
+   - Add additional nodes to handle the opportunities as needed
+
+## API Usage
+
+The server provides both a web interface and an API endpoint at `/api/predict`. The API accepts POST requests with the following parameters:
+
+```json
+{
+  "data": [
+    "keyword",     // optional
+    "topic",       // optional
+    "per_page",    // default: 5
+    "page",        // default: 1
+    "token"        // GitHub token
+  ]
+}
+```
+
+Response:
+```json
+{
+  "data": [
+    {
+      "opportunities": [
+        {
+          "repo_name": "tiangolo/fastapi",
+          "repo_url": "https://github.com/tiangolo/fastapi",
+          "issue_title": "Add more examples",
+          "issue_url": "https://github.com/tiangolo/fastapi/issues/1234",
+          "issue_labels": ["good first issue"],
+          "issue_body": "Please add more examples to the docs..."
+        }
+      ],
+      "total_count": 123
+    }
+  ]
+}
+```
+
+## License
+MIT

app.py

@@ -0,0 +1,82 @@
+import gradio as gr
+from github_client import GitHubClient
+from models import SearchRequest, SearchResponse
+import os
+from typing import Optional, Dict, Any, List
+
+
+def search_pr_opportunities(
+    keyword: Optional[str] = None, 
+    topic: Optional[str] = None, 
+    per_page: int = 5, 
+    page: int = 1, 
+    token: Optional[str] = None
+) -> Dict[str, Any]:
+    """Search GitHub for PR opportunities.
+    
+    Args:
+        keyword: Keyword to search in repositories (optional)
+        topic: Topic to filter repositories (optional)
+        per_page: Number of results per page (default: 5)
+        page: Page number (default: 1)
+        token: GitHub token for authentication
+        
+    Returns:
+        A dictionary containing opportunities and total count
+    """
+    if not token:
+        token = os.getenv("GITHUB_TOKEN")
+    if not token:
+        raise gr.Error("GitHub token required in Authorization header or .env")
+        
+    try:
+        client: GitHubClient = GitHubClient(token)
+        opportunities, total_count = client.find_pr_opportunities(
+            keyword=keyword,
+            topic=topic,
+            per_page=per_page,
+            page=page
+        )
+        
+        # The return structure matches a dictionary format, so we type it as Dict[str, Any]
+        response: Dict[str, Any] = {
+            "opportunities": [
+                {
+                    "repo_name": opp.repo_name,
+                    "repo_url": opp.repo_url,
+                    "issue_title": opp.issue_title,
+                    "issue_url": opp.issue_url,
+                    "issue_labels": opp.issue_labels,
+                    "issue_body": opp.issue_body
+                } for opp in opportunities
+            ],
+            "total_count": total_count
+        }
+        return response
+    except Exception as e:
+        raise gr.Error(str(e))
+
+# Create the Gradio interface
+demo: gr.Interface = gr.Interface(
+    fn=search_pr_opportunities,
+    inputs=[
+        gr.Textbox(label="Keyword", placeholder="e.g., fastapi"),
+        gr.Textbox(label="Topic", placeholder="e.g., python"),
+        gr.Slider(minimum=1, maximum=20, value=5, step=1, label="Results per page"),
+        gr.Slider(minimum=1, maximum=10, value=1, step=1, label="Page number"),
+        gr.Textbox(label="GitHub Token", type="password")
+    ],
+    outputs=gr.JSON(label="Search Results"),
+    title="GitHub PR Opportunity Finder",
+    description="Search GitHub repositories for PR opportunities (issues labeled 'good first issue' or 'help wanted')",
+    examples=[
+        ["fastapi", "python", 5, 1, ""],
+        ["react", "javascript", 3, 1, ""],
+        ["machine-learning", None, 2, 1, ""],
+        [None, "web-development", 4, 1, ""]
+    ]
+)
+
+# Launch with MCP server enabled
+if __name__ == "__main__":
+    demo.launch(mcp_server=True)

github_client.py

@@ -0,0 +1,51 @@
+import os
+from github import Github
+from typing import List, Optional
+try:
+    from .models import PROpportunity
+except ImportError:
+    from models import PROpportunity
+
+HELP_LABELS = ["good first issue", "help wanted"]
+
+class GitHubClient:
+    def __init__(self, token: Optional[str] = None):
+        self.token = token or os.getenv("GITHUB_TOKEN")
+        if not self.token:
+            raise ValueError("GitHub token must be provided via argument or GITHUB_TOKEN env var.")
+        self.client = Github(self.token)
+
+    def search_repositories(self, keyword: Optional[str], topic: Optional[str], per_page: int, page: int):
+        query = []
+        if keyword:
+            query.append(keyword)
+        if topic:
+            query.append(f"topic:{topic}")
+        query_str = " ".join(query)
+        return self.client.search_repositories(query_str, sort="stars", order="desc")
+
+    def find_pr_opportunities(self, keyword: Optional[str], topic: Optional[str], per_page: int = 10, page: int = 1) -> List[PROpportunity]:
+        repos = self.search_repositories(keyword, topic, per_page, page)
+        opportunities = []
+        count = 0
+        for repo in repos.get_page(page-1):
+            issues = repo.get_issues(state="open", labels=HELP_LABELS)
+            for issue in issues:
+                if issue.pull_request is not None:
+                    continue  # skip PRs
+                labels = [l.name for l in issue.labels]
+                if any(l.lower() in HELP_LABELS for l in labels):
+                    opportunities.append(PROpportunity(
+                        repo_name=repo.full_name,
+                        repo_url=repo.html_url,
+                        issue_title=issue.title,
+                        issue_url=issue.html_url,
+                        issue_labels=labels,
+                        issue_body=issue.body
+                    ))
+                    count += 1
+                    if count >= per_page:
+                        break
+            if count >= per_page:
+                break
+        return opportunities, repos.totalCount 

main.py

@@ -0,0 +1,36 @@
+from fastapi import FastAPI, Depends, HTTPException, Header
+from typing import Optional
+try:
+    from .models import SearchRequest, SearchResponse
+    from .github_client import GitHubClient
+except ImportError:
+    from models import SearchRequest, SearchResponse
+    from github_client import GitHubClient
+import os
+
+app = FastAPI(title="MCP GitHub PR Opportunity Server")
+
+def get_github_token(authorization: Optional[str] = Header(None)) -> str:
+    if authorization and authorization.startswith("token "):
+        return authorization.split(" ", 1)[1]
+    token = os.getenv("GITHUB_TOKEN")
+    if not token:
+        raise HTTPException(status_code=401, detail="GitHub token required in Authorization header or .env")
+    return token
+
+@app.post("/search_pr_opportunities", response_model=SearchResponse)
+def search_pr_opportunities(
+    request: SearchRequest,
+    token: str = Depends(get_github_token)
+):
+    try:
+        client = GitHubClient(token)
+        opportunities, total_count = client.find_pr_opportunities(
+            keyword=request.keyword,
+            topic=request.topic,
+            per_page=request.per_page,
+            page=request.page
+        )
+        return SearchResponse(opportunities=opportunities, total_count=total_count)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) 

models.py

@@ -0,0 +1,20 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional
+
+class SearchRequest(BaseModel):
+    keyword: Optional[str] = Field(None, description="Keyword to search in repositories.")
+    topic: Optional[str] = Field(None, description="Topic to filter repositories.")
+    per_page: int = Field(10, description="Results per page.")
+    page: int = Field(1, description="Page number.")
+
+class PROpportunity(BaseModel):
+    repo_name: str
+    repo_url: str
+    issue_title: str
+    issue_url: str
+    issue_labels: List[str]
+    issue_body: Optional[str]
+
+class SearchResponse(BaseModel):
+    opportunities: List[PROpportunity]
+    total_count: int 

requirements.txt

@@ -0,0 +1,6 @@
+gradio[mcp]
+PyGithub
+python-dotenv
+pydantic 
+mcp
+gradio