@cyanheads/git-mcp-server 2.2.1 → 2.2.3

package/README.md

@@ -1,18 +1,31 @@
-# Git MCP Server
+<div align="center">
 
-[![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.15.1-green.svg)](https://modelcontextprotocol.io/)
-[![Version](https://img.shields.io/badge/Version-2.2.0-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)
+# @cyanheads/git-mcp-server
 
 **Empower your AI agents with comprehensive, secure, and programmatic control over Git repositories!**
 
+[![TypeScript](https://img.shields.io/badge/TypeScript-^5.8.3-blue?style=flat-square)](https://www.typescriptlang.org/)
+[![Model Context Protocol SDK](https://img.shields.io/badge/MCP%20SDK-^1.17.0-green?style=flat-square)](https://github.com/modelcontextprotocol/typescript-sdk)
+[![MCP Spec Version](https://img.shields.io/badge/MCP%20Spec-2025--06--18-lightgrey?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-06-18/changelog.mdx)
+[![Version](https://img.shields.io/badge/Version-2.2.3-blue?style=flat-square)](./CHANGELOG.md)
+[![Coverage](https://img.shields.io/badge/Coverage-0.0%25-red?style=flat-square)](./vitest.config.ts)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
+[![Status](https://img.shields.io/badge/Status-Stable-green?style=flat-square)](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)
+
+</div>
+
 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.
 
 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.
 
+## 🤔 Why Use This Server?
+
+- **Automate Git Workflows**: Enable AI agents to programmatically clone, commit, push, and manage branches.
+- **Gain Repository Insights**: Allow tools to check status, view logs, and diff changes without direct shell access.
+- **Integrate Git into AI-driven Development**: Let LLMs manage version control as part of their coding tasks.
+- **Production-Ready Foundation**: Inherits logging, error handling, and security from the template.
+
 ## 🚀 Core Capabilities: Git Tools 🛠️
 
 This server equips your AI with a comprehensive suite of tools to interact with Git repositories:
@@ -104,35 +117,41 @@ Add the following to your MCP client's configuration file (e.g., `cline_mcp_sett
 #### Install via npm
 
 ```bash
-npm install @cyanheads/git-mcp-server
+npm run build
+# Or use 'npm run rebuild' for a clean install
 ```
 
-#### Alternatively Install from Source (recommended for development)
+### 3. Running the Server
 
-1. Clone the repository:
+- **Via Stdio (Default):**
+  ```bash
+  npm run start:server
+  ```
+- **Via Streamable HTTP:**
+  ```bash
+  npm run start:server:http
+  ```
 
-   ```bash
-   git clone https://github.com/cyanheads/git-mcp-server.git
-   cd git-mcp-server
-   ```
+### 4. Running Tests
 
-2. Install dependencies:
+This server uses [Vitest](https://vitest.dev/) for testing.
 
-   ```bash
-   npm install
-   ```
+- **Run all tests once:**
+  ```bash
+  npm test
+  ```
+- **Run tests in watch mode:**
+  ```bash
+  npm run test:watch
+  ```
+- **Run tests and generate a coverage report:**
+  ```bash
+  npm run test:coverage
+  ```
 
-3. Build the project:
-   ```bash
-   npm run build
-   # or npm run rebuild
-   ```
+## ⚙️ Configuration
 
-## Configuration
-
-### Environment Variables
-
-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)
+Configure the server using these environment variables (or a `.env` file):
 
 | Variable              | Description                                                                                                                           | Default     |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
@@ -147,111 +166,31 @@ Configure the server using environment variables. These environmental variables
 | `OAUTH_ISSUER_URL`    | OIDC issuer URL for OAuth validation (if `MCP_AUTH_MODE=oauth`).                                                                      | `''`        |
 | `OAUTH_AUDIENCE`      | Audience claim for OAuth validation (if `MCP_AUTH_MODE=oauth`).                                                                       | `''`        |
 
-## Project Structure
-
-The codebase follows a modular structure within the `src/` directory:
-
-```
-src/
-├── index.ts           # Entry point: Initializes and starts the server
-├── config/            # Configuration loading (env vars, package info)
-│   └── index.ts
-├── mcp-server/        # Core MCP server logic and capability 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
-└── utils/             # Common utility functions (logger, error handler, etc.)
-```
-
-For a detailed file tree, run `npm run tree` or see [docs/tree.md](docs/tree.md).
-
-## Tools
-
-The Git MCP Server provides a suite of tools for interacting with Git repositories, callable via the Model Context Protocol.
+## 🏗️ Project Structure
 
-| Tool Name                 | Description                                                                                                | Key Arguments                                                                                                                   |
-| :------------------------ | :--------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
-| `git_add`                 | Stages specified files or patterns.                                                                        | `path?`, `files?`                                                                                                               |
-| `git_branch`              | Manages branches (list, create, delete, rename, show current).                                             | `path?`, `mode`, `branchName?`, `newBranchName?`, `startPoint?`, `force?`, `all?`, `remote?`                                    |
-| `git_checkout`            | Switches branches or restores working tree files.                                                          | `path?`, `branchOrPath`, `newBranch?`, `force?`                                                                                 |
-| `git_cherry_pick`         | Applies changes introduced by existing commits.                                                            | `path?`, `commitRef`, `mainline?`, `strategy?`, `noCommit?`, `signoff?`                                                         |
-| `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. 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?`, `includeUntracked?`                                                        |
-| `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. Defaults to 'main' for initial branch.    | `path`, `initialBranch?`, `bare?`, `quiet?`                                                                                     |
-| `git_log`                 | Shows commit logs.                                                                                         | `path?`, `maxCount?`, `author?`, `since?`, `until?`, `branchOrFile?`                                                            |
-| `git_merge`               | Merges the specified branch into the current branch.                                                       | `path?`, `branch`, `commitMessage?`, `noFf?`, `squash?`, `abort?`                                                               |
-| `git_pull`                | Fetches from and integrates with another repository or local branch.                                       | `path?`, `remote?`, `branch?`, `rebase?`, `ffOnly?`                                                                             |
-| `git_push`                | Updates remote refs using local refs.                                                                      | `path?`, `remote?`, `branch?`, `remoteBranch?`, `force?`, `forceWithLease?`, `setUpstream?`, `tags?`, `delete?`                 |
-| `git_rebase`              | Reapplies commits on top of another base tip.                                                              | `path?`, `mode?`, `upstream?`, `branch?`, `interactive?`, `strategy?`, `strategyOption?`, `onto?`                               |
-| `git_remote`              | Manages remote repositories (list, add, remove, show).                                                     | `path?`, `mode`, `name?`, `url?`                                                                                                |
-| `git_reset`               | Resets current HEAD to a specified state. Supports soft, mixed, hard modes. **USE 'hard' WITH CAUTION**.   | `path?`, `mode?`, `commit?`                                                                                                     |
-| `git_set_working_dir`     | Sets the default working directory. Can optionally initialize repo if not present. Requires absolute path. | `path`, `validateGitRepo?`, `initializeIfNotPresent?`                                                                           |
-| `git_show`                | Shows information about Git objects (commits, tags, etc.).                                                 | `path?`, `ref`, `filePath?`                                                                                                     |
-| `git_stash`               | Manages stashed changes (list, apply, pop, drop, save).                                                    | `path?`, `mode`, `stashRef?`, `message?`                                                                                        |
-| `git_status`              | Gets repository status (branch, staged, modified, untracked files).                                        | `path?`                                                                                                                         |
-| `git_tag`                 | Manages tags (list, create annotated/lightweight, delete).                                                 | `path?`, `mode`, `tagName?`, `message?`, `commitRef?`, `annotate?`                                                              |
-| `git_worktree`            | Manages Git worktrees (list, add, remove, move, prune).                                                    | `path?`, `mode`, `worktreePath?`, `commitish?`, `newBranch?`, `force?`, `detach?`, `newPath?`, `verbose?`, `dryRun?`, `expire?` |
-| `git_wrapup_instructions` | Provides a standard Git wrap-up workflow.                                                                  | `acknowledgement`, `updateAgentMetaFiles?`                                                                                      |
+- **`src/mcp-server/`**: Contains the core MCP server, tools, resources, and transport handlers.
+- **`src/config/`**: Handles loading and validation of environment variables.
+- **`src/types-global/`**: Defines shared TypeScript interfaces and type definitions.
+- **`src/utils/`**: Core utilities (logging, error handling, security, etc.).
+- **`src/index.ts`**: The main entry point that initializes and starts the server.
 
-_Note: The `path` parameter for most tools defaults to the session's working directory if set via `git_set_working_dir`._
+**Explore the full structure yourself:**
 
-## Resources
-
-**MCP Resources are not implemented in this version (v2.2.0).**
-
-This version focuses on the refactored Git tools implementation based on the latest `mcp-ts-template` and MCP SDK v1.15.1. 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.
-
-## Development
-
-### Build and Test
+See the current file tree in [docs/tree.md](docs/tree.md) or generate it dynamically:
 
 ```bash
-# Build the project (compile TS to JS in dist/ and make executable)
-npm run build
-
-# Test the server locally using the MCP inspector tool (stdio transport)
-npm run inspector
-
-# Test the server locally using the MCP inspector tool (http transport)
-npm run inspector:http
-
-# Clean build artifacts
-npm run clean
-
-# Generate a file tree representation for documentation
 npm run tree
+```
 
-# Clean build artifacts and then rebuild the project
-npm run rebuild
-
-# Format code with Prettier
-npm run format
+## 🧩 Extending the System
 
-# Start the server using stdio (default)
-npm start
-# Or explicitly:
-npm run start:stdio
+The canonical pattern for adding new tools is defined in the [.clinerules](.clinerules) file. It mandates a strict separation of concerns:
 
-# Start the server using HTTP transport
-npm run start:http
-```
+1.  **`logic.ts`**: Contains the pure business logic, Zod schemas, and type definitions. This file throws structured errors on failure.
+2.  **`registration.ts`**: Acts as the "handler." It registers the tool with the server, wraps the logic call in a `try...catch` block, and formats the final success or error response.
 
-## License
+This "Logic Throws, Handler Catches" pattern ensures that core logic remains pure and testable, while the registration layer handles all side effects and response formatting.
 
-This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+## 📜 License
 
----
-
-<div align="center">
-Built with the <a href="https://modelcontextprotocol.io/">Model Context Protocol</a>
-</div>
+This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.

package/dist/config/index.js

@@ -1,76 +1,271 @@
+/**
+ * @fileoverview Loads, validates, and exports application configuration.
+ * This module centralizes configuration management, sourcing values from
+ * environment variables and `package.json`. It uses Zod for schema validation
+ * to ensure type safety and correctness of configuration parameters.
+ *
+ * Key responsibilities:
+ * - Load environment variables from a `.env` file.
+ * - Read `package.json` for default server name and version.
+ * - Define a Zod schema for all expected environment variables.
+ * - Validate environment variables against the schema.
+ * - Construct and export a comprehensive `config` object.
+ * - Export individual configuration values like `logLevel` and `environment` for convenience.
+ *
+ * @module src/config/index
+ */
 import dotenv from "dotenv";
-import { readFileSync } from "fs";
-import { dirname, join } from "path";
+import { existsSync, mkdirSync, readFileSync, statSync } from "fs";
+import path, { dirname, join } from "path";
 import { fileURLToPath } from "url";
-// Removed logger import to break circular dependency
-// Suppress dotenv debug output which can interfere with stdio transport
-dotenv.config({ debug: false }); // 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: "git-mcp-server-SOMETHINGBROKE", version: "0.0.0" };
+import { z } from "zod";
+dotenv.config();
+// --- Determine Project Root ---
+/**
+ * Finds the project root directory by searching upwards for package.json.
+ * @param startDir The directory to start searching from.
+ * @returns The absolute path to the project root, or throws an error if not found.
+ */
+const findProjectRoot = (startDir) => {
+    let currentDir = startDir;
+    while (true) {
+        const packageJsonPath = join(currentDir, "package.json");
+        if (existsSync(packageJsonPath)) {
+            return currentDir;
+        }
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            // Reached the root of the filesystem without finding package.json
+            throw new Error(`Could not find project root (package.json) starting from ${startDir}`);
+        }
+        currentDir = parentDir;
+    }
+};
+let projectRoot;
+try {
+    // For ESM, __dirname is not available directly.
+    // import.meta.url gives the URL of the current module.
+    const currentModuleDir = dirname(fileURLToPath(import.meta.url));
+    projectRoot = findProjectRoot(currentModuleDir);
+}
+catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.error(`FATAL: Error determining project root: ${errorMessage}`);
+    // Fallback to process.cwd() if project root cannot be determined.
+    // This might happen in unusual execution environments.
+    projectRoot = process.cwd();
+    console.warn(`Warning: Using process.cwd() (${projectRoot}) as fallback project root.`);
+}
+// --- End Determine Project Root ---
+const pkgPath = join(projectRoot, "package.json"); // Use determined projectRoot
+let pkg = { name: "git-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"));
 }
 catch (error) {
-    // Silently use default pkg info if reading fails. Error will be logged later if needed.
+    if (process.stdout.isTTY) {
+        console.error("Warning: Could not read package.json for default config values. Using hardcoded defaults.", error);
+    }
+}
+/**
+ * Zod schema for validating environment variables.
+ * Provides type safety, validation, defaults, and clear error messages.
+ * @private
+ */
+const EnvSchema = z.object({
+    /** Optional. The desired name for the MCP server. Defaults to `package.json` name. */
+    MCP_SERVER_NAME: z.string().optional(),
+    /** Optional. The version of the MCP server. Defaults to `package.json` version. */
+    MCP_SERVER_VERSION: z.string().optional(),
+    /** Minimum logging level. See `McpLogLevel` in logger utility. Default: "info". */
+    MCP_LOG_LEVEL: z.string().default("info"),
+    /** Directory for log files. Defaults to "logs" in project root. */
+    LOGS_DIR: z.string().default(path.join(projectRoot, "logs")),
+    /** Runtime environment (e.g., "development", "production"). Default: "development". */
+    NODE_ENV: z.string().default("development"),
+    /** MCP communication transport ("stdio" or "http"). Default: "stdio". */
+    MCP_TRANSPORT_TYPE: z.enum(["stdio", "http"]).default("stdio"),
+    /** MCP session mode ('stateless', 'stateful', 'auto'). Default: 'auto'. */
+    MCP_SESSION_MODE: z.enum(["stateless", "stateful", "auto"]).default("auto"),
+    /** HTTP server port (if MCP_TRANSPORT_TYPE is "http"). Default: 3010. */
+    MCP_HTTP_PORT: z.coerce.number().int().positive().default(3010),
+    /** HTTP server host (if MCP_TRANSPORT_TYPE is "http"). Default: "127.0.0.1". */
+    MCP_HTTP_HOST: z.string().default("127.0.0.1"),
+    /** The endpoint path for the MCP server. Default: "/mcp". */
+    MCP_HTTP_ENDPOINT_PATH: z.string().default("/mcp"),
+    /** Max retries for binding to a port if the initial one is in use. Default: 15. */
+    MCP_HTTP_MAX_PORT_RETRIES: z.coerce.number().int().nonnegative().default(15),
+    /** Delay in ms between port binding retries. Default: 50. */
+    MCP_HTTP_PORT_RETRY_DELAY_MS: z.coerce
+        .number()
+        .int()
+        .nonnegative()
+        .default(50),
+    /** Timeout in ms for considering a stateful session stale and eligible for cleanup. Default: 1800000 (30 minutes). */
+    MCP_STATEFUL_SESSION_STALE_TIMEOUT_MS: z.coerce
+        .number()
+        .int()
+        .positive()
+        .default(1_800_000),
+    /** Optional. Comma-separated allowed origins for CORS (HTTP transport). */
+    MCP_ALLOWED_ORIGINS: z.string().optional(),
+    /** Optional. Secret key (min 32 chars) for auth tokens (HTTP transport). CRITICAL for production. */
+    MCP_AUTH_SECRET_KEY: z
+        .string()
+        .min(32, "MCP_AUTH_SECRET_KEY must be at least 32 characters long for security reasons.")
+        .optional(),
+    /** The authentication mode to use. 'jwt' for internal simple JWTs, 'oauth' for OAuth 2.1, or 'none'. Default: 'none'. */
+    MCP_AUTH_MODE: z.enum(["jwt", "oauth", "none"]).default("none"),
+    /** The expected issuer URL for OAuth 2.1 access tokens. CRITICAL for validation. */
+    OAUTH_ISSUER_URL: z.string().url().optional(),
+    /** The JWKS (JSON Web Key Set) URI for the OAuth 2.1 provider. If not provided, it's often discoverable from the issuer URL. */
+    OAUTH_JWKS_URI: z.string().url().optional(),
+    /** The audience claim for the OAuth 2.1 access tokens. This server will reject tokens not intended for it. */
+    OAUTH_AUDIENCE: z.string().optional(),
+    /** Optional. Client ID to use in development mode for JWT strategy. Default: "dev-client-id". */
+    DEV_MCP_CLIENT_ID: z.string().optional(),
+    /** Optional. Comma-separated scopes for development mode JWT strategy. Default: "dev-scope". */
+    DEV_MCP_SCOPES: z.string().optional(),
+    /** Flag to enable GPG signing for commits made by the git_commit tool. */
+    GIT_SIGN_COMMITS: z.string().transform((val) => val === "true").optional(),
+});
+const parsedEnv = EnvSchema.safeParse(process.env);
+if (!parsedEnv.success) {
+    if (process.stdout.isTTY) {
+        console.error("❌ Invalid environment variables found:", parsedEnv.error.flatten().fieldErrors);
+    }
+    // Consider throwing an error in production for critical misconfigurations.
+}
+const env = parsedEnv.success ? parsedEnv.data : EnvSchema.parse({});
+// --- Directory Ensurance Function ---
+const ensureDirectory = (dirPath, rootDir, dirName) => {
+    const resolvedDirPath = path.isAbsolute(dirPath)
+        ? dirPath
+        : path.resolve(rootDir, dirPath);
+    if (!resolvedDirPath.startsWith(rootDir + path.sep) &&
+        resolvedDirPath !== rootDir) {
+        if (process.stdout.isTTY) {
+            console.error(`Error: ${dirName} path "${dirPath}" resolves to "${resolvedDirPath}", which is outside the project boundary "${rootDir}".`);
+        }
+        return null;
+    }
+    if (!existsSync(resolvedDirPath)) {
+        try {
+            mkdirSync(resolvedDirPath, { recursive: true });
+            if (process.stdout.isTTY) {
+                console.log(`Created ${dirName} directory: ${resolvedDirPath}`);
+            }
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            if (process.stdout.isTTY) {
+                console.error(`Error creating ${dirName} directory at ${resolvedDirPath}: ${errorMessage}`);
+            }
+            return null;
+        }
+    }
+    else {
+        try {
+            const stats = statSync(resolvedDirPath);
+            if (!stats.isDirectory()) {
+                if (process.stdout.isTTY) {
+                    console.error(`Error: ${dirName} path ${resolvedDirPath} exists but is not a directory.`);
+                }
+                return null;
+            }
+        }
+        catch (statError) {
+            if (process.stdout.isTTY) {
+                const statErrorMessage = statError instanceof Error ? statError.message : String(statError);
+                console.error(`Error accessing ${dirName} path ${resolvedDirPath}: ${statErrorMessage}`);
+            }
+            return null;
+        }
+    }
+    return resolvedDirPath;
+};
+// --- End Directory Ensurance Function ---
+// --- Logs Directory Handling ---
+let validatedLogsPath = ensureDirectory(env.LOGS_DIR, projectRoot, "logs");
+if (!validatedLogsPath) {
+    if (process.stdout.isTTY) {
+        console.warn(`Warning: Custom logs directory ('${env.LOGS_DIR}') is invalid or outside the project boundary. Falling back to default.`);
+    }
+    const defaultLogsDir = path.join(projectRoot, "logs");
+    validatedLogsPath = ensureDirectory(defaultLogsDir, projectRoot, "logs");
+    if (!validatedLogsPath) {
+        if (process.stdout.isTTY) {
+            console.warn("Warning: Default logs directory could not be created. File logging will be disabled.");
+        }
+    }
 }
+// --- End Logs Directory Handling ---
 /**
  * Main application configuration object.
- * Aggregates settings from environment variables and package.json.
+ * Aggregates settings from validated environment variables and `package.json`.
  */
 export const config = {
-    /** The name of the MCP server, derived from package.json. */
-    mcpServerName: pkg.name,
-    /** The version of the MCP server, derived from package.json. */
-    mcpServerVersion: pkg.version,
-    /** Logging level for the application (e.g., "debug", "info", "warning", "error"). Defaults to "info". */
-    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(",") || [],
+    /** Information from package.json. */
+    pkg,
+    /** MCP server name. Env `MCP_SERVER_NAME` > `package.json` name > "git-mcp-server". */
+    mcpServerName: env.MCP_SERVER_NAME || pkg.name,
+    /** MCP server version. Env `MCP_SERVER_VERSION` > `package.json` version > "0.0.0". */
+    mcpServerVersion: env.MCP_SERVER_VERSION || pkg.version,
+    /** Logging level. From `MCP_LOG_LEVEL` env var. Default: "info". */
+    logLevel: env.MCP_LOG_LEVEL,
+    /** Absolute path to the logs directory. From `LOGS_DIR` env var. */
+    logsPath: validatedLogsPath,
+    /** Runtime environment. From `NODE_ENV` env var. Default: "development". */
+    environment: env.NODE_ENV,
+    /** MCP transport type ('stdio' or 'http'). From `MCP_TRANSPORT_TYPE` env var. Default: "stdio". */
+    mcpTransportType: env.MCP_TRANSPORT_TYPE,
+    /** MCP session mode ('stateless', 'stateful', 'auto'). From `MCP_SESSION_MODE` env var. Default: "auto". */
+    mcpSessionMode: env.MCP_SESSION_MODE,
+    /** HTTP server port (if http transport). From `MCP_HTTP_PORT` env var. Default: 3010. */
+    mcpHttpPort: env.MCP_HTTP_PORT,
+    /** HTTP server host (if http transport). From `MCP_HTTP_HOST` env var. Default: "127.0.0.1". */
+    mcpHttpHost: env.MCP_HTTP_HOST,
+    /** MCP endpoint path for HTTP transport. From `MCP_HTTP_ENDPOINT_PATH`. Default: "/mcp". */
+    mcpHttpEndpointPath: env.MCP_HTTP_ENDPOINT_PATH,
+    /** Max retries for port binding. From `MCP_HTTP_MAX_PORT_RETRIES`. Default: 15. */
+    mcpHttpMaxPortRetries: env.MCP_HTTP_MAX_PORT_RETRIES,
+    /** Delay between port binding retries. From `MCP_HTTP_PORT_RETRY_DELAY_MS`. Default: 50. */
+    mcpHttpPortRetryDelayMs: env.MCP_HTTP_PORT_RETRY_DELAY_MS,
+    /** Timeout for stale stateful sessions. From `MCP_STATEFUL_SESSION_STALE_TIMEOUT_MS`. Default: 1800000. */
+    mcpStatefulSessionStaleTimeoutMs: env.MCP_STATEFUL_SESSION_STALE_TIMEOUT_MS,
+    /** Array of allowed CORS origins (http transport). From `MCP_ALLOWED_ORIGINS` (comma-separated). */
+    mcpAllowedOrigins: env.MCP_ALLOWED_ORIGINS?.split(",")
+        .map((origin) => origin.trim())
+        .filter(Boolean),
+    /** Auth secret key (JWTs, http transport). From `MCP_AUTH_SECRET_KEY`. CRITICAL. */
+    mcpAuthSecretKey: env.MCP_AUTH_SECRET_KEY,
+    /** The authentication mode ('jwt' or 'oauth'). From `MCP_AUTH_MODE`. */
+    mcpAuthMode: env.MCP_AUTH_MODE,
+    /** OAuth 2.1 Issuer URL. From `OAUTH_ISSUER_URL`. */
+    oauthIssuerUrl: env.OAUTH_ISSUER_URL,
+    /** OAuth 2.1 JWKS URI. From `OAUTH_JWKS_URI`. */
+    oauthJwksUri: env.OAUTH_JWKS_URI,
+    /** OAuth 2.1 Audience. From `OAUTH_AUDIENCE`. */
+    oauthAudience: env.OAUTH_AUDIENCE,
+    /** Development mode client ID. From `DEV_MCP_CLIENT_ID`. */
+    devMcpClientId: env.DEV_MCP_CLIENT_ID,
+    /** Development mode scopes. From `DEV_MCP_SCOPES`. */
+    devMcpScopes: env.DEV_MCP_SCOPES?.split(",").map((s) => s.trim()),
     /** 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",
-    /** The authentication mode ('jwt', 'oauth', or 'none'). Defaults to 'none'. */
-    mcpAuthMode: process.env.MCP_AUTH_MODE || "none",
-    /** Secret key for signing/verifying JWTs. Required if mcpAuthMode is 'jwt'. */
-    mcpAuthSecretKey: process.env.MCP_AUTH_SECRET_KEY,
-    /** The OIDC issuer URL for OAuth token validation. Required if mcpAuthMode is 'oauth'. */
-    oauthIssuerUrl: process.env.OAUTH_ISSUER_URL,
-    /** The audience claim for OAuth token validation. Required if mcpAuthMode is 'oauth'. */
-    oauthAudience: process.env.OAUTH_AUDIENCE,
-    /** The JWKS URI for fetching public keys for OAuth. Optional, can be derived from issuer URL. */
-    oauthJwksUri: process.env.OAUTH_JWKS_URI,
+    gitSignCommits: env.GIT_SIGN_COMMITS,
     /** 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,
+        authRequired: env.MCP_AUTH_MODE !== "none",
     },
-    // Note: mcpClient configuration is now loaded separately from mcp-config.json
 };
 /**
- * The configured logging level for the application.
- * Exported separately for convenience (e.g., logger initialization).
- * @type {string}
+ * Configured logging level for the application.
+ * Exported for convenience.
  */
 export const logLevel = config.logLevel;
 /**
- * The configured runtime environment for the application.
- * Exported separately for convenience.
- * @type {string}
+ * Configured runtime environment ("development", "production", etc.).
+ * Exported for convenience.
  */
 export const environment = config.environment;
-// 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/mcp-server/server.js

@@ -37,8 +37,8 @@ import { registerGitTagTool } from "./tools/gitTag/index.js";
 import { registerGitWorktreeTool } from "./tools/gitWorktree/index.js";
 import { registerGitWrapupInstructionsTool } from "./tools/gitWrapupInstructions/index.js";
 // Import transport setup functions
-import { startHttpTransport } from "./transports/httpTransport.js";
-import { connectStdioTransport } from "./transports/stdioTransport.js";
+import { startHttpTransport } from "./transports/http/index.js";
+import { startStdioTransport } from "./transports/stdio/index.js";
 async function createMcpServerInstance() {
     const context = requestContextService.createRequestContext({
         operation: "createMcpServerInstance",
@@ -121,13 +121,13 @@ async function startTransport() {
         transport: transportType,
     });
     logger.info(`Starting transport: ${transportType}`, context);
-    const server = await createMcpServerInstance();
     if (transportType === "http") {
-        await startHttpTransport(server, context);
-        return;
+        const { server } = await startHttpTransport(createMcpServerInstance, context);
+        return server;
     }
     if (transportType === "stdio") {
-        await connectStdioTransport(server, context);
+        const server = await createMcpServerInstance();
+        await startStdioTransport(server, context);
         return server;
     }
     logger.fatal(`Unsupported transport type configured: ${transportType}`, context);