Which integrations are available for this server?

Allows AI agents in Windsurf (Codeium IDE) to generate commit messages, PR descriptions, and release notes from git changes. Allows AI agents in VS Code via GitHub Copilot to generate commit messages, PR descriptions, and release notes from git changes.

How do I use pr-narrator-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pr-narrator-mcp generate a PR description from my recent changes" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

pr-narrator-mcp

by mhaviv

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

pr-narrator-mcp

npm version License: MIT

Generate consistent commit messages, PR content, and release notes automatically.

An MCP server that generates commit messages, PR content (titles, descriptions, and templates), and release notes from your git changes. If your repo doesn't already have a PR template, it auto-detects the domain (mobile, frontend, backend, devops, security, ML) and applies the right one — no config needed.

Install

npx pr-narrator-mcp

Related MCP server: MCP Git Commit Generator

Quick Start

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "pr-narrator": {
      "command": "npx",
      "args": ["-y", "pr-narrator-mcp"],
      "env": {
        "BASE_BRANCH": "develop",
        "TICKET_PATTERN": "[A-Z]+-\\d+"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pr-narrator": {
      "command": "npx",
      "args": ["-y", "pr-narrator-mcp"],
      "env": {
        "BASE_BRANCH": "develop",
        "TICKET_PATTERN": "[A-Z]+-\\d+"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "pr-narrator": {
      "command": "npx",
      "args": ["-y", "pr-narrator-mcp"],
      "env": {
        "BASE_BRANCH": "develop",
        "TICKET_PATTERN": "[A-Z]+-\\d+"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "pr-narrator": {
      "command": "npx",
      "args": ["-y", "pr-narrator-mcp"],
      "env": {
        "BASE_BRANCH": "develop",
        "TICKET_PATTERN": "[A-Z]+-\\d+"
      }
    }
  }
}

Other MCP Clients

Any MCP client that supports stdio transport can use this server. The command is:

npx -y pr-narrator-mcp

That's it! No config files needed. All env vars are optional.

Settings

All settings are optional env vars in MCP JSON:

Env Var	What it does	Example
`BASE_BRANCH`	Base branch for PRs	`develop`
`TICKET_PATTERN`	Ticket regex	`[A-Z]+-\\d+`
`TICKET_LINK`	Ticket URL template	`https://jira.example.com/browse/{ticket}`
`PREFIX_STYLE`	Prefix format	`capitalized` or `bracketed`
`DEFAULT_REPO_PATH`	Fallback repo path (single-repo workflows)	`/Users/me/my-project`
`PR_TEMPLATE_PRESET`	Force a PR template preset	`mobile`, `backend`, `devops`
`PR_DETECT_REPO_TEMPLATE`	Enable/disable repo template detection	`true` (default) or `false`

If BASE_BRANCH is not set, it auto-detects from the repo (main, master, develop).

Note on repoPath: All tools accept a repoPath parameter. The AI calling the tool should pass the user's current workspace directory. DEFAULT_REPO_PATH is only a fallback for single-repo workflows.

Tools

PR Generation

generate_pr

Generate a complete PR with title, description, and context for AI enhancement. Automatically resolves the best template for the repo (see PR Templates).

Returns:

title — PR title (placeholder derived from branch/commits — AI should rewrite)
description — PR description with sections from the resolved template
purposeContext — ALL commit titles, ALL commit bullets, test info, file count
purposeGuidelines — Instructions for AI to rewrite title and Purpose from ALL data

Important: Both the title and Purpose are placeholders. The AI must read ALL purposeContext.commitTitles and purposeContext.commitBullets to synthesize a title and description that reflects the full scope of changes.

Optional templatePreset parameter to force a specific template (e.g., mobile, backend).

generate_pr_title

Generate a PR title based on branch info and commits.

generate_pr_description

Generate a PR description with auto-populated sections. Same template resolution as generate_pr but returns only the description. Accepts optional templatePreset and summary parameters.

get_pr_template

Preview the resolved PR template for a repo before generating. Shows which sections will appear based on the repo's template file, domain auto-detection, or configured preset. Useful for understanding what a PR will look like before calling generate_pr.

Returns the template source (repo, preset, auto-detected, or default), detected domain, and each section's visibility based on current branch changes.

Commit Messages

generate_commit_message

Prepare commit message context from staged or unstaged changes.

If nothing is staged, the tool automatically falls back to unstaged working tree changes and provides staging instructions — no need to run git add first just to analyze your changes. The response includes a source field ("staged" or "unstaged") and a hint with the exact git add command to run.

When includeBody is true, the actual diff is provided so the AI can write a meaningful body that describes what changed functionally — not just file type counts.

Two modes:

With summary param (recommended): Returns a ready-to-use commit message with proper prefix/formatting. Add includeBody: true to get diff-based body generation.
Without summary: Returns placeholder title + diff + guidelines for AI to compose the message and body

validate_commit_message

Check a commit message against configured rules (length, format, capitalization, imperative mood).

Release Notes

generate_changelog

Generate a changelog / release notes from git commit history between two refs (tags, SHAs, or branches).

Auto-resolves refs — defaults from to the latest tag (or initial commit if no tags) and to to HEAD
Parses commits — detects conventional commit types/scopes, infers types from keywords for non-conventional messages, extracts co-authors and ticket references
Deduplicates squash-merge artifacts
Three output formats: keepachangelog (default), github-release, plain
Three grouping modes: type (default), scope, ticket
Includes stats — commit count, contributor count, ticket count, and a one-line summary

Returns changelog (formatted markdown), entries (structured data), summary, stats, range, and warnings.

Repository Analysis

analyze_git_changes

Analyze the current repository state: staged changes, branch info, working tree status, and file categorization.

extract_tickets

Find ticket numbers in the branch name and commit messages using the configured TICKET_PATTERN.

get_config

See current settings and their resolved values.

Prefix Examples

Branch	Commit/PR Prefix
`feature/PROJ-123-add-login`	`PROJ-123:`
`task/update-readme`	`Task:`
`bug/fix-crash`	`Bug:`
`main`	(no prefix)

PR Templates

PR Narrator automatically selects the best template for each repository through a resolution pipeline:

Repo template — if a PULL_REQUEST_TEMPLATE.md exists in the repo (.github/, root, or docs/), it's parsed into sections
Explicit preset — if PR_TEMPLATE_PRESET is set or templatePreset is passed to a tool
Auto-detected domain — the repo's file tree is scanned and scored to detect its domain
Default — a universal 6-section template

This means switching between repos (iOS app, Express API, Terraform infra) automatically uses the right template with zero configuration.

Domain Auto-Detection

PR Narrator scans the top 3 levels of the repo file tree and scores files against domain signal patterns. The domain with the highest score wins, as long as it reaches a minimum threshold.

Domain	Key Signals	Sections Added
mobile	`.swift`, `.kt`, `.xcodeproj`, `AndroidManifest.xml`	Screenshots, Device Testing, Accessibility
frontend	`.tsx`, `.vue`, `next.config`, `vite.config`	Screenshots / Visual Changes, Browser Compatibility, Accessibility
backend	`.go`, `.rs`, `migrations/`, `prisma/schema`	API Changes, Database / Migration, Breaking Changes
devops	`.tf`, `helm/`, `k8s/`, `Dockerfile`	Infrastructure Impact, Affected Environments, Rollback Plan
security	`.snyk`, `tfsec`, `trivy`	Security Impact, Threat Model Changes
ml	`.ipynb`, `model/`, `training/`, `dvc.yaml`	Model Changes, Dataset Changes, Metrics / Evaluation

Available Presets

Preset	Sections	Best For
`default`	6	General-purpose repos
`minimal`	2	Quick PRs (Purpose + Test Plan)
`detailed`	10	Thorough reviews with screenshots, breaking changes, deployment notes
`mobile`	8	iOS and Android apps
`frontend`	8	Web apps (React, Vue, Svelte, etc.)
`backend`	8	APIs and services
`devops`	8	Infrastructure and CI/CD
`security`	7	Security-focused changes
`ml`	8	Machine learning and data science

Conditional Sections

Sections can appear or hide based on context:

has_tickets — Ticket section only appears when tickets are found in the branch name or commits
file_pattern — Screenshots section only appears when UI files are changed; Database section only when migration files are changed
commit_count_gt — Changes (commit list) section only appears when there's more than 1 commit

Repo Template Detection

If your repo has a PULL_REQUEST_TEMPLATE.md, PR Narrator will find and parse it automatically. Supported locations:

.github/pull_request_template.md
.github/PULL_REQUEST_TEMPLATE/ (picks default.md first)
pull_request_template.md (repo root)
docs/pull_request_template.md

File names are matched case-insensitively. Both .md and .txt extensions are supported.

Set PR_DETECT_REPO_TEMPLATE=false to skip repo template detection and use presets or auto-detection instead.

Security

This MCP server is read-only and local-only (stdio transport). It never modifies your git repository, makes network requests, or handles authentication tokens.

Things to be aware of:

Diffs may contain secrets. Staged changes and branch diffs are sent to the AI for analysis. If your commits contain API keys or passwords, these will be visible to the model. Use git-secrets or gitleaks to prevent committing sensitive data.
Commit messages are untrusted input. Git commit messages from collaborators are passed to the AI. Adversarial commit messages could theoretically attempt prompt injection. The read-only nature of this MCP limits impact.
Regex patterns are validated. The TICKET_PATTERN env var is checked for ReDoS safety (catastrophic backtracking, length limits) before use.

For full details, see SECURITY.md.

Development

git clone https://github.com/mhaviv/pr-narrator-mcp.git
cd pr-narrator-mcp
npm install
npm run build
npm test

License

MIT

Available Tools

10 tools

analyze_git_changesA

Read-onlyIdempotent

Analyze the current git repository state and changes. Provides context for generating commit messages and PR content.

Returns:

Repository info (branch, base branch)
Ticket extracted from branch name
Branch prefix (task/, bug/, feature/, etc.)
Staged changes with file list and suggested commit type/scope
Branch changes since base branch with commit history
Working tree status (unstaged modified, untracked, and deleted files)
All tickets found in branch name and commits

Use this before generating commits or PRs to understand the changes.

ParametersJSON Schema

Name	Required	Description	Default
`repoPath`	No	Path to the git repository. IMPORTANT: Always pass the user's current project/workspace directory.
`includeFullDiff`	No	Include the full diff content (can be large)

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds substantial value by detailing the extensive return information (repo info, tickets, staged changes, branch changes, working tree status), going well beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections and bullet points for return values. It is slightly verbose but front-loaded with the purpose sentence, making it easy to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description thoroughly enumerates what the tool returns: repository info, tickets, branch prefix, staged changes, branch changes, working tree status, and all tickets. This is complete for an agent to understand the tool's output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% coverage with clear descriptions for both parameters (repoPath and includeFullDiff). The description does not add additional meaning beyond the schema, but the schema is already sufficient, resulting in a baseline score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool analyzes git repository state and changes, listing specific return types. It distinguishes itself from sibling tools like extract_tickets and generate_commit_message by positioning itself as a prerequisite for commit/PR generation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'Use this before generating commits or PRs to understand the changes,' providing clear when-to-use guidance. It doesn't explicitly mention when not to use, but context from siblings implies alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

extract_ticketsA

Read-onlyIdempotent

Extract ticket numbers from the current branch, commits, and optional additional text.

Uses TICKET_PATTERN env var to find tickets in:

Branch name (e.g., "feature/PROJ-1234-add-login")
Commit messages since base branch
Additional text provided

ParametersJSON Schema

Name	Required	Description
`repoPath`	No	Path to the git repository. IMPORTANT: Always pass the user's current project/workspace directory.
`includeCommits`	No	Whether to search commit messages for tickets
`additionalText`	No	Additional text to search for tickets (e.g., PR title)

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds valuable context: it uses TICKET_PATTERN env var, searches branch, commits, and text in a specific order. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four concise sentences, front-loaded with the main action, no fluff. Every sentence adds information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Explains what the tool does and how it works, but lacks output details (e.g., return format, behavior when no tickets found). Since no output schema exists, description should cover return values more completely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers all parameters with descriptions (100% coverage). The description enhances understanding by mentioning TICKET_PATTERN env var and search order, adding value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Extract ticket numbers from the current branch, commits, and optional additional text.' It specifies the verb and resource, and distinguishes from sibling tools like analyze_git_changes or generate_commit_message.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs siblings or when not to use it. The description only explains what it does, not when it's appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_changelogA

Read-onlyIdempotent

Generate release notes / changelog from git commit history between two refs.

Analyzes commits between two refs (tags, SHAs, or branches) and produces a formatted changelog. Supports three output formats: Keep a Changelog (keepachangelog), GitHub Release (github-release), and plain text.

Auto-detects:

Latest tag as the start ref if not provided
Conventional commit types and scopes
Non-conventional commit types via keyword inference
Co-authors from commit trailers
Ticket references from commit messages

Use this when a user wants to generate release notes, changelogs, or understand what changed between two versions.

ParametersJSON Schema

Name	Required	Description	Default
`repoPath`	No	Path to the git repository. IMPORTANT: Always pass the user's current project/workspace directory.
`from`	No	Start ref — tag, SHA, or branch. Defaults to the latest tag. If no tags exist, uses the initial commit.
`to`	No	End ref. Defaults to HEAD.
`groupBy`	No	How to group changelog entries.	type
`includeAuthors`	No	Include contributor attribution.
`format`	No	Output format.	keepachangelog

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds valuable behavioral information beyond annotations, such as auto-detection of latest tag, conventional commit types, co-authors, and ticket references. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear first sentence stating purpose, followed by formats, auto-detection details, and usage. It is informative but slightly verbose; some sentences could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, no output schema), the description covers inputs, output formats, auto-detection features, and appropriate usage context. It is reasonably complete for an AI agent to understand when and how to use the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The description adds little beyond summarizing the output formats and auto-detection behavior, which does not significantly enhance parameter understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates release notes/changelogs from git commit history between two refs. It specifies the verb (generate), resource (changelog from git history), and scope (between two refs). This distinguishes it from siblings like generate_commit_message or generate_pr.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes 'Use this when a user wants to generate release notes, changelogs, or understand what changed between two versions.' It provides clear context, though it does not explicitly state when not to use it or differentiate from siblings like analyze_git_changes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_commit_messageA

Read-onlyIdempotent

Prepare commit message context from staged changes. Falls back to unstaged working tree changes when nothing is staged, so you can analyze changes before running 'git add'. Check 'source' in the response to see whether staged or unstaged changes were used, and 'hint' for staging instructions.

TWO MODES:

WITH summary parameter (recommended): Returns a ready-to-use commit message. Pass a brief description of what the changes do, and the tool formats it with the proper prefix, capitalization, and validation. Check context.availableSummaryLength to see how many characters your summary can use (prefix uses the rest). When includeBody is true, the diff and changeSummary are provided so YOU can write a meaningful body — the tool does NOT auto-generate the body.
WITHOUT summary: Returns context for YOU to compose the message.
- 'title' is a best-effort PLACEHOLDER based on file patterns
- 'changes.diff' contains the actual diff
- 'changeSummary' groups ALL files by category (Swift source, config, etc.)
- 'commitGuidelines' explains how to write the message
- YOU must analyze the diff and compose a meaningful title and body

For best results: First analyze the staged changes yourself, then call this tool WITH the summary parameter to get a properly formatted commit message.

Prefix behavior:

No prefix on main/master/develop branches
If ticket found: "PROJ-123: message"
If branch type: "Task: message", "Bug: message"

Examples:

"Task: Fix suffix removal for usernames containing -by- substring"
"Bug: Fix HolaSpark loading race condition with ReachabilityState enum"
"WTHRAPP-3104: Update winter weather icons and illustration mappings"

ParametersJSON Schema

Name	Required	Description
`repoPath`	No	Path to the git repository. IMPORTANT: Always pass the user's current project/workspace directory.
`summary`	No	Summary of changes - RECOMMENDED for best results. Tool formats it with proper prefix.
`type`	No	Optional commit type override (feat, fix, etc.)
`scope`	No	Optional scope override
`includeBody`	No	Whether to include a commit body

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds significant behavioral context beyond annotations: fallback to unstaged, prefix rules based on branch, response fields (source, hint), and that the body is not auto-generated. Annotations already indicate read-only and idempotent, which description complements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections, examples, and bullet points. Some redundancy (e.g., repeating 'best results' advice) but overall efficient for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all aspects: modes, fallback, prefix, response meaning, and examples. No output schema, but description sufficiently explains return values. Handles edge cases like unstaged changes and branch-based prefixes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds value by explaining the summary length constraint and that includeBody provides diff for manual body writing. Examples clarify parameter usage further.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it prepares commit message context from staged changes with two modes. It distinguishes itself from sibling tools like analyze_git_changes by focusing on commit message generation but does not explicitly name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use for each mode, recommends using the summary parameter, and explains fallback behavior. Gives best practices and examples, leaving little ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_prA

Read-onlyIdempotent

Generate a PR title and description.

IMPORTANT: The returned 'description' has a PLACEHOLDER Purpose. You MUST rewrite it using purposeContext.commitTitles, purposeContext.commitBullets, and purposeGuidelines BEFORE showing to the user.

You MUST also rewrite the title to reflect ALL changes, not just the branch name. Read ALL commitTitles and commitBullets to understand the full scope before writing.

FORMAT:

1-2 changes: prose sentence(s)
3+ changes: intro sentence + bullet points

Example (3+ changes): "Enables automatic Slack notifications to PR authors when builds fail.

Extracts PR author from GitHub PR metadata
Maps GitHub usernames to Slack user IDs for @mentions
Posts threaded failure notifications
Includes unit tests for notification functionality"

Show ONLY the final title + rewritten description. Never mention "MCP provided" or show raw purposeContext.

ParametersJSON Schema

Name	Required	Description
`repoPath`	No	Path to the git repository. IMPORTANT: Always pass the user's current project/workspace directory.
`baseBranch`	No	Base branch to compare against. Auto-detects if not specified.
`titleSummary`	No	Summary for the PR title (extracted from branch if not provided)
`summary`	No	Summary text for the PR description
`testPlan`	No	Test plan text
`additionalSections`	No	Additional section content keyed by section name
`templatePreset`	No	Force a specific template preset (default, minimal, detailed, mobile, frontend, backend, devops, security, ml).

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, non-destructive, idempotent. Description adds crucial context that the returned description contains a placeholder that must be rewritten, and specifies format rules. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is lengthy with multiple sections and examples, but is well-structured with bullet points and formatting rules. Some redundancy exists; could be more concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description thoroughly explains the output format with rules and examples. It covers how to handle the placeholder and formatting, making it fairly complete for a generation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters with descriptions. The description does not add significant meaning beyond what is already in the schema, achieving baseline adequacy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Generate a PR title and description' which is a specific verb+resource. It distinguishes from sibling tools like generate_pr_title and generate_pr_description which focus on individual parts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit instructions on how to use the output (rewrite placeholder before showing), but does not contrast with siblings or state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_pr_descriptionA

Read-onlyIdempotent

Generate a PR description with sections.

Auto-populates:

"purpose": Summary from commits, files, and branch name
"commits": Lists all commits since base branch
"extracted": Lists all tickets found

ParametersJSON Schema

Name	Required	Description
`repoPath`	No	Path to the git repository. IMPORTANT: Always pass the user's current project/workspace directory.
`summary`	No	Summary text for the PR
`testPlan`	No	Test plan text
`additionalSections`	No	Additional section content keyed by section name
`templatePreset`	No	Force a specific template preset (default, minimal, detailed, mobile, frontend, backend, devops, security, ml).

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare the tool as read-only and idempotent. The description adds valuable behavioral details about auto-populating sections from commits, files, and branch names, which goes beyond the annotations. No contradiction is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, with a clear main sentence followed by bullet points for auto-populated fields. Every sentence adds value, and the structure is front-loaded with the primary purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 5 parameters, no output schema, and available annotations, the description adequately explains the generated output and auto-population behavior. It lacks details on how the 'templatePreset' parameter affects the output, but the schema covers that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description provides additional context about auto-populated sections but does not significantly enhance understanding of parameter semantics beyond what is in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Generate a PR description with sections' and lists auto-populated sections, making the action and output clear. However, it does not explicitly distinguish itself from sibling tools like 'generate_pr_title' or 'generate_commit_message', though the context implies a broader scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as 'generate_pr_title' or 'generate_changelog'. The description lacks explicit when-to-use, when-not-to-use, or comparison with siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_pr_titleA

Read-onlyIdempotent

Generate a PR title based on branch info.

Prefix behavior:

If ticket found in branch name, uses ticket as prefix
If no ticket but branch has prefix (task/, bug/, etc.), uses that

If no summary is provided, extracts one from the branch name.

ParametersJSON Schema

Name	Required	Description	Default
`repoPath`	No	Path to the git repository. IMPORTANT: Always pass the user's current project/workspace directory.
`summary`	No	Summary for the PR title (if not provided, will extract from branch)

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations (readOnlyHint, idempotentHint) indicate no side effects. Description adds detail on prefix logic and summary extraction, which is consistent. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise three-sentence description, front-loaded with purpose. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains input handling (prefix, summary) adequately. Could mention default title format or output structure for completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

100% schema coverage so baseline is 3. Description mentions branch name extraction but does not add significant meaning beyond the schema's property descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it generates a PR title based on branch info, with specific prefix behaviors and summary extraction. This distinguishes it from siblings like extract_tickets, generate_commit_message, and generate_pr_description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives (e.g., analyze_git_changes, generate_changelog). Usage is implied but not stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_configA

Read-onlyIdempotent

Get the current pr-narrator configuration. Returns settings from MCP env vars or defaults.

Set in MCP JSON:

BASE_BRANCH: Base branch for PRs (e.g., "develop")
TICKET_PATTERN: Ticket regex (e.g., "[A-Z]+-\d+")
TICKET_LINK: Ticket URL template
PREFIX_STYLE: "capitalized" or "bracketed"
DEFAULT_REPO_PATH: Fallback repo path for single-repo workflows

ParametersJSON Schema

Name	Required	Description	Default
`repoPath`	No	Path to the git repository. IMPORTANT: Always pass the user's current project/workspace directory.

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnly and idempotent behavior. The description adds value by detailing the specific environment variables returned, such as BASE_BRANCH and TICKET_PATTERN, providing concrete context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: a one-sentence summary, a line about return values, and a bullet list of settings. No redundant information, well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description fully covers the tool's purpose, the settings it returns, and lacks an output schema, but the list of settings provides sufficient context for selecting and invoking the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a well-described 'repoPath' parameter in the schema. The description does not add extra parameter semantics, but this is acceptable given the schema's sufficiency.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get the current pr-narrator configuration' and specifies it returns settings from MCP env vars or defaults. This differentiates it from sibling tools which focus on analysis, ticket extraction, and generation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for retrieving configuration but does not explicitly state when to use or when not to use this tool versus alternatives. However, sibling tools have clearly distinct purposes, reducing confusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pr_templateA

Read-onlyIdempotent

Returns the resolved PR template for a repository, showing which sections will appear based on repo template detection, domain auto-detection, or explicit preset. Useful for previewing the template structure before generating a PR.

ParametersJSON Schema

Name	Required	Description	Default
`repoPath`	No	Path to the git repository. IMPORTANT: Always pass the user's current project/workspace directory.
`preset`	No	Force a specific preset (default, minimal, detailed, mobile, frontend, backend, devops, security, ml).

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds context about template resolution logic (repo detection, domain auto-detection, preset) but does not disclose additional behavioral traits beyond what annotations cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences: the first explains the core function, the second states when to use it. No extraneous information, well front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately covers the return value (resolved template with sections). The tool has low complexity with two optional parameters, and the description is sufficient for understanding its use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed parameter descriptions. The description adds value by explaining how the template is resolved (based on detection or explicit preset), which gives semantic context beyond the schema's parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns the resolved PR template for a repository, showing which sections will appear. It distinguishes from sibling tools like generate_pr, which generate the PR, by focusing on previewing the template structure.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Useful for previewing the template structure before generating a PR', providing clear when-to-use guidance. However, it does not explicitly mention when not to use or name alternatives, though the sibling tools context implies other options.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_commit_messageA

Read-onlyIdempotent

Validate a commit message against configured rules.

Checks:

Title length (max characters)
Conventional commit format (if configured)
Required scope (if configured)
Imperative mood (e.g., "Add" not "Added")
Title capitalization
No trailing period

ParametersJSON Schema

Name	Required	Description	Default
`repoPath`	No	Path to the git repository. IMPORTANT: Always pass the user's current project/workspace directory.
`message`	Yes	The commit message to validate

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate read-only, non-destructive, idempotent behavior. The description adds value by detailing the specific validation checks performed, such as title length, conventional commit format, and imperative mood.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with a clear first sentence and a bulleted list of checks. Every sentence adds value without unnecessary verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's checks well but does not mention return values or behavior when validation fails. Since there is no output schema, this omission slightly reduces completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters (repoPath, message). The tool description does not add additional parameter information beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Validate a commit message against configured rules' and lists specific checks (title length, conventional commit format, etc.), which distinguishes it from sibling tools like generate_commit_message.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for validating commit messages but does not explicitly state when not to use or provide alternative tools. However, sibling tools like generate_commit_message clarify the differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

10 tool updatesv0.3.1May 28, 2026
- First observedanalyze_git_changes
- First observedextract_tickets
- First observedgenerate_changelog
- First observedgenerate_commit_message
- First observedgenerate_pr
- First observedgenerate_pr_description
- First observedgenerate_pr_title
- First observedget_config
- First observedget_pr_template
- First observedvalidate_commit_message

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-05-28 02:50 across 10 tools

Disambiguation4/5

Most tools have clear distinct purposes, but there is overlap between generate_pr, generate_pr_title, and generate_pr_description, which could confuse an agent about which to use.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with underscore_case, using verbs like analyze_, extract_, generate_, get_, and validate_.

Tool Count5/5

10 tools is well-scoped for a PR narration server, covering analysis, generation, validation, and configuration without excess.

Completeness4/5

The tool set covers the core workflow of analyzing changes and generating commits and PRs, but lacks tools for editing generated content or directly creating PRs on remote (though that may be out of scope). Minor redundancy in PR generation tools.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

ShipstarOAuth
ai.shipstar
Generate changelogs, release emails, help-center articles, banners, and social posts from commits.
Developer Tools CI/CD & DevOps Marketing
1
Gluecron B
com.gluecron
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
Version Control CI/CD & DevOps Code Analysis
622
Moltline Code Review A
com.moltlinestudio
Risk-scan a diff, flag AI-generated-code tells, find secrets. 5 of 7 tools need no account.
Code Analysis Developer Tools Testing & QA Tools
71
GitHubOAuth
io.github.github
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Version Control Developer Tools CI/CD & DevOps
1232,954

Related MCP Servers

Git Auto Commit MCP Server
Version Control Developer Tools Autonomous Agents
hypermodel-labs
A
license
Not graded
quality
F
maintenance
Analyzes git changes in repositories and generates conventional commit messages using OpenAI's GPT models, supporting both staged and unstaged changes with detailed summaries.
Updated a year ago (2025-03-17 17:46 UTC)
5 npm
15
MIT
MCP Git Commit Generator
Version Control Developer Tools
theoklitosBam7
A
license
A
quality
C
maintenance
Automatically generates conventional commit messages from staged git changes and checks repository status. Analyzes git diffs to create properly formatted commit messages following conventional commit standards.
Updated 8 months ago (2026-01-17 17:58 UTC)
2
8
MIT
MCP Git Commit Generator
Version Control Developer Tools
LuiccianDev
A
license
A
quality
D
maintenance
Analyzes Git repository changes and generates conventional, context-aware commit messages using the Model Context Protocol.
Updated 6 months ago (2026-03-22 20:09 UTC)
15
MIT
Git Commit MCP Server
Version Control Developer Tools
surajfale
A
license
A
quality
D
maintenance
Enables AI assistants to create conventional Git commits, update changelogs, and optionally push changes to remote repositories.
Updated 10 months ago (2025-11-23 22:03 UTC)
2
2
MIT