Prodbeam MCP Server

Engineering intelligence reports from GitHub and Jira, delivered through any MCP client or the standalone CLI.

• Daily standups from your commits, PRs, reviews, and Jira issues
• Weekly summaries with delivery metrics, repo breakdowns, and trend analysis
• Sprint retrospectives with merge time analysis, completion rates, and action items
• Sprint reviews with mid-sprint progress, risks, blockers, and per-developer status
• Team health scoring with anomaly detection and recommendations

Table of Contents

• Quick Start
• Prerequisites
• Usage
• Sample Output
• Available Tools
• Architecture
• Security
• Known Limitations
• Documentation
• Contributing
• License

Quick Start

Option 1: Global install with setup wizard

npm install -g @prodbeam/mcp
prodbeam init

The wizard walks you through authentication (OAuth or tokens), discovers your repos and projects, and registers the MCP server automatically.

Option 2: npx (zero install)

claude mcp add prodbeam \
  -e GITHUB_TOKEN=ghp_YOUR_TOKEN \
  -e JIRA_HOST=company.atlassian.net \
  -e JIRA_EMAIL=you@company.com \
  -e JIRA_API_TOKEN=your_jira_token \
  -- npx -y @prodbeam/mcp

Then set up your team in a Claude Code session:

Set up my prodbeam team called "My Team" with emails: alice@company.com, bob@company.com

Option 3: MCP client config file

For Cursor, Windsurf, VS Code, or other MCP clients that use a JSON config:

{
  "mcpServers": {
    "prodbeam": {
      "command": "npx",
      "args": ["-y", "@prodbeam/mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_YOUR_TOKEN",
        "JIRA_HOST": "company.atlassian.net",
        "JIRA_EMAIL": "you@company.com",
        "JIRA_API_TOKEN": "your_jira_token"
      }
    }
  }
}

Config file locations:

For more setup options, see the Setup & Usage Guide.

Prerequisites

Jira is optional — reports work with GitHub alone, with Jira sections omitted.

Usage

In any MCP client

Ask naturally — the client invokes the right tool:

CLI

prodbeam auth login                        # Authenticate (OAuth or token)
prodbeam auth status                       # Check token expiry
prodbeam standup                           # Personal standup (last 24h)
prodbeam standup --email alice@co.com      # Standup for a specific member
prodbeam team-standup                      # Full team standup
prodbeam weekly                            # Weekly summary (current week)
prodbeam weekly --weeks-ago 1              # Last week's summary
prodbeam sprint-retro                      # Sprint retro (auto-detect sprint)
prodbeam sprint-retro --sprint "Sprint 12" # Specific sprint
prodbeam sprint-review                     # Mid-sprint health check
prodbeam status                            # Check config and credentials
prodbeam help                              # All commands
prodbeam help weekly                       # Detailed help for a command

Sample Output

# Daily Standup - Friday, February 7, 2026

**alice**

## Completed

