Jira MCP Server

# Jira MCP Server

A collection of tools designed for interacting with Jira via the Model Context Protocol (MCP), providing core Jira functionalities and a unified, guided Issue Creation and Update Wizard.

## Installation

To install this into a client:

```bash
{
  "mcpServers": {
    "JiraMCP_Published": {
      "command": "npx",
      "args": [
        "@timbreeding/jira-mcp-server@latest",
        "--jira-base-url=https://example.atlassian.net",
        "--jira-username=someJiraUserEmail@domain.com",
        "--jira-api-token=<your jira token>"
      ],
      "env": {
        "DEBUG": "true",
        "LOG_FILE_PATH": "" // Some full path. If blank, it will not write logs to a file.
      }
    }
  }
}

```

## Usage
...
## Configuration

### Environment Variables
 For running locally, you can put the DEBUG and LOG_FILE_PATH into your .env.

## Available Tools

This application exposes the following tools via the Model Context Protocol:

### Core Jira Tools

- `getJiraIssue`: Fetches a Jira issue by its key.
- `analyzeJiraIssue`: Performs comprehensive analysis of a Jira issue.
- `jiraGet`: Fetches data from any Jira API GET endpoint.
- `getIssuesByJql`: Searches for Jira issues using a JQL query.

### Issue Creation Wizard Tools

These tools provide a step-by-step, guided process for creating new Jira issues. The wizard maintains state throughout the creation flow, typically involving these stages: initiating the process, selecting a project (`getProjects`), choosing an issue type (`getIssueTypes`), retrieving and populating the necessary fields (`getFields`, `updateFields`), optionally analyzing the issue details, and finally confirming and creating the issue (`createIssue`). Use `getState` and `getStatus` to monitor progress, and `resetState` to start over.

- `issueCreation_getState`: Gets the current internal state of the wizard.
- `issueCreation_getStatus`: Gets the high-level status of the wizard.
- `issueCreation_initiateState`: Initializes a new wizard state.
- `issueCreation_resetState`: Resets the wizard state.
- `issueCreation_updateState`: Updates the wizard state (project, issue type, fields, step).
- `issueCreation_createIssue`: Creates a Jira issue using the wizard's state.
- `issueCreation_getProjects`: Retrieves available Jira projects.
- `issueCreation_getIssueTypes`: Gets available issue types for the selected project.
- `issueCreation_getFields`: Retrieves fields required for the selected project/issue type.
- `issueCreation_updateFields`: Updates specific field values in the wizard state.
- `issueCreation_setAnalysisComplete`: Sets the analysis complete flag.
- `issueCreation_setUserConfirmation`: Sets the user confirmation flag before creation.
- `issueCreation_analyzeIssue`: Analyzes the issue details within the wizard context.

### Issue Update Wizard Tools (Unified Update Workflow)

These tools provide a unified, robust mechanism for updating any Jira issue—whether newly created or already existing. All updates now use a single, consistent workflow:

- `issueUpdateWizard_loadIssueIntoState`: Fetch a Jira issue by key and load it into the state manager for unified update workflows.
- `issueUpdateWizard_updateIssueFromState`: Update any loaded issue using the current state (fields, project, type, etc.).

**Key Principles:**
- All issue updates (new or existing) follow the same pattern: load the issue into state, modify fields, and update via the API.
- No code duplication between new and existing issue updates.
- Minimal, explicit, and robust error handling.
- 100% unit test coverage for update operations.

## Development

### Running Tests

Jest is configured for testing. To run the test suite:

```bash
npm test
```

### Code Quality Checks

To run type checking, linting, and tests together:

```bash
npm run check-codebase
```

### Running with MCP Inspector

For local development and testing using the Model Context Protocol Inspector, you can launch the application and pass the required environment variables using the `-e` flag:

```bash
npx @modelcontextprotocol/inspector -e JIRA_BASE_URL=https://your-domain.atlassian.net -e JIRA_USERNAME=your-email@example.com -e JIRA_API_TOKEN=your-api-token -e DEBUG=true node build/index.js
```

_(Ensure you have built the project first if using `build/index.js`)_

## License

This project is licensed under the MIT License - see the `LICENSE` file for details.