@gbrandtio/rw-git-mcp 2.0.2

package/README.md

@@ -0,0 +1,130 @@
+# @gbrandtio/rw-git-mcp
+
+**Model Context Protocol (MCP) server for rw-git**
+
+This package provides an embedded Model Context Protocol (MCP) server that allows AI agents and IDEs (like Claude Desktop, Cursor, and Antigravity) to interact directly with your git repositories. It communicates over standard I/O using JSON-RPC 2.0.
+
+`rw-git-mcp` provides a comprehensive suite of tools for AI agents to analyze and manipulate your repository, including core git commands (init, clone, checkout), code quality metrics, dependency drift analysis, compliance auditing, and LLM-assisted code review evaluations.
+
+The MCP can also be used to provide Git harness to your agent, while keeping AI tokens to a minimum. It can be installed with bundled AI agent skills that offer structured workflows and best practices for repository analysis.
+
+## Available MCP Tools
+
+`rw-git-mcp` provides a comprehensive suite of tools for AI agents to analyze and manipulate your repository:
+
+**Repository Operations:**
+- `init_repository`: Initializes a new Git repository.
+- `clone_repository`: Clones a remote repository.
+- `clone_specific_branch`: Clones a specific branch of a remote repository.
+- `checkout_branch`: Switches branches.
+- `is_git_repository`: Checks if a directory is a valid Git repository.
+- `fetch_tags`: Retrieves all tags from the repository.
+
+**Analysis & Metrics:**
+- `analyze_code_quality`: Analyzes recent commits to identify code smells and technical debt.
+- `analyze_code_quality_with_authors`: Analyzes code quality metrics along with author contributions.
+- `analyze_bus_factor`: Calculates the "bus factor" by analyzing file ownership and contribution concentration.
+- `analyze_commit_velocity`: Computes time-series commit velocity to track team productivity trends.
+- `analyze_dependency_drift`: Parses dependency manifests for supply chain risk analysis.
+- `analyze_file_ownership`: Cross-references CODEOWNERS with git blame history for ownership drift.
+- `analyze_pr_diff`: Analyzes PR diffs for risk signals like high churn and exposed secrets.
+- `analyze_release_delta`: Analyzes the changes and impact between two release tags.
+- `predict_merge_conflicts`: Identifies files modified on both branches to predict merge conflicts.
+- `analyze_dart_ast_quality`: Performs deep AST-level analysis of Dart files.
+- `analyze_architecture_drift`: Analyzes git history to detect architectural drift by identifying commits that modify multiple layers.
+- `analyze_clean_code`: Language-agnostic tool to analyze basic clean code heuristics.
+- `calculate_universal_lexical_metrics`: Calculates language-agnostic code quality metrics (Cyclomatic, Halstead, Cognitive, Maintainability Index) for any source file.
+- `get_stats`: Retrieves Git statistics like insertions and deletions.
+- `get_commits_between`: Lists commits between two tags or branches.
+- `get_contributions_by_author`: Retrieves commit counts grouped by author.
+
+
+**Security & Compliance:**
+- `audit_compliance`: Scans commit history for unsigned commits, empty messages, and unrecognized author emails.
+- `detect_secrets_in_commits`: Scans commit history for exposed secrets or credentials.
+
+**Code Review AI Agents:**
+- `evaluate_comment_llm_generation`: Detects if code comments were likely generated by an LLM.
+- `evaluate_comment_necessity`: Evaluates if comments are redundant or if the code could be self-documenting.
+- `evaluate_comment_quality`: Analyzes the quality and usefulness of newly added comments.
+
+## Available Prompts
+
+The server natively exposes MCP Prompts that provide AI agents with detailed instructions and workflows on how to effectively use the repository tools:
+
+- `rw-git-mcp-reporting`: A comprehensive, step-by-step workflow instructing the AI on how to orchestrate the analysis tools to generate thorough repository reports, code quality assessments, and risk analysis.
+
+## Installation
+
+This package acts as an installer that automatically downloads a pre-compiled, highly-optimized native executable of the rw-git MCP for your operating system and architecture.
+
+### Option 1: Run dynamically via `npx` (Recommended for MCP Clients)
+This is the easiest way to integrate the server into tools like Claude Desktop or Cursor:
+```bash
+npx -y @gbrandtio/rw-git-mcp
+```
+
+### Option 2: Install Globally
+To install the server globally on your machine:
+```bash
+npm install -g @gbrandtio/rw-git-mcp
+```
+After installation, you can run the server simply by typing `rw-git-mcp` in your terminal.
+
+## Installing Agent Skills
+
+To install the bundled AI agent skills directly into your local workspace, you can use `npx`:
+```bash
+npx @gbrandtio/rw-git-mcp install-skills
+```
+
+Alternatively, if you have installed the package globally via `npm install -g`, you can simply run:
+```bash
+rw-git-mcp install-skills
+```
+
+This will extract the skills to `./.agents/skills/rw-git-mcp/` in your current directory.
+
+## MCP Client Configuration
+
+
+### Claude Desktop
+Add the following to your `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "rw_git": {
+      "command": "npx",
+      "args": ["-y", "@gbrandtio/rw-git-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+Add the following to your Cursor's `mcp.json` or `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "rw_git": {
+      "command": "npx",
+      "args": ["-y", "@gbrandtio/rw-git-mcp"]
+    }
+  }
+}
+```
+
+### Antigravity (AGY CLI / Web IDE)
+Add this to your MCP configuration block:
+```json
+{
+  "mcpServers": {
+    "rw_git": {
+      "command": "npx",
+      "args": ["-y", "@gbrandtio/rw-git-mcp"]
+    }
+  }
+}
+```
+
+For more details, visit the [main repository on GitHub](https://github.com/gbrandtio/rw-git).

package/bin/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const fs = require('fs');
+const { spawn } = require('child_process');
+const os = require('os');
+
+const command = process.argv[2];
+
+if (command === 'install-skills') {
+  const skillsSourceDir = path.join(__dirname, '../skills');
+  const targetDir = path.join(process.cwd(), '.agents', 'skills', 'rw-git-mcp');
+
+  if (!fs.existsSync(skillsSourceDir)) {
+    console.error(`Error: Skills directory not found in the package at ${skillsSourceDir}`);
+    console.error('This may be a packaging issue.');
+    process.exit(1);
+  }
+
+  try {
+    fs.mkdirSync(targetDir, { recursive: true });
+    fs.cpSync(skillsSourceDir, targetDir, { recursive: true });
+    console.log(`Successfully installed rw-git-mcp skills to ${targetDir}`);
+    process.exit(0);
+  } catch (error) {
+    console.error(`Failed to copy skills: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// Proxy to the actual Dart binary
+const isWindows = os.platform() === 'win32';
+const binName = isWindows ? 'rw-git-mcp-bin.exe' : 'rw-git-mcp-bin';
+const binPath = path.join(__dirname, binName);
+
+if (!fs.existsSync(binPath)) {
+  console.error(`Error: The executable ${binName} was not found.`);
+  console.error('Make sure the postinstall script completed successfully.');
+  process.exit(1);
+}
+
+// Pass all arguments down, minus the 'node' and 'cli.js' parts
+const args = process.argv.slice(2);
+
+const child = spawn(binPath, args, {
+  stdio: 'inherit'
+});
+
+child.on('error', (err) => {
+  console.error(`Failed to start child process: ${err}`);
+  process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+  if (code !== null) {
+    process.exit(code);
+  } else if (signal) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(0);
+  }
+});

