@cyanheads/git-mcp-server 2.9.1 → 2.10.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 (3) hide show
  1. package/README.md +151 -323
  2. package/dist/index.js +25937 -75115
  3. package/package.json +1 -19
package/README.md CHANGED
@@ -1,68 +1,58 @@
1
1
  <div align="center">
2
2
  <h1>@cyanheads/git-mcp-server</h1>
3
- <p><b>A secure and scalable Git MCP server giving AI agents powerful version control for local and (soon) serverless environments. STDIO & Streamable HTTP</b>
4
- <div>28 Tools • 1 Resource • 1 Prompt</div>
3
+ <p><b>A Git MCP server for AI agents. STDIO & Streamable HTTP.</b>
4
+ <div>28 Tools · 1 Resource · 1 Prompt</div>
5
5
  </p>
6
6
  </div>
7
7
 
8
8
  <div align="center">
9
9
 
10
- [![Version](https://img.shields.io/badge/Version-2.9.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Status](https://img.shields.io/badge/Status-Stable-brightgreen.svg?style=flat-square)](https://github.com/cyanheads/git-mcp-server/issues) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.2.21-blueviolet.svg?style=flat-square)](https://bun.sh/)
10
+ [![Version](https://img.shields.io/badge/Version-2.10.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Status](https://img.shields.io/badge/Status-Stable-brightgreen.svg?style=flat-square)](https://github.com/cyanheads/git-mcp-server/issues) [![TypeScript](https://img.shields.io/badge/TypeScript-^5.9.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.2.21-blueviolet.svg?style=flat-square)](https://bun.sh/)
11
11
 
12
12
  </div>
13
13
 
14
14
  ---
15
15
 
16
- ## 🛠️ Tools Overview
16
+ ## Tools
17
17
 
18
- This server provides 28 comprehensive Git operations organized into seven functional categories:
18
+ 28 git operations organized into seven categories:
19
19
 
20
- | Category | Tools | Description |
21
- | :------------------------ | :----------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
22
- | **Repository Management** | `git_init`, `git_clone`, `git_status`, `git_clean` | Initialize repos, clone from remotes, check status, and clean untracked files |
23
- | **Staging & Commits** | `git_add`, `git_commit`, `git_diff` | Stage changes, create commits, and compare changes |
24
- | **History & Inspection** | `git_log`, `git_show`, `git_blame`, `git_reflog` | View commit history, inspect objects, trace line-by-line authorship, and view ref logs |
25
- | **Analysis** | `git_changelog_analyze` | Gather git context and review instructions for LLM-driven changelog analysis (security, features, storyline, gaps, breaking changes, quality) |
26
- | **Branching & Merging** | `git_branch`, `git_checkout`, `git_merge`, `git_rebase`, `git_cherry_pick` | Manage branches, switch contexts, integrate changes, and apply specific commits |
27
- | **Remote Operations** | `git_remote`, `git_fetch`, `git_pull`, `git_push` | Configure remotes, download updates, synchronize repositories, and publish changes |
28
- | **Advanced Workflows** | `git_tag`, `git_stash`, `git_reset`, `git_worktree`, `git_set_working_dir`, `git_clear_working_dir`, `git_wrapup_instructions` | Tag releases, stash changes, reset state, manage worktrees, set/clear session directory, and access workflow guidance |
20
+ | Category | Tools | Description |
21
+ | :------------------------ | :----------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
22
+ | **Repository Management** | `git_init`, `git_clone`, `git_status`, `git_clean` | Initialize repos, clone from remotes, check status, clean untracked files |
23
+ | **Staging & Commits** | `git_add`, `git_commit`, `git_diff` | Stage changes, create commits, compare changes |
24
+ | **History & Inspection** | `git_log`, `git_show`, `git_blame`, `git_reflog` | View commit history, inspect objects, trace authorship, view ref logs |
25
+ | **Analysis** | `git_changelog_analyze` | Gather git context and instructions for LLM-driven changelog analysis |
26
+ | **Branching & Merging** | `git_branch`, `git_checkout`, `git_merge`, `git_rebase`, `git_cherry_pick` | Manage branches, switch contexts, integrate changes, apply specific commits |
27
+ | **Remote Operations** | `git_remote`, `git_fetch`, `git_pull`, `git_push` | Configure remotes, fetch updates, synchronize repositories, publish changes |
28
+ | **Advanced Workflows** | `git_tag`, `git_stash`, `git_reset`, `git_worktree`, `git_set_working_dir`, `git_clear_working_dir`, `git_wrapup_instructions` | Tag releases, stash changes, reset state, manage worktrees, set/clear session directory |
29
29
 
30
- ## 📦 Resources Overview
30
+ ## Resources
31
31
 
32
- The server provides resources that offer contextual information about the Git environment:
32
+ | Resource | URI | Description |
33
+ | :------------------------ | :------------------------ | :--------------------------------------------------------------------------- |
34
+ | **Git Working Directory** | `git://working-directory` | The current session working directory, set via `git_set_working_dir`. |
33
35
 
34
- | Resource | URI | Description |
35
- | :------------------------ | :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------- |
36
- | **Git Working Directory** | `git://working-directory` | Provides the current session working directory for git operations. This is the directory set via `git_set_working_dir` and used as the default. |
36
+ ## Prompts
37
37
 
38
- ## 🎯 Prompts Overview
38
+ | Prompt | Description | Parameters |
39
+ | :-------------- | :----------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- |
40
+ | **Git Wrap-up** | Workflow protocol for completing git sessions: review, document, commit, and tag changes. | `changelogPath`, `skipDocumentation`, `createTag`, `updateAgentFiles`. |
39
41
 
40
- The server provides structured prompt templates that guide AI agents through complex workflows:
42
+ ## Getting started
41
43
 
42
- | Prompt | Description | Parameters |
43
- | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- |
44
- | **Git Wrap-up** | A systematic workflow protocol for completing git sessions. Guides agents through reviewing, documenting, committing, and tagging changes. | `changelogPath`, `skipDocumentation`, `createTag`, and `updateAgentFiles`. |
44
+ ### Runtime
45
45
 
46
- ## 🚀 Getting Started
46
+ Works with both Bun and Node.js. Runtime is auto-detected.
47
47
 
48
- ### Runtime Compatibility
48
+ | Runtime | Command | Minimum Version |
49
+ | ----------- | --------------------------------------- | --------------- |
50
+ | **Node.js** | `npx @cyanheads/git-mcp-server@latest` | >= 20.0.0 |
51
+ | **Bun** | `bunx @cyanheads/git-mcp-server@latest` | >= 1.2.0 |
49
52
 
50
- This server works with **both Bun and Node.js runtimes**:
53
+ ### MCP client configuration
51
54
 
52
- | Runtime | Command | Minimum Version | Notes |
53
- | ----------- | --------------------------------------- | --------------- | -------------------------- |
54
- | **Node.js** | `npx @cyanheads/git-mcp-server@latest` | ≥ 20.0.0 | Universal compatibility |
55
- | **Bun** | `bunx @cyanheads/git-mcp-server@latest` | ≥ 1.2.0 | Alternative runtime option |
56
-
57
- The server automatically detects the runtime and uses the appropriate process spawning method for git operations.
58
-
59
- ### MCP Client Settings/Configuration
60
-
61
- Add the following to your MCP Client configuration file (e.g., `cline_mcp_settings.json`). Clients have different ways to configure servers, so refer to your client's documentation for specifics.
62
-
63
- **Be sure to update environment variables as needed (especially your Git information!)**
64
-
65
- #### Using npx (Node.js)
55
+ Add the following to your MCP client config (e.g., `cline_mcp_settings.json`). Update the environment variables to match your setup — especially the git identity fields.
66
56
 
67
57
  ```json
68
58
  {
@@ -78,223 +68,122 @@ Add the following to your MCP Client configuration file (e.g., `cline_mcp_settin
78
68
  "LOGS_DIR": "~/Developer/logs/git-mcp-server/",
79
69
  "GIT_USERNAME": "cyanheads",
80
70
  "GIT_EMAIL": "casey@caseyjhand.com",
81
- "GIT_SIGN_COMMITS": "false"
71
+ "GIT_SIGN_COMMITS": "true"
82
72
  }
83
73
  }
84
74
  }
85
75
  }
