devnarrate 0.1.0a1__py3-none-any.whl

devnarrate/__init__.py

@@ -0,0 +1,3 @@
+"""DevNarrate - MCP server for developer workflow automation."""
+
+__version__ = "0.1.0"

devnarrate/git_operations.py

@@ -0,0 +1,462 @@
+"""Git operations for DevNarrate."""
+
+import subprocess
+from typing import Optional
+
+import tiktoken
+
+# MCP response token limit is 25,000 - we'll use 20,000 to be safe
+MAX_RESPONSE_TOKENS = 20000
+
+# Default PR template
+DEFAULT_PR_TEMPLATE = """## Summary
+[Brief description of what this PR does and why]
+
+## Changes
+-
+-
+
+## Testing
+[How to test these changes]
+
+## Related Issues
+[Links to related issues, if any]
+"""
+
+
+def count_tokens(text: str) -> int:
+    """Count tokens in text using tiktoken (cl100k_base encoding).
+
+    Args:
+        text: Text to count tokens for
+
+    Returns:
+        Number of tokens
+    """
+    try:
+        encoding = tiktoken.get_encoding("cl100k_base")
+        return len(encoding.encode(text))
+    except Exception:
+        # Fallback to rough estimate: ~4 chars per token
+        return len(text) // 4
+
+
+def get_diff(repo_path: str) -> str:
+    """Get git diff output for staged changes only.
+
+    Args:
+        repo_path: Path to the git repository
+
+    Returns:
+        Raw git diff output for staged changes
+
+    Raises:
+        subprocess.CalledProcessError: If git command fails
+    """
+    result = subprocess.run(
+        ['git', 'diff', '--staged'],
+        cwd=repo_path,
+        capture_output=True,
+        text=True,
+        check=True
+    )
+    return result.stdout
+
+
+def get_file_stats(repo_path: str) -> dict:
+    """Get statistics about staged files only.
+
+    Args:
+        repo_path: Path to the git repository
+
+    Returns:
+        Dict with staged file changes
+    """
+    # Get list of changed files with status
+    status_result = subprocess.run(
+        ['git', 'status', '--porcelain'],
+        cwd=repo_path,
+        capture_output=True,
+        text=True,
+        check=True
+    )
+
+    # Parse file status
+    # Format: XY filepath (X=staged, Y=unstaged, space=no change)
+    files = []
+    for line in status_result.stdout.strip().split('\n'):
+        if not line:
+            continue
+
+        # First 2 chars are status codes (XY), rest is filepath
+        staged_status = line[0]
+        filepath = line[2:].strip()  # Skip status codes and strip whitespace
+
+        # Skip files with no staged changes (untracked or not staged)
+        if staged_status in (' ', '?'):
+            continue
+
+        file_status = 'modified'
+        if staged_status == 'A':
+            file_status = 'added'
+        elif staged_status == 'D':
+            file_status = 'deleted'
+        elif staged_status == 'M':
+            file_status = 'modified'
+        elif staged_status == 'R':
+            file_status = 'renamed'
+
+        files.append({
+            'path': filepath,
+            'status': file_status
+        })
+
+    return {'files': files}
+
+
+def paginate_diff(diff_text: str, cursor: Optional[str], max_tokens: int = MAX_RESPONSE_TOKENS) -> dict:
+    """Paginate diff output by token count (MCP limit: 25k tokens).
+
+    This ensures responses stay under the MCP token limit while preserving
+    line boundaries for readability. Reusable for PR diffs as well.
+
+    Args:
+        diff_text: Full diff text
+        cursor: Current cursor position (line number as string)
+        max_tokens: Maximum tokens per chunk (default: 20,000 to stay under 25k limit)
+
+    Returns:
+        Dict with diff chunk, token counts, and nextCursor
+    """
+    if not diff_text:
+        return {
+            'diff_chunk': '',
+            'next_cursor': None,
+            'chunk_info': {
+                'start_line': 0,
+                'end_line': 0,
+                'total_lines': 0,
+                'chunk_tokens': 0,
+                'total_tokens': 0
+            }
+        }
+
+    lines = diff_text.split('\n')
+    total_lines = len(lines)
+    total_tokens = count_tokens(diff_text)
+
+    # Parse cursor (line number) or start from 0
+    start_line = 0
+    if cursor:
+        try:
+            start_line = int(cursor)
+        except ValueError:
+            start_line = 0
+
+    # Build chunk line by line, staying under token limit
+    chunk_lines = []
+    chunk_text = ""
+    end_line = start_line
+
+    for i in range(start_line, total_lines):
+        line = lines[i]
+        test_chunk = chunk_text + line + '\n'
+        test_tokens = count_tokens(test_chunk)
+
+        if test_tokens > max_tokens and chunk_lines:
+            # Would exceed limit, stop here
+            break
+
+        chunk_lines.append(line)
+        chunk_text = test_chunk
+        end_line = i + 1
+
+    # Determine next cursor
+    next_cursor = None
+    if end_line < total_lines:
+        next_cursor = str(end_line)
+
+    chunk_tokens = count_tokens(chunk_text)
+
+    return {
+        'diff_chunk': '\n'.join(chunk_lines),
+        'next_cursor': next_cursor,
+        'chunk_info': {
+            'start_line': start_line,
+            'end_line': end_line,
+            'total_lines': total_lines,
+            'chunk_tokens': chunk_tokens,
+            'total_tokens': total_tokens,
+            'chunk_percentage': round((chunk_tokens / total_tokens * 100) if total_tokens > 0 else 100, 1)
+        }
+    }
+
+
+def execute_commit(repo_path: str, message: str) -> str:
+    """Execute git commit with the given message.
+
+    Args:
+        repo_path: Path to the git repository
+        message: Commit message
+
+    Returns:
+        Success message with commit hash
+
+    Raises:
+        subprocess.CalledProcessError: If git commit fails
+    """
+    # Execute commit
+    result = subprocess.run(
+        ['git', 'commit', '-m', message],
+        cwd=repo_path,
+        capture_output=True,
+        text=True,
+        check=True
+    )
+
+    # Get the commit hash
+    hash_result = subprocess.run(
+        ['git', 'rev-parse', 'HEAD'],
+        cwd=repo_path,
+        capture_output=True,
+        text=True,
+        check=True
+    )
+
+    commit_hash = hash_result.stdout.strip()[:7]
+
+    return f"Successfully committed as {commit_hash}\n{result.stdout}"
+
+
+def get_current_branch(repo_path: str) -> str:
+    """Get the current git branch name.
+
+    Args:
+        repo_path: Path to the git repository
+
+    Returns:
+        Current branch name
+
+    Raises:
+        subprocess.CalledProcessError: If git command fails
+    """
+    result = subprocess.run(
+        ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
+        cwd=repo_path,
+        capture_output=True,
+        text=True,
+        check=True
+    )
+    return result.stdout.strip()
+
+
+def get_branch_diff(repo_path: str, base_branch: str, head_branch: Optional[str] = None) -> str:
+    """Get diff between two branches.
+
+    Args:
+        repo_path: Path to the git repository
+        base_branch: Base branch (e.g., "main", "dev")
+        head_branch: Head branch (defaults to current branch)
+
+    Returns:
+        Raw git diff output
+
+    Raises:
+        subprocess.CalledProcessError: If git command fails
+    """
+    if head_branch is None:
+        head_branch = get_current_branch(repo_path)
+
+    # Use three-dot diff to compare from common ancestor
+    result = subprocess.run(
+        ['git', 'diff', f'{base_branch}...{head_branch}'],
+        cwd=repo_path,
+        capture_output=True,
+        text=True,
+        check=True
+    )
+    return result.stdout
+
+
+def get_branch_commits(repo_path: str, base_branch: str, head_branch: Optional[str] = None) -> list[dict]:
+    """Get list of commits in head branch not in base branch.
+
+    Args:
+        repo_path: Path to the git repository
+        base_branch: Base branch (e.g., "main", "dev")
+        head_branch: Head branch (defaults to current branch)
+
+    Returns:
+        List of commit dicts with 'hash' and 'message'
+
+    Raises:
+        subprocess.CalledProcessError: If git command fails
+    """
+    if head_branch is None:
+        head_branch = get_current_branch(repo_path)
+
+    # Get commits in head but not in base
+    result = subprocess.run(
+        ['git', 'log', f'{base_branch}..{head_branch}', '--oneline'],
+        cwd=repo_path,
+        capture_output=True,
+        text=True,
+        check=True
+    )
+
+    commits = []
+    for line in result.stdout.strip().split('\n'):
+        if line:
+            parts = line.split(' ', 1)
+            commits.append({
+                'hash': parts[0],
+                'message': parts[1] if len(parts) > 1 else ''
+            })
+
+    return commits
+
+
+def get_branch_file_stats(repo_path: str, base_branch: str, head_branch: Optional[str] = None) -> dict:
+    """Get file statistics for changes between branches.
+
+    Args:
+        repo_path: Path to the git repository
+        base_branch: Base branch (e.g., "main", "dev")
+        head_branch: Head branch (defaults to current branch)
+
+    Returns:
+        Dict with file changes
+
+    Raises:
+        subprocess.CalledProcessError: If git command fails
+    """
+    if head_branch is None:
+        head_branch = get_current_branch(repo_path)
+
+    # Get list of changed files with status
+    result = subprocess.run(
+        ['git', 'diff', '--name-status', f'{base_branch}...{head_branch}'],
+        cwd=repo_path,
+        capture_output=True,
+        text=True,
+        check=True
+    )
+
+    files = []
+    for line in result.stdout.strip().split('\n'):
+        if not line:
+            continue
+
+        parts = line.split('\t', 1)
+        if len(parts) < 2:
+            continue
+
+        status_char = parts[0]
+        filepath = parts[1]
+
+        file_status = 'modified'
+        if status_char == 'A':
+            file_status = 'added'
+        elif status_char == 'D':
+            file_status = 'deleted'
+        elif status_char == 'M':
+            file_status = 'modified'
+        elif status_char.startswith('R'):
+            file_status = 'renamed'
+
+        files.append({
+            'path': filepath,
+            'status': file_status
+        })
+
+    return {'files': files}
+
+
+def detect_git_platform(repo_path: str) -> str:
+    """Detect git platform from remote URL.
+
+    Args:
+        repo_path: Path to the git repository
+
+    Returns:
+        Platform name: 'github', 'gitlab', 'bitbucket', or 'unknown'
+
+    Raises:
+        subprocess.CalledProcessError: If git command fails
+    """
+    try:
+        result = subprocess.run(
+            ['git', 'remote', 'get-url', 'origin'],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        remote_url = result.stdout.strip().lower()
+
+        if 'github.com' in remote_url:
+            return 'github'
+        elif 'gitlab.com' in remote_url or 'gitlab' in remote_url:
+            return 'gitlab'
+        elif 'bitbucket.org' in remote_url:
+            return 'bitbucket'
+        else:
+            return 'unknown'
+    except subprocess.CalledProcessError:
+        return 'unknown'
+
+
+def execute_pr_creation(
+    repo_path: str,
+    title: str,
+    body: str,
+    base_branch: str,
+    head_branch: Optional[str] = None,
+    draft: bool = False
+) -> str:
+    """Create a pull request using platform CLI.
+
+    Args:
+        repo_path: Path to the git repository
+        title: PR title
+        body: PR description
+        base_branch: Base branch (e.g., "main", "dev")
+        head_branch: Head branch (defaults to current branch)
+        draft: Create as draft PR
+
+    Returns:
+        Success message with PR URL
+
+    Raises:
+        subprocess.CalledProcessError: If command fails
+        ValueError: If platform not supported or CLI not available
+    """
+    if head_branch is None:
+        head_branch = get_current_branch(repo_path)
+
+    platform = detect_git_platform(repo_path)
+
+    if platform == 'github':
+        # Use GitHub CLI
+        cmd = ['gh', 'pr', 'create', '--base', base_branch, '--head', head_branch, '--title', title, '--body', body]
+        if draft:
+            cmd.append('--draft')
+
+    elif platform == 'gitlab':
+        # Use GitLab CLI
+        cmd = ['glab', 'mr', 'create', '--target-branch', base_branch, '--source-branch', head_branch, '--title', title, '--description', body]
+        if draft:
+            cmd.append('--draft')
+
+    else:
+        raise ValueError(f"Platform '{platform}' not supported or CLI not configured. Supported: github (gh), gitlab (glab)")
+
+    result = subprocess.run(
+        cmd,
+        cwd=repo_path,
+        capture_output=True,
+        text=True,
+        check=True
+    )
+
+    return result.stdout

devnarrate/server.py

@@ -0,0 +1,307 @@
+#!/usr/bin/env python3
+"""
+DevNarrate MCP Server
+
+An MCP server that helps developers with:
+- Writing commit messages
+- Generating PR descriptions
+- Posting CI/CD results to Slack
+- Sharing development updates to Slack
+"""
+
+import json
+import subprocess
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from . import git_operations
+
+# Create MCP server instance
+mcp = FastMCP("devnarrate")
+
+
+@mcp.tool()
+async def get_commit_context(
+    cursor: Optional[str] = None,
+    max_diff_tokens: int = 20000,
+    repo_path: Optional[str] = None
+) -> str:
+    """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 <file1> <file2>"
+    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.
+
+    After receiving a non-empty diff, analyze it and 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
+        - 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
+    """
+    try:
+        # Get working directory from MCP roots if repo_path not provided
+        if repo_path is None:
+            context = mcp.get_context()
+            roots_result = await context.session.list_roots()
+            if roots_result.roots:
+                repo_path = roots_result.roots[0].uri.path
+            else:
+                return json.dumps({'error': 'No repository path provided and no roots available'})
+
+        # Get file stats (staged changes only)
+        stats = git_operations.get_file_stats(repo_path)
+
+        # Get full diff (staged changes only)
+        diff_output = git_operations.get_diff(repo_path)
+
+        # Paginate diff by token count
+        paginated = git_operations.paginate_diff(diff_output, cursor, max_diff_tokens)
+
+        # Check if there are any changes - trust the diff as source of truth
+        # If git diff --staged is empty, there's nothing to commit
+        has_changes = bool(diff_output.strip())
+
+        result = {
+            'repository': repo_path,
+            'has_changes': has_changes,
+            'files': stats['files'],
+            'diff': paginated['diff_chunk'],
+            'next_cursor': paginated['next_cursor'],
+            'pagination_info': paginated['chunk_info'],
+            'commit_format_guide': {
+                'subject_line': 'Max 50 characters',
+                'body_line_length': 'Max 72 characters per line',
+                'format': 'type(scope): description\\n\\nBody paragraphs...\\n\\nFooter',
+                'types': ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore'],
+                'important': 'DO NOT include AI signatures, attribution, or "Generated with" footers in the commit message'
+            }
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        return json.dumps({'error': str(e)})
+
+
+@mcp.tool()
+async def commit_changes(
+    message: str,
+    user_approved: bool,
+    repo_path: Optional[str] = None
+) -> str:
+    """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
+    """
+    # Safety check
+    if not user_approved:
+        return "Error: user_approved must be True. Show the commit message to the user and get their approval first."
+    try:
+        # Get working directory from MCP roots if repo_path not provided
+        if repo_path is None:
+            context = mcp.get_context()
+            roots_result = await context.session.list_roots()
+            if roots_result.roots:
+                repo_path = roots_result.roots[0].uri.path
+            else:
+                return "Error: No repository path provided and no roots available"
+
+        result = git_operations.execute_commit(repo_path, message)
+        return result
+    except Exception as e:
+        return f"Error: {str(e)}"
+
+
+@mcp.tool()
+async def get_pr_context(
+    base_branch: str,
+    head_branch: Optional[str] = None,
+    cursor: Optional[str] = None,
+    max_diff_tokens: int = 12000,
+    repo_path: Optional[str] = None
+) -> str:
+    """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
+    """
+    try:
+        # Get working directory from MCP roots if repo_path not provided
+        if repo_path is None:
+            context = mcp.get_context()
+            roots_result = await context.session.list_roots()
+            if roots_result.roots:
+                repo_path = roots_result.roots[0].uri.path
+            else:
+                return json.dumps({'error': 'No repository path provided and no roots available'})
+
+        # Get current branch if head not specified
+        if head_branch is None:
+            head_branch = git_operations.get_current_branch(repo_path)
+
+        # Get commits between branches
+        commits = git_operations.get_branch_commits(repo_path, base_branch, head_branch)
+
+        # Get file stats
+        stats = git_operations.get_branch_file_stats(repo_path, base_branch, head_branch)
+
+        # Get diff between branches
+        diff_output = git_operations.get_branch_diff(repo_path, base_branch, head_branch)
+
+        # Paginate diff by token count
+        paginated = git_operations.paginate_diff(diff_output, cursor, max_diff_tokens)
+
+        # Detect platform
+        platform = git_operations.detect_git_platform(repo_path)
+
+        result = {
+            'repository': repo_path,
+            'base_branch': base_branch,
+            'head_branch': head_branch,
+            'platform': platform,
+            'commits': commits,
+            'commit_count': len(commits),
+            'files': stats['files'],
+            'diff': paginated['diff_chunk'],
+            'next_cursor': paginated['next_cursor'],
+            'pagination_info': paginated['chunk_info'],
+            'template_instructions': {
+                'templates_directory': '.devnarrate/pr-templates/',
+                'default_template_available': True,
+                'steps': [
+                    '1. Check if .devnarrate/pr-templates/ exists',
+                    '2. If yes, list templates and ask user which to use',
+                    '3. Read chosen template or use DEFAULT_PR_TEMPLATE',
+                    '4. Fill template with analysis of commits and diff'
+                ]
+            }
+        }
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        return json.dumps({'error': str(e)})
+
+
+@mcp.tool()
+async def create_pr(
+    title: str,
+    body: str,
+    base_branch: str,
+    user_approved: bool,
+    head_branch: Optional[str] = None,
+    draft: bool = False,
+    repo_path: Optional[str] = None
+) -> str:
+    """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
+    """
+    # Safety check
+    if not user_approved:
+        return "Error: user_approved must be True. Show the PR description to the user and get their approval first."
+    try:
+        # Get working directory from MCP roots if repo_path not provided
+        if repo_path is None:
+            context = mcp.get_context()
+            roots_result = await context.session.list_roots()
+            if roots_result.roots:
+                repo_path = roots_result.roots[0].uri.path
+            else:
+                return "Error: No repository path provided and no roots available"
+
+        result = git_operations.execute_pr_creation(
+            repo_path=repo_path,
+            title=title,
+            body=body,
+            base_branch=base_branch,
+            head_branch=head_branch,
+            draft=draft
+        )
+        return result
+
+    except subprocess.CalledProcessError as e:
+        return f"Error creating PR: {e.stderr if e.stderr else str(e)}\n\nMake sure the platform CLI is installed and configured (gh for GitHub, glab for GitLab)"
+    except Exception as e:
+        return f"Error: {str(e)}"
+
+
+if __name__ == "__main__":
+    mcp.run()

devnarrate-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: devnarrate
+Version: 0.1.0a1
+Summary: MCP server that narrates your code changes, from commits to deployments.
+Author: K Man
+Maintainer: K Man
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,commit,git,mcp,pr
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.12
+Requires-Dist: mcp[cli]>=1.20.0
+Requires-Dist: tiktoken>=0.5.0
+Description-Content-Type: text/markdown
+
+# DevNarrate
+MCP server that narrates your code changes, from commits to deployments.
+
+## Features
+
+- **Smart Commit Messages**: Generate conventional commit messages from staged changes with full user control
+- **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
+
+### Option 1: Install from PyPI (Recommended)
+
+1. **Install the package:**
+```bash
+pip install devnarrate
+
+# Or for pre-release versions:
+pip install --pre devnarrate
+```
+
+2. **Configure with Claude Code:**
+```bash
+# Add MCP server using your Python path
+claude mcp add DevNarrate -- python -m devnarrate.server
+
+# Verify it's connected
+claude mcp list
+```
+
+3. **Configure with Cursor:**
+
+Edit `~/.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "DevNarrate": {
+      "command": "python",
+      "args": ["-m", "devnarrate.server"]
+    }
+  }
+}
+```
+
+Then restart Cursor.
+
+### Option 2: Install from Source (Development)
+
+1. **Prerequisites:** Install [uv](https://docs.astral.sh/uv/getting-started/installation/):
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+2. **Clone and setup:**
+```bash
+git clone https://github.com/krishnamandanapu/DevNarrate.git
+cd DevNarrate
+uv sync
+```
+
+3. **Configure with Claude Code:**
+```bash
+claude mcp add DevNarrate -- uv --directory /path/to/DevNarrate run python -m devnarrate.server
+```
+
+4. **Configure with Cursor:**
+```json
+{
+  "mcpServers": {
+    "DevNarrate": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/DevNarrate", "run", "python", "-m", "devnarrate.server"]
+    }
+  }
+}
+```
+
+## Usage
+
+### Commit Messages
+
+**Important:** DevNarrate only works with **staged changes** to ensure you have full control over what gets committed. This prevents accidental commits of unintended files.
+
+1. First, stage the files you want to commit:
+```bash
+git add <file1> <file2>
+# or for all tracked files with changes:
+git add -u
+```
+
+2. Ask Claude to generate the commit message:
+```
+Ask Claude: "Generate a commit message for my changes"
+```
+
+3. Claude will analyze your staged changes, show you the proposed commit message, and ask for approval before committing.
+
+If you haven't staged any changes, Claude will prompt you to stage them first.
+
+### PR Descriptions
+
+1. Ask Claude: "Create a PR to main from my current branch"
+2. Claude will analyze the diff and ask which template to use (if you have custom templates)
+3. Claude generates the PR description and shows it to you
+4. Review and approve, then Claude creates the PR
+
+### PR Templates (Optional)
+Create custom templates in `.devnarrate/pr-templates/`:
+
+```bash
+mkdir -p .devnarrate/pr-templates
+```
+
+Example template (`.devnarrate/pr-templates/feature.md`):
+```markdown
+## Summary
+[What does this PR do?]
+
+## Changes
+-
+-
+
+## Testing
+[How to test]
+
+## Related Issues
+[Links]
+```
+
+If no templates exist, a default template will be used.
+
+## Platform Support
+
+**Commits:** Works everywhere (uses git)
+
+**PRs:** Requires platform CLI:
+- GitHub: Install [gh](https://cli.github.com/) and run `gh auth login`
+- GitLab: Install [glab](https://gitlab.com/gitlab-org/cli) and run `glab auth login`
+
+## Development
+
+For maintainers: See [RELEASING.md](RELEASING.md) for instructions on publishing releases to PyPI.

devnarrate-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,7 @@
+devnarrate/__init__.py,sha256=1h03V_pZh_m06lMN5ihHpN43JlphDiJkEMKa-ujFAfI,88
+devnarrate/git_operations.py,sha256=MLZDSUlqT9NdV2aCJj3ONsxYEJBlbM7X1V61rK40CDE,12200
+devnarrate/server.py,sha256=mdAKKJljhkfTV7tlmeFI4rsTLy4F-bPm00isKitzn3s,12337
+devnarrate-0.1.0a1.dist-info/METADATA,sha256=arQYDu0m_ve-rvKt7FrYIvXAP0YWX3KWqnnZY9F9n3M,4262
+devnarrate-0.1.0a1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+devnarrate-0.1.0a1.dist-info/licenses/LICENSE,sha256=gfDhdn_B7dhZkfIMrv7tT7Y_llChBs_ZSdxpscMipps,1062
+devnarrate-0.1.0a1.dist-info/RECORD,,

devnarrate-0.1.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

devnarrate-0.1.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 K Man
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.