package/install.js

@@ -0,0 +1,57 @@
+const fs = require('fs');
+const https = require('https');
+const os = require('os');
+const path = require('path');
+
+const version = require('./package.json').version;
+const binDir = path.join(__dirname, 'bin');
+if (!fs.existsSync(binDir)) {
+  fs.mkdirSync(binDir);
+}
+
+const platform = os.platform();
+const arch = os.arch();
+
+let artifactName = '';
+if (platform === 'linux' && arch === 'x64') {
+  artifactName = 'rw_git_mcp_linux_x64';
+} else if (platform === 'darwin' && arch === 'arm64') {
+  artifactName = 'rw_git_mcp_macos_arm64';
+} else if (platform === 'darwin' && arch === 'x64') {
+  artifactName = 'rw_git_mcp_macos_x64';
+} else if (platform === 'win32' && arch === 'x64') {
+  artifactName = 'rw_git_mcp_windows_x64.exe';
+} else {
+  console.error(`Unsupported platform/architecture: ${platform}/${arch}`);
+  process.exit(1);
+}
+
+const url = `https://github.com/gbrandtio/rw-git/releases/download/v${version}/${artifactName}`;
+const destPath = path.join(binDir, platform === 'win32' ? 'rw-git-mcp-bin.exe' : 'rw-git-mcp-bin');
+
+console.log(`Downloading ${url} ...`);
+
+https.get(url, (res) => {
+  if (res.statusCode === 302 || res.statusCode === 301) {
+    https.get(res.headers.location, (redirectRes) => {
+      saveFile(redirectRes);
+    });
+  } else {
+    saveFile(res);
+  }
+}).on('error', (err) => {
+  console.error('Download failed:', err);
+  process.exit(1);
+});
+
+function saveFile(res) {
+  const fileStream = fs.createWriteStream(destPath);
+  res.pipe(fileStream);
+  fileStream.on('finish', () => {
+    fileStream.close();
+    if (platform !== 'win32') {
+      fs.chmodSync(destPath, 0o755); // Make executable
+    }
+    console.log('Download complete.');
+  });
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@gbrandtio/rw-git-mcp",
+  "version": "2.0.2",
+  "description": "Model Context Protocol (MCP) server for rw-git",
+  "main": "index.js",
+  "scripts": {
+    "prepack": "node -e \"const fs = require('fs'); fs.cpSync('../../.agents/skills', './skills', {recursive: true});\"",
+    "postinstall": "node install.js"
+  },
+  "bin": {
+    "rw-git-mcp": "bin/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gbrandtio/rw-git.git"
+  },
+  "keywords": [
+    "mcp",
+    "git",
+    "ai",
+    "claude",
+    "cursor",
+    "gemini",
+    "harness"
+  ],
+  "author": "Ioannis Brant-Ioannidis",
+  "license": "MIT"
+}

