MCP MGit Server

# MCP MGit Server A MCP server for executing `mgit push` operations with multiple instance support. ## Prerequisites **⚠️ Important:** This MCP server requires the [MGit](https://github.com/liliangshan/mgit) tool to be installed and configured on your system. MGit is a command-line tool for managing multiple Git projects. It helps you efficiently manage, synchronize, and update multiple Git repositories. ### MGit Installation and Setup Before using this MCP server, please: 1. **Install MGit**: Download and install MGit from [https://github.com/liliangshan/mgit/releases](https://github.com/liliangshan/mgit/releases) 2. **Initialize MGit**: Follow the MGit setup instructions in the [MGit README](https://github.com/liliangshan/mgit/blob/main/README.md) 3. **Configure Projects**: Use `mgit init` to add your Git repositories to MGit 4. **Verify Setup**: Use `mgit list` to view available repository names For detailed MGit usage instructions, features, and configuration, please refer to the [MGit README](https://github.com/liliangshan/mgit/blob/main/README.md). ### Key MGit Features - Multi-project Management: Manage multiple Git projects with one click - Multi-language Support: Supports multiple languages including Chinese (Simplified/Traditional), English, Japanese, Korean, French - Remote Database Sync: Supports project configuration synchronization across multiple devices - Smart Branch Management: Automatically detects and switches branches to avoid conflicts - Batch Operations: Supports pulling/pushing changes for multiple projects simultaneously ## Features - ✅ Execute `mgit push` command for repositories - ✅ Configurable mgit command (default: `mgit`) - ✅ Multiple instance support with repository name isolation - ✅ Operation logging - ✅ Error handling and recovery ## Installation ### Global Installation (Recommended) ```bash npm install -g @liangshanli/mcp-server-mgit ``` ### Local Installation ```bash npm install @liangshanli/mcp-server-mgit ``` ### From Source ```bash git clone https://github.com/liliangshan/mcp-server-mgit.git cd mcp-server-mgit npm install ``` ## Configuration Set environment variables: ```bash # Required: Repository name (use 'mgit list' to view available repository names) export REPO_NAME="my-repo" # Optional: MGit command (default: mgit) export MGIT_CMD="mgit" # Optional: Language setting (default: en) # Supported values: en (English), zh (Chinese), zh-CN (Simplified Chinese), zh-TW (Traditional Chinese) export LANGUAGE="en" # Optional: Enable/disable push history check (default: true) # Set to false to skip history check requirement export CHECK_PUSH_HISTORY="true" # Optional: Project branding export PROJECT_NAME="MyProject" ``` ## Usage ### 1. Direct Run (Global Installation) ```bash mcp-server-mgit ``` ### 2. Using npx (Recommended) ```bash npx @liangshanli/mcp-server-mgit ``` ### 3. Direct Start (Source Installation) ```bash npm start ``` ### 4. Managed Start (Recommended for Production) ```bash npm run start-managed ``` Managed start provides: - Auto-restart (up to 10 times) - Error recovery - Process management - Logging ### 5. Development Mode ```bash npm run dev ``` ## Editor Integration ### Cursor Editor Configuration 1. Create `.cursor/mcp.json` file in your project root: ```json { "mcpServers": { "mgit": { "command": "npx", "args": ["@liangshanli/mcp-server-mgit"], "env": { "REPO_NAME": "my-repo", "MGIT_CMD": "mgit", "LANGUAGE": "en", "PROJECT_NAME": "MyProject" } } } } ``` ### VS Code Configuration 1. Install the MCP extension for VS Code 2. Create `.vscode/settings.json` file: ```json { "mcp.servers": { "mgit": { "command": "npx", "args": ["@liangshanli/mcp-server-mgit"], "env": { "REPO_NAME": "my-repo", "MGIT_CMD": "mgit", "LANGUAGE": "en", "PROJECT_NAME": "MyProject" } } } } ``` ### Multiple MGit Server Instances Support You can configure multiple MGit server instances with different `REPO_NAME` and `PROJECT_NAME` to isolate tools and configurations. Each instance must have a unique `REPO_NAME` (required). This is useful when you need to push to different repositories or manage different project groups. Use `mgit list` (or `${MGIT_CMD} list`) to view available repository names. **Example: Cursor Editor Configuration** Create `.cursor/mcp.json` file: ```json { "mcpServers": { "mgit-local": { "disabled": false, "timeout": 60, "command": "npx", "args": ["@liangshanli/mcp-server-mgit"], "env": { "REPO_NAME": "local-repo", "MGIT_CMD": "mgit", "PROJECT_NAME": "local-mgit" } }, "mgit-custom": { "disabled": false, "timeout": 60, "command": "npx", "args": ["@liangshanli/mcp-server-mgit"], "env": { "REPO_NAME": "custom-repo", "MGIT_CMD": "/path/to/custom-mgit", "PROJECT_NAME": "custom-mgit" } } } } ``` **Benefits of Multiple Instances:** - **Tool Isolation**: Each instance has its own tool names (e.g., `local_mgit_push`, `custom_mgit_push`) - **Config Isolation**: Logs are stored in separate directories (e.g., `./.setting.local/`, `./.setting.custom/`) - **Different Commands**: Configure different mgit commands for each instance - **Project Branding**: Each instance can have its own project name for better identification **Note**: When using multiple instances, tools will be prefixed with `REPO_NAME`. For example: - `local-repo_mgit_push` - uses local mgit command for local-repo - `custom-repo_mgit_push` - uses custom mgit command for custom-repo ### As MCP Server The server communicates with MCP clients via stdin/stdout after startup: ```json {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18"}} ``` ### Available Tools 1. **mgit_push**: Execute mgit push command for the repository configured via REPO_NAME environment variable ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "mgit_push", "arguments": { "message": "Update project files" } } } ``` 2. **get_operation_logs**: Get operation logs ```json { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "get_operation_logs", "arguments": { "limit": 50, "offset": 0 } } } ``` ## Logging ### General Logs Log file location: `./.setting/mcp-mgit.log` (or `./.setting.<REPO_NAME>/mcp-mgit.log` if REPO_NAME is set) Logged content: - All requests and responses - MGit operation records - Error messages - Server status changes ## Error Handling - Individual request errors don't affect the entire server - Process exceptions are automatically restarted (managed mode) - Detailed error messages in logs ## Environment Variables | Variable | Default | Description | |----------|---------|-------------| | REPO_NAME | | **Required** repository name for push operations. Use `mgit list` (or `${MGIT_CMD} list`) to view available repository names. Example: `export REPO_NAME="my-repo"` | | MGIT_CMD | mgit | Optional mgit command to execute (can be full path) | | LANGUAGE | en | Optional language setting for commit messages. Supported values: `en` (English), `zh` or `zh-CN` (Simplified Chinese), `zh-TW` (Traditional Chinese). The tool will prompt users to provide commit messages in the configured language. | | CHECK_PUSH_HISTORY | true | Optional flag to enable/disable push history check before pushing. Set to `false` to skip the history check requirement. When `true` (default), you must call `get_push_history` tool before using `mgit_push`. When `false`, you can push directly without checking history. **Note:** If you encounter the error `Encountered error in step execution: error executing cascade step: CORTEX_STEP_TYPE_MCP_TOOL: calling "tools/call": EOF`, please set `CHECK_PUSH_HISTORY="false"` to disable push history check. | | PROJECT_NAME | | Optional project branding for tool descriptions | | MCP_LOG_DIR | ./.setting (or ./.setting.<REPO_NAME> if REPO_NAME is set) | Log directory | | MCP_LOG_FILE | mcp-mgit.log | Log filename | ## Development ### Project Structure ``` mcp-server-mgit/ ├── src/ │ └── server-final.js # Main server file ├── bin/ │ └── cli.js # CLI entry point ├── start-server.js # Managed startup script ├── package.json └── README.md ``` ### Testing ```bash npm test ``` ## Quick Start ### 1. Install Package ```bash npm install -g @liangshanli/mcp-server-mgit ``` ### 2. Configure Environment Variables ```bash # Required: Repository name export REPO_NAME="my-repo" # Optional: MGit command (default: mgit) export MGIT_CMD="mgit" # Optional: Language setting (default: en) export LANGUAGE="en" # Optional: Enable/disable push history check (default: true) # Set to false to skip history check requirement export CHECK_PUSH_HISTORY="true" # Optional: Project branding export PROJECT_NAME="MyProject" ``` ### 3. Run Server ```bash mcp-server-mgit ``` ## Usage Example ### Using the mgit_push tool The `mgit_push` tool executes the command: `${MGIT_CMD} push ${REPO_NAME} "<message>"` **Note:** The repository name is configured via the `REPO_NAME` environment variable (required). Use `mgit list` (or `${MGIT_CMD} list`) to view available repository names. **Parameters:** - `message` (required): The commit message for the push operation **Example:** ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "mgit_push", "arguments": { "message": "Update documentation" } } } ``` If `REPO_NAME="my-project"` and `MGIT_CMD="mgit"`, this will execute: `mgit push my-project "Update documentation"` ## Troubleshooting ### Error: `Encountered error in step execution: error executing cascade step: CORTEX_STEP_TYPE_MCP_TOOL: calling "tools/call": EOF` If you encounter this error when trying to push code, it may be caused by the push history check feature. To resolve this issue, disable the push history check by setting the environment variable: ```bash export CHECK_PUSH_HISTORY="false" ``` After setting this variable, restart the MCP server and try pushing again. This will allow you to push directly without checking push history first. ## License MIT