@selfagency/git-mcp 0.1.2 → 0.2.0

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 (7) hide show
  1. package/README.md +173 -93
  2. package/index.js +3813 -1999
  3. package/index.js.map +1 -1
  4. package/package.json +4 -3
  5. package/skills/git-mcp-workflow/SKILL.md +218 -0
  6. package/skills/git-mcp-workflow/references/tooling-map.md +390 -0
  7. package/skills/git-mcp-workflow/references/workflow-playbooks.md +370 -0
package/README.md CHANGED
@@ -8,14 +8,14 @@ Exposes the full Git workflow to any MCP-compatible AI client — inspect, write
8
8
 
9
9
  ## Features
10
10
 
11
- - **30+ tools** covering everyday Git workflows and advanced recovery operations
11
+ - **11 grouped tools with 60+ actions** covering everyday Git workflows and advanced recovery operations
12
12
  - **Safety-first** — destructive operations require explicit confirmation; force push and hook bypass are opt-in via server config
13
13
  - **GPG/SSH signing** for commits and tags, with server-level auto-sign support
14
14
  - **Git LFS** — track patterns, manage objects, install hooks, migrate history
15
- - **Git Flow** — full branching model (feature/release/hotfix/support) without requiring the `git-flow` CLI
15
+ - **Git Flow** — git-flow-next-style workflow support with preset init, overview, config CRUD, generalized topic actions, finish recovery, optional hook/filter parity, and classic feature/release/hotfix/support aliases, without requiring the external CLI
16
16
  - **Documentation lookup** — search git-scm.com and fetch man pages directly from the LLM
17
17
  - **MCP Resources** — URI-addressable read-only views of status, log, branches, and diff
