@abdelrahmanhsn/jira-mcp 1.0.0 → 1.2.0

package/README.md

@@ -0,0 +1,136 @@
+# @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 |
+| `add_comment` | Add a comment to any Jira issue |
+| `get_my_standup` | Get a standup summary of tickets you updated since yesterday |
+| `get_sprint_summary` | Get all sprint tickets grouped by status (Todo / In Progress / Done) |
+| `search_tickets` | Search tickets with plain English or raw JQL |
+
+## 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"*
+- *"Add a comment to PROJ-123 saying the fix is deployed to staging"*
+- *"Give me my standup for today"*
+- *"Summarize the active sprint — how many tickets are done vs in progress?"*
+- *"Search for open bugs related to login"*
+
+## 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.2.0",
+  "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) }] };
   }
@@ -79,6 +80,117 @@ server.tool(
   }
 );
 
+// Tool: add_comment
+server.tool(
+  "add_comment",
+  "Add a comment to a Jira issue",
+  {
+    issueKey: z.string().describe("The Jira issue key, e.g. PROJ-123"),
+    comment:  z.string().describe("The comment text to add"),
+  },
+  async ({ issueKey, comment }) => {
+    await jiraClient.post(`/issue/${issueKey}/comment`, {
+      body: {
+        type: "doc",
+        version: 1,
+        content: [{ type: "paragraph", content: [{ type: "text", text: comment }] }],
+      },
+    });
+    return { content: [{ type: "text", text: `Comment added to ${issueKey}.` }] };
+  }
+);
+
+// Tool: get_my_standup
+server.tool(
+  "get_my_standup",
+  "Get a standup summary: tickets you updated or commented on yesterday and today",
+  {},
+  async () => {
+    const yesterday = new Date();
+    yesterday.setDate(yesterday.getDate() - 1);
+    const since = yesterday.toISOString().split("T")[0]; // YYYY-MM-DD
+
+    const [updated, commented] = await Promise.all([
+      searchJira(
+        `assignee = currentUser() AND updated >= "${since}" ORDER BY updated DESC`,
+        "summary,status,priority,issuetype"
+      ),
+      searchJira(
+        `issueFunction in commented("by currentUser() after ${since}")`,
+        "summary,status,issuetype"
+      ).catch(() => []), // issueFunction requires ScriptRunner; gracefully skip if unavailable
+    ]);
+
+    const result = {
+      updated_tickets: updated,
+      commented_tickets: commented,
+      summary: `You updated ${updated.length} ticket(s) since ${since}.`,
+    };
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// Tool: get_sprint_summary
+server.tool(
+  "get_sprint_summary",
+  "Get a summary of all tickets in the active sprint grouped by status",
+  {},
+  async () => {
+    const issues = await searchJira(
+      `project = '${JIRA_PROJECT}' AND sprint IN openSprints()`,
+      "summary,status,priority,issuetype,assignee"
+    );
+
+    const grouped = issues.reduce((acc, issue) => {
+      const s = issue.status || "Unknown";
+      if (!acc[s]) acc[s] = [];
+      acc[s].push({ key: issue.key, summary: issue.summary, priority: issue.priority, type: issue.type });
+      return acc;
+    }, {});
+
+    const result = {
+      total: issues.length,
+      by_status: grouped,
+    };
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// Tool: search_tickets
+server.tool(
+  "search_tickets",
+  "Search Jira tickets using a plain-text query or a JQL string",
+  {
+    query: z.string().describe(
+      "Plain English query (e.g. 'open bugs assigned to me') or raw JQL (e.g. 'project = PROJ AND status = Open')"
+    ),
+    maxResults: z.number().optional().default(20).describe("Maximum number of results to return (default 20)"),
+  },
+  async ({ query, maxResults }) => {
+    // Use as raw JQL if it looks like JQL, otherwise wrap in a text search
+    const looksLikeJql = /\b(AND|OR|IN|=|!=|~|project|status|assignee|sprint|priority|issuetype)\b/i.test(query);
+    const jql = looksLikeJql
+      ? query
+      : `project = '${JIRA_PROJECT}' AND text ~ "${query.replace(/"/g, '\\"')}" ORDER BY updated DESC`;
+
+    const response = await jiraClient.get("/search/jql", {
+      params: { jql, fields: "summary,status,priority,issuetype,assignee,reporter", maxResults },
+    });
+
+    const issues = (response.data.issues || []).map(i => ({
+      key: i.key,
+      summary: i.fields?.summary,
+      status: i.fields?.status?.name,
+      priority: i.fields?.priority?.name,
+      type: i.fields?.issuetype?.name,
+      assignee: i.fields?.assignee?.displayName ?? "Unassigned",
+      reporter: i.fields?.reporter?.displayName,
+    }));
+
+    return { content: [{ type: "text", text: JSON.stringify(issues, null, 2) }] };
+  }
+);
+
 // ── Start ────────────────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);