@nexus2520/jira-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,318 @@
+# Jira MCP Server
+
+[![npm version](https://badge.fury.io/js/@nexus2520%2Fjira-mcp-server.svg)](https://www.npmjs.com/package/@nexus2520/jira-mcp-server)
+
+A Model Context Protocol (MCP) server for Jira API integration. This server enables AI assistants like Claude to interact with Jira Cloud instances for issue management, search, comments, and workflow transitions.
+
+## Features
+
+- **Issue Management**: Get, create, update, and assign Jira issues with custom field support
+- **JQL Search**: Search issues using Jira Query Language
+- **Comments**: Add and retrieve comments on issues (supports mentions and links)
+- **Workflow**: Get available transitions and change issue status
+- **Metadata Discovery**: Get field requirements and allowed values for projects
+- **User Search**: Find users by email or name for assignments
+- **Projects**: List all accessible projects
+- **API Token Authentication**: Secure authentication using email + API token
+
+## Installation
+
+### Using npm (Recommended)
+
+```bash
+npm install -g @nexus2520/jira-mcp-server
+```
+
+### From Source
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/pdogra1299/jira-mcp-server.git
+   cd jira-mcp-server
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   pnpm install
+   ```
+
+3. **Build the project**:
+   ```bash
+   pnpm run build
+   ```
+
+### Prerequisites
+
+- Node.js >= 16.0.0
+- A Jira Cloud account with API access
+- Jira API token (generate from [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens))
+
+## Configuration
+
+### Environment Variables
+
+The server requires the following environment variables:
+
+- `JIRA_EMAIL`: Your Atlassian account email
+- `JIRA_API_TOKEN`: Your Jira API token
+- `JIRA_BASE_URL`: Your Jira instance URL (e.g., `https://yourcompany.atlassian.net`)
+
+### Claude Desktop Configuration
+
+Add the following to your Claude Desktop MCP settings file:
+
+**Location**:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+**Configuration (if installed via npm)**:
+```json
+{
+  "mcpServers": {
+    "jira": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@nexus2520/jira-mcp-server"
+      ],
+      "env": {
+        "JIRA_EMAIL": "your-email@company.com",
+        "JIRA_API_TOKEN": "your-api-token-here",
+        "JIRA_BASE_URL": "https://yourcompany.atlassian.net"
+      }
+    }
+  }
+}
+```
+
+**Configuration (if built from source)**:
+```json
+{
+  "mcpServers": {
+    "jira": {
+      "name": "jira",
+      "command": "node",
+      "args": [
+        "/absolute/path/to/jira-mcp-server/build/index.js"
+      ],
+      "transport": "stdio",
+      "env": {
+        "JIRA_EMAIL": "your-email@company.com",
+        "JIRA_API_TOKEN": "your-api-token-here",
+        "JIRA_BASE_URL": "https://yourcompany.atlassian.net"
+      }
+    }
+  }
+}
+```
+
+### Getting Your Jira API Token
+
+1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
+2. Click "Create API token"
+3. Give it a label (e.g., "Claude MCP")
+4. Copy the generated token
+5. Use it in your configuration
+
+## Available Tools
+
+### Issue Management
+
+#### `get_issue`
+Get detailed information about a Jira issue.
+
+**Parameters**:
+- `issueKey` (required): The issue key (e.g., "PROJ-123")
+
+**Example**:
+```
+Get details for issue PROJ-123
+```
+
+#### `create_issue`
+Create a new Jira issue.
+
+**Important**: Always use `get_create_metadata` first to discover required fields, custom fields, and allowed values.
+
+**Parameters**:
+- `projectKey` (required): Project key (e.g., "PROJ", "DEV")
+- `summary` (required): Issue title
+- `issueType` (required): Type (e.g., "Bug", "Task", "Story")
+- `description` (optional): Issue description
+- `priority` (optional): Priority name
+- `assignee` (optional): Assignee account ID or email
+- `labels` (optional): Array of labels
+- `customFields` (optional): Custom fields object
+
+**Example**:
+```
+Create a bug in project PROJ with summary "Login button not working" and description "Users cannot log in"
+```
+
+#### `update_issue`
+Update fields of an existing issue.
+
+**Tip**: Use `get_create_metadata` to discover available custom fields and their allowed values.
+
+**Parameters**:
+- `issueKey` (required): Issue to update
+- `summary` (optional): New summary
+- `description` (optional): New description
+- `priority` (optional): New priority
+- `assignee` (optional): New assignee
+- `labels` (optional): New labels array
+- `customFields` (optional): Custom fields object
+
+#### `assign_issue`
+Assign an issue to a user.
+
+**Parameters**:
+- `issueKey` (required): Issue to assign
+- `assignee` (required): User account ID, email, or "-1" to unassign
+
+### Metadata & Discovery
+
+#### `get_create_metadata`
+Get field requirements and metadata for creating issues in a project.
+
+**Parameters**:
+- `projectKey` (required): Project key
+- `issueType` (optional): Filter by specific issue type
+
+#### `search_users`
+Search for users by name or email to get their account ID.
+
+**Parameters**:
+- `query` (required): Search query (email or name)
+- `maxResults` (optional): Max results (default: 50)
+
+### Search
+
+#### `search_issues`
+Search for issues using JQL. Returns issue keys and titles.
+
+**Parameters**:
+- `jql` (required): JQL query string
+- `maxResults` (optional): Max results (default: 50)
+
+**Example JQL queries**:
+- `"project = PROJ AND status = Open"`
+- `"assignee = currentUser() AND status != Done"`
+- `"priority = High AND created >= -7d"`
+
+#### `list_projects`
+List all accessible projects.
+
+**Parameters**:
+- `maxResults` (optional): Max results (default: 50)
+
+### Comments
+
+#### `add_comment`
+Add a comment to an issue.
+
+**Parameters**:
+- `issueKey` (required): Issue to comment on
+- `comment` (required): Comment text
+
+#### `get_comments`
+Get all comments for an issue.
+
+**Parameters**:
+- `issueKey` (required): Issue key
+
+### Workflow Transitions
+
+#### `get_transitions`
+Get available status transitions for an issue.
+
+**Parameters**:
+- `issueKey` (required): Issue key
+
+#### `transition_issue`
+Change the status of an issue.
+
+**Parameters**:
+- `issueKey` (required): Issue to transition
+- `transitionId` (required): Transition ID (from get_transitions)
+- `comment` (optional): Comment to add with transition
+
+## Usage Examples
+
+### With Claude Desktop
+
+Once configured, you can interact with Jira naturally:
+
+```
+"Show me all open bugs in project PROJ"
+"Create a new task in PROJ with summary 'Update documentation'"
+"Add a comment to PROJ-123 saying 'Fixed in latest release'"
+"What are the available transitions for PROJ-123?"
+"Move PROJ-123 to In Progress"
+"Assign PROJ-123 to john.doe@company.com"
+"Get the required fields for creating issues in PROJ"
+```
+
+## Development
+
+### Project Structure
+
+```
+jira-mcp-server/
+├── src/
+│   ├── index.ts                    # Main server entry point
+│   ├── utils/
+│   │   ├── api-client.ts          # Jira API client
+│   │   └── formatters.ts          # Response formatters
+│   ├── handlers/
+│   │   ├── issue-handlers.ts      # Issue CRUD operations
+│   │   ├── search-handlers.ts     # JQL search
+│   │   ├── comment-handlers.ts    # Comment operations
+│   │   ├── transition-handlers.ts # Workflow transitions
+│   │   └── project-handlers.ts    # Project operations
+│   └── tools/
+│       └── definitions.ts         # MCP tool definitions
+├── build/                          # Compiled JavaScript output
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+### Build Commands
+
+- `pnpm run build` - Compile TypeScript to JavaScript
+- `pnpm run dev` - Watch mode for development
+- `pnpm start` - Run the compiled server
+
+### API Reference
+
+This server uses the [Jira REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/).
+
+## Troubleshooting
+
+### "Error: JIRA_EMAIL and JIRA_API_TOKEN are required"
+
+Make sure you've set the environment variables in your MCP configuration.
+
+### Authentication errors
+
+- Verify your API token is correct
+- Ensure your email matches your Atlassian account
+- Check that your JIRA_BASE_URL doesn't have a trailing slash
+
+### Permission errors
+
+The API token uses the permissions of the user who created it. Make sure your account has the necessary permissions for the actions you're trying to perform.
+
+## License
+
+MIT
+
+## Author
+
+Parth Dogra
+
+## Contributing
+
+Feel free to open issues or submit pull requests for improvements!

package/build/handlers/comment-handlers.d.ts

@@ -0,0 +1,32 @@
+import { JiraApiClient } from '../utils/api-client.js';
+export declare class CommentHandlers {
+    private apiClient;
+    constructor(apiClient: JiraApiClient);
+    handleAddComment(args: any): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+    handleGetComments(args: any): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+}
+//# sourceMappingURL=comment-handlers.d.ts.map

package/build/handlers/comment-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-handlers.d.ts","sourceRoot":"","sources":["../../src/handlers/comment-handlers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD,qBAAa,eAAe;IACd,OAAO,CAAC,SAAS;gBAAT,SAAS,EAAE,aAAa;IAEtC,gBAAgB,CAAC,IAAI,EAAE,GAAG;;;;;;;;;;;;;IA2D1B,iBAAiB,CAAC,IAAI,EAAE,GAAG;;;;;;;;;;;;;CA8BlC"}

package/build/handlers/comment-handlers.js

@@ -0,0 +1,91 @@
+import { JiraFormatters } from '../utils/formatters.js';
+export class CommentHandlers {
+    apiClient;
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    async handleAddComment(args) {
+        try {
+            const { issueKey, comment } = args;
+            if (!issueKey || !comment) {
+                throw new Error('issueKey and comment are required');
+            }
+            // Handle comment body - convert to ADF format if it's plain text
+            let commentBody;
+            if (typeof comment === 'string') {
+                // Convert plain text to Atlassian Document Format
+                commentBody = {
+                    type: 'doc',
+                    version: 1,
+                    content: [
+                        {
+                            type: 'paragraph',
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: comment,
+                                },
+                            ],
+                        },
+                    ],
+                };
+            }
+            else {
+                // Already in ADF format
+                commentBody = comment;
+            }
+            const commentData = {
+                body: commentBody,
+            };
+            const result = await this.apiClient.post(`/issue/${issueKey}/comment`, commentData);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `✅ Comment added to ${issueKey} successfully!\n\n**Comment ID**: ${result.id}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JiraFormatters.formatError(error),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    async handleGetComments(args) {
+        try {
+            const { issueKey } = args;
+            if (!issueKey) {
+                throw new Error('issueKey is required');
+            }
+            const result = await this.apiClient.get(`/issue/${issueKey}/comment`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JiraFormatters.formatComments(result),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JiraFormatters.formatError(error),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+}
+//# sourceMappingURL=comment-handlers.js.map

package/build/handlers/comment-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-handlers.js","sourceRoot":"","sources":["../../src/handlers/comment-handlers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,MAAM,OAAO,eAAe;IACN;IAApB,YAAoB,SAAwB;QAAxB,cAAS,GAAT,SAAS,CAAe;IAAG,CAAC;IAEhD,KAAK,CAAC,gBAAgB,CAAC,IAAS;QAC9B,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;YAEnC,IAAI,CAAC,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;YACvD,CAAC;YAED,iEAAiE;YACjE,IAAI,WAAW,CAAC;YAChB,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAChC,kDAAkD;gBAClD,WAAW,GAAG;oBACZ,IAAI,EAAE,KAAK;oBACX,OAAO,EAAE,CAAC;oBACV,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,WAAW;4BACjB,OAAO,EAAE;gCACP;oCACE,IAAI,EAAE,MAAM;oCACZ,IAAI,EAAE,OAAO;iCACd;6BACF;yBACF;qBACF;iBACF,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,wBAAwB;gBACxB,WAAW,GAAG,OAAO,CAAC;YACxB,CAAC;YAED,MAAM,WAAW,GAAG;gBAClB,IAAI,EAAE,WAAW;aAClB,CAAC;YAEF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,QAAQ,UAAU,EAAE,WAAW,CAAC,CAAC;YAEpF,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,sBAAsB,QAAQ,qCAAqC,MAAM,CAAC,EAAE,EAAE;qBACrF;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,cAAc,CAAC,WAAW,CAAC,KAAK,CAAC;qBACxC;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,iBAAiB,CAAC,IAAS;QAC/B,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;YAE1B,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;YAC1C,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,UAAU,QAAQ,UAAU,CAAC,CAAC;YAEtE,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,cAAc,CAAC,cAAc,CAAC,MAAM,CAAC;qBAC5C;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,cAAc,CAAC,WAAW,CAAC,KAAK,CAAC;qBACxC;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/build/handlers/issue-handlers.d.ts

@@ -0,0 +1,65 @@
+import { JiraApiClient } from '../utils/api-client.js';
+import { UserHandlers } from './user-handlers.js';
+export declare class IssueHandlers {
+    private apiClient;
+    private userHandlers;
+    private fieldMetadataCache;
+    constructor(apiClient: JiraApiClient, userHandlers: UserHandlers);
+    /**
+     * Fetch and cache field metadata (field ID -> display name mapping)
+     */
+    private getFieldMetadata;
+    handleGetIssue(args: any): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+    handleCreateIssue(args: any): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+    handleUpdateIssue(args: any): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+    handleAssignIssue(args: any): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+}
+//# sourceMappingURL=issue-handlers.d.ts.map

package/build/handlers/issue-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue-handlers.d.ts","sourceRoot":"","sources":["../../src/handlers/issue-handlers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,qBAAa,aAAa;IAGZ,OAAO,CAAC,SAAS;IAAiB,OAAO,CAAC,YAAY;IAFlE,OAAO,CAAC,kBAAkB,CAAoC;gBAE1C,SAAS,EAAE,aAAa,EAAU,YAAY,EAAE,YAAY;IAEhF;;OAEG;YACW,gBAAgB;IAuBxB,cAAc,CAAC,IAAI,EAAE,GAAG;;;;;;;;;;;;;IAgCxB,iBAAiB,CAAC,IAAI,EAAE,GAAG;;;;;;;;;;;;;IAmF3B,iBAAiB,CAAC,IAAI,EAAE,GAAG;;;;;;;;;;;;;IA+E3B,iBAAiB,CAAC,IAAI,EAAE,GAAG;;;;;;;;;;;;;CA2ClC"}