- ENG-431: Webhook retry failures → PR #142 (merged, +187/-43)
- [ENG-428](https://company.atlassian.net/browse/ENG-428): Implement API rate limiting [Done]

## In Progress

- #89: Update shared ESLint config [open] (+45/-22)
- [ENG-445](https://company.atlassian.net/browse/ENG-445): Upgrade ESLint to v9 [In Progress]

## Blockers & Risks

- [!] PR #134: Refactor auth middleware — open 9 days

## Activity Summary

| Metric | Count |
|--------|-------|
| Commits | 3 |
| Pull Requests | 2 |
| Reviews | 1 |
| Jira Issues | 3 |

**Recent Commits**
- `a1b2c3d` fix: resolve race condition in webhook handler (acme/api-gateway)
- `d4e5f6a` test: add integration tests for retry logic (acme/api-gateway)
- `b7c8d9e` chore: update eslint config (acme/shared-config)

**Reviews Given**
- PR #137: Add rate limiting middleware [APPROVED]

---

# Weekly Engineering Summary - Friday, February 7, 2026

**alice** — Last 7 Days

## Highlights

- Merged 3 PRs this week
- Completed 3 Jira issues
- Average cycle time: 14.2h — healthy turnaround

## Delivery Metrics

| Metric | Value |
|--------|-------|
| Commits | 12 |
| Pull Requests | 5 (3 merged, 1 open, 1 closed) |
| Code Changes | +847/-312 |
| Cycle Time (avg) | 14.2 hours |
| Reviews | 8 (6 approved, 2 changes requested) |

## Key Deliverables

- ENG-431: Webhook retry failures → PR #142 (merged, +187/-43)
- ENG-428: API rate limiting → PR #137 (merged, +312/-45)
- ENG-435: Redis connection pooling → PR #139 (merged, +94/-12)

## Investment Balance

| Type | Count |
|------|-------|
| Story | 3 |
| Bug | 2 |
| Task | 1 |

## PR Size Distribution

| Size | Lines Changed | Count |
|------|--------------|-------|
| Small | 1-100 | 2 |
| Medium | 101-500 | 2 |
| Large | 501+ | 1 |

## Repository Breakdown

| Repository | Commits | PRs | Merged | +/- | Reviews |
|------------|---------|-----|--------|-----|---------|
| acme/api-gateway | 8 | 3 | 2 | +612/-198 | 5 |
| acme/shared-config | 2 | 1 | 1 | +45/-22 | 1 |
| acme/docs | 2 | 1 | 0 | +190/-92 | 2 |

## Jira Issues: 6

| Status | Count |
|--------|-------|
| Done | 3 |
| In Progress | 2 |
| In Review | 1 |

## Trends vs Previous Period

| Metric | Change | Direction | Severity |
|--------|--------|-----------|----------|
| Commits | +25% | Up | [i] info |
| PRs Merged | -15% | Down | [!] warning |
| Merge Time | +40% | Up | [!] warning |

- [i] Commit volume up 25% — consistent with sprint mid-point
- [!] PR merge rate declined 15% — may indicate review bottleneck
- [!] Average merge time increased to 18h (was 12.8h last week)

## Insights

- [!] **warning:** PR #134 open for 9 days without review
- [i] **info:** 3 PRs merged same-day — healthy turnaround

## Team Health: 72/100

| Dimension | Score | Trend |
|-----------|-------|-------|
| Velocity | 78 | Up |
| Throughput | 70 | Down |
| Review Coverage | 65 | Stable |
| Issue Flow | 74 | Up |

### Recommendations

- Review coverage below 75% — consider distributing reviews more evenly
- 1 PR has been open >7 days — prioritize review to unblock work

## Appendix

### Commits: 12
- `a1b2c3d` fix: resolve race condition in webhook handler (acme/api-gateway)
- `d4e5f6a` test: add integration tests for retry logic (acme/api-gateway)
- ...

### Pull Requests: 5
- #142: Fix webhook retry logic [merged] (+187/-43)
- #139: Refactor auth middleware [merged] (+312/-155)
- ...

### Reviews: 8
- PR #137: Add rate limiting middleware [APPROVED]
- PR #141: Migrate auth to OAuth2 [APPROVED]
- ...

---

# Sprint Retrospective: Sprint 12

**Period:** 2026-01-27 to 2026-02-07
**Developer:** alice

## Sprint Goal

> Deliver webhook reliability improvements and API rate limiting

## Sprint Scorecard

| Metric | Value |
|--------|-------|
| Completion Rate | 8/11 (73%) |
| Carryover | 3 issues |
| Merge Rate | 78% |
| Avg Merge Time | 14.2 hours |

## What Went Well

- 8 of 11 sprint issues completed (73%) — above team average
- 5 of 7 merged PRs had same-day reviews
- Sprint goal partially achieved: webhook reliability improvements shipped

## What Needs Improvement

- Average merge time of 14.2h exceeds 8h target
- PR #134 blocked on review for 12 days
- 3 issues carried over from previous sprint

## Action Items

- Set up daily review rotation to reduce merge time
- Break down large issues to improve estimation accuracy
- Address PR #134 review bottleneck

## Delivery Metrics

| Metric | Value |
|--------|-------|
| Commits | 24 |
| Pull Requests | 9 (7 merged, 1 open, 1 closed) |
| Code Changes | +2,145/-876 |
| Reviews | 15 (12 approved, 3 changes requested) |

## Developer Contributions

### alice
- PRs: 3 merged, 1 open
- Reviews given: 4
- Focus: webhook reliability (ENG-431, ENG-433)

### bob
- PRs: 3 merged, 0 open
- Reviews given: 8
- Focus: API rate limiting (ENG-428)

## Jira Issues

| Status | Count |
|--------|-------|
| Done | 8 |
| In Progress | 2 |
| In Review | 1 |

| Type | Count |
|------|-------|
| Story | 5 |
| Bug | 3 |
| Task | 2 |
| Spike | 1 |

| Priority | Count |
|----------|-------|
| High | 4 |
| Medium | 5 |
| Low | 2 |

## Trends vs Previous Period

| Metric | Change | Direction | Severity |
|--------|--------|-----------|----------|
| Commits | +14% | Up | [i] info |
| Merge Rate | -8% | Down | [!] warning |
| Completion Rate | +5% | Up | [i] info |

- [i] Commit volume increased 14% over previous sprint
- [!] Merge rate dropped 8% — 2 PRs blocked on review for 3+ days
- [i] Jira completion improved to 73% (was 68% last sprint)

## Insights

- [!] **warning:** PR #134 open for 12 days — oldest unmerged PR in sprint
- [i] **info:** 5 of 7 merged PRs had same-day reviews

## Team Health: 70/100

| Dimension | Score | Trend |
|-----------|-------|-------|
| Velocity | 76 | Up |
| Throughput | 68 | Stable |
| Review Coverage | 62 | Down |
| Issue Flow | 73 | Up |

### Recommendations

- Review coverage declining — consider pairing sessions to distribute knowledge
- 3 issues carried over from previous sprint — review estimation accuracy

## Appendix

### Commits: 24
- `a1b2c3d` fix: resolve race condition in webhook handler (acme/api-gateway)
- `d4e5f6a` test: add integration tests for retry logic (acme/api-gateway)
- ...

### Pull Requests: 9
- #142: Fix webhook retry logic [merged] (+187/-43)
- #139: Refactor auth middleware [merged] (+312/-155)
- ...

### Reviews: 15
- PR #137: Add rate limiting middleware [APPROVED]
- PR #141: Migrate auth to OAuth2 [APPROVED]
- ...

---

# Sprint Review: Sprint 12

**Period:** 2026-01-27 to 2026-02-07
**Sprint Progress:** Day 8 of 14 (57%)

## Sprint Goal

> Deliver webhook reliability improvements and API rate limiting

## Progress Summary

| Metric | Value |
|--------|-------|
| Days Elapsed | 8 of 14 |
| Issues Completed | 5 of 11 (45%) |
| Issues In Progress | 4 |
| Issues Not Started | 2 |
| PRs Merged | 6 |
| PRs Awaiting Review | 2 |

## Key Deliverables

- ENG-431: Webhook retry failures → PR #142 (merged)
- ENG-428: API rate limiting → PR #137 (merged)
- ENG-435: Redis connection pooling → PR #139 (merged)

## In Progress

- ENG-445: Upgrade ESLint to v9 → PR #89 (open 3 days)
- ENG-440: Redis connection pool tuning → PR #143 (open 1 day)
- ENG-450: Add monitoring dashboard
- ENG-452: Update deployment runbook

## Risks & Blockers

- [!] 1 PR open for extended period — may not merge before sprint end
- [!] 6 days remaining with 6 incomplete items
- [!] 1 high-priority issue stalled

## Developer Progress

### alice
- Completed: 3 PRs merged
- In Progress: 1 PRs open
- Reviews Given: 4

### bob
- Completed: 2 PRs merged
- In Progress: 1 PRs open
- Reviews Given: 6

### carol
- Completed: 1 PRs merged
- In Progress: 0 PRs open
- Reviews Given: 2

## Delivery Metrics

| Metric | Value |
|--------|-------|
| Commits | 18 |
| Pull Requests | 8 (6 merged, 2 open) |
| Code Changes | +1,547/-623 |
| Reviews | 12 (10 approved, 2 changes requested) |

---

Available Tools

Setup

Reports

For full parameter documentation and sample output for every tool, see the Tool Reference.

Architecture

Prodbeam is self-sufficient — it fetches data directly from GitHub and Jira APIs. No separate MCP servers needed. One tool call produces one complete report with no multi-step orchestration.

End-to-End Workflow

┌─────────────────────────────────────────────────────────────────────────────┐
│                        MCP Client / CLI                                    │
│              (Claude Code, Cursor, Windsurf, CLI)                          │
└────────────────────────────┬────────────────────────────────────────────────┘
                             │ tool call (stdio / argv)
                             ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                      Prodbeam MCP Server                                   │
│                                                                            │
│  ┌──────────────┐    ┌──────────────────────────────────────────────────┐  │
│  │ Auth Provider │───▶│               Data Fetcher                      │  │
│  │              │    │                                                  │  │
│  │ env vars     │    │  ┌─────────────┐       ┌─────────────┐          │  │
│  │   ▼ OAuth    │    │  │ GitHub REST  │       │  Jira REST  │          │  │
│  │   ▼ PAT      │    │  │   Client    │       │   Client    │          │  │
│  └──────────────┘    │  └──────┬──────┘       └──────┬──────┘          │  │
│                      │         │                     │                  │  │
│  ┌──────────────┐    │         └──────────┬──────────┘                  │  │
│  │ Team Config  │───▶│      Promise.allSettled (parallel, per-repo)     │  │
│  │ ~/.prodbeam/ │    └──────────────────┬───────────────────────────────┘  │
│  │ team.json    │                       │                                  │
│  └──────────────┘                       ▼                                  │
│                      ┌──────────────────────────────────────────────────┐  │
│                      │           Metrics Calculator                     │  │
│                      │                                                  │  │
│                      │  Raw activity ──▶ aggregate metrics              │  │
│                      │  (pure functions, no I/O)                        │  │
│                      └──────────────────┬───────────────────────────────┘  │
│                                         │                                  │
│                                         ▼                                  │
│                      ┌──────────────────────────────────────────────────┐  │
│                      │        ★ Intelligence Engine ★                   │  │
│                      │        (best-effort, try-catch wrapped)          │  │
│                      │                                                  │  │
│                      │  ┌──────────────┐  ┌──────────────────────────┐  │  │
│                      │  │   Trend      │  │   Anomaly                │  │  │
│                      │  │   Analyzer   │  │   Detector               │  │  │
│                      │  │  7 metrics   │  │  5 anomaly types         │  │  │
│                      │  └──────────────┘  └──────────────────────────┘  │  │
│                      │  ┌──────────────┐  ┌──────────────────────────┐  │  │
│                      │  │  Team Health │  │   Content Insights       │  │  │
│                      │  │   Scorer     │  │   Engine                 │  │  │
│                      │  │  4 dimensions│  │  qualitative analysis    │  │  │
│                      │  └──────────────┘  └──────────────────────────┘  │  │
│                      └──────────────────┬───────────────────────────────┘  │
│                                         │                                  │
│                                         ▼                                  │
│                      ┌──────────────────────────────────────────────────┐  │
│                      │          Report Generator                        │  │
│                      │                                                  │  │
│                      │  metrics + intelligence ──▶ Markdown report      │  │
│                      │  (pure functions, no I/O)                        │  │
│                      └──────────────────┬───────────────────────────────┘  │
│                                         │                                  │
│                                         ▼                                  │
│                      ┌──────────────────────────────────────────────────┐  │
│                      │          History Store                           │  │
│                      │                                                  │  │
│                      │  SQLite (WAL mode) ── aggregate snapshots only   │  │
│                      │  (fire-and-forget, feeds future trend analysis)  │  │
│                      └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

Component Details

Auth Provider

Resolves credentials through a three-tier chain: environment variables (highest priority, always wins), OAuth tokens (auto-refreshed before expiry), personal access tokens (fallback). OAuth supports GitHub Device Flow and Jira OAuth 2.0 (3LO). Token refresh happens transparently — if an access token expires within 5 minutes, the provider silently exchanges the refresh token for a new one. Users only re-authenticate when refresh tokens expire (GitHub: 6 months, Jira: 90 days of inactivity).

Data Fetcher

Orchestrates parallel API calls across all configured repos and projects using Promise.allSettled. In team mode, each repo is fetched once and activity is split by member (avoiding N×M API calls). Individual repo failures are silently skipped — a 404 on one repo doesn't block the rest of the report. GitHub and Jira fetching run concurrently.

Metrics Calculator

Pure functions that transform raw API responses into aggregate metrics: commit counts, PR states (merged/open/closed), code churn (additions + deletions), review counts, average merge time, and Jira completion rates. No I/O — deterministic given the same input.

Report Generator

Pure Markdown renderers for all five report types (daily standup, team standup, weekly summary, sprint retro, sprint review). Each generator takes pre-computed metrics and optional intelligence extras (trends, anomalies, health scores) and returns a Markdown string. No API calls, no side effects, no randomness — testable with mock data.

History Store

SQLite database (via better-sqlite3, WAL mode) that persists aggregate metric snapshots. Each snapshot captures 16 team-level fields (commits, PRs, merge rates, code churn, reviews, Jira counts) and 7 per-member fields. Snapshots are saved fire-and-forget after report generation and feed the trend analyzer for period-over-period comparisons. The database never stores textual content — no commit messages, PR descriptions, or code.

Intelligence Engine

The intelligence engine is Prodbeam's core differentiator. It transforms raw metrics into actionable insights through four independent analyzers. Each runs in a try-catch wrapper — if any fails, the report still generates without that section.

Trend Analyzer

Compares the current period against the previous snapshot stored in SQLite. Tracks 7 metrics with directional awareness:

Each metric change is classified by configurable thresholds: info (<25% change), warning (25-50%), alert (>50%). The direction awareness means a 40% increase in merge time is a warning, while a 40% increase in PRs merged is just info. Results are sorted by severity so alerts surface first.

Anomaly Detector

Scans current activity for five anomaly patterns, each with configurable thresholds:

Review imbalance uses a Gini coefficient concept to detect concentration, only triggering when the team has at least 2 active reviewers to avoid false positives on small teams.

Team Health Scorer

Produces a composite health score (0-100) across four weighted dimensions:

Overall Score = Velocity × 0.20 + Throughput × 0.30 + Review Coverage × 0.25 + Issue Flow × 0.25

Each dimension includes a trend indicator (up/down/stable) comparing against the previous snapshot. The scorer generates context-aware recommendations when dimension scores fall below healthy thresholds — e.g., review coverage below 75% triggers a suggestion to distribute reviews more evenly.

Content Insights Engine

Derives qualitative analysis from raw activity data:

• PR-Jira Linking — Regex pattern matching ([A-Z]+-\d+) extracts Jira issue keys from PR titles, linking code changes to tracked work items. Linked items appear together in reports for traceability.
• Accomplishments — Identifies completed deliverables by matching merged PRs to resolved Jira issues. Linked pairs (PR + issue) display together; unlinked items listed separately.
• What Went Well — Detects positive patterns: fast merge cycles (<24h average), high completion rates (>70%), strong merge rates (>80%), clean sprint boards.
• What Needs Improvement — Surfaces friction: stale PRs, PRs without approvals, high carryover (>30% of sprint), low Jira completion (<50%), review imbalance.
• Action Items — Generates specific follow-ups: triage stale PRs, establish approval workflows, review team capacity, rotate review assignments.
• Investment Balance — Groups Jira issues by type (Story, Bug, Task, Spike) to show where sprint effort was allocated.
• Developer Summaries — Per-member breakdown: commits, PRs, reviews given, deliverables, in-progress items, and carryover count.

Graceful Degradation

Prodbeam follows a partial data > no data principle at every layer:

Config directory

All data lives in ~/.prodbeam/ (override with PRODBEAM_HOME):

Security

• Local-only — all data stays on your machine. No telemetry, no Prodbeam cloud, no third-party services
• Three auth methods — OAuth (tokens refresh automatically), environment variables, or personal access tokens
• Read-only — all GitHub and Jira operations are read-only. Nothing is created, modified, or deleted
• Minimal storage — history database stores only aggregate numbers (counts, percentages, averages). Never commit messages, PR descriptions, or code
• Credential isolation — credentials.json is created with 600 permissions (owner read/write only)
• Network scope — api.github.com, your Jira instance, and OAuth endpoints (github.com/login, auth.atlassian.com) during authentication only

For details on token scopes, credential storage, and CI security checks, see SECURITY.md.

Known Limitations

• Code changes may show +0/-0 — line count metrics depend on GitHub API diff stats availability
• Weekly report title shows "Last 7 Days" for historical queries — the data is correct; the title doesn't reflect the weeksAgo offset
• Stale PR alerts are current-state — historical reports show today's stale PRs, not the state during that historical week
• Standup email must match team.json exactly — use prodbeam init or edit team.json to correct mismatches
• Sprint tools require Jira sprints — teams not using Jira Scrum boards will have limited sprint data

Documentation

Contributing

Bug reports and feature requests welcome via GitHub Issues.

Pull requests accepted — see CONTRIBUTING.md for development setup and guidelines.

License

MIT — See LICENSE.