PR-Description MCP Skill

An MCP server that generates structured PR descriptions from Jira tickets and git diffs.

Prerequisites

• Node.js ≥ 18 — nodejs.org
• Git
• GitHub CLI (gh) — cli.github.com (required for publish_pr)
• AI Tool — at least one of: Augment, Cursor, Claude Desktop, VS Code (Copilot), or Windsurf

Quick Install

curl -fsSL https://raw.githubusercontent.com/edmoura/pr-description-skill/main/scripts/install.sh | bash

This will clone the repo, install dependencies, build, run the setup wizard, and auto-register the MCP server with every detected AI tool — all idempotently.

Supported AI tools (auto-detected)

Tool	Config location	Merge behavior
Augment	~/.augment/mcp/pr-description.json + ~/.augment/skills/	Standalone file (overwritten)
Cursor	~/.cursor/mcp.json	Merged into mcpServers
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json	Merged into mcpServers
VS Code	~/Library/Application Support/Code/User/mcp.json	Merged into servers
Windsurf	~/.codeium/windsurf/mcp_config.json	Merged into mcpServers

The installer checks whether each tool is installed (config dir exists or command is on PATH). Detected tools get the config entry; others are skipped. Existing servers in the same config file are preserved — only the pr-description entry is added or updated.

Manual Install

git clone https://github.com/edmoura/pr-description-skill.git ~/.pr-description-skill
cd ~/.pr-description-skill
npm install          # installs deps + builds (via postinstall)
npm run setup        # interactive credential wizard

Then run the installer to register MCP with all detected tools:

bash scripts/install.sh

Or register manually with Augment by creating ~/.augment/mcp/pr-description.json:

{
  "name": "pr-description",
  "command": "node",
  "args": ["<path-to-repo>/dist/src/index.js"],
  "env": {}
}

And copy the skill prompt:

mkdir -p ~/.augment/skills/pr-description
cp .augment/skills/pr-description/SKILL.md ~/.augment/skills/pr-description/SKILL.md

Configuration

All configuration is stored in a global ~/.pr-description-skill/.env (owner-read-only), so credentials configured once apply in every project you open. Run npm run setup from anywhere to reconfigure at any time. A project-local ./.env (if present) is layered on top and can override the global values for that repo.

Variable	Required	Description
JIRA_BASE_URL	Yes	Jira instance URL (e.g. https://yourcompany.atlassian.net)
JIRA_EMAIL	Yes	Your Atlassian login email
JIRA_API_TOKEN	Yes	API token from Atlassian
JIRA_AC_FIELD_ID	No	Custom field ID for Acceptance Criteria (default: customfield_10222)
JIRA_INTEGRATION_DISABLED	No	Set to true to skip Jira (paste ACs manually)

See .env.example for a documented template.

Usage

In your IDE or Auggie CLI, type /pr-description on any feature branch. The skill will:

1. Security scan — check the diff for accidentally committed secrets
2. Ask for Jira ticket — fetch title, description, and acceptance criteria
3. Ask clarifying questions — breaking changes, dates, feature flags, etc.
4. Generate the PR description — structured Markdown following the team template
5. Publish — create or update the PR via gh (with your approval)

Updating / Self-Update

Re-run the installer — it detects the existing clone and does a git pull + rebuild:

bash ~/.pr-description-skill/scripts/install.sh

Or with the explicit --update flag:

bash ~/.pr-description-skill/scripts/install.sh --update

Troubleshooting

General

Issue	Fix
fetch_jira_ticket returns 401	Verify JIRA_EMAIL and JIRA_API_TOKEN in ~/.pr-description-skill/.env, or re-run npm run setup
Acceptance Criteria always empty	Your Jira instance may use a different custom field. Find the ID (see below) and set JIRA_AC_FIELD_ID via npm run setup
publish_pr fails	Ensure gh is installed and authenticated (gh auth login)
MCP server not found	Check ~/.augment/mcp/pr-description.json points to the correct dist/src/index.js path
postinstall loop	Run npm install --ignore-scripts then npm run build separately
Permission denied writing .env	Run chmod u+w ~/.pr-description-skill/.env and retry

MCP Host-Specific Issues

Host	Symptom	Fix
Augment	"Tool not found" after install	Restart Augment or reload the window. Verify ~/.augment/mcp/pr-description.json exists.
Cursor	Server fails to connect	Check ~/.cursor/mcp.json has a valid mcpServers.pr-description entry. Restart Cursor.
VS Code	Tools not appearing	VS Code uses servers (not mcpServers). Check ~/Library/Application Support/Code/User/mcp.json. Reload window (Cmd+Shift+P → "Reload Window").
Claude Desktop	Server not listed	Fully quit and relaunch Claude Desktop. Check ~/Library/Application Support/Claude/claude_desktop_config.json.
Windsurf	Connection timeout	Verify ~/.codeium/windsurf/mcp_config.json has the correct node path. Restart Windsurf.
All hosts	Server crashes on startup	Check the debug log: cat ~/.pr-description-skill/debug.log. Ensure Node.js ≥ 18 is on PATH.
All hosts	"ENOENT" or "spawn node" errors	The node binary might not be on the host's PATH. Use the full path in the config: replace "command": "node" with "command": "/usr/local/bin/node" (or wherever which node points).

Debug Log

All tool invocations are logged to ~/.pr-description-skill/debug.log. Share this file with the support team when reporting issues. The log auto-rotates at 5 MB.

Finding your Acceptance Criteria field ID

Acceptance Criteria is a Jira custom field, and its ID varies per instance. To find yours, open a ticket that has AC filled in and query the API:

curl -s -u "you@example.com:$JIRA_API_TOKEN" \
  "$JIRA_BASE_URL/rest/api/3/issue/PROJ-123?expand=names" \
  | node -e 'const d=JSON.parse(require("fs").readFileSync(0));for(const[k,v]of Object.entries(d.names)){if(/accept|criteria|expected result/i.test(v))console.log(k,"=>",v)}'

Set the resulting customfield_XXXXX via npm run setup. If none is configured, the tool tries a fallback chain (Acceptance Criteria → Expected Results → Definition of Done); see src/config.ts.

Notes on formatting

• Jira descriptions and AC are stored in ADF (Atlassian Document Format) and converted to plain text/Markdown. Rich elements (tables, links, inline emphasis) may be simplified or dropped.
• get_sanitized_diff performs best-effort secret redaction (AWS/GitHub/ Slack/Stripe tokens, private keys, password=/token= assignments) before returning the diff. This is defense-in-depth — always review diffs manually before publishing.