DevNarrate
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@DevNarrate Review the changes you just made"
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.
DevNarrate
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 | sh2. Clone and set up
git clone https://github.com/krishnamandanapu/DevNarrate.git
cd DevNarrate
uv sync3. 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.serverCursor (~/.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 -uThen ask Claude:
Generate a commit message for my changesClaude 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 madeDevNarrate 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 secretPR Descriptions
Ask Claude: "Create a PR to main from my current branch"
Claude analyzes the diff and offers template options (custom templates live in
.devnarrate/pr-templates/)Review the generated description and approve to let Claude create the PR via
ghorglab
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-templatesExample (.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
Development
Format/lint through uv-managed tooling
Build artifacts with
uv run pyproject-buildUse
bump-my-version(seeRELEASING.md) for tagged releases
License
MIT
Available Tools
5 toolscommit_changesA
Execute git commit with a user-approved commit message.
CRITICAL WORKFLOW - YOU MUST FOLLOW THESE STEPS IN ORDER:
Call get_commit_context to get the diff
Generate a commit message based on the actual diff
SHOW the generated commit message to the user in your response
ASK the user: "Should I proceed with this commit?" and WAIT for their response
ONLY call this tool AFTER the user explicitly approves (says "yes", "proceed", "commit it", etc.)
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:
Call get_pr_context to analyze the changes
Generate PR title and description based on the diff
SHOW the generated PR title and body to the user in your response
ASK the user: "Should I create this PR?" and WAIT for their response
ONLY call this tool AFTER the user explicitly approves (says "yes", "proceed", "create it", etc.)
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:
STOP immediately - do NOT proceed with generating a commit message
Tell the user: "No staged changes found. Please stage the files you want to commit first using: git add "
DO NOT attempt to stage files automatically
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:
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.
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.
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:
Check if .devnarrate/pr-templates/ directory exists (use ls or Bash)
If templates exist, list them and ask user which template to use
Read the chosen template file (use Read tool)
If no templates exist, use git_operations.DEFAULT_PR_TEMPLATE
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:
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.
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.
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?
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
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
Scored across 5 tools
Each tool has a clearly distinct purpose: commit changes, create PR, get commit context, get PR context, and review changes. No overlaps in functionality.
All tool names follow the verb_noun snake_case pattern consistently, e.g., commit_changes, get_commit_context, create_pr.
With 5 tools, the server is well-scoped for assisting with git workflows without being overwhelming or insufficient.
Covers core workflow: commit, PR, context retrieval, and review. Missing staging or branch management, but these are minor gaps for the intended domain.
Maintenance
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
A MCP server built for developers enabling Git based project management with project and personal…
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA 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
- AlicenseAqualityDmaintenanceMCP server to automate Pull Request creation with AI. Analyzes Git branches, generates descriptions, titles, suggests reviewers, and performs code reviews.84MIT
- AlicenseNot gradedqualityDmaintenanceProduction-ready MCP server for enforcing git/PR/Jira workflows with atomic, composable tools. Enables automated branch creation, conventional commits, PR generation, and Jira ticket operations with safety guardrails.MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that automates developer workflows across GitHub, Jira, and Slack, enabling PR/code review automation, CI checks, and team notifications.-