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 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"}