Skip to content

Commit 4b2d8d1

Browse files
peteroycepeteroyce
committed
Add Claude Desktop setup guide, tool reference, and example prompts
1 parent ef9c8e5 commit 4b2d8d1

1 file changed

Lines changed: 168 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# devscope-mcp
2+
3+
An MCP server that gives Claude live access to your GitHub workspace — PR reviews, issue triaging, repo search, and weekly digest reports through natural language.
4+
5+
Built on the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), devscope-mcp plugs directly into Claude Desktop (or any MCP-compatible client) and lets you work with GitHub without ever leaving the conversation.
6+
7+
---
8+
9+
## Features
10+
11+
- **PR Summaries** — full diff metadata, comments, and review stats for any pull request
12+
- **Issue Triage** — list and filter open/closed issues across any repository
13+
- **Repo Explorer** — browse repos for a user or org, with stats at a glance
14+
- **Code Search** — GitHub code-search with optional repo scoping
15+
- **Contributor Stats** — commit volume, lines changed, and active weeks per contributor
16+
- **Weekly Digest** — merged PRs, opened issues, and top contributors for the past 7 days
17+
18+
---
19+
20+
## Tech Stack
21+
22+
| Layer | Technology |
23+
|---|---|
24+
| Protocol | [Model Context Protocol](https://modelcontextprotocol.io/) (`mcp >= 1.0`) |
25+
| GitHub API | [PyGithub](https://pygithub.readthedocs.io/) `>= 2.3` |
26+
| HTTP client | [httpx](https://www.python-httpx.org/) `>= 0.27` |
27+
| Config | [python-dotenv](https://pypi.org/project/python-dotenv/) `>= 1.0` |
28+
| Runtime | Python 3.11+ |
29+
| Tests | pytest 8, pytest-asyncio, pytest-mock |
30+
| Build | [Hatchling](https://hatch.pypa.io/) via `pyproject.toml` |
31+
32+
---
33+
34+
## Setup
35+
36+
### 1. Prerequisites
37+
38+
- Python 3.11 or later
39+
- A [GitHub Personal Access Token](https://github.com/settings/tokens) with the following scopes:
40+
- `repo` (full repository access)
41+
- `read:org`
42+
- `read:user`
43+
44+
### 2. Clone and install
45+
46+
```bash
47+
git clone https://github.com/your-user/devscope-mcp.git
48+
cd devscope-mcp
49+
python -m venv .venv
50+
source .venv/bin/activate # Windows: .venv\Scripts\activate
51+
pip install -e ".[dev]"
52+
```
53+
54+
### 3. Configure environment
55+
56+
```bash
57+
cp .env.example .env
58+
# edit .env and set GITHUB_TOKEN (and optionally GITHUB_DEFAULT_ORG)
59+
```
60+
61+
### 4. Add to Claude Desktop
62+
63+
Open your Claude Desktop config file:
64+
65+
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
66+
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
67+
68+
Add the devscope-mcp entry to `mcpServers`:
69+
70+
```json
71+
{
72+
"mcpServers": {
73+
"devscope-mcp": {
74+
"command": "python",
75+
"args": ["-m", "src.server"],
76+
"cwd": "/absolute/path/to/devscope-mcp",
77+
"env": {
78+
"GITHUB_TOKEN": "ghp_your_token_here",
79+
"GITHUB_DEFAULT_ORG": "your-org-name"
80+
}
81+
}
82+
}
83+
}
84+
```
85+
86+
If you installed with `pip install -e .`, you can use the console script instead:
87+
88+
```json
89+
{
90+
"mcpServers": {
91+
"devscope-mcp": {
92+
"command": "devscope-mcp",
93+
"env": {
94+
"GITHUB_TOKEN": "ghp_your_token_here",
95+
"GITHUB_DEFAULT_ORG": "your-org-name"
96+
}
97+
}
98+
}
99+
}
100+
```
101+
102+
Restart Claude Desktop. You should see the devscope-mcp tools available in the tools menu.
103+
104+
---
105+
106+
## Available Tools
107+
108+
| Tool | Description |
109+
|---|---|
110+
| `list_repos` | List repositories for a GitHub org or authenticated user, sorted by last push |
111+
| `get_repo_info` | Detailed metadata for a single repo (language, stars, forks, topics, etc.) |
112+
| `summarize_pr` | Full summary of a pull request including changed files, comments, and deltas |
113+
| `list_issues` | List issues with state filter (open / closed / all) and configurable limit |
114+
| `search_code` | GitHub code search with optional repo scope |
115+
| `get_contributor_stats` | Per-contributor commit count, lines added/deleted, and active weeks |
116+
| `get_weekly_digest` | 7-day activity digest: merged PRs, opened issues, top contributors |
117+
118+
---
119+
120+
## Example Prompts
121+
122+
> "Summarise the last 5 PRs in my repo"
123+
124+
> "List all open issues in peteroyce/devscope-mcp labelled 'bug'"
125+
126+
> "Show me the weekly digest for the myorg/backend repository"
127+
128+
> "Who are the top contributors to myorg/frontend this week?"
129+
130+
> "Search for usages of `authenticate_user` across the myorg/api repo"
131+
132+
> "Give me the full diff and comments for PR #47 in myorg/payments"
133+
134+
> "List all repos in the myorg organisation sorted by most recently active"
135+
136+
---
137+
138+
## Running Tests
139+
140+
```bash
141+
pytest -v
142+
```
143+
144+
Tests mock all PyGithub calls so no real GitHub token is required.
145+
146+
---
147+
148+
## Project Structure
149+
150+
```
151+
devscope-mcp/
152+
├── src/
153+
│ ├── __init__.py
154+
│ ├── github_client.py # PyGithub wrapper — all GitHub logic lives here
155+
│ └── server.py # MCP server — tool definitions, dispatch, formatting
156+
├── tests/
157+
│ └── test_github_client.py
158+
├── .env.example
159+
├── .gitignore
160+
├── pyproject.toml
161+
└── README.md
162+
```
163+
164+
---
165+
166+
## License
167+
168+
MIT

0 commit comments

Comments
 (0)