@cyanheads/git-mcp-server 2.1.2 → 2.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +90 -72
  2. package/package.json +8 -8
package/README.md CHANGED
@@ -1,55 +1,70 @@
1
1
  # Git MCP Server
2
2
 
3
3
  [![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
4
- [![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.12.3-green.svg)](https://modelcontextprotocol.io/)
5
- [![Version](https://img.shields.io/badge/Version-2.1.2-blue.svg)](./CHANGELOG.md)
4
+ [![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.13.0-green.svg)](https://modelcontextprotocol.io/)
5
+ [![Version](https://img.shields.io/badge/Version-2.1.3-blue.svg)](./CHANGELOG.md)
6
6
  [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
7
7
  [![Status](https://img.shields.io/badge/Status-Stable-green.svg)](https://github.com/cyanheads/git-mcp-server/issues)
8
8
  [![GitHub](https://img.shields.io/github/stars/cyanheads/git-mcp-server?style=social)](https://github.com/cyanheads/git-mcp-server)
9
9
 
10
- An MCP (Model Context Protocol) server providing tools to interact with Git repositories. Enables LLMs and AI agents to perform Git operations like clone, commit, push, pull, branch, diff, log, status, and more via the MCP standard.
10
+ **Empower your AI agents with comprehensive, secure, and programmatic control over Git repositories!**
11
11
 
12
- Built on the [`cyanheads/mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template), this server follows a modular architecture:
12
+ An MCP (Model Context Protocol) server providing a robust, LLM-friendly interface to the standard `git` command-line tool. Enables LLMs and AI agents to perform a wide range of Git operations like clone, commit, push, pull, branch, diff, log, status, and more via the MCP standard.
13
13
 
14
- > **Developer Note**: This repository includes a [.clinerules](.clinerules) file that serves as a developer cheat sheet for your LLM coding agent with quick reference for the codebase patterns, file locations, and code snippets.
14
+ Built on the [`cyanheads/mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template), this server follows a modular architecture with robust error handling, logging, and security features.
15
15
 
16
- ## Table of Contents
16
+ ## 🚀 Core Capabilities: Git Tools 🛠️
17
17
 
18
- | [Overview](#overview) | [Features](#features) | [Installation](#installation) |
18
+ This server equips your AI with a comprehensive suite of tools to interact with Git repositories:
19
19
 
20
- | [Configuration](#configuration) | [Project Structure](#project-structure) |
20
+ | Tool Category | Description | Key Features - |
21
+ | :----------------------- | :---------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
22
+ | **Repository & Staging** | Manage repository state, from initialization to staging changes. | - `git_init`: Initialize a new repository.<br/>- `git_clone`: Clone remote repositories.<br/>- `git_add`: Stage changes for commit.<br/>- `git_status`: Check the status of the working directory.<br/>- `git_clean`: Remove untracked files (requires force flag). - |
23
+ | **Committing & History** | Create commits, inspect history, and view changes over time. | - `git_commit`: Create new commits with conventional messages.<br/>- `git_log`: View commit history with filtering options.<br/>- `git_diff`: Show changes between commits, branches, or the working tree.<br/>- `git_show`: Inspect Git objects like commits and tags. - |
24
+ | **Branching & Merging** | Manage branches, merge changes, and rebase commits. | - `git_branch`: List, create, delete, and rename branches.<br/>- `git_checkout`: Switch between branches or commits.<br/>- `git_merge`: Merge branches together.<br/>- `git_rebase`: Re-apply commits on top of another base.<br/>- `git_cherry_pick`: Apply specific commits from other branches. - |
25
+ | **Remote Operations** | Interact with remote repositories. | - `git_remote`: Manage remote repository connections.<br/>- `git_fetch`: Download objects and refs from a remote.<br/>- `git_pull`: Fetch and integrate with another repository.<br/>- `git_push`: Update remote refs with local changes. - |
26
+ | **Advanced Workflows** | Support for more complex Git workflows and repository management. | - `git_tag`: Create, list, or delete tags.<br/>- `git_stash`: Temporarily store modified files.<br/>- `git_worktree`: Manage multiple working trees attached to a single repository.<br/>- `git_set_working_dir`: Set a persistent working directory for a session.<br/>- `git_wrapup_instructions`: Get a standard workflow for finalizing changes. - |
21
27
 
22
- | [Tools](#tools) | [Resources](#resources) | [Development](#development) | [License](#license) |
28
+ ---
23
29
 
24
- ## Overview
30
+ ## Table of Contents
25
31
 
26
- **Empower your AI agents and development tools with seamless Git integration!**
32
+ | [Overview](#overview) | [Features](#features) | [Installation](#installation) |
33
+ | :------------------------------ | :-------------------------------------- | :---------------------------- | ------------------- |
34
+ | [Configuration](#configuration) | [Project Structure](#project-structure) |
35
+ | [Tools](#tools) | [Resources](#resources) | [Development](#development) | [License](#license) |
27
36
 
28
- The Git MCP Server acts as a bridge, allowing applications (MCP Clients) that understand the Model Context Protocol (MCP) – like advanced AI assistants (LLMs), IDE extensions, or custom scripts – to interact directly and safely with local Git repositories.
37
+ ## Overview
38
+
39
+ The Git MCP Server acts as a bridge, allowing applications (MCP Clients) that understand the Model Context Protocol (MCP) – like advanced AI coding assistants (LLMs), IDE extensions, or custom research tools – to interact directly and safely with local Git repositories.
29
40
 
30
- Instead of complex scripting or manual CLI, your tools can leverage this server to:
41
+ Instead of complex scripting or manual command-line interaction, your tools can leverage this server to:
31
42
 
32
43
  - **Automate Git workflows**: Clone repositories, create branches, stage changes, commit work, push updates, and manage tags programmatically.
33
44
  - **Gain repository insights**: Check status, view logs, diff changes, and inspect Git objects without leaving the host application.
34
- - **Integrate Git into AI-driven development**: Enable LLMs to manage version control as part of their coding or refactoring tasks.
45
+ - **Integrate Git into AI-driven development**: Enable LLMs to manage version control as part of their coding or refactoring tasks, ensuring code integrity and history.
46
+ - **Support CI/CD and DevOps automation**: Build custom scripts and tools that orchestrate complex Git operations for automated builds, testing, and deployments.
35
47
 
36
48
  Built on the robust `mcp-ts-template`, this server provides a standardized, secure, and efficient way to expose Git functionality via the MCP standard. It achieves this by securely executing the standard `git` command-line tool installed on the system using Node.js's `child_process` module, ensuring compatibility and leveraging the full power of Git.
37
49
 
50
+ > **Developer Note**: This repository includes a [.clinerules](.clinerules) file that serves as a developer cheat sheet for your LLM coding agent with quick reference for the codebase patterns, file locations, and code snippets.
51
+
38
52
  ## Features
39
53
 
40
- ### Core Utilities (from Template)
54
+ ### Core Utilities
41
55
 
42
56
  Leverages the robust utilities provided by the `mcp-ts-template`:
43
57
 
44
- - **Logging**: Structured, configurable logging (file rotation, console, MCP notifications) with sensitive data redaction.
58
+ - **Logging**: Structured, configurable logging (file rotation, stdout JSON, MCP notifications) with sensitive data redaction.
45
59
  - **Error Handling**: Centralized error processing, standardized error types (`McpError`), and automatic logging.
46
- - **Configuration**: Environment variable loading (`dotenv`).
60
+ - **Configuration**: Environment variable loading (`dotenv`) with comprehensive validation.
47
61
  - **Input Validation/Sanitization**: Uses `zod` for schema validation and custom sanitization logic (crucial for paths).
48
- - **Request Context**: Tracking and correlation of operations via unique request IDs.
62
+ - **Request Context**: Tracking and correlation of operations via unique request IDs using `AsyncLocalStorage`.
49
63
  - **Type Safety**: Strong typing enforced by TypeScript and Zod schemas.
50
- - **HTTP Transport Option**: Built-in Express server with SSE, session management, and CORS support.
64
+ - **HTTP Transport**: High-performance HTTP server using **Hono**, featuring session management with garbage collection, CORS, and IP-based rate limiting.
65
+ - **Deployment**: Multi-stage `Dockerfile` for creating small, secure production images with native dependency support.
51
66
 
52
- ### Git Operations
67
+ ### Git Integration
53
68
 
54
69
  - **Direct Git CLI Execution**: Interacts with Git by securely executing the standard `git` command-line tool via Node.js `child_process`, ensuring full compatibility and access to Git's features.
55
70
  - **Comprehensive Command Coverage**: Exposes a wide range of Git commands as MCP tools (see [Tools](#tools) section).
@@ -62,39 +77,63 @@ Leverages the robust utilities provided by the `mcp-ts-template`:
62
77
 
63
78
  ### Prerequisites
64
79
 
65
- - [Node.js (>=18.0.0)](https://nodejs.org/)
80
+ - [Node.js (>=20.0.0)](https://nodejs.org/)
66
81
  - [npm](https://www.npmjs.com/) (comes with Node.js)
67
82
  - [Git](https://git-scm.com/) installed and accessible in the system PATH.
68
83
 
69
- ### Install via npm
70
-
71
- 1. Install the package globally:
72
- ```bash
73
- npm install @cyanheads/git-mcp-server
74
- ```
75
-
76
- ### Install from Source
77
-
78
- 1. Clone the repository:
79
- ```bash
80
- git clone https://github.com/cyanheads/git-mcp-server.git
81
- cd git-mcp-server
82
- ```
83
- 2. Install dependencies:
84
- ```bash
85
- npm install
86
- ```
87
- 3. Build the project:
88
- ```bash
89
- npm run build (or `npm run rebuild`)
90
- ```
91
- This compiles the TypeScript code to JavaScript in the `dist/` directory and makes the entry point executable.
84
+ ### MCP Client Settings
85
+
86
+ Add the following to your MCP client's configuration file (e.g., `cline_mcp_settings.json`). This configuration uses `npx` to run the server, which will automatically install the package if not already present:
87
+
88
+ ```json
89
+ {
90
+ "mcpServers": {
91
+ "git-mcp-server": {
92
+ "command": "npx",
93
+ "args": ["@cyanheads/git-mcp-server"],
94
+ "env": {
95
+ "MCP_LOG_LEVEL": "info",
96
+ "GIT_SIGN_COMMITS": "false"
97
+ }
98
+ }
99
+ }
100
+ }
101
+ ```
102
+
103
+ ### If running manually (not via MCP client for development or testing)
104
+
105
+ #### Install via npm
106
+
107
+ ```bash
108
+ npm install @cyanheads/git-mcp-server
109
+ ```
110
+
111
+ #### Alternatively Install from Source (recommended for development)
112
+
113
+ 1. Clone the repository:
114
+
115
+ ```bash
116
+ git clone https://github.com/cyanheads/git-mcp-server.git
117
+ cd git-mcp-server
118
+ ```
119
+
120
+ 2. Install dependencies:
121
+
122
+ ```bash
123
+ npm install
124
+ ```
125
+
126
+ 3. Build the project:
127
+ ```bash
128
+ npm run build
129
+ # or npm run rebuild
130
+ ```
92
131
 
93
132
  ## Configuration
94
133
 
95
134
  ### Environment Variables
96
135
 
97
- Configure the server using environment variables. Create a `.env` file in the project root (copy from `.env.example`) or set them in your environment.
136
+ Configure the server using environment variables. These environmental variables are set within your MCP client config/settings (e.g. `claude_desktop_config.json` for Claude Desktop)
98
137
 
99
138
  | Variable | Description | Default |
100
139
  | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
@@ -106,28 +145,6 @@ Configure the server using environment variables. Create a `.env` file in the pr
106
145
  | `GIT_SIGN_COMMITS` | Set to `"true"` to enable signing attempts for commits made by the `git_commit` tool. Requires server-side Git/key setup (see below). | `false` |
107
146
  | `MCP_AUTH_SECRET_KEY` | Secret key for signing/verifying authentication tokens (required if auth is enabled in the future). | `''` |
108
147
 
109
- ### MCP Client Settings
110
-
111
- Add to your MCP client settings (e.g., `cline_mcp_settings.json`):
112
-
113
- ```json
114
- {
115
- "mcpServers": {
116
- "git-mcp-server": {
117
- "command": "node",
118
- "args": ["/path/to/your/git-mcp-server/dist/index.js"],
119
- "env": {
120
- "GIT_SIGN_COMMITS": "true"
121
- },
122
- "disabled": false,
123
- "autoApprove": []
124
- }
125
- }
126
- }
127
- ```
128
-
129
- **Note**: You can see [mcp.json](mcp.json) for an example MCP client configuration file that includes the Git MCP Server.\*
130
-
131
148
  ## Project Structure
132
149
 
133
150
  The codebase follows a modular structure within the `src/` directory:
@@ -186,14 +203,12 @@ _Note: The `path` parameter for most tools defaults to the session's working dir
186
203
 
187
204
  **MCP Resources are not implemented in this version (v2.1.2).**
188
205
 
189
- This version focuses on the refactored Git tools implementation based on the latest `mcp-ts-template` and MCP SDK v1.12.3. Resource capabilities, previously available, have been temporarily removed during this major update.
206
+ This version focuses on the refactored Git tools implementation based on the latest `mcp-ts-template` and MCP SDK v1.13.0. Resource capabilities, previously available, have been temporarily removed during this major update.
190
207
 
191
208
  If you require MCP Resource access (e.g., for reading file content directly via the server), please use the stable **[v1.2.4 release](https://github.com/cyanheads/git-mcp-server/releases/tag/v1.2.4)**.
192
209
 
193
210
  Future development may reintroduce resource capabilities in a subsequent release.
194
211
 
195
- > **Note:** This version (v2.0.0) focuses on refactoring and updating the core Git tools based on the latest MCP SDK. MCP Resource capabilities are not implemented in this version. For resource access, please use [v1.2.4](https://github.com/cyanheads/git-mcp-server/releases/tag/v1.2.4).
196
-
197
212
  ## Development
198
213
 
199
214
  ### Build and Test
@@ -208,15 +223,18 @@ npm run inspector
208
223
  # Test the server locally using the MCP inspector tool (http transport)
209
224
  npm run inspector:http
210
225
 
211
- # Clean build artifacts (runs scripts/clean.ts)
226
+ # Clean build artifacts
212
227
  npm run clean
213
228
 
214
- # Generate a file tree representation for documentation (runs scripts/tree.ts)
229
+ # Generate a file tree representation for documentation
215
230
  npm run tree
216
231
 
217
232
  # Clean build artifacts and then rebuild the project
218
233
  npm run rebuild
219
234
 
235
+ # Format code with Prettier
236
+ npm run format
237
+
220
238
  # Start the server using stdio (default)
221
239
  npm start
222
240
  # Or explicitly:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cyanheads/git-mcp-server",
3
- "version": "2.1.2",
3
+ "version": "2.1.3",
4
4
  "description": "An MCP (Model Context Protocol) server enabling LLMs and AI agents to interact with Git repositories. Provides tools for comprehensive Git operations including clone, commit, branch, diff, log, status, push, pull, merge, rebase, worktree, tag management, and more, via the MCP standard. STDIO & HTTP.",
5
5
  "main": "dist/index.js",
6
6
  "files": [
@@ -35,12 +35,12 @@
35
35
  "clean": "ts-node --esm scripts/clean.ts"
36
36
  },
37
37
  "dependencies": {
38
- "@modelcontextprotocol/inspector": "^0.14.1",
39
- "@modelcontextprotocol/sdk": "^1.12.3",
40
- "@types/jsonwebtoken": "^9.0.9",
41
- "@types/node": "^24.0.1",
38
+ "@modelcontextprotocol/inspector": "^0.14.3",
39
+ "@modelcontextprotocol/sdk": "^1.13.0",
40
+ "@types/jsonwebtoken": "^9.0.10",
41
+ "@types/node": "^24.0.3",
42
42
  "@types/sanitize-html": "^2.16.0",
43
- "@types/validator": "^13.15.1",
43
+ "@types/validator": "^13.15.2",
44
44
  "chalk": "^5.4.1",
45
45
  "chrono-node": "2.8.0",
46
46
  "cli-table3": "^0.6.5",
@@ -49,7 +49,7 @@
49
49
  "ignore": "^7.0.5",
50
50
  "jose": "^6.0.11",
51
51
  "jsonwebtoken": "^9.0.2",
52
- "openai": "^5.3.0",
52
+ "openai": "^5.6.0",
53
53
  "partial-json": "^0.1.7",
54
54
  "sanitize-html": "^2.17.0",
55
55
  "tiktoken": "^1.0.21",
@@ -59,7 +59,7 @@
59
59
  "winston": "^3.17.0",
60
60
  "winston-daily-rotate-file": "^5.0.0",
61
61
  "yargs": "^18.0.0",
62
- "zod": "^3.25.64"
62
+ "zod": "^3.25.67"
63
63
  },
64
64
  "keywords": [
65
65
  "typescript",