mcp-jira-cloud 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,139 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-02-15
+
+### Added
+
+- **Phase 1: Core Issue CRUD** (14 new tools)
+  - `jira_create_issue` - Create new issues with full field support
+  - `jira_update_issue` - Update issues with partial field support
+  - `jira_delete_issue` - Delete issues with safety confirmation
+  - `jira_assign_issue` - Assign/unassign users
+  - `jira_get_transitions` - Get available workflow transitions
+  - `jira_transition_issue` - Move issues through workflow
+  - `jira_get_issue_types` - Get available issue types
+  - `jira_get_priorities` - Get priority levels
+  - `jira_get_statuses` - Get available statuses
+  - `jira_get_components` - Get project components
+  - `jira_get_versions` - Get project versions
+  - `jira_search_users` - Search for Jira users
+  - `jira_get_changelog` - Get issue history
+
+- **Phase 2: Agile Tools** (16 new tools)
+  - `jira_get_boards` - List Scrum/Kanban boards
+  - `jira_get_board` - Get board details
+  - `jira_get_board_configuration` - Get board configuration
+  - `jira_get_sprints` - List sprints for a board
+  - `jira_get_sprint` - Get sprint details
+  - `jira_create_sprint` - Create new sprints
+  - `jira_update_sprint` - Update sprint details
+  - `jira_start_sprint` - Start a future sprint
+  - `jira_complete_sprint` - Complete an active sprint
+  - `jira_delete_sprint` - Delete sprints with confirmation
+  - `jira_get_sprint_issues` - Get issues in a sprint
+  - `jira_move_issues_to_sprint` - Move issues to a sprint
+  - `jira_get_backlog_issues` - Get backlog issues
+  - `jira_move_issues_to_backlog` - Move issues to backlog
+  - `jira_rank_issues` - Change issue ranking
+
+- **Phase 3: Issue Relationships** (11 new tools)
+  - `jira_get_issue_links` - Get linked issues
+  - `jira_create_issue_link` - Link issues together
+  - `jira_delete_issue_link` - Remove issue links
+  - `jira_get_link_types` - Get available link types
+  - `jira_get_watchers` - Get issue watchers
+  - `jira_add_watcher` - Add watchers to issues
+  - `jira_remove_watcher` - Remove watchers
+  - `jira_get_votes` - Get issue vote count
+  - `jira_add_vote` - Vote for an issue
+  - `jira_remove_vote` - Remove vote from issue
+
+- **Phase 4: Attachments** (2 new tools)
+  - `jira_get_attachments` - Get issue attachments
+  - `jira_delete_attachment` - Delete attachments
+
+- **Phase 5: Epic Management** (4 new tools)
+  - `jira_get_epics` - Get epics for a board
+  - `jira_get_epic_issues` - Get issues in an epic
+  - `jira_move_issues_to_epic` - Move issues to epic
+  - `jira_remove_issues_from_epic` - Remove issues from epic
+
+- **Phase 6: Fields and Metadata** (3 new tools)
+  - `jira_get_fields` - Get all available fields
+  - `jira_get_create_metadata` - Get metadata for creating issues
+  - `jira_get_edit_metadata` - Get metadata for editing issues
+
+- **Phase 7: Filters** (7 new tools)
+  - `jira_get_filters` - Search saved filters
+  - `jira_get_filter` - Get filter details
+  - `jira_create_filter` - Create new filters
+  - `jira_update_filter` - Update existing filters
+  - `jira_delete_filter` - Delete filters with confirmation
+  - `jira_get_my_filters` - Get filters owned by current user
+  - `jira_get_favourite_filters` - Get favourite filters
+
+### Changed
+
+- Version bumped to 2.0.0 (major feature release)
+- Helper functions for field building (`buildIssueFields`, `buildUpdateOperations`)
+- Improved TypeScript strict mode compliance
+- Total tools: 57 (up from 18)
+
+---
+
+## [1.0.0] - 2026-02-15
+
+### Added
+
+- Initial release
+- **Authentication**
+  - Basic Auth support (email + API token)
+  - OAuth 2.0 support with automatic token refresh
+  - Keytar integration for secure credential storage
+  - Multiple authentication status tools
+  
+- **Issue Management**
+  - `jira_get_issue` - Get full issue details
+  - `jira_get_issue_summary` - Get issue summary with acceptance criteria
+  - `jira_search_issues` - Search with JQL (full results)
+  - `jira_search_issues_summary` - Search with minimal fields
+  - `jira_get_my_open_issues` - Get current user's open tickets
+  - `jira_resolve` - Smart routing for common intents
+
+- **Comments**
+  - `jira_get_issue_comments` - Retrieve issue comments
+  - `jira_add_comment` - Add comments to issues
+
+- **Work Logs**
+  - `jira_add_worklog` - Log time spent on issues
+  - `jira_get_worklogs` - Retrieve work logs from issues
+
+- **Projects**
+  - `jira_list_projects` - List accessible projects
+  - `jira_get_project` - Get project details
+
+- **User**
+  - `jira_whoami` - Get current user profile
+
+### Security
+
+- Credentials stored securely via Keytar
+- `.gitignore` and `.npmignore` configured to protect sensitive data
+- OAuth tokens auto-refresh before expiration
+
+---
+
+## [Unreleased]
+
+### Planned
+
+- Attachment upload support
+- Bulk operations
+- Dashboard management
+- Advanced JQL builder
+- Webhook integration

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tezaswi Raj (github: tezaswi7222)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,452 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/tezaswi7222/jira-mcp/main/assets/logo.png" alt="Jira MCP Logo" width="120" height="120">
+</p>
+
+<h1 align="center">Jira MCP Server</h1>
+
+<p align="center">
+  <strong>Supercharge your AI assistant with seamless Jira integration</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/mcp-jira-cloud">
+    <img src="https://img.shields.io/npm/v/mcp-jira-cloud?style=flat-square&color=cb3837&logo=npm" alt="npm version">
+  </a>
+  <a href="https://www.npmjs.com/package/mcp-jira-cloud">
+    <img src="https://img.shields.io/npm/dm/mcp-jira-cloud?style=flat-square&color=blue" alt="npm downloads">
+  </a>
+  <a href="https://github.com/tezaswi7222/jira-mcp/blob/main/LICENSE">
+    <img src="https://img.shields.io/npm/l/mcp-jira-cloud?style=flat-square&color=green" alt="license">
+  </a>
+  <a href="https://github.com/tezaswi7222/jira-mcp">
+    <img src="https://img.shields.io/github/stars/tezaswi7222/jira-mcp?style=flat-square&logo=github" alt="GitHub stars">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://modelcontextprotocol.io/">
+    <img src="https://img.shields.io/badge/MCP-Compatible-8A2BE2?style=flat-square" alt="MCP Compatible">
+  </a>
+  <a href="https://nodejs.org/">
+    <img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 18+">
+  </a>
+  <a href="https://www.typescriptlang.org/">
+    <img src="https://img.shields.io/badge/TypeScript-5.0%2B-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript 5.0+">
+  </a>
+</p>
+
+<p align="center">
+  <a href="#-quick-start">Quick Start</a> •
+  <a href="#-features">Features</a> •
+  <a href="#%EF%B8%8F-configuration">Configuration</a> •
+  <a href="#-available-tools">Tools</a> •
+  <a href="#-usage-examples">Examples</a> •
+  <a href="#-troubleshooting">Troubleshooting</a>
+</p>
+
+---
+
+A **Model Context Protocol (MCP)** server that enables AI assistants like **GitHub Copilot** and **Claude** to interact with your Jira Cloud instance. Search issues, manage tickets, log work, and more — all through natural language conversation.
+
+## ✨ Features
+
+<table>
+<tr>
+<td>
+
+### 🔐 Authentication
+- Basic Auth (API Token)
+- OAuth 2.0 with auto-refresh
+- Secure credential storage via Keytar
+
+</td>
+<td>
+
+### 📋 Issue Management
+- Search with JQL
+- Get issue details & comments
+- View your open tickets
+
+</td>
+</tr>
+<tr>
+<td>
+
+### ⏱️ Time Tracking
+- Log work on issues
+- View work logs
+- Flexible time formats
+
+</td>
+<td>
+
+### 💬 Collaboration
+- Add comments to issues
+- Access project information
+- List accessible projects
+
+</td>
+</tr>
+</table>
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install -g mcp-jira-cloud
+```
+
+Or use directly with `npx`:
+
+```bash
+npx mcp-jira-cloud
+```
+
+### Get Your API Token
+
+1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+2. Click **Create API token**
+3. Copy the token
+
+### Configure Your AI Assistant
+
+<details>
+<summary><strong>📘 VS Code (GitHub Copilot)</strong></summary>
+
+Create or edit `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "jira": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["mcp-jira-cloud"],
+      "env": {
+        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
+        "JIRA_EMAIL": "your-email@example.com",
+        "JIRA_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>🤖 Claude Desktop</strong></summary>
+
+Add to your Claude configuration (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "jira": {
+      "command": "npx",
+      "args": ["mcp-jira-cloud"],
+      "env": {
+        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
+        "JIRA_EMAIL": "your-email@example.com",
+        "JIRA_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>⚡ Cursor</strong></summary>
+
+Create `.cursor/mcp.json` in your project or home directory:
+
+```json
+{
+  "mcpServers": {
+    "jira": {
+      "command": "npx",
+      "args": ["mcp-jira-cloud"],
+      "env": {
+        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
+        "JIRA_EMAIL": "your-email@example.com",
+        "JIRA_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>🔧 Windsurf</strong></summary>
+
+Add to your Windsurf MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "jira": {
+      "command": "npx",
+      "args": ["mcp-jira-cloud"],
+      "env": {
+        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
+        "JIRA_EMAIL": "your-email@example.com",
+        "JIRA_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+#### Basic Authentication (Recommended)
+
+| Variable | Description | Required |
+|----------|-------------|:--------:|
+| `JIRA_BASE_URL` | Your Jira instance URL (e.g., `https://company.atlassian.net`) | ✅ |
+| `JIRA_EMAIL` | Your Atlassian account email | ✅ |
+| `JIRA_API_TOKEN` | API token from Atlassian | ✅ |
+
+#### OAuth 2.0 Authentication
+
+<details>
+<summary>Click to expand OAuth configuration</summary>
+
+For OAuth authentication:
+
+1. Create an OAuth 2.0 app in the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/)
+2. Configure the required scopes:
+   - `read:jira-work`
+   - `read:jira-user`
+   - `write:jira-work`
+   - `offline_access`
+
+| Variable | Description | Required |
+|----------|-------------|:--------:|
+| `JIRA_OAUTH_CLIENT_ID` | OAuth Client ID | ✅ |
+| `JIRA_OAUTH_CLIENT_SECRET` | OAuth Client Secret | ✅ |
+| `JIRA_OAUTH_ACCESS_TOKEN` | Access token | ✅ |
+| `JIRA_OAUTH_REFRESH_TOKEN` | Refresh token | ⬜ |
+| `JIRA_CLOUD_ID` | Your Jira Cloud ID | ✅ |
+
+</details>
+
+#### Optional Settings
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `JIRA_ACCEPTANCE_CRITERIA_FIELD` | Custom field ID for acceptance criteria | — |
+
+## 🛠️ Available Tools
+
+### Authentication
+
+| Tool | Description |
+|------|-------------|
+| `jira_auth_status` | Check current authentication status |
+| `jira_whoami` | Get current user's Jira profile |
+| `jira_clear_auth` | Clear stored credentials |
+
+<details>
+<summary><strong>OAuth Tools</strong></summary>
+
+| Tool | Description |
+|------|-------------|
+| `jira_oauth_get_auth_url` | Generate OAuth authorisation URL |
+| `jira_oauth_exchange_code` | Exchange OAuth code for tokens |
+| `jira_oauth_refresh` | Manually refresh OAuth token |
+| `jira_oauth_list_sites` | List accessible Jira sites |
+
+</details>
+
+### Issue Management
+
+| Tool | Description |
+|------|-------------|
+| `jira_get_issue` | Get full details of a Jira issue |
+| `jira_get_issue_summary` | Get summary, description, and acceptance criteria |
+| `jira_search_issues` | Search issues with JQL (full results) |
+| `jira_search_issues_summary` | Search with minimal fields (key, summary, status) |
+| `jira_get_my_open_issues` | Get your open/in-progress issues |
+| `jira_resolve` | Smart routing tool for common intents |
+
+### Comments & Work Logs
+
+| Tool | Description |
+|------|-------------|
+| `jira_get_issue_comments` | Get comments on an issue |
+| `jira_add_comment` | Add a comment to an issue |
+| `jira_add_worklog` | Log time spent on an issue |
+| `jira_get_worklogs` | Get work logs for an issue |
+
+### Projects
+
+| Tool | Description |
+|------|-------------|
+| `jira_list_projects` | List accessible Jira projects |
+| `jira_get_project` | Get project details and metadata |
+
+## 💡 Usage Examples
+
+Once configured, interact with Jira through natural conversation:
+
+### Issue Management
+
+```
+👤 "What's the status of PROJ-123?"
+🤖 Fetches and displays issue details, status, and assignee
+
+👤 "Find all open bugs assigned to me"
+🤖 Searches using JQL and returns matching issues
+
+👤 "What tickets am I working on?"
+🤖 Lists your in-progress issues
+```
+
+### Time Tracking
+
+```
+👤 "Log 2 hours on PROJ-456 for code review"
+🤖 Creates work log entry with description
+
+👤 "How much time has been logged on PROJ-789?"
+🤖 Retrieves and summarises work logs
+```
+
+### Collaboration
+
+```
+👤 "Add a comment to PROJ-123 saying 'Fixed in latest commit'"
+🤖 Adds the comment to the issue
+
+👤 "Show me the comments on PROJ-456"
+🤖 Displays all comments with authors and timestamps
+```
+
+## 🔧 Troubleshooting
+
+<details>
+<summary><strong>❌ "MISSING_AUTH" Error</strong></summary>
+
+Ensure your environment variables are correctly set. Verify with `jira_auth_status`.
+
+**Checklist:**
+- ✅ `JIRA_BASE_URL` includes `https://` and is your full Jira domain
+- ✅ `JIRA_EMAIL` matches your Atlassian account email
+- ✅ `JIRA_API_TOKEN` is a valid, non-expired token
+
+</details>
+
+<details>
+<summary><strong>❌ "401 Unauthorised" Error</strong></summary>
+
+Your credentials are invalid or expired.
+
+**For Basic Auth:**
+- Verify your API token at [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+- Ensure the token hasn't been revoked
+
+**For OAuth:**
+- Try refreshing the token with `jira_oauth_refresh`
+- Re-authenticate if the refresh token has expired
+
+</details>
+
+<details>
+<summary><strong>❌ "403 Forbidden" Error</strong></summary>
+
+You don't have permission to access the requested resource.
+
+**Solutions:**
+- Check your Jira permissions for the project
+- Contact your Jira administrator
+- Verify your OAuth scopes include required permissions
+
+</details>
+
+<details>
+<summary><strong>❌ "404 Not Found" Error</strong></summary>
+
+The issue or project doesn't exist, or you don't have access to view it.
+
+**Solutions:**
+- Verify the issue key is correct (e.g., `PROJ-123`)
+- Check if you have access to the project
+- Ensure the issue hasn't been deleted or moved
+
+</details>
+
+## 📦 Package Information
+
+| Attribute | Value |
+|-----------|-------|
+| Package name | [`mcp-jira-cloud`](https://www.npmjs.com/package/mcp-jira-cloud) |
+| License | [MIT](LICENSE) |
+| Node.js | ≥18.0.0 |
+| TypeScript | ≥5.0.0 |
+| Module | ES Modules |
+
+### Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) | MCP protocol implementation |
+| [`axios`](https://www.npmjs.com/package/axios) | HTTP client for Jira API |
+| [`keytar`](https://www.npmjs.com/package/keytar) | Secure credential storage |
+| [`zod`](https://www.npmjs.com/package/zod) | Schema validation |
+
+## 🔒 Security
+
+- Credentials are stored securely via system keychain (Keytar)
+- OAuth tokens auto-refresh before expiration
+- No credentials are logged or exposed in error messages
+- See [SECURITY.md](SECURITY.md) for our security policy
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📄 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a list of changes in each version.
+
+## 📜 License
+
+This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.
+
+## 🔗 Links
+
+| Resource | Link |
+|----------|------|
+| GitHub | [github.com/tezaswi7222/jira-mcp](https://github.com/tezaswi7222/jira-mcp) |
+| npm | [npmjs.com/package/mcp-jira-cloud](https://www.npmjs.com/package/mcp-jira-cloud) |
+| Issues | [Report a bug](https://github.com/tezaswi7222/jira-mcp/issues) |
+| MCP Protocol | [modelcontextprotocol.io](https://modelcontextprotocol.io/) |
+| Jira API | [Jira REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/) |
+
+---
+
+<p align="center">
+  Made with ❤️ by <a href="https://github.com/tezaswi7222">Tezaswi Raj (github: tezaswi7222)</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/sponsors/tezaswi7222">
+    <img src="https://img.shields.io/badge/Sponsor-❤️-ea4aaa?style=for-the-badge" alt="Sponsor">
+  </a>
+</p>