README.md•4.41 kB
# 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.