bob-pr-reviewer v0.0.11

An MCP (Model Context Protocol) server that gives AI assistants in VS Code/IBM Bob the ability to read GitHub Enterprise pull requests, fetch Jira ticket requirements, and post structured review comments — all via natural language.

No clone required. No build step. No manual server startup. VS Code/IBM Bob launches this automatically via npx — just configure once and it works everywhere.

Quick Start (5 minutes)

Full step-by-step instructions: see SETUP.md

Step 1 — Get your tokens

| Token | Where to get it | | -------------------------- | ------------------------------------------------------------------------- | | GitHub Enterprise PAT | https://github.ibm.com/settings/tokens → scope: repo | | Jira Personal Access Token | https://jsw.ibm.com/secure/ViewProfile.jspa → Personal Access Tokens |

Step 2 — Set your tokens

Add to your ~/.zshrc (or ~/.bashrc):

export GITHUB_TOKEN=ghp_yourGitHubTokenHere
export JIRA_ISV_PERSONAL_ACCESS_TOKEN=yourJiraTokenHere

Then reload: source ~/.zshrc and restart VS Code/IBM Bob completely.

Step 3 — Add to VS Code/IBM Bob User Settings

Open VS Code/IBM Bob global settings JSON (Cmd+Shift+P → "MCP Server -> Global MCPs") and add:

{
  "mcpServers": {
    "bob-pr-reviewer": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "bob-pr-reviewer@latest"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}",
        "GITHUB_BASE_URL": "https://github.ibm.com/api/v3",
        "JIRA_ISV_PERSONAL_ACCESS_TOKEN": "${env:JIRA_ISV_PERSONAL_ACCESS_TOKEN}",
        "JIRA_BASE_URL": "https://jsw.ibm.com"
      }
    }
  }
}

⚠️ 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.

Step 4 — Reload VS Code/IBM Bob

Cmd+Shift+P → "Developer: Reload Window"

That's it. The server starts automatically. Open any project and the tools are available.

How It Works

You:    "Use the bob-pr-reviewer MCP server to review PR #1758 in sec-ci/notification"
           │
           ▼
     VS Code/IBM Bob AI Assistant
           │  sees MCP tools available, decides which to call
           ▼
     bob-pr-reviewer (auto-launched by VS Code/IBM Bob via npx)
           │  calls GitHub Enterprise API + Jira API in parallel
           ▼
     GitHub Enterprise (github.ibm.com)  +  Jira (jsw.ibm.com)
           │  returns PR diff + Jira requirements
           ▼
     AI analyzes code vs requirements → posts structured comment to PR

VS Code/IBM Bob 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.

Auto-Sync Bob Commands

New in v0.0.11: Bob commands are automatically synced to your ~/.bob/commands/ directory on server startup.

The server includes 7 Bob commands that provide structured workflows:

Quick Operations (< 1 min):
├── /bob-pr-reviewer-check-setup          # Verify prerequisites & sync status
├── /bob-pr-reviewer-get-pr-info          # Fetch PR metadata only
├── /bob-pr-reviewer-get-jira-ticket      # Fetch Jira ticket details
└── /bob-pr-reviewer-post-comment         # Post a simple comment

Pre-Commit Review (1-3 min):
└── /bob-pr-reviewer-pre-commit-review    # Review local changes before committing

Standard Review (2-5 min):
└── /bob-pr-reviewer-review-pr            # Jira + inline code review

Comprehensive Review (5-15 min):
└── /bob-pr-reviewer-comprehensive-review # Full 8-layer analysis

How it works:

• Commands are bundled in the npm package under .bob/commands/
• On server startup, they're automatically copied to ~/.bob/commands/
• Version tracking ensures you always have the latest commands
• Reload IBM Bob to see new commands: Cmd+Shift+P → "Developer: Reload Window"

Check sync status:

/bob-pr-reviewer-check-setup

How to Invoke in IBM Bob

⚠️ Important: Use Structured Commands for Consistent Results

Problem: Generic commands like "review this PR" give inconsistent behavior because the AI has to guess which workflow you want.

Solution: Use Bob commands (slash commands in IBM Bob) or explicit text commands for structured, repeatable workflows.

Quick Reference: Copy-Paste Commands

1️⃣ Standard PR Review (Recommended)

Bob command (IBM Bob):

/bob-pr-reviewer-review-pr

Text command (works everywhere):

Use the bob-pr-reviewer MCP server to review PR #1758 in sec-ci/notification

2️⃣ Comprehensive 8-Layer Review

Bob command (IBM Bob):

