bob-pr-reviewer 0.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +576 -0
- package/dist/github-client.d.ts +73 -0
- package/dist/github-client.d.ts.map +1 -0
- package/dist/github-client.js +124 -0
- package/dist/github-client.js.map +1 -0
- package/dist/index.d.ts +30 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +645 -0
- package/dist/index.js.map +1 -0
- package/dist/jira-client.d.ts +75 -0
- package/dist/jira-client.d.ts.map +1 -0
- package/dist/jira-client.js +204 -0
- package/dist/jira-client.js.map +1 -0
- package/dist/prerequisites.d.ts +29 -0
- package/dist/prerequisites.d.ts.map +1 -0
- package/dist/prerequisites.js +374 -0
- package/dist/prerequisites.js.map +1 -0
- package/dist/tools.d.ts +7 -0
- package/dist/tools.d.ts.map +1 -0
- package/dist/tools.js +131 -0
- package/dist/tools.js.map +1 -0
- package/package.json +37 -0
package/README.md
ADDED
|
@@ -0,0 +1,576 @@
|
|
|
1
|
+
# bob-pr-reviewer `v0.0.5`
|
|
2
|
+
|
|
3
|
+
An MCP (Model Context Protocol) server that gives AI assistants in VS Code the ability to **read GitHub Enterprise pull requests**, **fetch Jira ticket requirements**, and **post structured review comments** — all via natural language.
|
|
4
|
+
|
|
5
|
+
**No clone required. No build step. No manual server startup.**
|
|
6
|
+
VS Code launches this automatically via `npx` — just configure once and it works everywhere.
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Table of Contents
|
|
11
|
+
|
|
12
|
+
- [How It Works](#how-it-works)
|
|
13
|
+
- [Quick Start (5 minutes)](#quick-start-5-minutes)
|
|
14
|
+
- [Tools Available](#tools-available)
|
|
15
|
+
- [Usage Examples](#usage-examples)
|
|
16
|
+
- [What to Expect in VS Code](#what-to-expect-in-vs-code)
|
|
17
|
+
- [What to Expect on GitHub](#what-to-expect-on-github)
|
|
18
|
+
- [Project Structure](#project-structure)
|
|
19
|
+
- [For Contributors / Local Development](#for-contributors--local-development)
|
|
20
|
+
- [Publishing a New Version](#publishing-a-new-version)
|
|
21
|
+
- [Troubleshooting](#troubleshooting)
|
|
22
|
+
- [Security Notes](#security-notes)
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## How It Works
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
You: "@bob-pr-reviewer Review PR #1758 in sec-ci/notification and check it against the Jira ticket"
|
|
30
|
+
│
|
|
31
|
+
▼
|
|
32
|
+
VS Code AI Assistant (IBM Bob / GitHub Copilot Chat / Cline)
|
|
33
|
+
│ sees MCP tools available, decides which to call
|
|
34
|
+
▼
|
|
35
|
+
bob-pr-reviewer (auto-launched by VS Code via npx — no clone needed)
|
|
36
|
+
│ calls GitHub Enterprise API + Jira API in parallel
|
|
37
|
+
▼
|
|
38
|
+
GitHub Enterprise (github.ibm.com) + Jira (jsw.ibm.com)
|
|
39
|
+
│ returns PR diff + Jira requirements
|
|
40
|
+
▼
|
|
41
|
+
AI analyzes code vs requirements → posts structured comment to PR
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
VS Code spawns this MCP server as a subprocess automatically using `npx`. The package is downloaded and cached on first use — you never need to clone this repo or run a build command.
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## Quick Start (5 minutes)
|
|
49
|
+
|
|
50
|
+
> **Full step-by-step instructions:** see [SETUP.md](./SETUP.md)
|
|
51
|
+
|
|
52
|
+
### Step 1 — Get your tokens
|
|
53
|
+
|
|
54
|
+
| Token | Where to get it |
|
|
55
|
+
|-------|----------------|
|
|
56
|
+
| GitHub Enterprise PAT | `https://github.ibm.com/settings/tokens` → scope: **`repo`** |
|
|
57
|
+
| Jira Personal Access Token | `https://jsw.ibm.com/secure/ViewProfile.jspa` → Personal Access Tokens |
|
|
58
|
+
|
|
59
|
+
### Step 2 — Set your tokens
|
|
60
|
+
|
|
61
|
+
Add to your `~/.zshrc` (or `~/.bashrc`):
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
export GITHUB_TOKEN=ghp_yourGitHubTokenHere
|
|
65
|
+
export JIRA_ISV_PERSONAL_ACCESS_TOKEN=yourJiraTokenHere
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Then reload: `source ~/.zshrc` and **restart VS Code completely**.
|
|
69
|
+
|
|
70
|
+
### Step 3 — Add to VS Code User Settings
|
|
71
|
+
|
|
72
|
+
Open VS Code global settings JSON (`Cmd+Shift+P` → **"Open User Settings (JSON)"**) and add:
|
|
73
|
+
|
|
74
|
+
```json
|
|
75
|
+
{
|
|
76
|
+
"mcp": {
|
|
77
|
+
"servers": {
|
|
78
|
+
"bob-pr-reviewer": {
|
|
79
|
+
"type": "stdio",
|
|
80
|
+
"command": "npx",
|
|
81
|
+
"args": ["-y", "bob-pr-reviewer"],
|
|
82
|
+
"env": {
|
|
83
|
+
"GITHUB_TOKEN": "${env:GITHUB_TOKEN}",
|
|
84
|
+
"GITHUB_BASE_URL": "https://github.ibm.com/api/v3",
|
|
85
|
+
"JIRA_ISV_PERSONAL_ACCESS_TOKEN": "${env:JIRA_ISV_PERSONAL_ACCESS_TOKEN}",
|
|
86
|
+
"JIRA_BASE_URL": "https://jsw.ibm.com"
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
> ⚠️ This goes in **User Settings (JSON)** — not in `.vscode/settings.json` or `.vscode/mcp.json` in your project. User Settings apply globally across all projects.
|
|
95
|
+
|
|
96
|
+
### Step 4 — Reload VS Code
|
|
97
|
+
|
|
98
|
+
`Cmd+Shift+P` → **"Developer: Reload Window"**
|
|
99
|
+
|
|
100
|
+
That's it. The server starts automatically. Open any project and the tools are available.
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## Slash Commands (Recommended)
|
|
105
|
+
|
|
106
|
+
MCP prompts appear as **slash commands** with autocomplete in IBM Bob and other MCP-compatible AI clients. Type `/bob-pr-reviewer` to see all available commands.
|
|
107
|
+
|
|
108
|
+
> 💡 The `bob-pr-reviewer:` prefix ensures these commands never clash with slash commands from other MCP servers you may have loaded.
|
|
109
|
+
|
|
110
|
+
| Slash command | Description | Arguments |
|
|
111
|
+
|---|---|---|
|
|
112
|
+
| `/bob-pr-reviewer:check-setup` | Run prerequisites check | none |
|
|
113
|
+
| `/bob-pr-reviewer:review-pr` | Full code review with inline comments | `repo`, `pr_number` |
|
|
114
|
+
| `/bob-pr-reviewer:review-pr-vs-jira` | Review PR against its Jira ticket | `repo`, `pr_number`, `ticket_key` (optional) |
|
|
115
|
+
| `/bob-pr-reviewer:get-pr-info` | Fetch PR metadata | `repo`, `pr_number` |
|
|
116
|
+
| `/bob-pr-reviewer:get-jira-ticket` | Fetch Jira ticket requirements | `ticket_key` |
|
|
117
|
+
| `/bob-pr-reviewer:post-comment` | Post a general comment on a PR | `repo`, `pr_number`, `comment` |
|
|
118
|
+
|
|
119
|
+
**How to use:**
|
|
120
|
+
1. Type `/bob-pr-reviewer:` in the IBM Bob chat — autocomplete shows all commands
|
|
121
|
+
2. Select a command — the AI prompts you for any required arguments
|
|
122
|
+
3. The AI fills in the message and calls the appropriate tools automatically
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## Tools Available
|
|
127
|
+
|
|
128
|
+
| Tool | Description |
|
|
129
|
+
|------|-------------|
|
|
130
|
+
| `check_setup` | Re-run all prerequisites checks and show status |
|
|
131
|
+
| `validate_token` | Verify your GitHub token is working |
|
|
132
|
+
| `get_pr_info` | Fetch PR title, author, branches, commit SHA, description |
|
|
133
|
+
| `fetch_pr_diff` | Fetch all changed files + unified diffs |
|
|
134
|
+
| `post_review` | Post a review with inline comments at diff positions |
|
|
135
|
+
| `post_comment` | Post a general (non-inline) PR comment |
|
|
136
|
+
| `get_jira_ticket` | Fetch a Jira ticket's summary, description, acceptance criteria |
|
|
137
|
+
| `check_pr_vs_jira` | Auto-detect Jira ticket from PR, fetch requirements, return analysis context |
|
|
138
|
+
| `post_jira_analysis` | Post the Jira vs PR analysis as a structured comment (called automatically after `check_pr_vs_jira`) |
|
|
139
|
+
|
|
140
|
+
### Tool call chain for Jira-aware review
|
|
141
|
+
|
|
142
|
+
```
|
|
143
|
+
check_pr_vs_jira
|
|
144
|
+
├── fetches PR info + diff from GitHub
|
|
145
|
+
├── auto-detects Jira ticket key from PR title/branch/description
|
|
146
|
+
├── fetches Jira requirements
|
|
147
|
+
└── returns structured context to AI
|
|
148
|
+
│
|
|
149
|
+
▼ (AI analyzes, then MUST call:)
|
|
150
|
+
post_jira_analysis
|
|
151
|
+
├── receives verdict, coverage list, gaps list, summary from AI
|
|
152
|
+
└── posts formatted Markdown comment to the PR on GitHub
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Usage Examples
|
|
158
|
+
|
|
159
|
+
> 💡 **Prefer slash commands** — type `/bob-pr-reviewer:` for autocomplete. Use the `@bob-pr-reviewer` prefix in free-text prompts when you need more control or have multiple MCP servers loaded.
|
|
160
|
+
|
|
161
|
+
### Jira-aware review (recommended)
|
|
162
|
+
|
|
163
|
+
**Slash command (autocomplete):**
|
|
164
|
+
```
|
|
165
|
+
/bob-pr-reviewer:review-pr-vs-jira
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
**Or free-text prompt:**
|
|
169
|
+
```
|
|
170
|
+
@bob-pr-reviewer Check PR #1758 in sec-ci/notification against its Jira ticket and post the analysis
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
If the PR title/branch/description contains a Jira key (e.g. `VDEV-47721`), it's detected automatically. If not, provide it explicitly:
|
|
174
|
+
|
|
175
|
+
```
|
|
176
|
+
@bob-pr-reviewer Check PR #1758 in sec-ci/notification against Jira ticket VDEV-47721
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
### Basic PR review with inline comments
|
|
180
|
+
|
|
181
|
+
**Slash command:**
|
|
182
|
+
```
|
|
183
|
+
/bob-pr-reviewer:review-pr
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
**Or free-text prompt:**
|
|
187
|
+
```
|
|
188
|
+
@bob-pr-reviewer Review PR #1758 in sec-ci/notification and post your findings as inline comments
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### Fetch PR info only
|
|
192
|
+
|
|
193
|
+
**Slash command:**
|
|
194
|
+
```
|
|
195
|
+
/bob-pr-reviewer:get-pr-info
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
**Or free-text prompt:**
|
|
199
|
+
```
|
|
200
|
+
@bob-pr-reviewer Get the details for PR #1758 in sec-ci/notification
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### Fetch a Jira ticket
|
|
204
|
+
|
|
205
|
+
**Slash command:**
|
|
206
|
+
```
|
|
207
|
+
/bob-pr-reviewer:get-jira-ticket
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
**Or free-text prompt:**
|
|
211
|
+
```
|
|
212
|
+
@bob-pr-reviewer Get the requirements for Jira ticket VDEV-47721
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
### Post a quick comment
|
|
216
|
+
|
|
217
|
+
**Slash command:**
|
|
218
|
+
```
|
|
219
|
+
/bob-pr-reviewer:post-comment
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
**Or free-text prompt:**
|
|
223
|
+
```
|
|
224
|
+
@bob-pr-reviewer Post a comment on PR #1758 in sec-ci/notification: "LGTM! Nice work."
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
### Verify setup
|
|
228
|
+
|
|
229
|
+
**Slash command:**
|
|
230
|
+
```
|
|
231
|
+
/bob-pr-reviewer:check-setup
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
**Or free-text prompt:**
|
|
235
|
+
```
|
|
236
|
+
@bob-pr-reviewer Run check_setup
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
---
|
|
240
|
+
|
|
241
|
+
## What to Expect in VS Code
|
|
242
|
+
|
|
243
|
+
### On first use
|
|
244
|
+
|
|
245
|
+
When VS Code first launches the server, `npx` downloads and caches the package automatically. You'll see a brief pause — subsequent launches are instant.
|
|
246
|
+
|
|
247
|
+
To verify the server is running:
|
|
248
|
+
1. Open the **Output** panel: `View → Output`
|
|
249
|
+
2. Select **MCP** from the dropdown
|
|
250
|
+
3. You should see output like this (shown as "errors" in VS Code's panel — this is normal, all MCP server logs go to stderr):
|
|
251
|
+
|
|
252
|
+
```
|
|
253
|
+
[bob-pr-reviewer] Starting up... GitHub: https://github.ibm.com/api/v3 | Jira: https://jsw.ibm.com
|
|
254
|
+
[bob-pr-reviewer] Prerequisites check:
|
|
255
|
+
✓ Node.js version: Node.js 18.19.0 (requires >= 18.x)
|
|
256
|
+
✓ GITHUB_TOKEN environment variable: GITHUB_TOKEN is set (length: 40)
|
|
257
|
+
✓ GitHub token validity: Token is valid — authenticated as: your-username
|
|
258
|
+
✓ GitHub API reachability: https://github.ibm.com/api/v3 is reachable
|
|
259
|
+
✓ JIRA_ISV_PERSONAL_ACCESS_TOKEN environment variable: set (length: 38)
|
|
260
|
+
✓ Jira token validity: Token is valid — authenticated as: Your Name
|
|
261
|
+
[bob-pr-reviewer] ✅ All checks passed — registering all tools
|
|
262
|
+
[bob-pr-reviewer] MCP server ready (stdio transport)
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
> **Note:** VS Code's MCP output panel labels all server log messages as "errors" — this is cosmetic. If you see the `✅ All checks passed` line, the server is healthy and working correctly.
|
|
266
|
+
|
|
267
|
+
If any check fails, the server runs in **degraded mode** — only the `check_setup` tool is available, and it will tell you exactly what to fix.
|
|
268
|
+
|
|
269
|
+
### Checking setup status
|
|
270
|
+
|
|
271
|
+
At any time, use the slash command:
|
|
272
|
+
```
|
|
273
|
+
/bob-pr-reviewer:check-setup
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
Or ask in free-text:
|
|
277
|
+
```
|
|
278
|
+
@bob-pr-reviewer Run check_setup
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
The AI will call `check_setup` and show you the current status of all prerequisites.
|
|
282
|
+
|
|
283
|
+
---
|
|
284
|
+
|
|
285
|
+
## What to Expect on GitHub
|
|
286
|
+
|
|
287
|
+
### After `check_pr_vs_jira` + `post_jira_analysis`
|
|
288
|
+
|
|
289
|
+
A structured comment is automatically posted to the PR on `github.ibm.com`. It looks like this:
|
|
290
|
+
|
|
291
|
+
---
|
|
292
|
+
|
|
293
|
+
**🤖 Requirements Check: [VDEV-47721](https://jsw.ibm.com/browse/VDEV-47721)**
|
|
294
|
+
|
|
295
|
+
**Jira:** Domain auth APIs rate limit
|
|
296
|
+
**Verdict:** ⚠️ Partial Match
|
|
297
|
+
|
|
298
|
+
**Requirements Coverage**
|
|
299
|
+
- ✅ Rate limiting logic implemented in `NotificationConfigResource.java`
|
|
300
|
+
- ✅ New `RateLimitConfig` class added with configurable thresholds
|
|
301
|
+
- ⚠️ Error response format differs from acceptance criteria (returns 429 but missing `Retry-After` header)
|
|
302
|
+
|
|
303
|
+
**Gaps / Concerns**
|
|
304
|
+
- Missing `Retry-After` header in 429 responses per RFC 6585
|
|
305
|
+
- No unit tests for the rate limit boundary conditions
|
|
306
|
+
- Config reload behavior under concurrent requests not tested
|
|
307
|
+
|
|
308
|
+
**Summary**
|
|
309
|
+
The PR implements the core rate limiting feature described in VDEV-47721 and correctly gates domain auth API calls per tenant. However, the HTTP 429 response is missing the `Retry-After` header required by the acceptance criteria, and test coverage for edge cases is absent.
|
|
310
|
+
|
|
311
|
+
---
|
|
312
|
+
_Automated check by bob-pr-reviewer • [VDEV-47721](https://jsw.ibm.com/browse/VDEV-47721)_
|
|
313
|
+
|
|
314
|
+
---
|
|
315
|
+
|
|
316
|
+
### After `post_review` (inline comments)
|
|
317
|
+
|
|
318
|
+
If you ask for a full code review with inline comments, the AI calls `post_review` which posts a GitHub review with:
|
|
319
|
+
- An overall summary
|
|
320
|
+
- Inline comments at specific diff positions (shown in the **Files changed** tab)
|
|
321
|
+
- A review state: `COMMENT`, `APPROVE`, or `REQUEST_CHANGES`
|
|
322
|
+
|
|
323
|
+
---
|
|
324
|
+
|
|
325
|
+
## Project Structure
|
|
326
|
+
|
|
327
|
+
```
|
|
328
|
+
bob-pr-reviewer/
|
|
329
|
+
├── src/
|
|
330
|
+
│ ├── index.ts # MCP server entry point — tool registration, startup flow
|
|
331
|
+
│ ├── github-client.ts # GitHub Enterprise REST API client
|
|
332
|
+
│ ├── jira-client.ts # Jira REST API v2 client (PAT auth, ADF parsing)
|
|
333
|
+
│ ├── prerequisites.ts # Startup validator (Node, tokens, APIs)
|
|
334
|
+
│ └── tools.ts # MCP tool schema definitions (reference)
|
|
335
|
+
├── dist/ # Compiled JavaScript — included in npm package
|
|
336
|
+
├── .vscode/
|
|
337
|
+
│ └── mcp.json # VS Code built-in MCP config for local dev (uses local dist/)
|
|
338
|
+
├── .bob/
|
|
339
|
+
│ └── mcp.json # IBM Bob extension MCP config for local dev (uses local dist/)
|
|
340
|
+
├── .env.example # Template showing required variables
|
|
341
|
+
├── package.json # includes "bin" field for npx support
|
|
342
|
+
├── tsconfig.json
|
|
343
|
+
├── SETUP.md # Detailed installation guide for end users
|
|
344
|
+
├── PROMPT_TEMPLATE.md # Reusable prompt template for building new MCP servers
|
|
345
|
+
└── README.md
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
### Key files explained
|
|
349
|
+
|
|
350
|
+
**`src/index.ts`** — The main server. Loads `.env`, runs prerequisites, registers tools. Two modes:
|
|
351
|
+
- **Healthy**: all 9 tools registered
|
|
352
|
+
- **Degraded**: only `check_setup` registered (with fix instructions)
|
|
353
|
+
|
|
354
|
+
**`src/github-client.ts`** — Wraps GitHub Enterprise REST API v3. Methods: `getPrInfo()`, `getPrFiles()`, `postReview()`, `postComment()`, `validateToken()`.
|
|
355
|
+
|
|
356
|
+
**`src/jira-client.ts`** — Wraps Jira REST API v2 with Bearer token auth. Handles Atlassian Document Format (ADF) → plain text conversion. Tries 6 custom field IDs to find Acceptance Criteria. Static `extractTicketKey()` regex for auto-detection.
|
|
357
|
+
|
|
358
|
+
**`src/prerequisites.ts`** — Runs checks at startup: Node.js version, `GITHUB_TOKEN` set, GitHub token valid (live API call), GitHub API reachable, `JIRA_ISV_PERSONAL_ACCESS_TOKEN` set, Jira token valid (live API call). Each failed check includes step-by-step fix instructions.
|
|
359
|
+
|
|
360
|
+
**`.vscode/mcp.json`** — Used by VS Code's built-in MCP support when this repo is open. Points to `dist/index.js` (local build) so changes are picked up immediately without publishing.
|
|
361
|
+
|
|
362
|
+
**`.bob/mcp.json`** — Used by the IBM Bob extension when this repo is open. Same purpose as `.vscode/mcp.json` but in Bob's format (`mcpServers` key). Both files override the global User Settings entry only while this project is open.
|
|
363
|
+
|
|
364
|
+
---
|
|
365
|
+
|
|
366
|
+
## For Contributors / Local Development
|
|
367
|
+
|
|
368
|
+
If you want to modify the server or contribute:
|
|
369
|
+
|
|
370
|
+
```bash
|
|
371
|
+
git clone git@github.ibm.com:himanshu-sao-ibm/bob-pr-reviewer.git
|
|
372
|
+
cd bob-pr-reviewer
|
|
373
|
+
npm install
|
|
374
|
+
npm run build
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
Both `.vscode/mcp.json` and `.bob/mcp.json` in this repo point directly to the local build output (`dist/index.js`) so your changes are picked up immediately — no publishing needed. They override the global User Settings entry **only when this project is open in VS Code**. All other projects continue to use the published npm version.
|
|
378
|
+
|
|
379
|
+
> **How precedence works:** Project-level MCP configs (`.vscode/mcp.json` for VS Code built-in, `.bob/mcp.json` for IBM Bob) take precedence over User Settings when the project is open. Both use the same server name (`bob-pr-reviewer`) — no conflicts, no duplicate servers.
|
|
380
|
+
|
|
381
|
+
**`.vscode/mcp.json`** (VS Code built-in MCP):
|
|
382
|
+
```json
|
|
383
|
+
{
|
|
384
|
+
"servers": {
|
|
385
|
+
"bob-pr-reviewer": {
|
|
386
|
+
"type": "stdio",
|
|
387
|
+
"command": "node",
|
|
388
|
+
"args": ["dist/index.js"],
|
|
389
|
+
"env": {
|
|
390
|
+
"GITHUB_TOKEN": "${env:GITHUB_TOKEN}",
|
|
391
|
+
"GITHUB_BASE_URL": "https://github.ibm.com/api/v3",
|
|
392
|
+
"JIRA_ISV_PERSONAL_ACCESS_TOKEN": "${env:JIRA_ISV_PERSONAL_ACCESS_TOKEN}",
|
|
393
|
+
"JIRA_BASE_URL": "https://jsw.ibm.com"
|
|
394
|
+
}
|
|
395
|
+
}
|
|
396
|
+
}
|
|
397
|
+
}
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
**`.bob/mcp.json`** (IBM Bob extension):
|
|
401
|
+
```json
|
|
402
|
+
{
|
|
403
|
+
"mcpServers": {
|
|
404
|
+
"bob-pr-reviewer": {
|
|
405
|
+
"type": "stdio",
|
|
406
|
+
"command": "node",
|
|
407
|
+
"args": ["dist/index.js"],
|
|
408
|
+
"env": {
|
|
409
|
+
"GITHUB_TOKEN": "${env:GITHUB_TOKEN}",
|
|
410
|
+
"GITHUB_BASE_URL": "https://github.ibm.com/api/v3",
|
|
411
|
+
"JIRA_ISV_PERSONAL_ACCESS_TOKEN": "${env:JIRA_ISV_PERSONAL_ACCESS_TOKEN}",
|
|
412
|
+
"JIRA_BASE_URL": "https://jsw.ibm.com"
|
|
413
|
+
}
|
|
414
|
+
}
|
|
415
|
+
}
|
|
416
|
+
}
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
After making code changes, rebuild and reload:
|
|
420
|
+
|
|
421
|
+
```bash
|
|
422
|
+
npm run build
|
|
423
|
+
# Then in VS Code: Cmd+Shift+P → "Developer: Reload Window"
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
---
|
|
427
|
+
|
|
428
|
+
## Publishing a New Version
|
|
429
|
+
|
|
430
|
+
> **Who does this:** Only the maintainer (`himanshu-sao-ibm`) needs to do this when releasing updates. Teammates never need to run these steps.
|
|
431
|
+
|
|
432
|
+
### First-time setup (one-time only)
|
|
433
|
+
|
|
434
|
+
1. Create an account at [npmjs.com](https://www.npmjs.com) if you don't have one
|
|
435
|
+
2. Log in from your terminal:
|
|
436
|
+
```bash
|
|
437
|
+
npm login
|
|
438
|
+
```
|
|
439
|
+
Enter your npm username, password, and email when prompted.
|
|
440
|
+
|
|
441
|
+
> **2FA / Granular Access Token:** If your npm account has 2FA enabled, you have two options:
|
|
442
|
+
> - Pass your OTP at publish time: `./publish.sh --otp=123456`
|
|
443
|
+
> - Or create a **Granular Access Token** on npmjs.com with "Read and write" + bypass 2FA, then set it:
|
|
444
|
+
> ```bash
|
|
445
|
+
> npm set //registry.npmjs.org/:_authToken YOUR_TOKEN
|
|
446
|
+
> ```
|
|
447
|
+
|
|
448
|
+
### Publishing an update (using `publish.sh`)
|
|
449
|
+
|
|
450
|
+
A [`publish.sh`](./publish.sh) script is included that handles build + version bump + publish in one step:
|
|
451
|
+
|
|
452
|
+
```bash
|
|
453
|
+
# Make executable (one-time)
|
|
454
|
+
chmod +x publish.sh
|
|
455
|
+
|
|
456
|
+
# Patch release — bug fixes (0.0.5 → 0.0.6)
|
|
457
|
+
./publish.sh
|
|
458
|
+
|
|
459
|
+
# Minor release — new features, backwards compatible (0.0.5 → 0.1.0)
|
|
460
|
+
./publish.sh minor
|
|
461
|
+
|
|
462
|
+
# Major release — breaking changes (0.0.5 → 1.0.0)
|
|
463
|
+
./publish.sh major
|
|
464
|
+
|
|
465
|
+
# Publish current version as-is (no version bump)
|
|
466
|
+
./publish.sh --no-bump
|
|
467
|
+
|
|
468
|
+
# With 2FA OTP (if your npm account requires it)
|
|
469
|
+
./publish.sh minor --otp=123456
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
The script will:
|
|
473
|
+
1. Verify you are logged in to npm
|
|
474
|
+
2. Run `npm run build` (TypeScript → `dist/`)
|
|
475
|
+
3. Bump the version in `package.json`
|
|
476
|
+
4. Run `npm publish`
|
|
477
|
+
5. Print the package URL and next steps for users
|
|
478
|
+
|
|
479
|
+
### Manual publish (without the script)
|
|
480
|
+
|
|
481
|
+
```bash
|
|
482
|
+
# 1. Make your code changes in src/
|
|
483
|
+
|
|
484
|
+
# 2. Build the compiled output
|
|
485
|
+
npm run build
|
|
486
|
+
|
|
487
|
+
# 3. Bump the version (choose one):
|
|
488
|
+
npm version patch # 0.0.5 → 0.0.6 (bug fixes)
|
|
489
|
+
npm version minor # 0.0.5 → 0.1.0 (new features, backwards compatible)
|
|
490
|
+
npm version major # 0.0.5 → 1.0.0 (breaking changes)
|
|
491
|
+
|
|
492
|
+
# 4. Publish to npm
|
|
493
|
+
npm publish
|
|
494
|
+
# With 2FA OTP:
|
|
495
|
+
npm publish --otp=123456
|
|
496
|
+
```
|
|
497
|
+
|
|
498
|
+
`npm version` automatically updates `package.json`. `npm publish` uploads only the `dist/` folder (as defined in `"files"` in `package.json`).
|
|
499
|
+
|
|
500
|
+
### Verify the publish succeeded
|
|
501
|
+
|
|
502
|
+
```bash
|
|
503
|
+
npm view bob-pr-reviewer version
|
|
504
|
+
# Should show the new version number
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
Or check: `https://www.npmjs.com/package/bob-pr-reviewer`
|
|
508
|
+
|
|
509
|
+
### After publishing — users get the update automatically
|
|
510
|
+
|
|
511
|
+
Users running `npx -y bob-pr-reviewer` will get the new version automatically on next VS Code launch. If they want to force a refresh of a cached version:
|
|
512
|
+
|
|
513
|
+
```bash
|
|
514
|
+
npx clear-npx-cache
|
|
515
|
+
# Then: Cmd+Shift+P → "Developer: Reload Window"
|
|
516
|
+
```
|
|
517
|
+
|
|
518
|
+
---
|
|
519
|
+
|
|
520
|
+
## Troubleshooting
|
|
521
|
+
|
|
522
|
+
### Server doesn't appear in VS Code
|
|
523
|
+
|
|
524
|
+
1. Check the MCP output panel: `View → Output → MCP`
|
|
525
|
+
2. Make sure you added the config to **User Settings (JSON)** (global), not workspace settings
|
|
526
|
+
3. Reload VS Code: `Cmd+Shift+P` → "Developer: Reload Window"
|
|
527
|
+
4. Verify `npx bob-pr-reviewer` works in your terminal
|
|
528
|
+
|
|
529
|
+
### All MCP logs show as "errors" in VS Code
|
|
530
|
+
|
|
531
|
+
This is normal and expected. VS Code's MCP output panel labels all stderr output as errors regardless of content. MCP servers must use stderr for logging (stdout is reserved for the JSON-RPC protocol). If you see `✅ All checks passed`, the server is working correctly.
|
|
532
|
+
|
|
533
|
+
### "GITHUB_TOKEN is not set"
|
|
534
|
+
|
|
535
|
+
The token isn't reaching the server. Make sure you:
|
|
536
|
+
1. Added `export GITHUB_TOKEN=...` to `~/.zshrc`
|
|
537
|
+
2. Ran `source ~/.zshrc`
|
|
538
|
+
3. **Fully restarted VS Code** (quit and reopen — not just reload window)
|
|
539
|
+
|
|
540
|
+
### "GitHub API error 401: Bad credentials"
|
|
541
|
+
|
|
542
|
+
Your token is invalid or expired. Generate a new one at `https://github.ibm.com/settings/tokens` with `repo` scope.
|
|
543
|
+
|
|
544
|
+
### "Cannot reach github.ibm.com"
|
|
545
|
+
|
|
546
|
+
You're not on IBM VPN. Connect to VPN and reload VS Code.
|
|
547
|
+
|
|
548
|
+
### "No Jira ticket key found in PR"
|
|
549
|
+
|
|
550
|
+
The PR title/branch/description doesn't contain a recognizable Jira key pattern (e.g. `ABC-1234`). Provide it explicitly:
|
|
551
|
+
```
|
|
552
|
+
Check PR #1758 in sec-ci/notification against Jira ticket VDEV-47721
|
|
553
|
+
```
|
|
554
|
+
|
|
555
|
+
### Inline comments fail with position errors
|
|
556
|
+
|
|
557
|
+
The `position` field in `post_review` refers to the **line position in the unified diff** (1-based), not the actual file line number. The AI calculates these from the diff returned by `fetch_pr_diff`. If positions are wrong, ask the AI to re-fetch the diff and recount.
|
|
558
|
+
|
|
559
|
+
### Degraded mode — only `check_setup` available
|
|
560
|
+
|
|
561
|
+
Ask the AI: `@bob-pr-reviewer Run check_setup` — it will show exactly which check failed and how to fix it.
|
|
562
|
+
|
|
563
|
+
---
|
|
564
|
+
|
|
565
|
+
## Security Notes
|
|
566
|
+
|
|
567
|
+
- **Never commit your `.env` file** — it's in `.gitignore`
|
|
568
|
+
- Tokens are passed via environment variables and never sent to the AI model
|
|
569
|
+
- The MCP server only has access to repos your GitHub token can access
|
|
570
|
+
- The server runs locally — no data leaves your machine except to `github.ibm.com` and `jsw.ibm.com`
|
|
571
|
+
|
|
572
|
+
---
|
|
573
|
+
|
|
574
|
+
## License
|
|
575
|
+
|
|
576
|
+
ISC
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* GitHub Enterprise API client for bob-pr-reviewer MCP server.
|
|
3
|
+
* Handles all communication with the GitHub Enterprise REST API.
|
|
4
|
+
*/
|
|
5
|
+
export interface PrInfo {
|
|
6
|
+
number: number;
|
|
7
|
+
title: string;
|
|
8
|
+
author: string;
|
|
9
|
+
state: string;
|
|
10
|
+
baseBranch: string;
|
|
11
|
+
headBranch: string;
|
|
12
|
+
description: string;
|
|
13
|
+
commitSha: string;
|
|
14
|
+
url: string;
|
|
15
|
+
createdAt: string;
|
|
16
|
+
updatedAt: string;
|
|
17
|
+
}
|
|
18
|
+
export interface PrFile {
|
|
19
|
+
filename: string;
|
|
20
|
+
status: string;
|
|
21
|
+
additions: number;
|
|
22
|
+
deletions: number;
|
|
23
|
+
patch: string;
|
|
24
|
+
}
|
|
25
|
+
export interface ReviewComment {
|
|
26
|
+
path: string;
|
|
27
|
+
position: number;
|
|
28
|
+
body: string;
|
|
29
|
+
}
|
|
30
|
+
export interface PostReviewRequest {
|
|
31
|
+
repo: string;
|
|
32
|
+
prNumber: number;
|
|
33
|
+
commitSha: string;
|
|
34
|
+
summary: string;
|
|
35
|
+
event: 'COMMENT' | 'APPROVE' | 'REQUEST_CHANGES';
|
|
36
|
+
comments: ReviewComment[];
|
|
37
|
+
}
|
|
38
|
+
export interface PostReviewResult {
|
|
39
|
+
reviewId: number;
|
|
40
|
+
htmlUrl: string;
|
|
41
|
+
state: string;
|
|
42
|
+
}
|
|
43
|
+
export declare class GitHubClient {
|
|
44
|
+
private baseUrl;
|
|
45
|
+
private token;
|
|
46
|
+
constructor(baseUrl: string, token: string);
|
|
47
|
+
private get headers();
|
|
48
|
+
private request;
|
|
49
|
+
/**
|
|
50
|
+
* Get PR metadata: title, author, branches, description, commit SHA
|
|
51
|
+
*/
|
|
52
|
+
getPrInfo(repo: string, prNumber: number): Promise<PrInfo>;
|
|
53
|
+
/**
|
|
54
|
+
* Get all changed files and their diffs for a PR
|
|
55
|
+
*/
|
|
56
|
+
getPrFiles(repo: string, prNumber: number): Promise<PrFile[]>;
|
|
57
|
+
/**
|
|
58
|
+
* Post a review with optional inline comments to a PR
|
|
59
|
+
*/
|
|
60
|
+
postReview(req: PostReviewRequest): Promise<PostReviewResult>;
|
|
61
|
+
/**
|
|
62
|
+
* Post a general (non-inline) comment on a PR
|
|
63
|
+
*/
|
|
64
|
+
postComment(repo: string, prNumber: number, body: string): Promise<{
|
|
65
|
+
commentId: number;
|
|
66
|
+
htmlUrl: string;
|
|
67
|
+
}>;
|
|
68
|
+
/**
|
|
69
|
+
* Validate that the token works and return the authenticated user
|
|
70
|
+
*/
|
|
71
|
+
validateToken(): Promise<string>;
|
|
72
|
+
}
|
|
73
|
+
//# sourceMappingURL=github-client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"github-client.d.ts","sourceRoot":"","sources":["../src/github-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,MAAM;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,iBAAiB,CAAC;IACjD,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAS;gBAEV,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAM1C,OAAO,KAAK,OAAO,GAOlB;YAEa,OAAO;IA0BrB;;OAEG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAkBhE;;OAEG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAYnE;;OAEG;IACG,UAAU,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA2BnE;;OAEG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAehH;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;CAIvC"}
|