Skip to main content
Glama
DevNarrate
by kmandana

DevNarrate

PyPI Package Status

MCP server for developer workflow automation — smart commits, secret scanning, PR descriptions, and more.

Features

  • Change Review: Understand AI-generated code changes before committing — narrative summaries, goal alignment, and attention guides instead of raw diffs

  • Smart Commit Messages: Generate conventional commit messages from staged changes with full user control

  • Secret Scanning: Detect leaked API keys, tokens, passwords, and private keys in staged diffs before they reach your repo — powered by detect-secrets with 25+ built-in detectors

  • PR Descriptions: Create detailed pull request descriptions with customizable templates

  • Multi-Platform: Supports GitHub and GitLab

  • Token-Aware: Handles large diffs with automatic pagination

  • Template System: Use custom PR templates or built-in defaults

  • Safety First: Only works with staged changes to prevent accidental commits

Related MCP server: pr-mcp-server

Installation (Source / Development)

1. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone and set up

git clone https://github.com/krishnamandanapu/DevNarrate.git
cd DevNarrate
uv sync

3. Register the MCP server

The server must be launched with the Python interpreter from your uv-managed virtual environment (typically /path/to/DevNarrate/.venv/bin/python on macOS/Linux or .venv\\Scripts\\python.exe on Windows).

# capture the interpreter path once
VENV_PY=$(pwd)/.venv/bin/python

# Claude Code (global scope)
claude mcp add --scope user DevNarrate -- "$VENV_PY" -m devnarrate.server

# Claude Code (project scope)
claude mcp add DevNarrate -- "$VENV_PY" -m devnarrate.server

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "DevNarrate": {
      "command": "/path/to/DevNarrate/.venv/bin/python",
      "args": ["-m", "devnarrate.server"]
    }
  }
}

For pip-based installation steps, head to https://pypi.org/project/devnarrate/.

Usage

Commit Messages

DevNarrate only works with staged changes to keep you in control.

git add <file1> <file2>
# or stage everything tracked:
git add -u

Then ask Claude:

Generate a commit message for my changes

Claude inspects the staged diff, proposes a conventional commit message, and asks for approval before running git commit.

Change Review

After an AI assistant makes changes to your code, ask it to review them before committing:

Review the changes you just made

DevNarrate analyzes the working tree diff and presents a layered summary:

  • Narrative overview — what changed, how many files, lines added/removed

  • Goal grouping — which changes map to the stated goal, which were inferred from comments/docstrings, and which are unrecognized (possibly from another session)

  • Attention guide — what needs human review vs what's routine

This replaces reading raw diffs with a structured, goal-oriented breakdown.

Secret Scanning

Secret scanning runs automatically as part of get_commit_context. When you stage changes and ask for a commit message, DevNarrate scans the diff for:

  • API keys (AWS, Google, Stripe, GitHub, Slack, etc.)

  • Passwords & tokens in config files

  • Private keys (RSA, SSH, PGP)

  • High-entropy strings that look like secrets

If secrets are found, Claude warns you before committing. To suppress false positives, add an inline comment:

SAFE_VALUE = "not-a-real-secret"  # pragma: allowlist secret

PR Descriptions

  1. Ask Claude: "Create a PR to main from my current branch"

  2. Claude analyzes the diff and offers template options (custom templates live in .devnarrate/pr-templates/)

  3. Review the generated description and approve to let Claude create the PR via gh or glab

Configuration (Optional)

DevNarrate ships a fully commented config file at .devnarrate/config.toml. Copy it into your repo root and edit the values you care about — every setting documents its purpose and default inline.

All settings are optional — delete or comment out any line to use the default.

PR Templates (Optional)

mkdir -p .devnarrate/pr-templates

Example (.devnarrate/pr-templates/feature.md):

## Summary
[What does this PR do?]

## Changes
-
-

## Testing
[How to test]

## Related Issues
[Links]

If no template is found, DevNarrate falls back to its default format.

Platform Support

  • Commits: Works anywhere git runs

  • PRs: Requires platform CLIs

    • GitHub: Install gh and run gh auth login

    • GitLab: Install glab and run glab auth login

Development

  • Format/lint through uv-managed tooling

  • Build artifacts with uv run pyproject-build

  • Use bump-my-version (see RELEASING.md) for tagged releases

License

MIT

Available Tools

5 tools
commit_changesA

Execute git commit with a user-approved commit message.

