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

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