# Developer Productivity MCP

A FastMCP server that exposes GitHub, Jira and engineering-metrics capabilities
as MCP tools, plus an OpenAI Agents SDK client that drives them as multi-step
workflows.

```text
                         ┌──────────────────┐
                         │      User        │
                         └────────┬─────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │ OpenAI Agent     │
                         │ Agents SDK       │
                         └────────┬─────────┘
                                  │
                            MCP Protocol
                                  │
                                  ▼
                    ┌─────────────────────────┐
                    │ FastMCP Server          │
                    │                         │
                    │ search_github_code      │
                    │ get_jira_sprint_status  │
                    │ analyze_pull_request    │
                    │ query_project_metrics   │
                    └──────┬──────┬──────┬────┘
                           │      │      │
                     GitHub API  Jira   PostgreSQL
```

The model never talks to GitHub, Jira or PostgreSQL directly. The MCP server
owns the credentials, pagination, error handling and response shaping, and
returns **facts**; the agent contributes **reasoning and explanation**. Prose is
therefore not a tool — an explanation tool would push judgement into the
server, where it cannot see the other tools' results.

## The four tools

| Tool | Backend | What it does beyond wrapping the API |
|---|---|---|
| `search_github_code` | GitHub REST | Normalizes search hits to `{repository, path, name, url}` |
| `get_jira_sprint_status` | Jira Agile | Completion %, story-point progress, blocked / high-priority / overdue / unassigned / at-risk tickets, sprint risk level |
| `analyze_pull_request` | GitHub REST | Static analysis of the diff: security, database, API-contract, dependency and test detection; deleted-code analysis; scored risk level; breaking-change and review recommendations |
| `query_project_metrics` | PostgreSQL | Six metrics behind an allow-list — the model picks a metric name, never SQL |

## Layout

```text
.
├── main.py                     # agent-side CLI entry point
├── .env.example
├── agent/
│   ├── developer_agent.py      # agent definitions + instructions
│   └── workflows.py            # multi-step agentic workflows
├── src/
│   ├── config.py               # MCP server environment
│   ├── pr_analysis.py          # PR static-analysis helpers
│   └── server.py               # FastMCP server + the four tools
└── sql/
    └── schema.sql              # tables backing query_project_metrics
```

## Setup

```bash
uv sync
cp .env.example .env      # then fill in your credentials
psql "$DATABASE_URL" -f sql/schema.sql
```

## Run

Terminal 1 — the MCP server (Streamable HTTP on `http://localhost:8000/mcp`):

```bash
uv run python -m src.server
```

Terminal 2 — an agent workflow:

```bash
# GitHub code search
uv run python main.py search --repository my-org/payments-api --query retry

# pull-request risk analysis
uv run python main.py pr --repository my-org/payments-api --number 142

# the full multi-tool sprint investigation
uv run python main.py sprint --project PAY --sprint 42
```

`MCP_TRANSPORT=stdio` runs the server over stdio instead, for clients that
launch it as a subprocess.

## The agentic workflow

`main.py sprint` asks one natural-language question, and the agent decides which
tools to call and in what order:

```text
1. get_jira_sprint_status()
             ↓
2. Agent selects the tickets worth investigating
             ↓
3. search_github_code()
             ↓
4. analyze_pull_request()
             ↓
5. query_project_metrics()
             ↓
6. Agent generates explanation
```

Step 2 needs no tool call. `get_jira_sprint_status` already has every issue in
hand, so blocked/high-priority/overdue classification happens there, and the
agent reasons over the returned `blocked_tickets` and `high_priority_tickets` to
choose what to look at next. Splitting that into a second round trip would cost
a request and add nothing.

## Design notes

- `analyze_pull_request` scores risk from filenames, diff patches and pattern
  matches, not from an LLM reading the code. It is cheap, deterministic and
  reproducible; an LLM review stage over the highest-risk patches is the
  planned extension.
- Jira story-point custom field IDs and board IDs differ per installation, so
  `JIRA_BOARD_ID` and `JIRA_STORY_POINTS_FIELD` are configuration rather than
  constants.
- `query_project_metrics` reads the tables in `sql/schema.sql`, which expect an
  ingestion job loading GitHub/Jira/CD history.