README.md•11.6 kB
# Jira-GitLab MCP Server
A Python-based Model Context Protocol (MCP) server that integrates Jira and GitLab, enabling AI agents to seamlessly manage issues and branches across both platforms.
## Features
- **Jira Integration**: Fetch issues, add comments, and manage project data
- **GitLab Integration**: Create branches, manage projects, and handle repository operations
- **AI-Powered Analysis**: Real OpenAI integration for intelligent issue analysis and code generation
- **Automated Workflow**: Complete SRE workflow from issue detection to fix deployment
- **Code Validation**: AST-based validation with security pattern detection
- **Secure Configuration**: Support for environment variables and encrypted credentials
- **Robust Error Handling**: Comprehensive error management with retry mechanisms
- **Async Support**: Full asynchronous operation for better performance
- **MCP Compliance**: Fully compatible with the Model Context Protocol specification
## Quick Start
### Prerequisites
- Python 3.8+
- Jira account with API access
- GitLab account with Personal Access Token
### Installation
1. Clone the repository:
```bash
git clone <repository-url>
cd mcp-jira-gitlab
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
3. Configure credentials (choose one method):
**Option A: Environment Variables (Recommended)**
```bash
export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export JIRA_EMAIL="your-email@example.com"
export JIRA_API_TOKEN="your-jira-api-token"
export GITLAB_BASE_URL="https://gitlab.com"
export GITLAB_ACCESS_TOKEN="your-gitlab-personal-access-token"
```
**Option B: Configuration File**
```bash
cp config.json.sample config.json
# Edit config.json with your credentials
```
4. Run the MCP server:
```bash
python mcp_server.py
```
## Configuration
### Environment Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `JIRA_BASE_URL` | Your Jira instance URL | Yes |
| `JIRA_EMAIL` | Your Jira account email | Yes |
| `JIRA_API_TOKEN` | Jira API token | Yes |
| `GITLAB_BASE_URL` | GitLab instance URL | No (defaults to gitlab.com) |
| `GITLAB_ACCESS_TOKEN` | GitLab Personal Access Token | Yes |
### Generating API Tokens
**Jira API Token:**
1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click "Create API token"
3. Copy the generated token
**GitLab Personal Access Token:**
1. Go to GitLab → Settings → Access Tokens
2. Create token with `api`, `read_repository`, and `write_repository` scopes
3. Copy the generated token
## MCP Tools
### `create_branch_for_issue`
Creates a GitLab branch for a Jira issue and links them.
**Parameters:**
- `issue_key` (string): Jira issue key (e.g., "PROJ-123")
- `project_id` (integer): GitLab project ID
- `base_branch` (string, optional): Base branch (default: "main")
**Branch Naming Convention:** `feature/{issue_key}-fix`
**Example:**
```json
{
"issue_key": "PROJ-123",
"project_id": 42,
"base_branch": "main"
}
```
### `get_jira_issues`
Fetch Jira issues using JQL query.
**Parameters:**
- `jql` (string, optional): JQL query string
- `max_results` (integer, optional): Maximum results (default: 50)
**Example:**
```json
{
"jql": "project = DEMO AND status = 'To Do'",
"max_results": 25
}
```
### `comment_on_issue`
Add a comment to a Jira issue.
**Parameters:**
- `issue_key` (string): Jira issue key
- `comment` (string): Comment text
**Example:**
```json
{
"issue_key": "PROJ-123",
"comment": "Branch created and ready for development"
}
```
### `get_issues_by_tags`
Fetch Jira issues by project and tags (labels).
**Parameters:**
- `project_key` (string): Jira project key (e.g., "PROJ", "DEMO")
- `tags` (array): List of tags/labels to filter by (1-10 tags)
- `max_results` (integer, optional): Maximum results (default: 50, max: 100)
**Example:**
```json
{
"project_key": "PROJ",
"tags": ["AI-Fix", "AutoFix"],
"max_results": 25
}
```
**Use Cases:**
- Find bugs tagged for AI-assisted fixing: `["AI-Fix", "AutoFix"]`
- Locate security issues: `["security", "vulnerability"]`
- Filter performance problems: `["performance", "optimization"]`
- Identify technical debt: `["tech-debt", "refactor"]`
### `analyze_and_fix_issue`
Use AI to analyze a Jira issue and generate code fixes.
**Parameters:**
- `issue_key` (string): Jira issue key to analyze
- `model` (string, optional): AI model to use (default: "gpt-4-turbo")
- `validation_level` (string, optional): Code validation strictness ("basic" or "strict")
- `include_context` (boolean, optional): Include repository context (default: true)
**Example:**
```json
{
"issue_key": "PROJ-123",
"model": "gpt-4-turbo",
"validation_level": "basic"
}
```
### `commit_ai_fix`
Commit AI-generated fixes to GitLab branch with validation.
**Parameters:**
- `project_id` (integer): GitLab project ID
- `branch_name` (string): Branch name to commit to
- `files` (array): Files to commit with content and actions
- `commit_message` (string): Commit message
**Example:**
```json
{
"project_id": 42,
"branch_name": "ai-fix/PROJ-123",
"files": [
{
"path": "src/main.py",
"content": "# Fixed code here",
"action": "update"
}
],
"commit_message": "AI-generated fix for PROJ-123"
}
```
### `create_merge_request`
Create a GitLab merge request.
**Parameters:**
- `project_id` (integer): GitLab project ID
- `source_branch` (string): Source branch name
- `target_branch` (string, optional): Target branch (default: "main")
- `title` (string, optional): MR title
- `description` (string, optional): MR description
- `draft` (boolean, optional): Create as draft (default: true)
**Example:**
```json
{
"project_id": 42,
"source_branch": "ai-fix/PROJ-123",
"title": "AI Fix: Bug in authentication",
"draft": true
}
```
### `update_issue_status`
Update Jira issue status and add comments.
**Parameters:**
- `issue_key` (string): Jira issue key
- `status` (string): New status (e.g., "In Review", "Done")
- `comment` (string, optional): Comment to add with status change
**Example:**
```json
{
"issue_key": "PROJ-123",
"status": "In Review",
"comment": "AI-generated fix created and ready for review"
}
```
### `sre_ai_workflow`
Complete SRE AI workflow: fetch tagged issues, create fixes, and update status.
**Parameters:**
- `project_key` (string): Jira project key
- `gitlab_project_id` (integer): GitLab project ID
- `tags` (array, optional): Tags to filter by (default: ["AI-Fix", "AutoFix"])
- `max_issues` (integer, optional): Maximum issues to process (default: 5)
- `auto_merge` (boolean, optional): Auto-merge approved fixes (default: false)
**Example:**
```json
{
"project_key": "PROJ",
"gitlab_project_id": 42,
"tags": ["AI-Fix", "security"],
"max_issues": 3
}
```
**Workflow Steps:**
1. Fetch issues with specified tags
2. Analyze each issue with AI
3. Generate and validate code fixes
4. Create branches and commit changes
5. Create draft merge requests
6. Update Jira issue status to "In Review"
## MCP Resources
### `jira://issues`
Access to Jira issues in the configured project.
### `gitlab://projects`
Access to GitLab projects and branches.
## Development
### Running Tests
```bash
# Install test dependencies
pip install pytest pytest-asyncio pytest-mock pytest-cov
# Run all tests
pytest
# Run with coverage
pytest --cov=. --cov-report=html
# Run specific test file
pytest tests/test_mcp_server.py
```
### Project Structure
```
mcp-jira-gitlab/
├── mcp_server.py # Main MCP server implementation
├── server.py # Legacy FastAPI server (deprecated)
├── config.json # Configuration file (optional)
├── requirements.txt # Python dependencies
├── README.md # This file
├── connectors/
│ ├── jira_client.py # Jira API client
│ ├── gitlab_client.py # GitLab API client
│ └── requirements.txt # Connector dependencies
├── utils/
│ ├── error_handler.py # Error handling utilities
│ └── config.py # Configuration management
└── tests/
├── test_mcp_server.py # MCP server tests
└── test_clients.py # Client tests
```
### Error Handling
The server implements comprehensive error handling:
- **Retry Mechanisms**: Automatic retry with exponential backoff
- **Authentication Errors**: Clear messages for credential issues
- **API Rate Limiting**: Handles rate limits gracefully
- **Network Issues**: Robust handling of connection problems
- **Validation**: Input validation with helpful error messages
### Logging
The server uses Python's logging module with configurable levels:
```python
import logging
logging.basicConfig(level=logging.INFO)
```
## Usage Examples
### Basic Workflow
1. **Fetch Jira Issues:**
```bash
# Using MCP tool
{
"tool": "get_jira_issues",
"arguments": {
"jql": "project = MYPROJ AND status = 'To Do'"
}
}
```
2. **Create Branch for Issue:**
```bash
# Using MCP tool
{
"tool": "create_branch_for_issue",
"arguments": {
"issue_key": "MYPROJ-123",
"project_id": 42
}
}
```
3. **Add Progress Comment:**
```bash
# Using MCP tool
{
"tool": "comment_on_issue",
"arguments": {
"issue_key": "MYPROJ-123",
"comment": "Development started in branch feature/MYPROJ-123-fix"
}
}
```
### Integration with AI Agents
This MCP server is designed to work with AI agents and LLMs. Example integration:
```python
# Example AI agent workflow
async def handle_new_issue(issue_key, project_id):
# 1. Get issue details
issues = await mcp_client.call_tool("get_jira_issues", {
"jql": f"key = {issue_key}"
})
# 2. Create branch
result = await mcp_client.call_tool("create_branch_for_issue", {
"issue_key": issue_key,
"project_id": project_id
})
# 3. Add status comment
await mcp_client.call_tool("comment_on_issue", {
"issue_key": issue_key,
"comment": "Automated branch creation completed"
})
```
## Security Considerations
- **Environment Variables**: Use environment variables for production
- **Token Rotation**: Regularly rotate API tokens
- **Network Security**: Use HTTPS for all API communications
- **Access Control**: Limit token permissions to minimum required
- **Logging**: Avoid logging sensitive information
## Troubleshooting
### Common Issues
**Authentication Errors:**
- Verify API tokens are correct and not expired
- Check that email matches Jira account
- Ensure GitLab token has required permissions
**Connection Issues:**
- Verify base URLs are correct
- Check network connectivity
- Confirm firewall settings allow HTTPS traffic
**Permission Errors:**
- Ensure Jira user has project access
- Verify GitLab token has repository permissions
- Check project visibility settings
### Debug Mode
Enable debug logging:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Support
For issues and questions:
1. Check the troubleshooting section
2. Review existing GitHub issues
3. Create a new issue with detailed information
## Changelog
### v1.0.0
- Initial MCP server implementation
- Jira and GitLab integration
- Comprehensive error handling
- Full test coverage
- Documentation and examples