mcp-jira-git

MCP Server - Jira & Git Integration

Overview

This project provides an MCP (Model Context Protocol) server that integrates with Jira and Git to automate common development workflows. It watches for file changes in a specified Git repository, checks the current branch for a Jira issue key, and updates the corresponding Jira issue status.

Additionally, it exposes MCP tools for:

• Retrieving Jira issue details (getJiraIssue).
• Creating a Git feature branch and a basic Pull Request template from a Jira issue (createGitBranchAndPR).
• Manually updating a Jira issue status (updateJiraStatus).

Features

• Automatic Jira Status Updates: Monitors file changes and updates linked Jira issues (e.g., to "In Progress") when code changes are detected on a feature branch.
• MCP Tool Integration: Provides tools callable by MCP clients (like AI agents or IDE extensions) to interact with Jira and Git.
• Configurable: Uses environment variables for Jira/Git credentials and behavior.

Setup

1. Clone the repository:

   git clone <repository-url>
   cd mcp-server 
   

2. Install dependencies:

   npm install
   

3. Configure Environment Variables: Create a .env file in the project root by copying .env.example:

   cp .env.example .env
   

   Then edit the .env file with your specific settings:

   # Jira Configuration
   JIRA_BASE_URL=https://<your-domain>.atlassian.net # Your Jira instance URL
   JIRA_EMAIL=<your-jira-email>
   JIRA_API_TOKEN=<your-jira-api-token> # Generate from Jira Account Settings > Security > API token
   JIRA_PROJECT_KEY=<YOUR_PROJ_KEY> # e.g., PROJ
   JIRA_UPDATE_STATUS="In Progress" # Target status for automatic updates
   
   # Git Configuration
   GIT_REPO_PATH=/path/to/your/local/repository # Absolute path to the Git repo to monitor
   GIT_DEFAULT_BRANCH=main # Or your default branch (e.g., develop)
   
   # Optional Debug Configuration
   # DEBUG=1 # Uncomment to enable debug mode
   # LOG_LEVEL=info # Options: debug, info, warn, error
   

   • Replace placeholders with your actual Jira credentials, project key, desired status, Git repository path, and default branch.
   • To generate a Jira API token, go to Atlassian Account Settings > Security > Create and manage API tokens.

Running the Server

• Development (with auto-restart on changes):

  npm run dev
  

• Production (build first):

  npm run build
  npm start
  

The server will start and connect using STDIN/STDOUT for MCP communication.

Usage (MCP Client)

An MCP client can connect to this server (via STDIN/STDOUT when run) and call the following tools:

• getJiraIssue:
  • Input: { "issueId": "PROJ-123" }
  • Output: JSON string containing Jira issue details.
• createGitBranchAndPR:
  • Input: { "issueId": "PROJ-123" }
  • Output: JSON string { "branchName": "feature/PROJ-123-summary", "prTemplate": "..." }
  • Side effects: Creates the Git branch, writes .github/PULL_REQUEST_TEMPLATE.md, updates Jira status to JIRA_UPDATE_STATUS.
• updateJiraStatus:
  • Input: { "issueId": "PROJ-123", "status": "Done" }
  • Output: Confirmation message.
  • Side effects: Updates the Jira issue status.

File Watching Behavior

When the server is running (npm start or npm run dev):

1. It monitors the directory specified by GIT_REPO_PATH for file changes (ignoring .git, node_modules, dist).
2. On detecting a change (add, change, unlink):
   • It checks the current branch name of the repository.
   • It extracts a Jira issue key (e.g., PROJ-123) from the branch name (expected format: type/KEY-123-description).
   • It checks if there are uncommitted Git changes (git status).
   • If an issue key is found AND there are Git changes, it attempts to update the corresponding Jira issue's status to the value defined in the JIRA_UPDATE_STATUS environment variable.

Environment Variables

• JIRA_BASE_URL: Base URL of your Jira instance.
• JIRA_EMAIL: Email associated with your Jira account.
• JIRA_API_TOKEN: Your Jira API token.
• JIRA_PROJECT_KEY: The project key for your Jira project.
• JIRA_UPDATE_STATUS: The target status name in Jira to set when file changes are detected (e.g., "In Progress", "Development").
• GIT_REPO_PATH: Absolute path to the local Git repository to monitor.
• GIT_DEFAULT_BRANCH: The default branch of the repository (e.g., main, master, develop).
• DEBUG: Set to 1 to enable debug mode (optional).
• LOG_LEVEL: Set logging level - debug, info, warn, error (optional, defaults to info).

Testing

Run unit tests:

npm test