/bob-pr-reviewer-comprehensive-review https://github.com/sec-ci/notification/pull/1758

Text command (works everywhere):

Use the bob-pr-reviewer MCP server to perform a comprehensive review of https://github.com/sec-ci/notification/pull/1758

3️⃣ Pre-Commit Review (Before Committing)

Bob command (IBM Bob):

/bob-pr-reviewer-pre-commit-review

Text command (works everywhere):

Use the bob-pr-reviewer MCP server to review my uncommitted changes before committing

4️⃣ Diagnose Setup Issues

Bob command (IBM Bob):

/bob-pr-reviewer-check-setup

Text command (works everywhere):

Use the bob-pr-reviewer MCP server to check setup

Why you need to mention the server name

Without the server name, Bob may try to answer from general knowledge instead of calling the actual GitHub/Jira APIs. Mentioning bob-pr-reviewer MCP server tells Bob to use the tools from this specific server.

IBM Bob limitations (current)

ℹ️ These are IBM Bob UI gaps — the MCP server code is fully correct and complete.

| Feature | IBM Bob | VS Code Copilot Chat | Cline / Roo | | --------------------------------------- | -------------------- | -------------------- | ----------- | | MCP tools (core functionality) | ✅ Works | ✅ Works | ✅ Works | | /server-name:command slash commands | ❌ Not yet supported | ✅ Works | ✅ Works | | @server-name mention autocomplete | ❌ Not yet supported | ✅ Works | ✅ Works |

The MCP prompts (slash commands) are registered in the server and will work automatically once IBM Bob adds support for them. No code changes will be needed.

Tools Available

| Tool | Description | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | check_setup | Re-run all prerequisites checks and show status | | sync_bob_files | Manually sync Bob commands to ~/.bob/commands/ | | validate_token | Verify your GitHub token is working | | get_pr_info | Fetch PR title, author, branches, commit SHA, description | | fetch_pr_diff | Fetch all changed files + unified diffs | | post_review | Post a review with inline comments at diff positions | | post_comment | Post a general (non-inline) PR comment | | get_jira_ticket | Fetch a Jira ticket's summary, description, acceptance criteria | | fetch_context_document | Fetch a context document from a URL or local file path (design docs, transcripts, RFCs, ADRs) | | generate_review_findings | Generate PR vs Jira analysis findings for user review (does NOT post to GitHub) | | post_jira_analysis | Post approved findings to GitHub as a PR comment (called after user reviews findings from generate_review_findings) |

Usage Examples

Full PR review with Jira check

In IBM Bob:

Use the bob-pr-reviewer MCP server to review PR #1758 in sec-ci/notification

Bob will ask for the repo and PR number if not provided, then ask whether you have any context documents (design docs, transcripts, etc.), then ask whether you want to include a Jira requirements check.

Review with a context document

In IBM Bob:

Use the bob-pr-reviewer MCP server to review PR #1758 in sec-ci/notification. I have a design doc at https://confluence.ibm.com/pages/viewpage.action?pageId=12345

Bob will call fetch_context_document to load the design doc, then incorporate it into the review alongside the PR diff and Jira requirements.

Pre-commit review

In IBM Bob:

Use the bob-pr-reviewer MCP server to review my uncommitted changes before committing

Bob will analyze your staged changes, check code quality and security, optionally validate against Jira requirements (if ticket key is in branch name), and generate a conventional commit message.

Verify setup

In IBM Bob:

Use the bob-pr-reviewer MCP server to check setup

What to Expect in VS Code

On first use

When VS Code first launches the server, npx downloads and caches the package automatically. You'll see a brief pause — subsequent launches are instant.

To verify the server is running:

1. Open the Output panel: View → Output
2. Select MCP from the dropdown
3. You should see output like this:

[bob-pr-reviewer] Starting up... GitHub: https://github.ibm.com/api/v3 | Jira: https://jsw.ibm.com
[bob-pr-reviewer] Prerequisites check:
  ✓ Node.js version: Node.js 18.19.0 (requires >= 18.x)
  ✓ GITHUB_TOKEN environment variable: GITHUB_TOKEN is set (length: 40)
  ✓ GitHub token validity: Token is valid — authenticated as: your-username
  ✓ GitHub API reachability: https://github.ibm.com/api/v3 is reachable
  ✓ JIRA_ISV_PERSONAL_ACCESS_TOKEN environment variable: set (length: 38)
  ✓ Jira token validity: Token is valid — authenticated as: Your Name
[bob-pr-reviewer] ✅ All checks passed — registering all tools
[bob-pr-reviewer] Bob commands sync: ✓ 6 commands synced to ~/.bob/commands/
[bob-pr-reviewer] MCP server ready (stdio transport)

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.

