@cyanheads/git-mcp-server 2.0.2 → 2.0.3

package/README.md

@@ -1,8 +1,8 @@
 # Git MCP Server
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue.svg)](https://www.typescriptlang.org/)
-[![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.10.2-green.svg)](https://modelcontextprotocol.io/)
-[![Version](https://img.shields.io/badge/Version-2.0.2-blue.svg)](./CHANGELOG.md)
+[![Model Context Protocol](https://img.shields.io/badge/MCP%20SDK-^1.11.0-green.svg)](https://modelcontextprotocol.io/)
+[![Version](https://img.shields.io/badge/Version-2.0.3-blue.svg)](./CHANGELOG.md)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Status](https://img.shields.io/badge/Status-Stable-green.svg)](https://github.com/cyanheads/git-mcp-server/issues)
 [![GitHub](https://img.shields.io/github/stars/cyanheads/git-mcp-server?style=social)](https://github.com/cyanheads/git-mcp-server)
@@ -11,64 +11,13 @@ An MCP (Model Context Protocol) server providing tools to interact with Git repo
 
 Built on the [`cyanheads/mcp-ts-template`](https://github.com/cyanheads/mcp-ts-template), this server follows a modular architecture:
 
-> **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).
-
-```mermaid
-flowchart TB
-    subgraph API["API Layer"]
-        direction LR
-        MCP["MCP Protocol"]
-        Val["Validation (Zod)"]
-        San["Sanitization"]
-
-        MCP --> Val --> San
-    end
-
-    subgraph Core["Core Components"]
-        direction LR
-        Config["Configuration"]
-        Logger["Logging System"]
-        Error["Error Handling"]
-        Server["MCP Server (SDK)"]
-
-        Config --> Server
-        Logger --> Server
-        Error --> Server
-    end
-
-    subgraph Implementation["Implementation Layer"]
-        direction LR
-        Tool["Tools (Git Logic)"]
-        Util["Utilities"]
-
-        Tool --> Server
-        Util --> Tool
-    end
-
-    San --> Config
-    San --> Server
-
-    classDef layer fill:#2d3748,stroke:#4299e1,stroke-width:3px,rx:5,color:#fff
-    classDef component fill:#1a202c,stroke:#a0aec0,stroke-width:2px,rx:3,color:#fff
-    class API,Core,Implementation layer
-    class MCP,Val,San,Config,Logger,Error,Server,Tool,Util component
-```
-
-Implemented as an MCP server, it allows LLM agents and other compatible clients to interact with local Git repositories using standardized commands.
-
 > **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.
 
 ## Table of Contents
 
-- [Overview](#overview)
-- [Features](#features)
-- [Installation](#installation)
-- [Configuration](#configuration)
-- [Project Structure](#project-structure)
-- [Tools](#tools)
-- [Resources](#resources)
-- [Development](#development)
-- [License](#license)
+| [Overview](#overview) | [Features](#features) | [Installation](#installation) |
+| [Configuration](#configuration) | [Project Structure](#project-structure) |
+| [Tools](#tools) | [Resources](#resources) | [Development](#development) | [License](#license) |
 
 ## Overview
 
@@ -101,20 +50,27 @@ Leverages the robust utilities provided by the `mcp-ts-template`:
 ### Git Operations
 
 - **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.
-
 - **Comprehensive Command Coverage**: Exposes a wide range of Git commands as MCP tools (see [Tools](#tools) section).
 - **Repository Interaction**: Supports status checking, branching, staging, committing, fetching, pulling, pushing, diffing, logging, resetting, tagging, and more.
 - **Working Directory Management**: Allows setting and clearing a session-specific working directory for context persistence across multiple Git operations.
 - **Safety Features**: Includes checks and requires explicit confirmation for potentially destructive operations like `git clean` and `git reset --hard`.
+- **Commit Signing**: Supports GPG or SSH signing for verified commits, controlled via the `GIT_SIGN_COMMITS` environment variable and server-side Git configuration. Includes an optional tool parameter to fall back to unsigned commits on signing failure.
 
 ## Installation
 
 ### Prerequisites
 
-- [Node.js (v18+)](https://nodejs.org/)
+- [Node.js (>=18.0.0)](https://nodejs.org/)
 - [npm](https://www.npmjs.com/) (comes with Node.js)
 - [Git](https://git-scm.com/) installed and accessible in the system PATH.
 
+### Install via npm
+
+1.  Install the package globally:
+    ```bash
+    npm install git-mcp-server
+    ```
+
 ### Install from Source
 
 1.  Clone the repository:
@@ -128,9 +84,9 @@ Leverages the robust utilities provided by the `mcp-ts-template`:
     ```
 3.  Build the project:
     ```bash
-    npm run build
+    npm run build (or `npm run rebuild`)
     ```
-    This compiles the TypeScript code to JavaScript in the `build/` directory and makes the entry point executable.
+    This compiles the TypeScript code to JavaScript in the `dist/` directory and makes the entry point executable.
 
 ## Configuration
 
@@ -138,20 +94,14 @@ Leverages the robust utilities provided by the `mcp-ts-template`:
 
 Configure the server using environment variables. Create a `.env` file in the project root (copy from `.env.example`) or set them in your environment.
 
-| Variable               | Description                                                                              | Default             |
-| ---------------------- | ---------------------------------------------------------------------------------------- | ------------------- |
-| `MCP_TRANSPORT_TYPE`   | Transport mechanism: `stdio` or `http`.                                                  | `stdio`             |
-| `MCP_HTTP_PORT`        | Port for the HTTP server (if `MCP_TRANSPORT_TYPE=http`). Retries next ports if busy.     | `3000`              |
-| `MCP_HTTP_HOST`        | Host address for the HTTP server (if `MCP_TRANSPORT_TYPE=http`).                         | `127.0.0.1`         |
-| `MCP_ALLOWED_ORIGINS`  | Comma-separated list of allowed origins for CORS (if `MCP_TRANSPORT_TYPE=http`).         | (none)              |
-| `MCP_SERVER_NAME`      | Name reported during MCP initialization.                                                 | `git-mcp-server`    |
-| `MCP_SERVER_VERSION`   | Version reported during MCP initialization.                                              | (from package.json) |
-| `LOG_LEVEL`            | Logging level (`debug`, `info`, `notice`, `warning`, `error`, `crit`, `alert`, `emerg`). | `info`              |
-| `LOG_REDACT_PATTERNS`  | Comma-separated regex patterns for redacting sensitive data in logs.                     | (predefined)        |
-| `LOG_FILE_PATH`        | Path for log file output. If unset, logs only to console.                                | (none)              |
-| `LOG_MAX_FILE_SIZE_MB` | Max size (MB) for log file rotation.                                                     | `10`                |
-| `LOG_MAX_FILES`        | Max number of rotated log files to keep.                                                 | `5`                 |
-| `LOG_ZIP_ARCHIVES`     | Compress rotated log files (`true`/`false`).                                             | `true`              |
+| Variable              | Description                                                                                                                           | Default     |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `MCP_TRANSPORT_TYPE`  | Transport mechanism: `stdio` or `http`.                                                                                               | `stdio`     |
+| `MCP_HTTP_PORT`       | Port for the HTTP server (if `MCP_TRANSPORT_TYPE=http`). Retries next ports if busy.                                                  | `3000`      |
+| `MCP_HTTP_HOST`       | Host address for the HTTP server (if `MCP_TRANSPORT_TYPE=http`).                                                                      | `127.0.0.1` |
+| `MCP_ALLOWED_ORIGINS` | Comma-separated list of allowed origins for CORS (if `MCP_TRANSPORT_TYPE=http`).                                                      | (none)      |
+| `MCP_LOG_LEVEL`       | Logging level (`debug`, `info`, `notice`, `warning`, `error`, `crit`, `alert`, `emerg`). Inherited from template.                     | `info`      |
+| `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`     |
 
 ### MCP Client Settings
 
@@ -160,12 +110,14 @@ Add to your MCP client settings (e.g., `cline_mcp_settings.json`):
 ```json
 {
   "mcpServers": {
-    "git": {
+    "git-mcp-server": {
+      // Use a descriptive name
       "command": "node", // Use node to run the script
-      "args": ["/path/to/your/git-mcp-server/build/index.js"], // Absolute path to the built entry point
+      "args": ["/path/to/your/git-mcp-server/dist/index.js"], // Absolute path to the built entry point
       "env": {
         // "MCP_TRANSPORT_TYPE": "http", // Optional: if using http
-        // "MCP_HTTP_PORT": "3001"      // Optional: if using http and non-default port
+        // "MCP_HTTP_PORT": "3010",     // Optional: if using http and non-default port
+        // "GIT_SIGN_COMMITS": "true"   // Optional: Enable commit signing attempts if server is configured
       },
       "disabled": false,
       "autoApprove": [] // Configure auto-approval rules if desired
@@ -184,7 +136,8 @@ src/
 ├── config/            # Configuration loading (env vars, package info)
 │   └── index.ts
 ├── mcp-server/        # Core MCP server logic and capability registration
-│   ├── server.ts      # Server setup, transport handling, tool registration
+│   ├── server.ts      # Server setup, capability registration
+│   ├── transports/    # Transport handling (stdio, http)
 │   ├── resources/     # MCP Resource implementations (currently none)
 │   └── tools/         # MCP Tool implementations (subdirs per tool)
 ├── types-global/      # Shared TypeScript type definitions
@@ -206,7 +159,7 @@ The Git MCP Server provides a suite of tools for interacting with Git repositori
 | `git_clean`             | Removes untracked files. **Requires `force: true`**.                                                     | `path?`, `force`, `dryRun?`, `directories?`, `ignored?`                                                         |
 | `git_clear_working_dir` | Clears the session-specific working directory.                                                           | (none)                                                                                                          |
 | `git_clone`             | Clones a repository into a specified absolute path.                                                      | `repositoryUrl`, `targetPath`, `branch?`, `depth?`, `quiet?`                                                    |
-| `git_commit`            | Commits staged changes with a message.                                                                   | `path?`, `message`, `author?`, `allowEmpty?`, `amend?`                                                          |
+| `git_commit`            | Commits staged changes. Supports author override, signing control.                                       | `path?`, `message`, `author?`, `allowEmpty?`, `amend?`, `forceUnsignedOnFailure?`                               |
 | `git_diff`              | Shows changes between commits, working tree, etc.                                                        | `path?`, `commit1?`, `commit2?`, `staged?`, `file?`                                                             |
 | `git_fetch`             | Downloads objects and refs from other repositories.                                                      | `path?`, `remote?`, `prune?`, `tags?`, `all?`                                                                   |
 | `git_init`              | Initializes a new Git repository at the specified absolute path.                                         | `path`, `initialBranch?`, `bare?`, `quiet?`                                                                     |
@@ -227,25 +180,24 @@ _Note: The `path` parameter for most tools defaults to the session's working dir
 
 ## Resources
 
-**MCP Resources are not implemented in this version (v2.0.0).**
+**MCP Resources are not implemented in this version (v2.0.2).**
 
-This version focuses on the refactored Git tools implementation based on the latest `mcp-ts-template` and MCP SDK v1.10.2. Resource capabilities, previously available, have been temporarily removed during this major update.
+This version focuses on the refactored Git tools implementation based on the latest `mcp-ts-template` and MCP SDK v1.11.0. Resource capabilities, previously available, have been temporarily removed during this major update.
 
 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)**.
 
 Future development may reintroduce resource capabilities in a subsequent release.
 
+> **Note:** This version (v2.0.2) 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).
+
 ## Development
 
 ### Build and Test
 
 ```bash
-# Build the project (compile TS to JS in build/ and make executable)
+# Build the project (compile TS to JS in dist/ and make executable)
 npm run build
 
-# Watch for changes and recompile automatically
-npm run watch
-
 # Test the server locally using the MCP inspector tool (stdio transport)
 npm run inspector
 
@@ -257,6 +209,14 @@ npm run tree
 
 # Clean build artifacts and then rebuild the project
 npm run rebuild
+
+# Start the server using stdio (default)
+npm start
+# Or explicitly:
+npm run start:stdio
+
+# Start the server using HTTP transport
+npm run start:http
 ```
 
 ## License

package/dist/config/index.js

@@ -2,14 +2,14 @@ import dotenv from "dotenv";
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { logger } from "../utils/logger.js"; // Import McpLogLevel and logger
+// Removed logger import to break circular dependency
 dotenv.config(); // Load environment variables from .env file
 // Determine the directory name of the current module
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Construct the path to package.json relative to the current file
 const pkgPath = join(__dirname, '../../package.json');
 // Default package information in case package.json is unreadable
-let pkg = { name: 'mcp-ts-template', version: '0.0.0' };
+let pkg = { name: 'obsidian-mcp-server', version: '0.0.0' };
 try {
     // Read and parse package.json to get server name and version
     pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
@@ -30,12 +30,24 @@ export const config = {
     logLevel: process.env.MCP_LOG_LEVEL || "info", // Use MCP_LOG_LEVEL consistently
     /** The runtime environment (e.g., "development", "production"). Defaults to "development". */
     environment: process.env.NODE_ENV || "development",
+    /** The communication transport type ('stdio' or 'http'). Defaults to 'stdio'. */
+    mcpTransportType: process.env.MCP_TRANSPORT_TYPE || "stdio",
+    /** Port for the HTTP transport. Defaults to 3000. */
+    mcpHttpPort: parseInt(process.env.MCP_HTTP_PORT || "3010", 10),
+    /** Host for the HTTP transport. Defaults to '127.0.0.1'. */
+    mcpHttpHost: process.env.MCP_HTTP_HOST || "127.0.0.1",
+    /** Allowed origins for HTTP transport (comma-separated). */
+    mcpAllowedOrigins: process.env.MCP_ALLOWED_ORIGINS?.split(',') || [],
+    /** Flag to enable GPG signing for commits made by the git_commit tool. Requires server-side GPG setup. */
+    gitSignCommits: process.env.GIT_SIGN_COMMITS === 'true',
     /** Security-related configurations. */
     security: {
         // Placeholder for security settings
         // Example: authRequired: process.env.AUTH_REQUIRED === 'true'
         /** Indicates if authentication is required for server operations. */
         authRequired: false,
+        /** Secret key for signing/verifying authentication tokens (required if authRequired is true). */
+        mcpAuthSecretKey: process.env.MCP_AUTH_SECRET_KEY || '', // Default to empty string, validation should happen elsewhere
     }
     // Note: mcpClient configuration is now loaded separately from mcp-config.json
 };
@@ -51,19 +63,5 @@ export const logLevel = config.logLevel;
  * @type {string}
  */
 export const environment = config.environment;
-// Define valid MCP log levels based on the logger's type definition
-const validMcpLogLevels = ['debug', 'info', 'notice', 'warning', 'error', 'crit', 'alert', 'emerg'];
-// Validate the configured log level
-let validatedMcpLogLevel = 'info'; // Default to 'info'
-if (validMcpLogLevels.includes(logLevel)) {
-    validatedMcpLogLevel = logLevel;
-}
-else {
-    // Silently default to 'info' if the configured level is invalid.
-    // The logger initialization message will show the actual level being used.
-}
-// Initialize the logger with the validated MCP level AFTER config is defined.
-logger.initialize(validatedMcpLogLevel);
-// Log initialization message using the logger itself (will go to file and potentially MCP)
-logger.info(`Logger initialized. MCP logging level: ${validatedMcpLogLevel}`);
-logger.debug("Configuration loaded successfully", { config }); // Log loaded config at debug level
+// Logger initialization is now handled in the main application entry point (e.g., src/index.ts)
+// after the config module has been fully loaded.

package/dist/index.js

@@ -1,15 +1,20 @@
 #!/usr/bin/env node
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; // Import McpServer type
-import { config, environment } from "./config/index.js";
-import { initializeAndStartServer } from "./mcp-server/server.js"; // Updated import
-import { logger } from "./utils/logger.js";
-// Import the service instance instead of the standalone function
-import { requestContextService } from "./utils/requestContext.js";
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import http from 'http'; // Import http module
+import { config, environment, logLevel } from "./config/index.js"; // Import logLevel from config
+import { initializeAndStartServer } from "./mcp-server/server.js";
+// Import utils from barrel
+import { logger, requestContextService } from './utils/index.js'; // Import McpLogLevel type
 /**
- * The main MCP server instance.
+ * The main MCP server instance (used for stdio transport).
  * @type {McpServer | undefined}
  */
-let server;
+let mcpServerInstance;
+/**
+ * The main HTTP server instance (used for http transport).
+ * @type {http.Server | undefined}
+ */
+let httpServerInstance;
 /**
  * Gracefully shuts down the main MCP server.
  * Handles process termination signals (SIGTERM, SIGINT) and critical errors.
@@ -17,22 +22,50 @@ let server;
  * @param signal - The signal or event name that triggered the shutdown (e.g., "SIGTERM", "uncaughtException").
  */
 const shutdown = async (signal) => {
-    // Define context for the shutdown operation
+    const transportType = (process.env.MCP_TRANSPORT_TYPE || 'stdio').toLowerCase();
     const shutdownContext = {
         operation: 'Shutdown',
         signal,
+        transport: transportType,
     };
     logger.info(`Received ${signal}. Starting graceful shutdown...`, shutdownContext);
     try {
-        // Close the main MCP server
-        if (server) {
-            logger.info("Closing main MCP server...", shutdownContext);
-            await server.close();
-            logger.info("Main MCP server closed successfully", shutdownContext);
+        let closePromise = Promise.resolve();
+        if (transportType === 'stdio') {
+            // Close the main MCP server instance for stdio
+            if (mcpServerInstance) {
+                logger.info("Closing main MCP server (stdio)...", shutdownContext);
+                closePromise = mcpServerInstance.close();
+            }
+            else {
+                logger.warning("Stdio MCP server instance not found during shutdown.", shutdownContext);
+            }
         }
-        else {
-            logger.warning("Server instance not found during shutdown.", shutdownContext);
+        else if (transportType === 'http') {
+            // Close the main HTTP server listener for http
+            if (httpServerInstance) {
+                logger.info("Closing main HTTP server listener...", shutdownContext);
+                closePromise = new Promise((resolve, reject) => {
+                    httpServerInstance.close((err) => {
+                        if (err) {
+                            logger.error("Error closing HTTP server listener", { ...shutdownContext, error: err.message });
+                            reject(err);
+                        }
+                        else {
+                            logger.info("Main HTTP server listener closed successfully", shutdownContext);
+                            resolve();
+                        }
+                    });
+                });
+            }
+            else {
+                logger.warning("HTTP server instance not found during shutdown.", shutdownContext);
+            }
+            // Note: Individual session transports (StreamableHTTPServerTransport) are closed
+            // when the client disconnects or sends a DELETE request, managed in httpTransport.ts.
         }
+        // Wait for the appropriate server/listener to close
+        await closePromise;
         logger.info("Graceful shutdown completed successfully", shutdownContext);
         process.exit(0);
     }
@@ -52,7 +85,21 @@ const shutdown = async (signal) => {
  * and registers signal handlers for graceful shutdown and error handling.
  */
 const start = async () => {
-    // Create application-level request context using the service instance
+    // --- Initialize Logger FIRST ---
+    // Define valid MCP log levels based on the logger's type definition
+    const validMcpLogLevels = ['debug', 'info', 'notice', 'warning', 'error', 'crit', 'alert', 'emerg'];
+    let validatedMcpLogLevel = 'info'; // Default to 'info'
+    if (validMcpLogLevels.includes(logLevel)) {
+        validatedMcpLogLevel = logLevel;
+    }
+    else {
+        // Use console.warn as logger isn't ready yet
+        console.warn(`Invalid MCP_LOG_LEVEL "${logLevel}" found in config. Defaulting to "info".`);
+    }
+    // Initialize the logger singleton instance with the validated level.
+    logger.initialize(validatedMcpLogLevel);
+    // Now it's safe to use the logger.
+    // --- Start Application ---
     const transportType = (process.env.MCP_TRANSPORT_TYPE || 'stdio').toLowerCase();
     const startupContext = requestContextService.createRequestContext({
         operation: `ServerStartup_${transportType}`, // Include transport in operation name
@@ -64,22 +111,25 @@ const start = async () => {
     try {
         // Initialize the server instance and start the selected transport
         logger.debug("Initializing and starting MCP server transport", startupContext);
-        // Start the server transport. For stdio, this returns the server instance.
-        // For http, it sets up the listener and returns void (or potentially the http.Server).
-        // We only need to store the instance for stdio shutdown.
-        const potentialServerInstance = await initializeAndStartServer();
-        if (transportType === 'stdio' && potentialServerInstance instanceof McpServer) {
-            server = potentialServerInstance; // Store only for stdio
+        // Start the server transport. This returns the McpServer instance for stdio
+        // or the http.Server instance for http.
+        const serverOrHttpInstance = await initializeAndStartServer();
+        if (transportType === 'stdio' && serverOrHttpInstance instanceof McpServer) {
+            mcpServerInstance = serverOrHttpInstance; // Store McpServer for stdio shutdown
+            logger.debug("Stored McpServer instance for stdio transport.", startupContext);
+        }
+        else if (transportType === 'http' && serverOrHttpInstance instanceof http.Server) {
+            httpServerInstance = serverOrHttpInstance; // Store http.Server for http shutdown
+            logger.debug("Stored http.Server instance for http transport.", startupContext);
         }
         else {
-            // For HTTP, server instances are managed per-session in server.ts
-            // The main http server listener keeps the process alive.
-            // Shutdown for HTTP needs to handle closing the main http server.
-            // We might need to return the httpServer from initializeAndStartServer if
-            // we want to close it explicitly here during shutdown.
-            // For now, we don't store anything globally for HTTP transport.
+            // This case should ideally not happen if initializeAndStartServer works correctly
+            logger.warning("initializeAndStartServer did not return the expected instance type.", {
+                ...startupContext,
+                instanceType: typeof serverOrHttpInstance
+            });
         }
-        // If initializeAndStartServer failed, it would have thrown an error,
+        // If initializeAndStartServer failed internally, it would have thrown an error,
         // and execution would jump to the outer catch block.
         logger.info(`${config.mcpServerName} is running with ${transportType} transport`, {
             ...startupContext,