package/skills/rw-git-mcp-installation/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: rw-git-mcp-installation
+description: "Guides the agent through installing and configuring the rw_git MCP server on the user's system."
+---
+
+# `rw-git` MCP Server Installation Guide
+
+This skill instructs you on how to set up the `rw_git` Model Context Protocol (MCP) server for a user so that their AI agents can access robust repository analysis tools.
+
+Trigger this skill whenever a user asks to "install rw_git MCP", "connect the git MCP server", or "set up the repo analysis AI tools".
+
+## 1. Determine the Target Environment
+
+First, identify which AI client the user wants to connect the MCP server to. If they haven't specified, ask them. Common clients include:
+- **Claude Desktop**
+- **Cursor IDE**
+- **Antigravity (AGY)**
+
+Also, ensure the user has Node.js installed, as `npx` is the recommended and easiest way to run the server. If they don't have Node.js, ask if they have Homebrew or the Dart SDK.
+
+## 2. Locate the Configuration File
+
+Based on their client and OS, locate the correct MCP configuration file:
+
+### Claude Desktop
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+### Cursor IDE
+- Check if `.cursor/mcp.json` exists in the current workspace. If so, update it.
+- Otherwise, guide the user to add it via the Cursor UI (Settings -> Features -> MCP), as Cursor's global config files are heavily nested.
+
+### Antigravity (AGY)
+- Configuration is usually located at `~/.gemini/config/mcp.json` or within a plugin configuration.
+
+## 3. Inject the Configuration
+
+Once the target file is located, use your file editing tools to safely merge the following `rw_git` configuration block into the `mcpServers` object.
+
+```json
+{
+  "mcpServers": {
+    "rw_git": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@gbrandtio/rw-git-mcp"
+      ]
+    }
+  }
+}
+```
+
+> [!WARNING]
+> Do NOT overwrite existing MCP servers in the configuration file. Parse the JSON carefully and only insert or update the `rw_git` key inside `mcpServers`.
+
+### Alternative Commands
+If the user prefers not to use `npx`, adjust the `command` and `args` accordingly:
+- **Homebrew:** `command: "rw-git-mcp", args: []`
+- **Dart global activate:** `command: "rw_git_mcp", args: []`
+
+## 4. Verification
+
+After updating the configuration file, instruct the user to restart their AI client (e.g., fully quit and reopen Claude Desktop or reload Cursor). 
+
+To proactively verify that the server works on their machine, you can run a quick test via standard input:
+
+```bash
+echo '{"jsonrpc": "2.0", "id": 1, "method": "prompts/list"}' | npx -y @gbrandtio/rw-git-mcp
+```
+If the command outputs a valid JSON-RPC response containing a prompt named `rw-git-mcp-reporting`, the installation is successful!

