mcp-jira-stdio 1.5.3 → 1.6.0

package/README.md

@@ -16,6 +16,28 @@
 
 A Model Context Protocol (MCP) server for Jira API integration. Enables reading, writing, and managing Jira issues and projects directly from your MCP client (e.g., Claude Desktop).
 
+## ⚡ Quick Install for Claude Code
+
+The fastest way to add this MCP server to Claude Code:
+
+```bash
+claude mcp add jira npx mcp-jira-stdio@latest \
+  --env JIRA_BASE_URL=https://yourcompany.atlassian.net \
+  --env JIRA_EMAIL=your-email@example.com \
+  --env JIRA_API_TOKEN=your-api-token
+```
+
+Replace the values with your actual Jira credentials:
+- **JIRA_BASE_URL**: Your Jira instance URL (e.g., `https://yourcompany.atlassian.net`)
+- **JIRA_EMAIL**: Your Jira account email
+- **JIRA_API_TOKEN**: Your Jira API token ([generate here](https://id.atlassian.com/manage-profile/security/api-tokens))
+
+That's it! The server will be automatically configured and ready to use.
+
+### Alternative: Manual Configuration
+
+If you prefer to configure manually or use Claude Desktop, see the [Configuration](#6-configure-mcp-client) section below.
+
 ## 🚀 Quick Start
 
 ### 1. Prerequisites
@@ -95,6 +117,19 @@ task jira:projects
 
 ### 6. Configure MCP Client
 
+#### For Claude Code
+
+Use the quick install command (recommended):
+
+```bash
+claude mcp add jira npx mcp-jira-stdio@latest \
+  --env JIRA_BASE_URL=https://yourcompany.atlassian.net \
+  --env JIRA_EMAIL=your-email@example.com \
+  --env JIRA_API_TOKEN=your-api-token
+```
+
+#### For Claude Desktop
+
 Add to your Claude Desktop config:
 
 - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

package/dist/index.js

@@ -4,6 +4,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import axios from 'axios';
 import { z } from 'zod';
+import mdToAdf from 'md-to-adf';
 
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -439,7 +440,7 @@ var require_package2 = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "mcp-jira-stdio",
-      version: "1.5.3",
+      version: "1.6.0",
       description: "Model Context Protocol (MCP) server for Jira API integration",
       author: "graslt",
       license: "MIT",
@@ -490,6 +491,7 @@ var require_package2 = __commonJS({
       dependencies: {
         "@modelcontextprotocol/sdk": "^1.17.1",
         axios: "^1.7.0",
+        "md-to-adf": "^0.6.4",
         zod: "^3.22.4"
       },
       devDependencies: {
@@ -759,7 +761,10 @@ var CreateIssueInputSchema = z.object({
   customFields: z.record(z.any()).optional().describe(
     'Additional Jira field mappings, e.g. { "customfield_12345": value }. Use for required custom fields.'
   ),
-  returnIssue: z.boolean().optional().describe("When false, skip fetching full issue after creation")
+  returnIssue: z.boolean().optional().describe("When false, skip fetching full issue after creation"),
+  format: z.enum(["markdown", "adf", "plain"]).optional().default("markdown").describe(
+    'Description format: "markdown" (converts Markdown to ADF), "adf" (use as-is ADF object), "plain" (converts plain text to ADF with basic formatting). Default: "markdown"'
+  )
 });
 var UpdateIssueInputSchema = z.object({
   issueKey: z.string().describe("Issue key to update").refine((v) => isValidIssueKey(v), "Invalid issue key format"),
@@ -769,7 +774,10 @@ var UpdateIssueInputSchema = z.object({
   assignee: z.string().optional().describe("New assignee account ID"),
   labels: z.array(z.string()).optional().describe("New labels (replaces existing)"),
   components: z.array(z.string()).optional().describe("New components (replaces existing)"),
-  returnIssue: z.boolean().optional().describe("When false, skip fetching full issue after update")
+  returnIssue: z.boolean().optional().describe("When false, skip fetching full issue after update"),
+  format: z.enum(["markdown", "adf", "plain"]).optional().default("markdown").describe(
+    'Description format: "markdown" (converts Markdown to ADF), "adf" (use as-is ADF object), "plain" (converts plain text to ADF with basic formatting). Default: "markdown"'
+  )
 });
 var GetMyIssuesInputSchema = z.object({
   nextPageToken: z.string().optional().describe(
@@ -800,7 +808,10 @@ var AddCommentInputSchema = z.object({
   visibility: z.object({
     type: z.enum(["group", "role"]).describe("Visibility type"),
     value: z.string().describe("Group name or role name")
-  }).optional().describe("Comment visibility restrictions")
+  }).optional().describe("Comment visibility restrictions"),
+  format: z.enum(["markdown", "adf", "plain"]).optional().default("markdown").describe(
+    'Comment format: "markdown" (converts Markdown to ADF), "adf" (use as-is ADF object), "plain" (converts plain text to ADF with basic formatting). Default: "markdown"'
+  )
 });
 var GetProjectInfoInputSchema = z.object({
   projectKey: z.string().describe("Project key to get detailed information for").refine((v) => isValidProjectKey(v), "Invalid project key format"),
@@ -813,7 +824,10 @@ var CreateSubtaskInputSchema = z.object({
   priority: z.string().optional().describe("Subtask priority"),
   assignee: z.string().optional().describe("Assignee account ID"),
   labels: z.array(z.string()).optional().describe("Subtask labels"),
-  components: z.array(z.string()).optional().describe("Component names")
+  components: z.array(z.string()).optional().describe("Component names"),
+  format: z.enum(["markdown", "adf", "plain"]).optional().default("markdown").describe(
+    'Description format: "markdown" (converts Markdown to ADF), "adf" (use as-is ADF object), "plain" (converts plain text to ADF with basic formatting). Default: "markdown"'
+  )
 });
 var GetCreateMetaInputSchema = z.object({
   projectKey: z.string().describe("Project key to get create metadata for").refine((v) => isValidProjectKey(v), "Invalid project key format"),
@@ -822,12 +836,21 @@ var GetCreateMetaInputSchema = z.object({
 var GetCustomFieldsInputSchema = z.object({
   projectKey: z.string().optional().describe("Project key to filter custom fields (optional)").refine((v) => v ? isValidProjectKey(v) : true, "Invalid project key format")
 });
-
-// src/utils/api-helpers.ts
-function ensureAdfDescription(desc) {
+function ensureAdfDescription(desc, format = "markdown") {
   if (!desc) return desc;
   if (typeof desc === "object") return desc;
   if (typeof desc !== "string") return desc;
+  if (format === "markdown") {
+    try {
+      return mdToAdf(desc);
+    } catch (error) {
+      console.warn("Markdown to ADF conversion failed, falling back to plain text:", error);
+      format = "plain";
+    }
+  }
+  if (format === "adf") {
+    return desc;
+  }
   const urlRegex = /https?:\/\/[^\s)]+/g;
   const makeTextNodes = (text) => {
     const nodes = [];
@@ -1010,7 +1033,10 @@ async function createIssue(issueData, options = { returnIssue: true }) {
     issuetype: { name: issueData.issueType }
   };
   if (issueData.description !== void 0) {
-    fields.description = ensureAdfDescription(issueData.description);
+    fields.description = ensureAdfDescription(
+      issueData.description,
+      issueData.format || "markdown"
+    );
   }
   if (issueData.priority) {
     fields.priority = { name: issueData.priority };
@@ -1048,7 +1074,7 @@ async function updateIssue(issueKey, updates) {
     fields.summary = updates.summary;
   }
   if (updates.description !== void 0) {
-    fields.description = ensureAdfDescription(updates.description);
+    fields.description = ensureAdfDescription(updates.description, updates.format || "markdown");
   }
   if (updates.priority !== void 0) {
     fields.priority = { name: updates.priority };
@@ -1145,8 +1171,8 @@ async function getStatuses(options = {}) {
   }
   return await makeJiraRequest(config);
 }
-async function addComment(issueKey, body, visibility) {
-  const adfBody = ensureAdfDescription(body);
+async function addComment(issueKey, body, visibility, format) {
+  const adfBody = ensureAdfDescription(body, format || "markdown");
   const data = {
     body: adfBody
   };
@@ -1187,7 +1213,10 @@ async function createSubtask(parentIssueKey, subtaskData) {
     issuetype: { id: subtaskType.id }
   };
   if (subtaskData.description !== void 0) {
-    fields.description = ensureAdfDescription(subtaskData.description);
+    fields.description = ensureAdfDescription(
+      subtaskData.description,
+      subtaskData.format || "markdown"
+    );
   }
   if (subtaskData.priority) {
     fields.priority = { name: subtaskData.priority };
@@ -2088,7 +2117,7 @@ async function handleGetStatuses(input) {
 var log11 = createLogger("tool:create-issue");
 var createIssueTool = {
   name: TOOL_NAMES.CREATE_ISSUE,
-  description: 'Creates a new Jira issue in the specified project. Supports setting issue type, priority, assignee, labels, components, and custom fields. Description accepts plain text and is auto-formatted to ADF: lines ending with ":" become headings, numbered lines create ordered lists, and URLs are linkified. For required custom fields, supply them via customFields (e.g., { "customfield_12345": { id: "..." } }). Returns the created issue with all details.',
+  description: 'Creates a new Jira issue in the specified project. Supports setting issue type, priority, assignee, labels, components, and custom fields. Description format is controlled by the "format" parameter (default: markdown). For required custom fields, supply them via customFields (e.g., { "customfield_12345": { id: "..." } }). Returns the created issue with all details.',
   inputSchema: {
     type: "object",
     properties: {
@@ -2103,7 +2132,7 @@ var createIssueTool = {
       },
       description: {
         anyOf: [{ type: "string" }, { type: "object" }],
-        description: "Detailed issue description (optional). Accepts plain text (auto-formatted to ADF) or an ADF document."
+        description: 'Detailed issue description (optional). Format depends on the "format" parameter.'
       },
       issueType: {
         type: "string",
@@ -2138,6 +2167,12 @@ var createIssueTool = {
         type: "boolean",
         description: "If false, returns only the issue key without fetching full details",
         default: true
+      },
+      format: {
+        type: "string",
+        enum: ["markdown", "adf", "plain"],
+        description: 'Description format: "markdown" (converts Markdown to ADF, default), "adf" (use as-is ADF object), "plain" (converts plain text to ADF with basic formatting)',
+        default: "markdown"
       }
     },
     required: ["projectKey", "summary", "issueType"]
@@ -2158,6 +2193,7 @@ async function handleCreateIssue(input) {
     if (validated.labels !== void 0) createParams.labels = validated.labels;
     if (validated.components !== void 0) createParams.components = validated.components;
     if (validated.customFields !== void 0) createParams.customFields = validated.customFields;
+    if (validated.format !== void 0) createParams.format = validated.format;
     let issueOrKey;
     if (validated.returnIssue === false) {
       issueOrKey = await createIssue(createParams, { returnIssue: false });
@@ -2182,7 +2218,7 @@ async function handleCreateIssue(input) {
 var log12 = createLogger("tool:update-issue");
 var updateIssueTool = {
   name: TOOL_NAMES.UPDATE_ISSUE,
-  description: 'Updates an existing Jira issue by its key. Supports updating summary, description, priority, assignee, labels, and components. Description accepts plain text and is auto-formatted to ADF: headings (lines ending with ":"), numbered/bullet lists, and links. Only specified fields will be updated.',
+  description: 'Updates an existing Jira issue by its key. Supports updating summary, description, priority, assignee, labels, and components. Description format is controlled by the "format" parameter (default: markdown). Only specified fields will be updated.',
   inputSchema: {
     type: "object",
     properties: {
@@ -2196,7 +2232,7 @@ var updateIssueTool = {
       },
       description: {
         anyOf: [{ type: "string" }, { type: "object" }],
-        description: "New issue description (optional). Accepts plain text (auto-formatted to ADF) or an ADF document."
+        description: 'New issue description (optional). Format depends on the "format" parameter.'
       },
       priority: {
         type: "string",
@@ -2220,6 +2256,12 @@ var updateIssueTool = {
         type: "boolean",
         description: "If false, returns a success message without fetching the updated issue",
         default: true
+      },
+      format: {
+        type: "string",
+        enum: ["markdown", "adf", "plain"],
+        description: 'Description format: "markdown" (converts Markdown to ADF, default), "adf" (use as-is ADF object), "plain" (converts plain text to ADF with basic formatting)',
+        default: "markdown"
       }
     },
     required: ["issueKey"]
@@ -2236,6 +2278,7 @@ async function handleUpdateIssue(input) {
     if (validated.assignee !== void 0) updateParams.assignee = validated.assignee;
     if (validated.labels !== void 0) updateParams.labels = validated.labels;
     if (validated.components !== void 0) updateParams.components = validated.components;
+    if (validated.format !== void 0) updateParams.format = validated.format;
     await updateIssue(validated.issueKey, updateParams);
     if (validated.returnIssue === false) {
       log12.info(`Updated issue ${validated.issueKey}`);
@@ -2254,7 +2297,7 @@ async function handleUpdateIssue(input) {
 var log13 = createLogger("tool:add-comment");
 var addCommentTool = {
   name: TOOL_NAMES.ADD_COMMENT,
-  description: "Adds a comment to an issue. Supports visibility restrictions for groups or roles. Returns the created comment with author details and timestamp.",
+  description: 'Adds a comment to an issue. Supports visibility restrictions for groups or roles. Comment format is controlled by the "format" parameter (default: markdown). Returns the created comment with author details and timestamp.',
   inputSchema: {
     type: "object",
     properties: {
@@ -2264,7 +2307,7 @@ var addCommentTool = {
       },
       body: {
         type: "string",
-        description: "Comment body text",
+        description: 'Comment body text. Format depends on the "format" parameter.',
         minLength: 1
       },
       visibility: {
@@ -2282,6 +2325,12 @@ var addCommentTool = {
           }
         },
         required: ["type", "value"]
+      },
+      format: {
+        type: "string",
+        enum: ["markdown", "adf", "plain"],
+        description: 'Comment format: "markdown" (converts Markdown to ADF, default), "adf" (use as-is ADF object), "plain" (converts plain text to ADF with basic formatting)',
+        default: "markdown"
       }
     },
     required: ["issueKey", "body"]
@@ -2291,7 +2340,12 @@ async function handleAddComment(input) {
   try {
     const validated = validateInput(AddCommentInputSchema, input);
     log13.info(`Adding comment to issue ${validated.issueKey}...`);
-    const comment = await addComment(validated.issueKey, validated.body, validated.visibility);
+    const comment = await addComment(
+      validated.issueKey,
+      validated.body,
+      validated.visibility,
+      validated.format
+    );
     log13.info(`Added comment to ${validated.issueKey}`);
     return formatCommentResponse(comment);
   } catch (error) {
@@ -2339,7 +2393,7 @@ async function handleGetProjectInfo(input) {
 var log15 = createLogger("tool:create-subtask");
 var createSubtaskTool = {
   name: TOOL_NAMES.CREATE_SUBTASK,
-  description: "Creates a subtask under an existing parent issue. Automatically determines the correct project and subtask issue type. Supports setting priority, assignee, labels, and components.",
+  description: 'Creates a subtask under an existing parent issue. Automatically determines the correct project and subtask issue type. Supports setting priority, assignee, labels, and components. Description format is controlled by the "format" parameter (default: markdown).',
   inputSchema: {
     type: "object",
     properties: {
@@ -2354,7 +2408,7 @@ var createSubtaskTool = {
       },
       description: {
         type: "string",
-        description: "Detailed subtask description (optional)"
+        description: 'Detailed subtask description (optional). Format depends on the "format" parameter.'
       },
       priority: {
         type: "string",
@@ -2375,6 +2429,12 @@ var createSubtaskTool = {
         items: { type: "string" },
         description: "Component names (optional)",
         default: []
+      },
+      format: {
+        type: "string",
+        enum: ["markdown", "adf", "plain"],
+        description: 'Description format: "markdown" (converts Markdown to ADF, default), "adf" (use as-is ADF object), "plain" (converts plain text to ADF with basic formatting)',
+        default: "markdown"
       }
     },
     required: ["parentIssueKey", "summary"]
@@ -2392,6 +2452,7 @@ async function handleCreateSubtask(input) {
     if (validated.assignee !== void 0) subtaskParams.assignee = validated.assignee;
     if (validated.labels !== void 0) subtaskParams.labels = validated.labels;
     if (validated.components !== void 0) subtaskParams.components = validated.components;
+    if (validated.format !== void 0) subtaskParams.format = validated.format;
     const subtask = await createSubtask(validated.parentIssueKey, subtaskParams);
     log15.info(`Created subtask ${subtask.key}`);
     return formatIssueResponse(subtask);