18
- - **Bundled agent skill** — `skills/git-mcp-workflow/` documents MCP-first Git workflows, recovery, worktrees, releases, and advanced operations for agent users
18
+ - **Bundled agent skill** — `skills/git-mcp-workflow/` documents MCP-first Git workflows, recovery, worktrees, releases, and advanced operations for agent users; installable via [`skills-npm`](https://github.com/antfu/skills-npm)
19
19
  - **Multi-repo** — pass `repo_path` per-call or configure a server-level default
20
20
  - **Cross-platform** — macOS, Linux, Windows (Git for Windows)
21
21
 
@@ -77,6 +77,7 @@ All configuration is via environment variables. Pass them in your MCP client con
77
77
  | `GIT_REPO_PATH` | — | Default repository path (also: `--repo-path` CLI arg) |
78
78
  | `GIT_ALLOW_NO_VERIFY` | `false` | Allow `--no-verify` on commit/push (bypasses hooks) |
79
79
  | `GIT_ALLOW_FORCE_PUSH` | `false` | Allow `--force` on push |
80
+ | `GIT_ALLOW_FLOW_HOOKS` | `false` | Allow `git_flow` hooks and filters to execute |
80
81
  | `GIT_AUTO_SIGN_COMMITS` | `false` | Automatically sign every commit |
81
82
  | `GIT_AUTO_SIGN_TAGS` | `false` | Automatically sign every tag |
82
83
  | `GIT_SIGNING_KEY` | — | Default GPG key ID or SSH key path |
@@ -86,85 +87,124 @@ All configuration is via environment variables. Pass them in your MCP client con
86
87
 
87
88
  ## Tool Reference
88
89
 
89
- ### Inspect (read-only)
90
-
91
- | Tool | Description |
92
- | ------------ | ------------------------------------------ |
93
- | `git_status` | Working tree and branch status |
94
- | `git_log` | Commit history with filters and pagination |
95
- | `git_show` | Patch and metadata for any ref |
96
- | `git_diff` | Unstaged, staged, or ref-to-ref diff |
97
- | `git_blame` | Line-level author attribution |
98
- | `git_reflog` | HEAD movement history for recovery |
99
-
100
- ### Write
101
-
102
- | Tool | Description |
103
- | ------------- | ---------------------------------------- |
104
- | `git_add` | Stage files |
105
- | `git_restore` | Restore paths from index or a source ref |
106
- | `git_commit` | Create commits (amend, sign, no-verify) |
107
- | `git_reset` | Soft/mixed/hard reset |
108
- | `git_revert` | Safe undo via revert commit |
109
-
110
- ### Branches
111
-
112
- | Tool | Description |
113
- | ------------------- | -------------------------------- |
114
- | `git_list_branches` | List local or all branches |
115
- | `git_create_branch` | Create branch from HEAD or ref |
116
- | `git_delete_branch` | Delete a local branch |
117
- | `git_rename_branch` | Rename a branch |
118
- | `git_checkout` | Switch to branch, tag, or commit |
119
- | `git_set_upstream` | Set upstream tracking |
120
-
121
- ### Remote
122
-
123
- | Tool | Description |
124
- | ------------ | ----------------------------------------- |
125
- | `git_remote` | Add, remove, or set-url for a remote |
126
- | `git_fetch` | Fetch with optional pruning |
127
- | `git_pull` | Pull with merge or rebase |
128
- | `git_push` | Push (force-with-lease, force, no-verify) |
129
-
130
- ### Advanced
131
-
132
- | Tool | Description |
133
- | ----------------- | ------------------------------------------- |
134
- | `git_stash` | Save, list, apply, pop, or drop stashes |
135
- | `git_rebase` | Start, continue, skip, or abort rebase |
136
- | `git_cherry_pick` | Start, continue, or abort cherry-pick |
137
- | `git_bisect` | Binary search to find regressions |
138
- | `git_tag` | List, create, or delete tags (with signing) |
139
- | `git_worktree` | Add, list, or remove worktrees |
140
- | `git_submodule` | Add, list, update, or sync submodules |
141
-
142
- ### Context & Config
143
-
144
- | Tool | Description |
145
- | --------------------- | ------------------------------------------ |
146
- | `git_context_summary` | High-signal repo summary for LLM workflows |
147
- | `git_search` | Pickaxe + grep across history |
148
- | `git_get_config` | Read git config values |
149
- | `git_set_config` | Write repository-local git config |
150
-
151
- ### LFS
152
-
153
- | Tool | Description |
154
- | --------- | --------------------------------------------------------- |
155
- | `git_lfs` | Track patterns, pull/push objects, install hooks, migrate |
156
-
157
- ### Git Flow
158
-
159
- | Tool | Description |
160
- | ---------- | ------------------------------------------------- |
161
- | `git_flow` | Init, feature, release, hotfix, support workflows |
162
-
163
- ### Documentation
164
-
165
- | Tool | Description |
166
- | ---------- | ------------------------------------- |
167
- | `git_docs` | Search git-scm.com or fetch man pages |
90
+ Tools are grouped by domain. Each root tool takes an `action` parameter that selects the operation. Where an action is marked as default, omitting `action` will use it.
91
+
92
+ ### Context (`git_context`)
93
+
94
+ | Action | Description |
95
+ | ------------ | ----------------------------------------------------------------------------------------- |
96
+ | `summary` | _(default)_ Full repo snapshot: branch, upstream, pending changes, in-progress operations |
97
+ | `search` | Search commit history and working tree content |
98
+ | `get_config` | Read a Git config value |
99
+ | `set_config` | Write a Git config value |
100
+ | `aliases` | List all configured git aliases |
101
+
102
+ ### Status (`git_status`)
103
+
104
+ | Action | Description |
105
+ | ----------- | ---------------------------------------------------------------------------- |
106
+ | `status` | _(default)_ Working tree and branch status |
107
+ | `diff` | Unstaged, staged, or ref-to-ref diff |
108
+ | `diff_main` | Changes from branch divergence point vs `main` (or configurable base branch) |
109
+
110
+ ### History (`git_history`)
111
+
112
+ | Action | Description |
113
+ | -------- | --------------------------------------------------------------------------------- |
114
+ | `log` | _(default)_ Commit log with filtering, pagination, revision ranges, and pathspecs |
115
+ | `show` | Inspect a single commit |
116
+ | `blame` | Line-by-line attribution for a file |
117
+ | `reflog` | Full reflog — the recovery ledger |
118
+ | `lg` | Compact graph log (`--oneline --graph --decorate --all`) |
119
+ | `who` | Contributor shortlog (supports optional `file_path`) |
120
+
121
+ ### Commits (`git_commits`)
122
+
123
+ | Action | Description |
124
+ | --------- | ------------------------------------------------------- |
125
+ | `add` | Stage files or hunks |
126
+ | `restore` | Discard working tree changes |
127
+ | `unstage` | Remove files from the staging area |
128
+ | `commit` | Create a commit with message, signing, and author flags |
129
+ | `amend` | Amend the last commit without editing the message |
130
+ | `wip` | Stage all changes and commit with message `WIP` |
131
+ | `revert` | Create a revert commit for a given ref |
132
+ | `undo` | Soft-reset the last commit (`reset --soft HEAD~1`) |
133
+ | `reset` | Reset HEAD with configurable mode (soft/mixed/hard) |
134
+ | `nuke` | Hard-reset the last commit — requires `confirm=true` |
135
+
136
+ ### Branches (`git_branches`)
137
+
138
+ | Action | Description |
139
+ | -------------- | ------------------------------------------- |
140
+ | `list` | _(default)_ Local and remote branch listing |
141
+ | `create` | Create a branch |
142
+ | `delete` | Delete a branch |
143
+ | `rename` | Rename a branch |
144
+ | `checkout` | Switch to a branch or ref |
145
+ | `set_upstream` | Set or update tracking upstream |
146
+ | `recent` | Recent branches sorted by committer date |
147
+
148
+ ### Remotes (`git_remotes`)
149
+
150
+ | Action | Description |
151
+ | -------- | ---------------------------------------------- |
152
+ | `list` | _(default)_ List configured remotes |
153
+ | `manage` | Add, remove, or rename a remote |
154
+ | `fetch` | Fetch from a remote |
155
+ | `pull` | Pull (fetch + merge/rebase) |
156
+ | `push` | Push to a remote; `force_with_lease` supported |
157
+
158
+ ### Workspace (`git_workspace`)
159
+
160
+ | Action | Description |
161
+ | ------------- | ------------------------------------------------------------- |
162
+ | `stash` | Stash and pop/apply/drop/list/show stash entries |
163
+ | `stash_all` | Stash tracked and untracked changes in one operation |
164
+ | `rebase` | Start, continue, abort, or skip a rebase |
165
+ | `cherry_pick` | Apply one or more commits; supports continue/abort/skip |
166
+ | `merge` | Merge branches with full flag control |
167
+ | `bisect` | Binary search for a regression (start, good, bad, reset, log) |
168
+ | `tag` | Create, list, delete, or push tags; supports GPG/SSH signing |
169
+ | `worktree` | Add, list, remove, or prune linked worktrees |
170
+ | `submodule` | Add, update, sync, init, deinit, and list submodules |
171
+
172
+ ### Git Flow (`git_flow`)
173
+
174
+ Preset git-flow-next workflow without requiring the external CLI.
175
+
176
+ | Operation | Description |
177
+ | ---------- | --------------------------------------------------------------- |
178
+ | `init` | Initialize a repository with git-flow branch conventions |
179
+ | `overview` | Show the current flow state and active branches |
180
+ | `config` | Read or write git-flow configuration values |
181
+ | `topic` | Generalized topic branch action (start, finish, publish, track) |
182
+ | `control` | Flow control: resume interrupted finish, abort, or recover |
183
+
184
+ ### LFS (`git_lfs`)
185
+
186
+ | Action | Description |
187
+ | ---------------- | ------------------------------------------ |
188
+ | `track` | Add a tracking pattern to `.gitattributes` |
189
+ | `untrack` | Remove a tracking pattern |
190
+ | `ls-files` | List tracked LFS files |
191
+ | `status` | Show LFS status |
192
+ | `pull` | Pull LFS objects |
193
+ | `push` | Push LFS objects |
194
+ | `install` | Install LFS hooks in the repository |
195
+ | `migrate-import` | Migrate existing history to LFS |
196
+ | `migrate-export` | Migrate LFS history back to plain objects |
197
+
198
+ ### Documentation (`git_docs`)
199
+
200
+ | Action | Description |
201
+ | -------- | ------------------------------------ |
202
+ | `search` | Search git-scm.com for documentation |
203
+ | `man` | Fetch and return a Git man page |
204
+
205
+ ### Health Check (`git_ping`)
206
+
207
+ Returns server status. Useful for confirming the server is reachable.
168
208
 
169
209
  ---
170
210
 
@@ -181,6 +221,57 @@ URI-addressable read-only snapshots (subscribe-capable):
181
221
 
182
222
  ---
183
223
 
224
+ ## Bundled Agent Skill
225
+
226
+ git-mcp ships a bundled agent skill at `skills/git-mcp-workflow/` that teaches any `skills-npm`-compatible agent to use the MCP tool surface instead of running raw `git` CLI commands. The skill covers:
227
+
228
+ - Why LLMs must not use the Git CLI (quoting hazards, silent failures)
229
+ - Inspect-before-mutate workflow rules
230
+ - Safety order for undo and recovery operations
231
+ - Full registered tool surface with action reference
232
+ - Workflow playbooks: feature branch, rebase, recovery, worktree, backport, release tagging, Git Flow, merge
233
+ - Git concept explanations anchored to MCP tools
234
+
235
+ ### Installing the skill
236
+
237
+ If your agent supports [skills-npm](https://github.com/antfu/skills-npm):
238
+
239
+ ```bash
240
+ npm install @selfagency/git-mcp # or pnpm/yarn
241
+ npx skills-npm
242
+ ```
243
+
244
+ Or add to your project's `package.json` so it runs automatically:
245
+
246
+ ```json
247
+ {
248
+ "scripts": {
249
+ "prepare": "skills-npm"
250
+ }
251
+ }
252
+ ```
253
+
254
+ Then add to `.gitignore`:
255
+
256
+ ```txt
257
+ skills/npm-*
258
+ ```
259
+
260
+ ---
261
+
262
+ ## Safety
263
+
264
+ - All mutating tools have `destructiveHint: true` in their MCP annotations
265
+ - `git_commits action=reset mode=hard` requires `confirm=true`
266
+ - `git_commits action=nuke` requires `confirm=true`
267
+ - Force push (`--force`) is disabled unless `GIT_ALLOW_FORCE_PUSH=true`; `force_with_lease` is always available
268
+ - Hook bypass (`--no-verify`) is disabled unless `GIT_ALLOW_NO_VERIFY=true`
269
+ - `git_flow` hook and filter execution is disabled unless `GIT_ALLOW_FLOW_HOOKS=true`
270
+ - Paths are validated against the repository root — traversal attempts are rejected
271
+ - Credentials and tokens are never included in responses
272
+
273
+ ---
274
+
184
275
  ## Development
185
276
 
186
277
  ```bash
@@ -213,17 +304,6 @@ pnpm docs:build
213
304
 
214
305
  ---
215
306
 
216
- ## Safety
217
-
218
- - All mutating tools have `destructiveHint: true` in their MCP annotations
219
- - `git_reset --hard` requires `confirm=true`
220
- - Force push (`--force`) is disabled unless `GIT_ALLOW_FORCE_PUSH=true`
221
- - Hook bypass (`--no-verify`) is disabled unless `GIT_ALLOW_NO_VERIFY=true`
222
- - Paths are validated against the repository root — traversal attempts are rejected
223
- - Credentials and tokens are never included in responses
224
-
225
- ---
226
-
227
307
  ## License
228
308
 
229
309
  MIT © [Daniel Sieradski](https://self.agency)