CRITICAL WORKFLOW - YOU MUST FOLLOW THESE STEPS IN ORDER:

  1. Call get_commit_context to get the diff

  2. Generate a commit message based on the actual diff

  3. SHOW the generated commit message to the user in your response

  4. ASK the user: "Should I proceed with this commit?" and WAIT for their response

  5. ONLY call this tool AFTER the user explicitly approves (says "yes", "proceed", "commit it", etc.)

  6. Set user_approved=True when calling this tool

DO NOT call this tool in the same response where you generate the commit message. The user MUST see the message and approve it first.

Args: message: User-approved commit message (should follow 50/72 rule) user_approved: REQUIRED - Must be True. Confirms user has seen and approved the commit message. repo_path: Path to git repository (optional, defaults to Claude's working directory)

Returns: Success message with commit hash or error

Inputs: message (required), user_approved (required), repo_path. Returns: result

create_prA

Create a pull request on the detected platform (GitHub/GitLab).

CRITICAL WORKFLOW - YOU MUST FOLLOW THESE STEPS IN ORDER:

  1. Call get_pr_context to analyze the changes

  2. Generate PR title and description based on the diff

  3. SHOW the generated PR title and body to the user in your response

  4. ASK the user: "Should I create this PR?" and WAIT for their response

  5. ONLY call this tool AFTER the user explicitly approves (says "yes", "proceed", "create it", etc.)

  6. Set user_approved=True when calling this tool

DO NOT call this tool in the same response where you generate the PR description. The user MUST see the content and approve it first.

Args: title: PR title (keep it concise, ~50 chars) body: PR description (formatted markdown) base_branch: Base branch (e.g., "main", "dev") user_approved: REQUIRED - Must be True. Confirms user has seen and approved the PR content. head_branch: Head branch (defaults to current branch) draft: Create as draft PR (default: False) repo_path: Path to git repository (optional, defaults to Claude's working directory)

Returns: Success message with PR URL or error message

Inputs: body (required), title (required), base_branch (required), user_approved (required), +3 more. Returns: result

get_commit_contextA

REQUIRED FIRST STEP: Get git diff and file changes to analyze before writing a commit message.

IMPORTANT: You MUST call this tool FIRST before generating any commit message. Never write a commit message without first seeing the actual git diff from this tool.

This tool ONLY shows STAGED changes. We intentionally do not support unstaged changes to ensure users have explicit control over what gets committed and prevent accidental commits.

CRITICAL: If the diff is empty and there are no files:

  1. STOP immediately - do NOT proceed with generating a commit message

  2. Tell the user: "No staged changes found. Please stage the files you want to commit first using: git add "

  3. DO NOT attempt to stage files automatically

  4. Wait for the user to stage their changes

Returns file changes and diff output with TOKEN-BASED pagination (MCP limit: 25k tokens). Large diffs are automatically paginated to stay under the token limit.

ANALYZING THE RESPONSE - follow these steps in order:

  1. SECRET SCAN (automated): Check secret_scan.status FIRST.

    • If "warnings_found": STOP and warn the user about each finding. Show the file, line number, type, and redacted preview for each finding. Recommend removing the secret before committing. Do NOT proceed to generate a commit message until the user acknowledges or explicitly chooses to proceed despite the warnings.

    • If "clean": proceed to step 2.

  2. SECRET SCAN (your review): Even if the automated scan is clean, briefly review the diff yourself for anything the regex-based scanner might miss:

    • Hardcoded credentials or secrets in unusual formats

    • Internal URLs, IP addresses, or hostnames that shouldn't be committed

    • Sensitive configuration values (database hosts, internal endpoints)

    • Comments containing passwords or access instructions If you spot anything suspicious, warn the user before proceeding.

  3. COMMIT MESSAGE: After confirming no secrets (or user acknowledgment), generate a commit message following:

    • 50/72 rule: 50 char subject line, 72 char body lines

    • Conventional commits format: type(scope): description

    • DO NOT include AI signatures, attribution, or "Generated with" footers

Args: cursor: Pagination cursor for large diffs (optional, returned as next_cursor) max_diff_tokens: Maximum tokens per response (default: 20000, safe under 25k limit) repo_path: Path to git repository (optional, defaults to Claude's working directory)

Returns: JSON string with: - has_changes: boolean - True if there are any staged changes to commit - files: list of changed files with status - secret_scan: results of secret detection on added lines - diff: the diff chunk (paginated) - next_cursor: pagination cursor for next chunk (if any) - pagination_info: token counts and chunk info - commit_format_guide: formatting rules for commit messages

Inputs: cursor, repo_path, max_diff_tokens. Returns: result

get_pr_contextA

Get diff and commits between branches for PR description.

IMPORTANT: After calling this tool, you should:

  1. Check if .devnarrate/pr-templates/ directory exists (use ls or Bash)

  2. If templates exist, list them and ask user which template to use

  3. Read the chosen template file (use Read tool)

  4. If no templates exist, use git_operations.DEFAULT_PR_TEMPLATE

  5. Analyze the diff and commits to fill the template

Args: base_branch: Base branch to compare against (e.g., "main", "dev") head_branch: Head branch (defaults to current branch) cursor: Pagination cursor for large diffs (optional, returned as next_cursor) max_diff_tokens: Maximum tokens per diff chunk (default: 12000, leaves room for commits/files in 25k limit) repo_path: Path to git repository (optional, defaults to Claude's working directory)

Returns: JSON string with commits, files, diff chunk, and pagination info

Inputs: base_branch (required), cursor, repo_path, head_branch, +1 more. Returns: result

review_changesA

Review code changes before staging/committing to understand what was done and why.

WHEN TO CALL: After you (the AI assistant) have made code changes on behalf of the user and BEFORE staging or committing. This lets the user understand what you did at a conceptual level rather than reading raw diffs.

REQUIRED: Before calling this tool, summarize what the user asked you to do. Pass this as the 'goal' parameter. Be specific — "add JWT authentication middleware" is better than "make changes".

HOW TO PRESENT THE RESPONSE — follow this layered approach:

  1. NARRATIVE SUMMARY (always show first): Start with a plain-language summary of what changed. Example: "I made 5 changes across 3 files to add JWT authentication." Include the key stats: files added/modified/deleted, lines changed.

  2. GOAL ALIGNMENT (group changes by purpose): Look at each changed file and classify it into one of three tiers:

    • KNOWN: Changes that directly relate to the 'goal' you passed. You know these because you made them for the stated purpose.

    • INFERRED: Changes whose context_clues (comments, docstrings) suggest a clear purpose different from the stated goal. These may be from a different AI agent session. Describe the inferred purpose.

    • UNKNOWN: Changes with no clear connection to any goal AND no useful context clues. Flag these — the user should review them.

  3. PER-FILE BREAKDOWN: For each goal group, list the files with a short description of what changed. Read the diff to explain HOW the goal was achieved:

    • What functions/classes were added or modified?

    • What's the approach? (e.g., "Added middleware pattern using decorators")

    • Any notable implementation choices?

  4. ATTENTION GUIDE: Tell the user what needs their eyes vs what's routine:

    • NEW FILES: "I created auth/middleware.py — worth a quick review"

    • MODIFIED FILES: "Added 3 lines to config.py — routine import addition"

    • UNKNOWN CHANGES: "utils.py was modified but doesn't match the goal — please check"

    • LARGE CHANGES: Any file with 50+ lines added deserves a mention

  5. DETAIL ON DEMAND: End with: "Want me to walk through any specific file in detail?"

IMPORTANT: You have the full diff in the response — READ IT to understand the actual code in any programming language. The context_clues are supplementary hints (comments/docstrings) to help you classify changes from other sessions that you didn't make yourself.

Args: goal: What the user asked the AI to do. Summarize from your conversation. Be specific — this is used to classify changes into goal groups. scope: What to analyze: - "working" (default): All unstaged working tree changes (git diff) plus untracked files. Use this before staging. - "staged": Only staged changes (git diff --staged). Use this if the user has already staged specific files. repo_path: Path to git repository (optional, defaults to MCP roots).

Returns: JSON string with: - goal: The stated goal (pass-through for your reference) - summary: File and line count statistics - changes: Per-file stats (path, status, lines_added, lines_removed) - context_clues: Comments and docstrings from added lines (per file) - diff: Raw diff text for you to read and understand the code - untracked_files: List of new files not yet tracked by git (working scope only) - pagination_info: Token counts and chunk info for the diff

Inputs: goal (required), scope, repo_path. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: commit changes, create PR, get commit context, get PR context, and review changes. No overlaps in functionality.

    Naming Consistency5/5

    All tool names follow the verb_noun snake_case pattern consistently, e.g., commit_changes, get_commit_context, create_pr.

    Tool Count5/5

    With 5 tools, the server is well-scoped for assisting with git workflows without being overwhelming or insufficient.

    Completeness4/5

    Covers core workflow: commit, PR, context retrieval, and review. Missing staging or branch management, but these are minor gaps for the intended domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A production-ready MCP server that provides AI assistants with comprehensive GitHub developer tooling including PR analysis, code review, changelog generation, dependency auditing, commit summarization, and refactoring suggestions.
      MIT