What to Expect on GitHub

After Jira analysis

A structured comment is automatically posted to the PR:

🤖 Requirements Check: VDEV-47721

Jira: Domain auth APIs rate limit Verdict: ⚠️ Partial Match

Requirements Coverage

• ✅ Rate limiting logic implemented
• ⚠️ Error response format differs from acceptance criteria

Gaps / Concerns

• Missing Retry-After header in 429 responses
• No unit tests for rate limit boundary conditions

Summary The PR implements the core rate limiting feature but is missing the Retry-After header required by the acceptance criteria.

After inline code review

When the AI calls post_review, it posts a GitHub review with:

• Overall summary — High-level assessment
• Inline comments — Specific feedback at exact diff positions
• Review action — COMMENT, APPROVE, or REQUEST_CHANGES

Project Structure

bob-pr-reviewer/
├── src/
│   ├── index.ts            # MCP server entry point
│   ├── github-client.ts    # GitHub Enterprise REST API client
│   ├── jira-client.ts      # Jira REST API v2 client
│   ├── prerequisites.ts    # Startup validator
│   ├── sync.ts             # Bob commands auto-sync
│   └── tools.ts            # MCP tool schema definitions
├── dist/                   # Compiled JavaScript (included in npm package)
├── .bob/
│   ├── mcp.json            # IBM Bob extension MCP config (local dev)
│   └── commands/           # Bob command definitions (auto-synced to ~/.bob/commands/)
├── .vscode/
│   └── mcp.json            # VS Code built-in MCP config (local dev)
├── package.json            # includes "bin" field for npx support
├── publish.sh              # Build + version bump + publish script
├── README.md               # This file
├── SETUP.md                # Detailed installation guide
├── ARCHITECTURE_ANALYSIS.md # Architecture decisions and migration path
└── TESTING_CHECKLIST.md    # Pre/post-publish verification

For Contributors / Local Development

If you want to modify the server or contribute:

git clone [email protected]:himanshu-sao-ibm/bob-pr-reviewer.git
cd bob-pr-reviewer
npm install
npm run build

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.

After making code changes, rebuild and reload:

npm run build
# Then in VS Code: Cmd+Shift+P → "Developer: Reload Window"

Publishing a New Version

Who does this: Only the maintainer (himanshu-sao-ibm) needs to do this when releasing updates.

First-time setup (one-time only)

npm login
chmod +x publish.sh

2FA note: If your npm account has 2FA enabled, either pass --otp=123456 to the script, or create a Granular Access Token on npmjs.com with "Read and write" + bypass 2FA, then set it:

npm set //registry.npmjs.org/:_authToken YOUR_TOKEN

Publishing an update

# Patch release — bug fixes (0.0.11 → 0.0.12)
./publish.sh

# Minor release — new features (0.0.11 → 0.1.0)
./publish.sh minor

# Major release — breaking changes (0.0.11 → 1.0.0)
./publish.sh major

# With 2FA OTP
./publish.sh minor --otp=123456

The script will build, bump the version, publish, and print next steps. Users get the update automatically on next VS Code launch.

Troubleshooting

Server doesn't appear in VS Code

1. Check the MCP output panel: View → Output → MCP
2. Make sure you added the config to User Settings (JSON) (global), not workspace settings
3. Reload VS Code: Cmd+Shift+P → "Developer: Reload Window"
4. Verify npx bob-pr-reviewer works in your terminal

All MCP logs show as "errors" in VS Code

This is normal and expected. VS Code's MCP output panel labels all stderr output as errors. 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.

IBM Bob doesn't show slash commands

This is a known IBM Bob limitation — Bob does not yet surface MCP prompts as / slash commands. Use the explicit invocation pattern instead:

Use the bob-pr-reviewer MCP server to review PR #1758 in sec-ci/notification

"GITHUB_TOKEN is not set"

The token isn't reaching the server. Make sure you:

1. Added export GITHUB_TOKEN=... to ~/.zshrc
2. Ran source ~/.zshrc
3. Fully restarted VS Code (quit and reopen — not just reload window)

Degraded mode — only check_setup available

Ask the AI:

Use the bob-pr-reviewer MCP server to check setup

It will show exactly which check failed and how to fix it.

Security Notes

• Never commit your .env file — it's in .gitignore
• Tokens are passed via environment variables and never sent to the AI model
• The MCP server only has access to repos your GitHub token can access
• The server runs locally — no data leaves your machine except to github.ibm.com and jsw.ibm.com

License

ISC