package/skills/rw-git-mcp-reporting/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: rw-git-mcp-reporting
+description: "Comprehensive workflow for orchestrating rw_git MCP tools to generate thorough repository reports, code quality assessments, and risk analysis."
+---
+
+# `rw-git` MCP Reporting Workflow
+
+This skill instructs you on how to orchestrate the complete suite of MCP tools provided by the `rw_git` server to generate a comprehensive, structured report of a repository.
+When a user asks you to analyze the repository, assess code quality, evaluate an entire project, or generate a report, strictly follow this step-by-step workflow to ensure no stone is left unturned.
+
+## 1. Environment & Scope Preparation
+Before diving into analysis, you **MUST** understand the context and establish the baseline environment.
+- **Is it a remote or local repo?** Use `clone_repository` or `clone_specific_branch` to fetch it remotely. If you need to initialize a fresh local repository for analysis from scratch, use `init_repository`.
+- **Local Verification:** If working locally, use `is_git_repository` to ensure you are in a valid Git directory.
+- **Branch Context:** Use `checkout_branch` to switch to the appropriate target branch before running analysis, if needed.
+- **Reference Gathering:** Use `fetch_tags` to get a list of available tags if you need to perform release comparisons.
+- **Internal Docs:** If you ever need to understand how the underlying `rw_git` commands execute or handle errors, run `get_rw_git_documentation`.
+- **Scope Resolution:** Resolve the exact arguments you will need for downstream tools (e.g., `limit`, `since`, `until`, `oldVersion`, `newVersion`, `branchA`, `branchB`).
+
+## 2. General Statistics & Contributor Activity
+Start by building a foundational understanding of the codebase's size, scope, and primary drivers.
+- **Overall Stats:** Run `get_stats` to get a high-level view of insertions, deletions, and total files changed.
+- **Commit History:** Run `get_commits_between` to retrieve the raw sequence of commits in the target range to understand the context of the work.
+- **Contributor Breakdown:** Run `get_contributions_by_author` to identify the most active contributors in the repository.
+
+## 3. Targeted Assessment & Velocity
+Dive into the specific changes, analyzing their impact and how fast the team is moving.
+- **For Branch/PR Comparisons:** Run `analyze_pr_diff` to get a breakdown of the specific risks introduced in a Pull Request.
+- **For Tag/Release Comparisons:** Run `analyze_release_delta` to understand the structural changes between versions.
+- **Code Quality:** Run `analyze_code_quality` (or `analyze_code_quality_with_authors` if the breakdown of contributors is important) to spot code smells, complex files, and technical debt.
+- **Bug Hotspots:** Run `analyze_bug_hotspots` to identify files that are frequently modified in bug-fix commits, highlighting areas that may need refactoring.
+- **Trend Analysis:** Run `analyze_commit_velocity` to gather time-series trend data, exposing anomalies in commit frequency and tracking team productivity over time.
+- **Deep Inspection:** If you are analyzing Dart code, use `analyze_dart_ast_quality` for AST-level insights into dead code, public signature diffs, and dependency graphs. Use `analyze_clean_code` on individual files to check basic SOLID principles and readability heuristics.
+
+## 4. Security & Compliance Check
+Ensure the code being analyzed meets security policies and project compliance standards. This step is critical for CI/CD environments.
+- **Secret Scanning:** Run `detect_secrets_in_commits` to aggressively flag any exposed credentials, API keys, or tokens.
+- **Compliance Auditing:** Run `audit_compliance` to ensure commit signatures exist, email addresses match recognized domains, and project commit message policies (like conventional commits or no empty messages) are being followed.
+
+## 5. Risk Analysis
+Detect architectural bottlenecks, ownership risks, and potential integration disasters.
+- **Knowledge Silos:** Run `analyze_bus_factor` and `analyze_file_ownership` to identify "mega-files" that have drifted in ownership or rely too heavily on a single author (low bus factor).
+- **Integration Risk:** If you are analyzing a branch intended for integration (PR), run `predict_merge_conflicts` to proactively surface files that will conflict with the base branch.
+- **Architecture Integrity:** Run `analyze_architecture_drift` to ensure that commits are not simultaneously modifying disparate architectural layers (which could signal leaky abstractions or tight coupling).
+
+## 6. Code Review & Ecosystem Health
+Deep dive into the contents of the changes, focusing on dependencies and documentation.
+- **Supply Chain Risks:** Use `analyze_dependency_drift` to flag vulnerable, unpinned, or floating dependencies across ecosystem manifests (e.g., `pubspec.yaml`, `package.json`).
+- **AI-Assisted Code Review:** Evaluate the quality and origin of code comments using `evaluate_comment_quality` and `evaluate_comment_necessity`. Use `evaluate_comment_llm_generation` to detect if documentation was hastily generated by an LLM without human oversight, helping maintain a clean, self-documenting codebase.
+
+## 7. Release Notes & Changelogs
+If the user's request involves summarizing changes between releases or wrapping up a large feature branch, prepare the user-facing documentation.
+- **Changelog Generation:** Run `generate_changelog` to retrieve a structured, human-readable list of features, fixes, and breaking changes. Note that this tool also structurally links fixes to bug-introducing commits via SZZ.
+
+## 8. Synthesis & Formatting
+Aggregate the outputs from all the invoked tools into a highly structured, unified Markdown artifact. 
+- Present the information with a clear executive summary followed by detailed sections.
+- Use Github-flavored markdown alerts (`> [!WARNING]`, `> [!IMPORTANT]`, `> [!CAUTION]`) to highlight critical risks, exposed secrets, severe compliance violations, or likely merge conflicts.
+- **Do not dump raw JSON.** Synthesize the metrics into readable tables, lists, and actionable insights. Use mermaid diagrams if it helps visualize complex relationships like contributor ownership.
+- Point the user directly to the most critical files requiring attention based on the analysis.