mcp-jira-stdio 1.3.0 → 1.5.1

package/dist/index.js

@@ -42,7 +42,7 @@ var require_package = __commonJS({
   "node_modules/dotenv/package.json"(exports, module) {
     module.exports = {
       name: "dotenv",
-      version: "17.2.1",
+      version: "17.2.3",
       description: "Loads environment variables from .env file",
       main: "lib/main.js",
       types: "lib/main.d.ts",
@@ -64,8 +64,8 @@ var require_package = __commonJS({
         "dts-check": "tsc --project tests/types/tsconfig.json",
         lint: "standard",
         pretest: "npm run lint && npm run dts-check",
-        test: "tap run --allow-empty-coverage --disable-coverage --timeout=60000",
-        "test:coverage": "tap run --show-full-coverage --timeout=60000 --coverage-report=text --coverage-report=lcov",
+        test: "tap run tests/**/*.js --allow-empty-coverage --disable-coverage --timeout=60000",
+        "test:coverage": "tap run tests/**/*.js --show-full-coverage --timeout=60000 --coverage-report=text --coverage-report=lcov",
         prerelease: "npm test",
         release: "standard-version"
       },
@@ -118,9 +118,12 @@ var require_main = __commonJS({
       "\u{1F510} encrypt with Dotenvx: https://dotenvx.com",
       "\u{1F510} prevent committing .env to code: https://dotenvx.com/precommit",
       "\u{1F510} prevent building .env in docker: https://dotenvx.com/prebuild",
-      "\u{1F4E1} observe env with Radar: https://dotenvx.com/radar",
-      "\u{1F4E1} auto-backup env with Radar: https://dotenvx.com/radar",
-      "\u{1F4E1} version env with Radar: https://dotenvx.com/radar",
+      "\u{1F4E1} add observability to secrets: https://dotenvx.com/ops",
+      "\u{1F465} sync secrets across teammates & machines: https://dotenvx.com/ops",
+      "\u{1F5C2}\uFE0F backup and recover secrets: https://dotenvx.com/ops",
+      "\u2705 audit secrets and track compliance: https://dotenvx.com/ops",
+      "\u{1F504} add secrets lifecycle management: https://dotenvx.com/ops",
+      "\u{1F511} add access controls to secrets: https://dotenvx.com/ops",
       "\u{1F6E0}\uFE0F  run anywhere with `dotenvx run -- yourcommand`",
       "\u2699\uFE0F  specify custom .env file path with { path: '/custom/path/.env' }",
       "\u2699\uFE0F  enable debug logging with { debug: true }",
@@ -436,7 +439,7 @@ var require_package2 = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "mcp-jira-stdio",
-      version: "1.3.0",
+      version: "1.5.1",
       description: "Model Context Protocol (MCP) server for Jira API integration",
       author: "graslt",
       license: "MIT",
@@ -552,7 +555,9 @@ var TOOL_NAMES = {
   UPDATE_ISSUE: "jira_update_issue",
   ADD_COMMENT: "jira_add_comment",
   GET_PROJECT_INFO: "jira_get_project_info",
-  CREATE_SUBTASK: "jira_create_subtask"
+  CREATE_SUBTASK: "jira_create_subtask",
+  GET_CREATE_META: "jira_get_create_meta",
+  GET_CUSTOM_FIELDS: "jira_get_custom_fields"
 };
 
 // src/utils/logger.ts
@@ -715,13 +720,10 @@ function isValidProjectKey(key) {
 function sanitizeJQL(jql) {
   return jql.replace(/[<>"'`]/g, "").replace(/\s+/g, " ").trim();
 }
-function validatePagination(startAt, maxResults) {
-  if (startAt < 0) {
-    throw new Error("startAt must be non-negative");
-  }
-  if (maxResults < 1 || maxResults > 100) {
-    throw new Error("maxResults must be between 1 and 100");
-  }
+function extractIssueKey(input) {
+  if (typeof input !== "string") return null;
+  const match = input.match(/[A-Z][A-Z0-9]*-\d+/);
+  return match ? match[0] : null;
 }
 
 // src/types/tools.ts
@@ -738,8 +740,10 @@ var GetIssueInputSchema = z.object({
 });
 var SearchIssuesInputSchema = z.object({
   jql: z.string().min(1).describe("JQL query string"),
-  startAt: z.number().min(0).default(0).describe("Index of first result to return"),
-  maxResults: z.number().min(1).max(100).default(50).describe("Maximum number of results to return"),
+  nextPageToken: z.string().optional().describe(
+    "Token for pagination. Omit for first page, use value from previous response for next page."
+  ),
+  maxResults: z.number().min(1).max(100).default(50).describe("Maximum number of results to return per page"),
   fields: z.array(z.string()).optional().describe("Specific fields to retrieve"),
   expand: z.array(z.string()).optional().describe("Additional details to include")
 });
@@ -768,8 +772,10 @@ var UpdateIssueInputSchema = z.object({
   returnIssue: z.boolean().optional().describe("When false, skip fetching full issue after update")
 });
 var GetMyIssuesInputSchema = z.object({
-  startAt: z.number().min(0).default(0).describe("Index of first result to return"),
-  maxResults: z.number().min(1).max(100).default(50).describe("Maximum number of results to return"),
+  nextPageToken: z.string().optional().describe(
+    "Token for pagination. Omit for first page, use value from previous response for next page."
+  ),
+  maxResults: z.number().min(1).max(100).default(50).describe("Maximum number of results to return per page"),
   fields: z.array(z.string()).optional().describe("Specific fields to retrieve"),
   expand: z.array(z.string()).optional().describe("Additional details to include")
 });
@@ -809,6 +815,13 @@ var CreateSubtaskInputSchema = z.object({
   labels: z.array(z.string()).optional().describe("Subtask labels"),
   components: z.array(z.string()).optional().describe("Component names")
 });
+var GetCreateMetaInputSchema = z.object({
+  projectKey: z.string().describe("Project key to get create metadata for").refine((v) => isValidProjectKey(v), "Invalid project key format"),
+  issueTypeName: z.string().optional().describe("Specific issue type name to get metadata for (optional)")
+});
+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) {
@@ -956,14 +969,15 @@ async function getIssue(issueKey, options = {}) {
   return await makeJiraRequest(config);
 }
 async function searchIssues(options) {
-  const { jql, startAt = 0, maxResults = 50 } = options;
-  validatePagination(startAt, maxResults);
+  const { jql, nextPageToken, maxResults = 50 } = options;
   const sanitizedJql = sanitizeJQL(jql);
   const data = {
     jql: sanitizedJql,
-    startAt,
     maxResults
   };
+  if (nextPageToken) {
+    data.nextPageToken = nextPageToken;
+  }
   if (options.fields) {
     data.fields = options.fields;
   }
@@ -972,7 +986,7 @@ async function searchIssues(options) {
   }
   const config = {
     method: "POST",
-    url: "/search",
+    url: "/search/jql",
     data
   };
   return await makeJiraRequest(config);
@@ -1047,9 +1061,9 @@ async function getMyIssues(options = {}) {
   const jql = `assignee = currentUser() ORDER BY updated DESC`;
   const searchParams = {
     jql,
-    startAt: options.startAt || 0,
     maxResults: options.maxResults || 50
   };
+  if (options.nextPageToken !== void 0) searchParams.nextPageToken = options.nextPageToken;
   if (options.fields !== void 0) searchParams.fields = options.fields;
   if (options.expand !== void 0) searchParams.expand = options.expand;
   return await searchIssues(searchParams);
@@ -1120,7 +1134,10 @@ async function getStatuses(options = {}) {
   return await makeJiraRequest(config);
 }
 async function addComment(issueKey, body, visibility) {
-  const data = { body };
+  const adfBody = ensureAdfDescription(body);
+  const data = {
+    body: adfBody
+  };
   if (visibility) {
     data.visibility = visibility;
   }
@@ -1180,6 +1197,31 @@ async function createSubtask(parentIssueKey, subtaskData) {
   const response = await makeJiraRequest(config);
   return await getIssue(response.key);
 }
+async function getCreateMeta(options = {}) {
+  const params = {};
+  if (options.projectKeys && options.projectKeys.length > 0) {
+    params.projectKeys = options.projectKeys.join(",");
+  }
+  if (options.issueTypeNames && options.issueTypeNames.length > 0) {
+    params.issuetypeNames = options.issueTypeNames.join(",");
+  }
+  if (options.expand) {
+    params.expand = options.expand;
+  }
+  const config = {
+    method: "GET",
+    url: "/issue/createmeta",
+    params
+  };
+  return await makeJiraRequest(config);
+}
+async function getFields() {
+  const config = {
+    method: "GET",
+    url: "/field"
+  };
+  return await makeJiraRequest(config);
+}
 
 // src/utils/redaction.ts
 function isRedactionEnabled() {
@@ -1302,16 +1344,28 @@ function formatSearchResultsResponse(result) {
     };
   }
   const issuesList = result.issues.map((issue) => {
-    const assignee = issue.fields.assignee?.displayName || "Unassigned";
-    return `\u2022 **${issue.key}** - ${issue.fields.summary}
-  Status: ${issue.fields.status.name} | Assignee: ${assignee} | Priority: ${issue.fields.priority?.name || "None"}`;
+    const assignee = issue.fields?.assignee?.displayName || "Unassigned";
+    const summary = issue.fields?.summary || "No summary";
+    const status = issue.fields?.status?.name || "Unknown";
+    const priority = issue.fields?.priority?.name || "None";
+    return `\u2022 **${issue.key}** - ${summary}
+  Status: ${status} | Assignee: ${assignee} | Priority: ${priority}`;
   }).join("\n\n");
   const rangeStart = result.startAt + 1;
   const rangeEnd = Math.min(result.startAt + result.maxResults, result.total);
   const showRangeInline = result.total > result.maxResults || result.startAt > 0;
-  const paginationInfo = showRangeInline ? `
+  let paginationInfo = "";
+  if (showRangeInline) {
+    paginationInfo = `
 
-*Showing ${rangeStart}-${rangeEnd} of ${result.total} results*` : "";
+*Showing ${rangeStart}-${rangeEnd} of ${result.total} results*`;
+  }
+  if (result.nextPageToken && !result.isLast) {
+    paginationInfo += `
+*Next page token: \`${result.nextPageToken}\`*`;
+  } else if (result.isLast) {
+    paginationInfo += "\n*This is the last page of results*";
+  }
   return {
     content: [
       {
@@ -1325,23 +1379,34 @@ ${issuesList}${paginationInfo}`
 }
 function formatErrorResponse(error) {
   let errorMessage = "An unexpected error occurred.";
+  let hasCustomFieldError = false;
   if (typeof error === "string") {
     errorMessage = error;
+    hasCustomFieldError = error.includes("customfield_");
   } else if (error instanceof Error) {
     errorMessage = error.message;
+    hasCustomFieldError = error.message.includes("customfield_");
   } else if (error?.response?.data) {
     const jiraError = error.response.data;
     if (jiraError.errorMessages && jiraError.errorMessages.length > 0) {
       errorMessage = jiraError.errorMessages.join(", ");
     } else if (jiraError.errors) {
-      errorMessage = Object.entries(jiraError.errors).map(([field, message]) => `${field}: ${message}`).join(", ");
+      const errors = Object.entries(jiraError.errors);
+      errorMessage = errors.map(([field, message]) => `${field}: ${message}`).join(", ");
+      hasCustomFieldError = errors.some(([field]) => field.startsWith("customfield_"));
     }
   }
+  let hint = "";
+  if (hasCustomFieldError) {
+    hint = `
+
+\u{1F4A1} **Hint:** This error involves custom fields. Use 'jira_get_create_meta' tool to discover required fields and their allowed values before creating an issue.`;
+  }
   return {
     content: [
       {
         type: "text",
-        text: `\u274C Error: ${errorMessage}`
+        text: `\u274C Error: ${errorMessage}${hint}`
       }
     ]
   };
@@ -1508,6 +1573,96 @@ Last Updated: ${new Date(project.insight.lastIssueUpdateTime).toISOString()}` :
     ]
   };
 }
+function formatCreateMetaResponse(meta) {
+  if (!meta.projects || meta.projects.length === 0) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "No create metadata found for the specified project."
+        }
+      ]
+    };
+  }
+  const project = meta.projects[0];
+  if (!project) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: "No create metadata found for the specified project."
+        }
+      ]
+    };
+  }
+  const issueTypesList = project.issuetypes.map((issueType) => {
+    const requiredFields = [];
+    const optionalFields = [];
+    Object.entries(issueType.fields).forEach(([fieldKey, field]) => {
+      const allowedValuesText = field.allowedValues ? `
+    Allowed values: ${field.allowedValues.map((v) => v.name || v.value || v.id).join(", ")}` : "";
+      const defaultValueText = field.hasDefaultValue ? `
+    Default: ${JSON.stringify(field.defaultValue)}` : "";
+      const fieldInfo = `  \u2022 **${field.name}** (${fieldKey})
+    Type: ${field.schema.type}${allowedValuesText}${defaultValueText}`;
+      if (field.required) {
+        requiredFields.push(fieldInfo);
+      } else {
+        optionalFields.push(fieldInfo);
+      }
+    });
+    const requiredSection = requiredFields.length > 0 ? `**Required Fields:**
+${requiredFields.join("\n\n")}` : "No required fields";
+    const optionalSection = optionalFields.length > 0 ? `
+
+**Optional Fields:**
+${optionalFields.join("\n\n")}` : "";
+    return `### ${issueType.name} (${issueType.subtask ? "Subtask" : "Issue"})
+${issueType.description}
+
+${requiredSection}${optionalSection}`;
+  }).join("\n\n---\n\n");
+  return {
+    content: [
+      {
+        type: "text",
+        text: `**Create Metadata for Project: ${project.name} (${project.key})**
+
+${issueTypesList}`
+      }
+    ]
+  };
+}
+function formatCustomFieldsResponse(fields, projectKey) {
+  const customFields = fields.filter((field) => field.custom);
+  if (customFields.length === 0) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: projectKey ? `No custom fields found for project ${projectKey}.` : "No custom fields found."
+        }
+      ]
+    };
+  }
+  const fieldsList = customFields.map((field) => {
+    const schemaInfo = field.schema.custom ? `Custom Type: ${field.schema.custom}` : `Type: ${field.schema.type}`;
+    return `\u2022 **${field.name}** (${field.key})
+  ${schemaInfo}
+  ID: ${field.id}`;
+  }).join("\n\n");
+  const header = projectKey ? `Found ${customFields.length} custom field(s) for project ${projectKey}:` : `Found ${customFields.length} custom field(s):`;
+  return {
+    content: [
+      {
+        type: "text",
+        text: `${header}
+
+${fieldsList}`
+      }
+    ]
+  };
+}
 
 // src/utils/error-handler.ts
 var log2 = createLogger("error-handler");
@@ -1627,7 +1782,8 @@ var getIssueTool = {
 async function handleGetIssue(input) {
   try {
     const validated = validateInput(GetIssueInputSchema, input);
-    const key = (validated.issueKey || "").trim();
+    const trimmedInput = (validated.issueKey || "").trim();
+    const key = extractIssueKey(trimmedInput) || trimmedInput;
     log4.info(`Getting issue ${key}...`);
     const getParams = {};
     if (validated.expand !== void 0) getParams.expand = validated.expand;
@@ -1645,7 +1801,7 @@ async function handleGetIssue(input) {
 var log5 = createLogger("tool:search-issues");
 var searchIssuesTool = {
   name: TOOL_NAMES.SEARCH_ISSUES,
-  description: 'Search for Jira issues using JQL. Supports complex queries with pagination and field selection. Examples: "project = PROJECT AND status = Open", "assignee = currentUser()".',
+  description: 'Search for Jira issues using JQL. Supports complex queries with pagination and field selection. Examples: "project = PROJECT AND status = Open", "assignee = currentUser()". For pagination, use nextPageToken from previous response.',
   inputSchema: {
     type: "object",
     properties: {
@@ -1653,15 +1809,13 @@ var searchIssuesTool = {
         type: "string",
         description: 'JQL query string (e.g., "project = PROJECT AND status = Open")'
       },
-      startAt: {
-        type: "number",
-        description: "Index of first result to return (for pagination)",
-        minimum: 0,
-        default: 0
+      nextPageToken: {
+        type: "string",
+        description: "Token for pagination. Omit for first page, use value from previous response for next page."
       },
       maxResults: {
         type: "number",
-        description: "Maximum number of results to return",
+        description: "Maximum number of results to return per page",
         minimum: 1,
         maximum: 100,
         default: 50
@@ -1688,7 +1842,7 @@ async function handleSearchIssues(input) {
     const searchParams = {
       jql: validated.jql
     };
-    if (validated.startAt !== void 0) searchParams.startAt = validated.startAt;
+    if (validated.nextPageToken !== void 0) searchParams.nextPageToken = validated.nextPageToken;
     if (validated.maxResults !== void 0) searchParams.maxResults = validated.maxResults;
     if (validated.fields !== void 0) searchParams.fields = validated.fields;
     if (validated.expand !== void 0) searchParams.expand = validated.expand;
@@ -1705,19 +1859,17 @@ async function handleSearchIssues(input) {
 var log6 = createLogger("tool:get-my-issues");
 var getMyIssuesTool = {
   name: TOOL_NAMES.GET_MY_ISSUES,
-  description: "Retrieves issues assigned to current user, sorted by most recently updated first. Supports pagination and field selection.",
+  description: "Retrieves issues assigned to current user, sorted by most recently updated first. Supports pagination and field selection. For pagination, use nextPageToken from previous response.",
   inputSchema: {
     type: "object",
     properties: {
-      startAt: {
-        type: "number",
-        description: "Index of first result to return (for pagination)",
-        minimum: 0,
-        default: 0
+      nextPageToken: {
+        type: "string",
+        description: "Token for pagination. Omit for first page, use value from previous response for next page."
       },
       maxResults: {
         type: "number",
-        description: "Maximum number of results to return",
+        description: "Maximum number of results to return per page",
         minimum: 1,
         maximum: 100,
         default: 50
@@ -1742,7 +1894,7 @@ async function handleGetMyIssues(input) {
     const validated = validateInput(GetMyIssuesInputSchema, input);
     log6.info("Getting issues assigned to current user...");
     const getParams = {};
-    if (validated.startAt !== void 0) getParams.startAt = validated.startAt;
+    if (validated.nextPageToken !== void 0) getParams.nextPageToken = validated.nextPageToken;
     if (validated.maxResults !== void 0) getParams.maxResults = validated.maxResults;
     if (validated.fields !== void 0) getParams.fields = validated.fields;
     if (validated.expand !== void 0) getParams.expand = validated.expand;
@@ -2237,6 +2389,76 @@ async function handleCreateSubtask(input) {
   }
 }
 
+// src/tools/get-create-meta.ts
+var log16 = createLogger("tool:get-create-meta");
+var getCreateMetaTool = {
+  name: TOOL_NAMES.GET_CREATE_META,
+  description: "Retrieves create metadata for a project, showing all available fields (including custom fields) for creating issues. Shows required vs optional fields, field types, and allowed values. Use this before creating issues to discover what fields are needed.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      projectKey: {
+        type: "string",
+        description: "Project key to get create metadata for (e.g., PROJECT)"
+      },
+      issueTypeName: {
+        type: "string",
+        description: "Specific issue type name to get metadata for (optional)"
+      }
+    },
+    required: ["projectKey"]
+  }
+};
+async function handleGetCreateMeta(input) {
+  try {
+    const validated = validateInput(GetCreateMetaInputSchema, input);
+    log16.info(`Getting create metadata for project ${validated.projectKey}...`);
+    const options = {
+      projectKeys: [validated.projectKey],
+      expand: "projects.issuetypes.fields"
+    };
+    if (validated.issueTypeName) {
+      options.issueTypeNames = [validated.issueTypeName];
+    }
+    const meta = await getCreateMeta(options);
+    log16.info(`Retrieved create metadata for ${validated.projectKey}`);
+    return formatCreateMetaResponse(meta);
+  } catch (error) {
+    log16.error("Error in handleGetCreateMeta:", error);
+    return handleError(error);
+  }
+}
+
+// src/tools/get-custom-fields.ts
+var log17 = createLogger("tool:get-custom-fields");
+var getCustomFieldsTool = {
+  name: TOOL_NAMES.GET_CUSTOM_FIELDS,
+  description: "Retrieves all custom fields available in Jira. Shows custom field names, IDs (e.g., customfield_10071), and types. Useful for discovering what custom fields exist and their identifiers.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      projectKey: {
+        type: "string",
+        description: "Project key to filter custom fields (optional)"
+      }
+    },
+    required: []
+  }
+};
+async function handleGetCustomFields(input) {
+  try {
+    const validated = validateInput(GetCustomFieldsInputSchema, input);
+    const projectMsg = validated.projectKey ? ` for project ${validated.projectKey}` : "";
+    log17.info(`Getting custom fields${projectMsg}...`);
+    const fields = await getFields();
+    log17.info(`Retrieved ${fields.filter((f) => f.custom).length} custom fields`);
+    return formatCustomFieldsResponse(fields, validated.projectKey);
+  } catch (error) {
+    log17.error("Error in handleGetCustomFields:", error);
+    return handleError(error);
+  }
+}
+
 // src/index.ts
 if (process.env.NODE_ENV !== "production") {
   try {
@@ -2245,7 +2467,7 @@ if (process.env.NODE_ENV !== "production") {
   } catch {
   }
 }
-var log16 = createLogger("server");
+var log18 = createLogger("server");
 var toolHandlers = /* @__PURE__ */ new Map([
   [TOOL_NAMES.GET_VISIBLE_PROJECTS, handleGetVisibleProjects],
   [TOOL_NAMES.GET_ISSUE, handleGetIssue],
@@ -2259,7 +2481,9 @@ var toolHandlers = /* @__PURE__ */ new Map([
   [TOOL_NAMES.UPDATE_ISSUE, handleUpdateIssue],
   [TOOL_NAMES.ADD_COMMENT, handleAddComment],
   [TOOL_NAMES.GET_PROJECT_INFO, handleGetProjectInfo],
-  [TOOL_NAMES.CREATE_SUBTASK, handleCreateSubtask]
+  [TOOL_NAMES.CREATE_SUBTASK, handleCreateSubtask],
+  [TOOL_NAMES.GET_CREATE_META, handleGetCreateMeta],
+  [TOOL_NAMES.GET_CUSTOM_FIELDS, handleGetCustomFields]
 ]);
 var allTools = [
   getVisibleProjectsTool,
@@ -2274,7 +2498,9 @@ var allTools = [
   updateIssueTool,
   addCommentTool,
   getProjectInfoTool,
-  createSubtaskTool
+  createSubtaskTool,
+  getCreateMetaTool,
+  getCustomFieldsTool
 ];
 async function main() {
   const isDryRun = (process.env.DRY_RUN || "").toLowerCase() === "1" || (process.env.DRY_RUN || "").toLowerCase() === "true";
@@ -2345,7 +2571,7 @@ async function main() {
   console.error("\u{1F680} Jira MCP server running on stdio");
 }
 main().catch((error) => {
-  log16.error("Fatal error:", error);
+  log18.error("Fatal error:", error);
   process.exit(1);
 });
 //# sourceMappingURL=index.js.map