86
76
  ```
87
77
 
88
- #### Using bunx (Bun)
89
-
90
- ```json
91
- {
92
- "mcpServers": {
93
- "git-mcp-server": {
94
- "type": "stdio",
95
- "command": "bunx",
96
- "args": ["@cyanheads/git-mcp-server@latest"],
97
- "env": {
98
- "MCP_TRANSPORT_TYPE": "stdio",
99
- "MCP_LOG_LEVEL": "info",
100
- "GIT_BASE_DIR": "~/Developer/",
101
- "LOGS_DIR": "~/Developer/logs/git-mcp-server/",
102
- "GIT_USERNAME": "cyanheads",
103
- "GIT_EMAIL": "casey@caseyjhand.com",
104
- "GIT_SIGN_COMMITS": "false"
105
- }
106
- }
107
- }
108
- }
109
- ```
110
-
111
- #### Streamable HTTP Configuration
112
-
113
- ```bash
114
- MCP_TRANSPORT_TYPE=http
115
- MCP_HTTP_PORT=3015
116
- ```
117
-
118
- ## ✨ Server Features
119
-
120
- This server is built on the [`mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template) and inherits its rich feature set:
121
-
122
- - **Declarative Tools**: Define agent capabilities in single, self-contained files. The framework handles registration, validation, and execution.
123
- - **Robust Error Handling**: A unified `McpError` system ensures consistent, structured error responses.
124
- - **Pluggable Authentication**: Secure your server with zero-fuss support for `none`, `jwt`, or `oauth` modes.
125
- - **Abstracted Storage**: Swap storage backends (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2`) without changing business logic.
126
- - **Full-Stack Observability**: Deep insights with structured logging (Pino) and optional, auto-instrumented OpenTelemetry for traces and metrics.
127
- - **Dependency Injection**: Built with `tsyringe` for a clean, decoupled, and testable architecture.
128
- - **Edge-Ready Architecture**: Built on an edge-compatible framework that runs seamlessly on local machines or Cloudflare Workers. _Note: Current git operations use the CLI provider which requires local git installation. Edge deployment support is planned through the isomorphic-git provider integration._
129
-
130
- Plus, specialized features for **Git integration**:
131
-
132
- - **Cross-Runtime Compatibility**: Works seamlessly with both Bun and Node.js runtimes. Automatically detects the runtime and uses optimal process spawning (Bun.spawn in Bun, child_process.spawn in Node.js).
133
- - **Provider-Based Architecture**: Pluggable git provider system with current CLI implementation and planned isomorphic-git provider for edge deployment.
134
- - **Optimized Git Execution**: Direct git CLI interaction with cross-runtime support for high-performance process management, streaming I/O, and timeout handling (current CLI provider).
135
- - **Comprehensive Coverage**: 28 tools covering all essential Git operations from init to push, plus changelog analysis.
136
- - **Working Directory Management**: Session-specific directory context for multi-repo workflows.
137
- - **Configurable Git Identity**: Override author/committer information via environment variables with automatic fallback to global git config.
138
- - **Safety Features**: Explicit confirmations for destructive operations like `git clean` and `git reset --hard`.
139
- - **Commit Signing**: Optional GPG/SSH signing support for all commit-creating operations (commits, merges, rebases, cherry-picks, and tags).
140
-
141
- ### Development Environment Setup
142
-
143
- ### Prerequisites
144
-
145
- - [Node.js v20.0.0+](https://nodejs.org/) (or [Bun v1.2.0+](https://bun.sh/) as an alternative)
146
- - [Git](https://git-scm.com/) installed and accessible in your system PATH
147
-
148
- ### Installation
149
-
150
- 1. **Clone the repository:**
151
-
152
- ```sh
153
- git clone https://github.com/cyanheads/git-mcp-server.git
154
- ```
155
-
156
- 2. **Navigate into the directory:**
157
-
158
- ```sh
159
- cd git-mcp-server
160
- ```
161
-
162
- 3. **Install dependencies:**
163
-
164
- ```sh
165
- npm install
166
- ```
167
-
168
- ## ⚙️ Configuration
169
-
170
- All configuration is centralized and validated at startup in `src/config/index.ts`. Key environment variables in your `.env` file include:
171
-
172
- | Variable | Description | Default |
173
- | :----------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------- |
174
- | `MCP_TRANSPORT_TYPE` | The transport to use: `stdio` or `http`. | `stdio` |
175
- | `MCP_SESSION_MODE` | Session mode for HTTP transport: `stateless`, `stateful`, or `auto`. | `auto` |
176
- | `MCP_RESPONSE_FORMAT` | Response format: `json` (LLM-optimized), `markdown` (human-readable), or `auto`. | `json` |
177
- | `MCP_RESPONSE_VERBOSITY` | Response detail level: `minimal`, `standard`, or `full`. | `standard` |
178
- | `MCP_HTTP_PORT` | The port for the HTTP server. | `3015` |
179
- | `MCP_HTTP_HOST` | The hostname for the HTTP server. | `127.0.0.1` |
180
- | `MCP_HTTP_ENDPOINT_PATH` | The endpoint path for MCP requests. | `/mcp` |
181
- | `MCP_AUTH_MODE` | Authentication mode: `none`, `jwt`, or `oauth`. | `none` |
182
- | `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv`, `r2`. | `in-memory` |
183
- | `OTEL_ENABLED` | Set to `true` to enable OpenTelemetry. | `false` |
184
- | `MCP_LOG_LEVEL` | The minimum level for logging (`debug`, `info`, `warn`, `error`). | `info` |
185
- | `GIT_SIGN_COMMITS` | Set to `"true"` to enable GPG/SSH signing for all commits, merges, rebases, cherry-picks, and tags. Requires GPG/SSH configuration. | `false` |
186
- | `GIT_AUTHOR_NAME` | Git author name. Aliases: `GIT_USERNAME`, `GIT_USER`. Falls back to global git config if not set. | `(none)` |
187
- | `GIT_AUTHOR_EMAIL` | Git author email. Aliases: `GIT_EMAIL`, `GIT_USER_EMAIL`. Falls back to global git config if not set. | `(none)` |
188
- | `GIT_BASE_DIR` | Optional absolute path to restrict all git operations to a specific directory tree. Provides security sandboxing for multi-tenant or shared environments. | `(none)` |
189
- | `GIT_WRAPUP_INSTRUCTIONS_PATH` | Optional path to custom markdown file with Git workflow instructions. | `(none)` |
190
- | `MCP_AUTH_SECRET_KEY` | **Required for `jwt` auth.** A 32+ character secret key. | `(none)` |
191
- | `OAUTH_ISSUER_URL` | **Required for `oauth` auth.** URL of the OIDC provider. | `(none)` |
192
-
193
- ## ▶️ Running the Server
194
-
195
- ### For End Users (via Package Manager)
196
-
197
- The easiest way to use the server is via `npx` (no installation required):
78
+ Bun users: replace `"command": "npx"` with `"command": "bunx"`.
79
+
80
+ For Streamable HTTP, set `MCP_TRANSPORT_TYPE=http` and `MCP_HTTP_PORT=3015`.
81
+
82
+ ## Features
83
+
84
+ Built on [`mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template).
85
+
86
+ | Feature | Details |
87
+ | :-- | :-- |
88
+ | Declarative tools | Define capabilities in single, self-contained files. The framework handles registration, validation, and execution. |
89
+ | Error handling | Unified `McpError` system for consistent, structured error responses. |
90
+ | Authentication | Supports `none`, `jwt`, and `oauth` modes. |
91
+ | Pluggable storage | Swap backends (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2`) without changing business logic. |
92
+ | Observability | Structured logging (Pino) and optional auto-instrumented OpenTelemetry for traces and metrics. |
93
+ | Dependency injection | Built with `tsyringe` for decoupled, testable architecture. |
94
+ | Cross-runtime | Auto-detects Bun or Node.js and uses the appropriate process spawning method. |
95
+ | Provider architecture | Pluggable git provider system. Current: CLI. Planned: isomorphic-git for edge deployment. |
96
+ | Working directory management | Session-specific directory context for multi-repo workflows. |
97
+ | Configurable git identity | Override author/committer info via environment variables, with fallback to global git config. |
98
+ | Commit signing | Optional GPG/SSH signing for commits, merges, rebases, cherry-picks, and tags. |
99
+ | Safety | Destructive operations (`git clean`, `git reset --hard`) require explicit confirmation flags. |
100
+
101
+ ## Security
102
+
103
+ - All file paths are validated and sanitized to prevent directory traversal.
104
+ - Optional `GIT_BASE_DIR` restricts operations to a specific directory tree for multi-tenant sandboxing.
105
+ - Git commands use validated arguments via process spawning — no shell interpolation.
106
+ - JWT and OAuth support for authenticated deployments.
107
+ - Optional rate limiting via the DI-managed `RateLimiter` service.
108
+ - All operations are logged with request context for auditing.
109
+
110
+ ## Configuration
111
+
112
+ All configuration is validated at startup in `src/config/index.ts`. Key environment variables:
113
+
114
+ | Variable | Description | Default |
115
+ | :----------------------------- | :------------------------------------------------------------------------------------------------------------------- | :---------- |
116
+ | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
117
+ | `MCP_SESSION_MODE` | HTTP session mode: `stateless`, `stateful`, or `auto`. | `auto` |
118
+ | `MCP_RESPONSE_FORMAT` | Response format: `json` (LLM-optimized), `markdown` (human-readable), or `auto`. | `json` |
119
+ | `MCP_RESPONSE_VERBOSITY` | Detail level: `minimal`, `standard`, or `full`. | `standard` |
120
+ | `MCP_HTTP_PORT` | HTTP server port. | `3015` |
121
+ | `MCP_HTTP_HOST` | HTTP server hostname. | `127.0.0.1` |
122
+ | `MCP_HTTP_ENDPOINT_PATH` | MCP request endpoint path. | `/mcp` |
123
+ | `MCP_AUTH_MODE` | Authentication mode: `none`, `jwt`, or `oauth`. | `none` |
124
+ | `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv`, `r2`. | `in-memory` |
125
+ | `OTEL_ENABLED` | Enable OpenTelemetry. | `false` |
126
+ | `MCP_LOG_LEVEL` | Minimum log level: `debug`, `info`, `warn`, `error`. | `info` |
127
+ | `GIT_SIGN_COMMITS` | Enable GPG/SSH signing for commits, merges, rebases, cherry-picks, and tags. | `false` |
128
+ | `GIT_AUTHOR_NAME` | Git author name. Aliases: `GIT_USERNAME`, `GIT_USER`. Falls back to global git config. | `(none)` |
129
+ | `GIT_AUTHOR_EMAIL` | Git author email. Aliases: `GIT_EMAIL`, `GIT_USER_EMAIL`. Falls back to global git config. | `(none)` |
130
+ | `GIT_BASE_DIR` | Absolute path to restrict all git operations to a specific directory tree. | `(none)` |
131
+ | `GIT_WRAPUP_INSTRUCTIONS_PATH` | Path to custom markdown file with workflow instructions. | `(none)` |
132
+ | `MCP_AUTH_SECRET_KEY` | Required for `jwt` auth. 32+ character secret key. | `(none)` |
133
+ | `OAUTH_ISSUER_URL` | Required for `oauth` auth. OIDC provider URL. | `(none)` |
134
+
135
+ ## Running the server
136
+
137
+ ### Via package manager (no install)
198
138
 
199
139
  ```sh
200
140
  npx @cyanheads/git-mcp-server@latest
201
141
  ```
202
142
 
203
- Configured through environment variables or your MCP client configuration. Bun users can alternatively use `bunx @cyanheads/git-mcp-server@latest`.
204
-
205
- ### Local Development
206
-
207
- - **Build and run the production version**:
208
-
209
- ```sh
210
- # One-time build
211
- npm run rebuild
212
-
213
- # Run the built server
214
- npm run start:http
215
- # or
216
- npm run start:stdio
217
- ```
143
+ Configure through environment variables or your MCP client config.
218
144
 
219
- - **Development mode with hot reload**:
220
-
221
- ```sh
222
- npm run dev:http
223
- # or
224
- npm run dev:stdio
225
- ```
226
-
227
- - **Run checks and tests**:
228
- ```sh
229
- npm run devcheck # Lints, formats, type-checks, and more
230
- npm test # Runs the test suite
231
- ```
232
-
233
- ### Cloudflare Workers
234
-
235
- 1. **Build the Worker bundle**:
145
+ ### Local development
236
146
 
237
147
  ```sh
238
- npm run build:worker
239
- ```
148
+ # Build and run
149
+ npm run rebuild
150
+ npm run start:stdio # or start:http
240
151
 
241
- 2. **Run locally with Wrangler**:
152
+ # Dev mode with hot reload
153
+ npm run dev:stdio # or dev:http
242
154
 
243
- ```sh
244
- npm run deploy:dev
155
+ # Checks and tests
156
+ npm run devcheck # lint, format, typecheck
157
+ npm test
245
158
  ```
246
159
 
247
- 3. **Deploy to Cloudflare**:
160
+ ### Cloudflare Workers
248
161
 
249
162
  ```sh
250
- npm run deploy:prod
163
+ npm run build:worker # Build the worker bundle
164
+ npm run deploy:dev # Run locally with Wrangler
165
+ npm run deploy:prod # Deploy to Cloudflare
251
166
  ```
252
167
 
253
- ## 📂 Project Structure
254
-
255
- | Directory | Purpose & Contents |
256
- | :-------------------------- | :------------------------------------------------------------------------------- |
257
- | `src/mcp-server/tools` | Your tool definitions (`*.tool.ts`). This is where Git capabilities are defined. |
258
- | `src/mcp-server/resources` | Your resource definitions (`*.resource.ts`). Provides Git context data sources. |
259
- | `src/mcp-server/transports` | Implementations for HTTP and STDIO transports, including auth middleware. |
260
- | `src/storage` | `StorageService` abstraction and all storage provider implementations. |
261
- | `src/services` | Integrations with external services (LLMs, Speech, etc.). |
262
- | `src/container` | Dependency injection container registrations and tokens. |
263
- | `src/utils` | Core utilities for logging, error handling, performance, and security. |
264
- | `src/config` | Environment variable parsing and validation with Zod. |
265
- | `tests/` | Unit and integration tests, mirroring the `src/` directory structure. |
266
-
267
- ## 📤 Understanding Tool Responses
268
-
269
- This server follows MCP's dual-output architecture for all tools ([MCP Tools Specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)):
270
-
271
- ### Response Format Options
168
+ ## Project structure
272
169
 
273
- Configure response format and verbosity via environment variables (see [Configuration](#️-configuration)):
170
+ | Directory | Purpose |
171
+ | :-------------------------- | :--------------------------------------------------------------- |
172
+ | `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Git capabilities live here. |
173
+ | `src/mcp-server/resources` | Resource definitions (`*.resource.ts`). Git context data sources. |
174
+ | `src/mcp-server/transports` | HTTP and STDIO transport implementations, including auth. |
175
+ | `src/storage` | `StorageService` abstraction and provider implementations. |
176
+ | `src/services` | Git service provider (CLI-based git operations). |
177
+ | `src/container` | DI container registrations and tokens. |
178
+ | `src/utils` | Logging, error handling, performance, security utilities. |
179
+ | `src/config` | Environment variable parsing and validation (Zod). |
180
+ | `tests/` | Unit and integration tests, mirroring `src/` structure. |
274
181
 
275
- | Variable | Values | Description |
276
- | :----------------------- | :-------------------------------------- | :------------------------------------------------------------------------ |
277
- | `MCP_RESPONSE_FORMAT` | `json` (default), `markdown`, `auto` | Output format: JSON for LLM parsing, Markdown for human UIs |
278
- | `MCP_RESPONSE_VERBOSITY` | `minimal`, `standard` (default), `full` | Detail level: minimal (core only), standard (balanced), full (everything) |
182
+ ## Response format
279
183
 
280
- ### What Users See (Human-Readable)
281
-
282
- When you invoke a tool through your MCP client, you see a **formatted summary** designed for human consumption. For example, `git_status` might show:
283
-
284
- **Markdown Format:**
285
-
286
- ```
287
- # Git Status: main
288
-
289
- ## Staged (2)
290
- - src/index.ts
291
- - README.md
292
-
293
- ## Unstaged (1)
294
- - package.json
295
- ```
184
+ Configure output format and verbosity via `MCP_RESPONSE_FORMAT` and `MCP_RESPONSE_VERBOSITY`.
296
185
 
297
- **JSON Format (LLM-Optimized):**
186
+ JSON format (default, optimized for LLM consumption):
298
187
 
299
188
  ```json
300
189
  {
@@ -306,123 +195,62 @@ When you invoke a tool through your MCP client, you see a **formatted summary**
306
195
  }
307
196
  ```
308
197
 
309
- ### What the LLM Sees (Complete Structured Data)
198
+ Markdown format (human-readable):
310
199
 
311
- Behind the scenes, the LLM receives **complete structured data** as [content blocks](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-results) via the `responseFormatter` function. This includes:
312
-
313
- - All metadata (commit hashes, timestamps, authors)
314
- - Full file lists and change details (never truncated - LLMs need complete context)
315
- - Structured JSON or formatted markdown based on configuration
316
- - Everything needed to answer follow-up questions
317
-
318
- **Why This Matters**: The LLM can answer detailed questions like "Who made the last commit?" or "What files changed in commit abc123?" because it has access to the full dataset, even if you only saw a summary.
319
-
320
- **Verbosity Levels**: Control the amount of detail returned:
321
-
322
- - **Minimal**: Core data only (success status, primary identifiers)
323
- - **Standard**: Balanced output with essential context (recommended)
324
- - **Full**: Complete data including all metadata and statistics
325
-
326
- **For Developers**: When creating custom tools, always include complete data in your `responseFormatter`. Balance human-readable summaries with comprehensive structured information. See [`AGENTS.md`](AGENTS.md) for response formatter best practices and the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) for technical details.
327
-
328
- ## 🧑‍💻 Agent Development Guide
329
-
330
- For strict rules when using this server with an AI agent, refer to the **`AGENTS.md`** file in this repository. Key principles include:
331
-
332
- - **Logic Throws, Handlers Catch**: Never use `try/catch` in your tool `logic`. Throw an `McpError` instead.
333
- - **Pass the Context**: Always pass the `RequestContext` object through your call stack for logging and tracing.
334
- - **Use the Barrel Exports**: Register new tools and resources only in the `index.ts` barrel files within their respective `definitions` directories.
335
- - **Declarative Tool Pattern**: Each tool is defined in a single `*.tool.ts` file with schema, logic, and response formatting.
336
-
337
- ## 🔒 Security Features
338
-
339
- - **Path Sanitization**: All file paths are validated and sanitized to prevent directory traversal attacks.
340
- - **Base Directory Restriction**: Optional `GIT_BASE_DIR` configuration to restrict all git operations to a specific directory tree, providing security sandboxing for multi-tenant or shared hosting environments.
341
- - **Command Injection Prevention**: Git commands are executed with carefully validated arguments via Bun.spawn.
342
- - **Destructive Operation Protection**: Dangerous operations require explicit confirmation flags.
343
- - **Authentication Support**: Built-in JWT and OAuth support for secure deployments.
344
- - **Rate Limiting**: Optional rate limiting via the DI-managed `RateLimiter` service.
345
- - **Audit Logging**: All Git operations are logged with full context for security auditing.
346
-
347
- ## 🧪 Testing
348
-
349
- Tests run via [Bun's test runner](https://bun.sh/docs/cli/test) with Vitest compatibility.
350
-
351
- - **Run all tests:**
352
-
353
- ```sh
354
- bun test
355
- ```
200
+ ```
201
+ # Git Status: main
356
202
 
357
- - **Run tests with coverage:**
203
+ ## Staged (2)
204
+ - src/index.ts
205
+ - README.md
358
206
 
359
- ```sh
360
- bun test --coverage
361
- ```
207
+ ## Unstaged (1)
208
+ - package.json
209
+ ```
362
210
 
363
- - **Run quality checks (lint, format, typecheck, audit):**
211
+ The LLM always receives the complete structured data via `responseFormatter` — full file lists, metadata, timestamps — regardless of what the client displays. Verbosity controls how much detail is included: `minimal` (core fields only), `standard` (balanced), or `full` (everything).
364
212
 
365
- ```sh
366
- bun run devcheck
367
- ```
213
+ ## Development guide
368
214
 
369
- ## 🗺️ Roadmap
215
+ See [`AGENTS.md`](AGENTS.md) for architecture, tool development patterns, and contribution rules.
370
216
 
371
- ### Planned Git Provider Integrations
217
+ ## Testing
372
218
 
373
- The server uses a **provider-based architecture** to support multiple git implementation backends:
219
+ Tests use [Bun's test runner](https://bun.sh/docs/cli/test) with Vitest compatibility.
374
220
 
375
- - **✅ CLI Provider** (Current): Full-featured git operations via native git CLI
376
- - Implementation coverage for all 28 git tools
377
- - Executes git commands using Bun.spawn for optimal performance
378
- - Streaming I/O handling for large outputs (10MB buffer limit)
379
- - Configurable timeouts (60s default) and automatic process cleanup
380
- - Requires local git installation
381
- - Best for local development and server deployments
221
+ ```sh
222
+ bun test # Run all tests
223
+ bun test --coverage # With coverage
224
+ bun run devcheck # Lint, format, typecheck, audit
225
+ ```
382
226
 
383
- - **🚧 Isomorphic Git Provider** (Planned): Pure JavaScript git implementation
384
- - Edge deployment compatibility (Cloudflare Workers, Vercel Edge, Deno Deploy)
385
- - No system dependencies required
386
- - Enables true serverless git operations
387
- - Core operations: clone, status, add, commit, push, pull, branch, checkout
388
- - Implementation: [isomorphic-git](https://isomorphic-git.org/)
227
+ ## Roadmap
389
228
 
390
- - **💡 GitHub API Provider** (Maybe): Cloud-native git operations via GitHub REST/GraphQL APIs
391
- - No local repository required
392
- - Direct integration with GitHub-hosted repositories
393
- - Ideal for GitHub-centric workflows
229
+ The server uses a provider-based architecture for git operations:
394
230
 
395
- The provider system allows seamless switching between implementations based on deployment environment and requirements. See [`AGENTS.md`](AGENTS.md#git-service-architecture-git-mcp-server-specific) for architectural details.
231
+ - **CLI provider** (current) — Full 28-tool coverage via native git CLI. Requires local git installation.
232
+ - **Isomorphic git provider** (planned) — Pure JS implementation for edge deployment (Cloudflare Workers, Vercel Edge, Deno Deploy). Uses [isomorphic-git](https://isomorphic-git.org/).
233
+ - **GitHub API provider** (maybe) — Cloud-native operations via GitHub REST/GraphQL APIs, no local repo required.
396
234
 
397
- ## 🤝 Contributing
235
+ ## Contributing
398
236
 
399
- Issues and pull requests are welcome! If you plan to contribute, please run the local checks and tests before submitting your PR.
237
+ Issues and pull requests are welcome. Run checks before submitting:
400
238
 
401
239
  ```sh
402
240
  npm run devcheck
403
241
  npm test
404
242
  ```
405
243
 
406
- ### Development Workflow
407
-
408
- 1. Fork the repository
409
- 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
410
- 3. Make your changes following the existing patterns
411
- 4. Run `npm run devcheck` to ensure code quality
412
- 5. Run `npm test` to verify all tests pass
413
- 6. Commit your changes with conventional commits
414
- 7. Push to your fork and open a Pull Request
415
-
416
- ## 📜 License
244
+ ## License
417
245
 
418
- This project is licensed under the Apache 2.0 License. See the [LICENSE](./LICENSE) file for details.
246
+ Apache 2.0. See [LICENSE](./LICENSE).
419
247
 
420
248
  ---
421
249
 
422
250
  <div align="center">
423
- <p>Built with ❤️ using the <a href="https://github.com/cyanheads/mcp-ts-template">mcp-ts-template</a></p>
251
+ <p>Built with the <a href="https://github.com/cyanheads/mcp-ts-template">mcp-ts-template</a></p>
424
252
  <p>
425
- <a href="https://github.com/sponsors/cyanheads">Sponsor this project</a> •
253
+ <a href="https://github.com/sponsors/cyanheads">Sponsor this project</a> ·
426
254
  <a href="https://www.buymeacoffee.com/cyanheads">Buy me a coffee</a>
427
255
  </p>
428
256
  </div>