@abdelrahmanhsn/jira-mcp 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,128 @@
+# @abdelrahmanhsn/jira-mcp
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects your AI IDE to Jira. Query your tickets, active sprint, and issue details directly from GitHub Copilot, Cursor, Claude Desktop, or any MCP-compatible client.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_my_tickets` | Get all Jira tickets assigned to you, ordered by last updated |
+| `get_active_sprint_tickets` | Get your tickets in the currently active sprint |
+| `get_issue_details` | Get full details (description + attachments) for a specific issue key |
+
+## Prerequisites
+
+- Node.js 18 or later
+- A Jira Cloud account
+- A Jira API token ([generate one here](https://id.atlassian.com/manage-profile/security/api-tokens))
+
+## Setup
+
+### 1. Get your Jira API token
+
+1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
+2. Click **Create API token**
+3. Copy the token — you'll need it below
+
+### 2. Configure your MCP client
+
+Pick your AI IDE below and add the config. Replace the `env` values with your own.
+
+---
+
+#### GitHub Copilot (VS Code)
+
+Open **User Settings (JSON)** via `Cmd+Shift+P` → `Open User Settings (JSON)` and add:
+
+```json
+"mcp": {
+  "servers": {
+    "jira-mcp": {
+      "command": "npx",
+      "args": ["-y", "@abdelrahmanhsn/jira-mcp"],
+      "env": {
+        "JIRA_EMAIL": "you@company.com",
+        "JIRA_TOKEN": "your-api-token",
+        "JIRA_DOMAIN": "yourcompany.atlassian.net",
+        "JIRA_PROJECT": "PROJ"
+      }
+    }
+  }
+}
+```
+
+---
+
+#### Cursor
+
+Open `~/.cursor/mcp.json` (or `Cursor Settings → MCP`) and add:
+
+```json
+{
+  "mcpServers": {
+    "jira-mcp": {
+      "command": "npx",
+      "args": ["-y", "@abdelrahmanhsn/jira-mcp"],
+      "env": {
+        "JIRA_EMAIL": "you@company.com",
+        "JIRA_TOKEN": "your-api-token",
+        "JIRA_DOMAIN": "yourcompany.atlassian.net",
+        "JIRA_PROJECT": "PROJ"
+      }
+    }
+  }
+}
+```
+
+---
+
+#### Claude Desktop
+
+Open `~/Library/Application Support/Claude/claude_desktop_config.json` and add:
+
+```json
+{
+  "mcpServers": {
+    "jira-mcp": {
+      "command": "npx",
+      "args": ["-y", "@abdelrahmanhsn/jira-mcp"],
+      "env": {
+        "JIRA_EMAIL": "you@company.com",
+        "JIRA_TOKEN": "your-api-token",
+        "JIRA_DOMAIN": "yourcompany.atlassian.net",
+        "JIRA_PROJECT": "PROJ"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `JIRA_EMAIL` | ✅ | Your Jira account email |
+| `JIRA_TOKEN` | ✅ | Your Jira API token |
+| `JIRA_DOMAIN` | ✅ | Your Jira domain, e.g. `yourcompany.atlassian.net` |
+| `JIRA_PROJECT` | ✅ | Your Jira project key, e.g. `PROJ` |
+
+## Usage Examples
+
+Once configured, you can ask your AI assistant:
+
+- *"Show me my current Jira tickets"*
+- *"What's in my active sprint?"*
+- *"Get me the details for PROJ-1234"*
+- *"Summarize the description of PROJ-5678"*
+
+## Security
+
+- Credentials are **never** stored in code — they are injected at runtime by your MCP client
+- Each user provides their own credentials in their local MCP config
+- Your API token is only sent to your own Jira domain over HTTPS
+
+## License
+
+ISC

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@abdelrahmanhsn/jira-mcp",
   "type": "module",
-  "version": "1.0.0",
-  "description": "MCP server for Jira — query tickets, sprints, and issue details from any AI IDE",
+  "version": "1.0.1",
+  "description": "MCP server for Jira — query your tickets, active sprints, and issue details from any AI IDE (GitHub Copilot, Cursor, Claude Desktop)",
   "main": "server.js",
   "bin": {
     "jira-mcp": "./server.js"
@@ -10,13 +10,32 @@
   "scripts": {
     "start": "node server.js"
   },
-  "keywords": ["mcp", "jira", "atlassian", "model-context-protocol", "ai"],
-  "author": "Abdelrahman Hassan",
+  "keywords": [
+    "mcp",
+    "jira",
+    "atlassian",
+    "model-context-protocol",
+    "ai",
+    "copilot",
+    "cursor",
+    "claude",
+    "sprint",
+    "tickets",
+    "devtools"
+  ],
+  "author": {
+    "name": "Abdelrahman Hassan",
+    "email": "abdelrahmanhsn1@gmail.com"
+  },
   "license": "ISC",
   "repository": {
     "type": "git",
     "url": ""
   },
+  "homepage": "https://www.npmjs.com/package/@abdelrahmanhsn/jira-mcp",
+  "bugs": {
+    "url": ""
+  },
   "engines": {
     "node": ">=18"
   },

package/server.js

@@ -5,11 +5,12 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 
 // ── Jira credentials (injected by MCP client via env) ──────────────────────
-const JIRA_EMAIL  = process.env.JIRA_EMAIL;
-const JIRA_TOKEN  = process.env.JIRA_TOKEN;
-const JIRA_DOMAIN = process.env.JIRA_DOMAIN;
+const JIRA_EMAIL   = process.env.JIRA_EMAIL;
+const JIRA_TOKEN   = process.env.JIRA_TOKEN;
+const JIRA_DOMAIN  = process.env.JIRA_DOMAIN;
+const JIRA_PROJECT = process.env.JIRA_PROJECT;
 
-const missing = ["JIRA_EMAIL", "JIRA_TOKEN", "JIRA_DOMAIN"].filter(k => !process.env[k]);
+const missing = ["JIRA_EMAIL", "JIRA_TOKEN", "JIRA_DOMAIN", "JIRA_PROJECT"].filter(k => !process.env[k]);
 if (missing.length) {
   process.stderr.write(
     `[jira-mcp] Missing required environment variables: ${missing.join(", ")}\n` +
@@ -58,11 +59,11 @@ server.tool(
 // Tool: get_active_sprint_tickets
 server.tool(
   "get_active_sprint_tickets",
-  "Get user tickets in the active sprint of the Core Team board (STUD project)",
+  "Get user tickets in the active sprint for the configured Jira project",
   {},
   async () => {
     const result = await searchJira(
-      "project = 'STUD' AND sprint IN openSprints() AND assignee = currentUser()"
+      `project = '${JIRA_PROJECT}' AND sprint IN openSprints() AND assignee = currentUser()`
     );
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   }