@ecubelabs/atlassian-mcp 1.0.0-next.3

package/dist/config.js

@@ -0,0 +1,22 @@
+export const atlassianConfig = {
+    jira: {
+        host: process.env.JIRA_HOST || "",
+        email: process.env.JIRA_EMAIL || "",
+        apiToken: process.env.JIRA_API_TOKEN || "",
+        apiVersion: process.env.JIRA_API_VERSION || "3",
+    },
+    //   confluence: {
+    //     host: process.env.CONFLUENCE_HOST || "https://your-domain.atlassian.net",
+    //     email: process.env.CONFLUENCE_EMAIL || "",
+    //     apiToken: process.env.CONFLUENCE_API_TOKEN || "",
+    //     apiVersion: process.env.CONFLUENCE_API_VERSION || "2",
+    //   },
+    retry: {
+        maxRetries: 3,
+        retryDelay: 1000,
+    },
+    rateLimit: {
+        maxConcurrent: 5,
+        minTime: 100,
+    },
+};

package/dist/index.js

@@ -0,0 +1,313 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { JiraService } from "./libs/jira-client.js";
+// Create server instance
+const server = new McpServer({
+    name: "jira",
+    version: "1.0.0",
+});
+// Initialize Jira service
+const jiraService = new JiraService();
+// Register Jira tools
+server.tool("get-issue", "Get details of a Jira issue by key", {
+    issueKey: z.string().describe("Jira issue key (e.g. PROJ-123)"),
+    expand: z
+        .enum([
+        "renderedFields",
+        "names",
+        "schema",
+        "transitions",
+        "editmeta",
+        "changelog",
+        "versionedRepresentations",
+    ])
+        .array()
+        .optional()
+        .describe("Optional fields to expand in the response. Options include: renderedFields (HTML format), names (display names), schema (field type descriptions), transitions (possible transitions), editmeta (field editing info), changelog (recent updates), versionedRepresentations (field value history)"),
+}, async ({ issueKey, expand }) => {
+    try {
+        const issue = await jiraService.getIssue(issueKey, expand);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(issue),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to retrieve issue: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+        };
+    }
+});
+server.tool("search-issues", "Search Jira issues using JQL", {
+    jql: z
+        .string()
+        .describe("JQL query string. Must be a bounded query with search restrictions."),
+    fields: z
+        .array(z.string())
+        .optional()
+        .describe("Optional fields to include in the response. Examples: ['summary', 'comment'] or ['*all', '-comment']"),
+    maxResults: z
+        .number()
+        .min(1)
+        .max(5000)
+        .optional()
+        .describe("Maximum number of results to return per page (default: 50, max: 5000)"),
+    nextPageToken: z
+        .string()
+        .optional()
+        .describe("Token for fetching the next page of results. The first page has null nextPageToken."),
+    expand: z
+        .enum([
+        "renderedFields",
+        "names",
+        "schema",
+        "transitions",
+        "editmeta",
+        "changelog",
+        "versionedRepresentations",
+    ])
+        .array()
+        .optional()
+        .describe("Comma-separated values to expand in response: renderedFields, names, schema, transitions, operations, editmeta, changelog, versionedRepresentations"),
+    properties: z
+        .array(z.string())
+        .max(5)
+        .optional()
+        .describe("List of up to 5 issue properties to include in results"),
+    fieldsByKeys: z
+        .boolean()
+        .optional()
+        .describe("Reference fields by their key rather than ID (default: false)"),
+    failFast: z
+        .boolean()
+        .optional()
+        .describe("Fail request early if we can't retrieve all field data (default: false)"),
+    reconcileIssues: z
+        .array(z.number())
+        .max(50)
+        .optional()
+        .describe("Strong consistency issue IDs to be reconciled with search results (max: 50 IDs)"),
+}, async ({ jql, fields, maxResults, nextPageToken, expand, properties, fieldsByKeys, failFast, reconcileIssues, }) => {
+    try {
+        const issues = await jiraService.searchIssues({
+            jql,
+            fields,
+            maxResults,
+            nextPageToken,
+            expand,
+            properties,
+            fieldsByKeys,
+            failFast,
+            reconcileIssues,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(issues),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to search issues: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+        };
+    }
+});
+server.tool("get-comments", "Get comments for a Jira issue", {
+    issueKey: z.string().describe("Jira issue key (e.g. PROJ-123)"),
+    startAt: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("The index of the first item to return (page offset). Default: 0"),
+    maxResults: z
+        .number()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("Maximum number of items per page. Default: 100"),
+    orderBy: z
+        .enum(["created", "-created", "+created"])
+        .optional()
+        .describe("Order comments by creation date. Default: created"),
+    expand: z
+        .array(z.enum(["renderedBody"]))
+        .optional()
+        .describe("Include additional information: renderedBody (comment body in HTML format)"),
+}, async ({ issueKey, startAt, maxResults, orderBy, expand }) => {
+    try {
+        const result = await jiraService.getComments(issueKey, {
+            startAt,
+            maxResults,
+            orderBy,
+            expand,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to retrieve comments: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+        };
+    }
+});
+server.tool("get-projects", "Get list of Jira projects", {
+    startAt: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("The index of the first item to return (page offset). Default: 0"),
+    maxResults: z
+        .number()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("Maximum number of items per page. Default: 50, Maximum: 100"),
+    orderBy: z
+        .enum([
+        "category",
+        "-category",
+        "+category",
+        "key",
+        "-key",
+        "+key",
+        "name",
+        "-name",
+        "+name",
+        "owner",
+        "-owner",
+        "+owner",
+        "issueCount",
+        "-issueCount",
+        "+issueCount",
+        "lastIssueUpdatedTime",
+        "-lastIssueUpdatedTime",
+        "+lastIssueUpdatedTime",
+        "archivedDate",
+        "-archivedDate",
+        "+archivedDate",
+        "deletedDate",
+        "-deletedDate",
+        "+deletedDate",
+    ])
+        .optional()
+        .describe("Field to order results by. Default: key"),
+    id: z
+        .array(z.number().int())
+        .max(50)
+        .optional()
+        .describe("Filter by project IDs. Maximum: 50 IDs"),
+    keys: z
+        .array(z.string())
+        .max(50)
+        .optional()
+        .describe("Filter by project keys. Maximum: 50 keys"),
+    query: z
+        .string()
+        .optional()
+        .describe("Filter by matching key or name (case insensitive)"),
+    typeKey: z
+        .string()
+        .optional()
+        .describe("Filter by project type. Accepts comma-separated list: business, service_desk, software"),
+    categoryId: z
+        .number()
+        .int()
+        .optional()
+        .describe("Filter by project category ID"),
+    action: z
+        .enum(["view", "browse", "edit", "create"])
+        .optional()
+        .describe("Filter by user's project permissions. Default: view"),
+    expand: z
+        .array(z.enum([
+        "description",
+        "projectKeys",
+        "lead",
+        "issueTypes",
+        "url",
+        "insight",
+    ]))
+        .optional()
+        .describe("Additional fields to include: description, projectKeys, lead, issueTypes, url, insight"),
+    status: z
+        .array(z.enum(["live", "archived", "deleted"]))
+        .optional()
+        .describe("EXPERIMENTAL. Filter by project status"),
+}, async ({ startAt, maxResults, orderBy, id, keys, query, typeKey, categoryId, action, expand, status, }) => {
+    try {
+        const projects = await jiraService.getProjects({
+            startAt,
+            maxResults,
+            orderBy,
+            id,
+            keys,
+            query,
+            typeKey,
+            categoryId,
+            action,
+            expand,
+            status,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(projects),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to retrieve projects: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+        };
+    }
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    /**
+     * stdout 을 사용하면 stdio server 특성상 문제가 되므로 필요한 출력이 있다면 stderr를 사용한다.
+     * @see https://modelcontextprotocol.io/quickstart/server#node
+     */
+    console.error("Jira MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/dist/libs/base-client.js

@@ -0,0 +1,117 @@
+import axios from "axios";
+import axiosRetry from "axios-retry";
+import pLimit from "p-limit";
+/**
+ * 기본적인 API Token 관리, 인터셉터, rate limit/retry 관리, 에러메세지 핸들링 등 Jira/Confluence 공통으로 필요한 기능을 제공하는 베이스 클래스
+ */
+export class BaseApiService {
+    config;
+    serviceName;
+    client;
+    rateLimiter;
+    constructor(config, serviceName) {
+        this.config = config;
+        this.serviceName = serviceName;
+        this.client = this.setupAxiosClient();
+        this.rateLimiter = pLimit(5); // 동시 요청 5개 제한
+        this.setupInterceptors();
+        this.setupRetry();
+    }
+    setupAxiosClient() {
+        const auth = Buffer.from(`${this.config.email}:${this.config.apiToken}`).toString("base64");
+        return axios.create({
+            baseURL: `${this.config.host}/rest/api/${this.config.apiVersion}`,
+            headers: {
+                Authorization: `Basic ${auth}`,
+                Accept: "application/json",
+                "Content-Type": "application/json",
+            },
+            timeout: 30000,
+        });
+    }
+    setupInterceptors() {
+        // Request 인터셉터
+        this.client.interceptors.request.use((config) => {
+            return config;
+        }, (error) => {
+            return Promise.reject(error);
+        });
+        // Response 인터셉터
+        this.client.interceptors.response.use((response) => {
+            return response;
+        }, (error) => {
+            return this.handleError(error);
+        });
+    }
+    setupRetry() {
+        axiosRetry(this.client, {
+            retries: 3,
+            retryDelay: axiosRetry.exponentialDelay,
+            retryCondition: (error) => {
+                return (axiosRetry.isNetworkOrIdempotentRequestError(error) ||
+                    error.response?.status === 429 || // Rate limit
+                    error.response?.status === 503); // Service unavailable
+            },
+        });
+    }
+    async handleError(error) {
+        const { response } = error;
+        if (response) {
+            const errorMessage = this.extractErrorMessage(response);
+            switch (response.status) {
+                case 401:
+                    throw new Error("Authentication failed");
+                case 403:
+                    throw new Error("Permission denied");
+                case 404:
+                    throw new Error("Resource not found");
+                case 429:
+                    throw error;
+                default:
+                    throw new Error(errorMessage);
+            }
+        }
+        else {
+            throw new Error("Network error occurred");
+        }
+    }
+    extractErrorMessage(response) {
+        if (response.data?.errorMessages) {
+            return response.data.errorMessages.join(", ");
+        }
+        if (response.data?.errors) {
+            return Object.values(response.data.errors).join(", ");
+        }
+        if (response.data?.message) {
+            return response.data.message;
+        }
+        return "Unknown error occurred";
+    }
+    // Rate limited request wrapper
+    async makeRequest(requestFn) {
+        return this.rateLimiter(async () => {
+            const response = await requestFn();
+            return response.data;
+        });
+    }
+    // Pagination helper
+    async *paginate(endpoint, params = {}, pageSize = 50) {
+        let startAt = 0;
+        let isLast = false;
+        while (!isLast) {
+            const response = await this.makeRequest(() => this.client.get(endpoint, {
+                params: {
+                    ...params,
+                    startAt,
+                    maxResults: pageSize,
+                },
+            }));
+            yield response.values || response.results || [];
+            isLast = response.isLast !== false;
+            startAt += pageSize;
+            if (!response.values && !response.results) {
+                break;
+            }
+        }
+    }
+}

package/dist/libs/error-handler.js

@@ -0,0 +1,21 @@
+export class ApiError extends Error {
+    statusCode;
+    details;
+    constructor(message, statusCode, details) {
+        super(message);
+        this.statusCode = statusCode;
+        this.details = details;
+        this.name = "ApiError";
+    }
+}
+export function handleApiError(error) {
+    if (error.response) {
+        throw new ApiError(error.response.data?.message || "API request failed", error.response.status, error.response.data);
+    }
+    else if (error.request) {
+        throw new ApiError("No response received from server");
+    }
+    else {
+        throw new ApiError(error.message || "Unknown error occurred");
+    }
+}

package/dist/libs/jira-client.js

@@ -0,0 +1,123 @@
+import { BaseApiService } from "./base-client.js";
+import { atlassianConfig } from "../config.js";
+export class JiraService extends BaseApiService {
+    constructor() {
+        super(atlassianConfig.jira, "JiraService");
+    }
+    /**
+     * Issue 조회
+     * @see https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-get
+     */
+    async getIssue(issueKey, expand) {
+        return this.makeRequest(() => this.client.get(`/issue/${issueKey}`, {
+            params: expand ? { expand: expand.join(",") } : undefined,
+        }));
+    }
+    /**
+     * JQL 검색
+     * @see https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/#api-rest-api-3-search-jql-get
+     */
+    async searchIssues(options) {
+        const allIssues = [];
+        const { jql, nextPageToken, maxResults = 50, fields, expand, properties, fieldsByKeys, failFast, reconcileIssues, } = options;
+        // Prepare parameters for API request
+        const params = {
+            jql,
+            maxResults,
+        };
+        // Add optional parameters if provided
+        if (nextPageToken)
+            params.nextPageToken = nextPageToken;
+        if (fields)
+            params.fields = fields.join(",");
+        if (expand)
+            params.expand = expand.join(",");
+        if (properties)
+            params.properties = properties.join(",");
+        if (fieldsByKeys !== undefined)
+            params.fieldsByKeys = fieldsByKeys;
+        if (failFast !== undefined)
+            params.failFast = failFast;
+        if (reconcileIssues)
+            params.reconcileIssues = reconcileIssues.join(",");
+        // Single page retrieval when nextPageToken is provided
+        if (nextPageToken) {
+            const response = await this.makeRequest(() => this.client.get("/search/jql", { params }));
+            return response.issues || [];
+        }
+        // Use pagination for complete result set
+        let token = null;
+        do {
+            if (token)
+                params.nextPageToken = token;
+            const response = await this.makeRequest(() => this.client.get("/search/jql", { params }));
+            if (response.issues) {
+                allIssues.push(...response.issues);
+            }
+            token = response.nextPageToken || null;
+        } while (token);
+        return allIssues;
+    }
+    /**
+     * 프로젝트 목록 조회
+     * @see https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-search-get
+     */
+    async getProjects(options) {
+        const params = {};
+        // Add optional parameters if provided
+        if (options) {
+            const { startAt, maxResults, orderBy, id, keys, query, typeKey, categoryId, action, expand, status, properties, propertyQuery } = options;
+            if (startAt !== undefined)
+                params.startAt = startAt;
+            if (maxResults !== undefined)
+                params.maxResults = maxResults;
+            if (orderBy)
+                params.orderBy = orderBy;
+            if (id)
+                params.id = id.join(',');
+            if (keys)
+                params.keys = keys.join(',');
+            if (query)
+                params.query = query;
+            if (typeKey)
+                params.typeKey = typeKey;
+            if (categoryId !== undefined)
+                params.categoryId = categoryId;
+            if (action)
+                params.action = action;
+            if (expand)
+                params.expand = expand.join(',');
+            if (status)
+                params.status = status.join(',');
+            if (properties) {
+                // Handle the nested StringList structure
+                properties.forEach((prop, index) => {
+                    params[`properties[${index}]`] = prop.join(',');
+                });
+            }
+            if (propertyQuery)
+                params.propertyQuery = propertyQuery;
+        }
+        return this.makeRequest(() => this.client.get("/project/search", { params }));
+    }
+    /**
+     * 이슈 댓글 목록 조회
+     * @see https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-comments/#api-rest-api-3-issue-issueidorkey-comment-get
+     */
+    async getComments(issueKey, options) {
+        const params = {};
+        // Add optional parameters if provided
+        if (options) {
+            const { startAt, maxResults, orderBy, expand } = options;
+            if (startAt !== undefined)
+                params.startAt = startAt;
+            if (maxResults !== undefined)
+                params.maxResults = maxResults;
+            if (orderBy)
+                params.orderBy = orderBy;
+            if (expand)
+                params.expand = expand.join(',');
+        }
+        return this.makeRequest(() => this.client.get(`/issue/${issueKey}/comment`, { params }));
+    }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ecubelabs/atlassian-mcp",
+  "version": "1.0.0-next.3",
+  "bin": "./dist/index.js",
+  "repository": {
+    "url": "https://github.com/Ecube-Labs/skynet.git"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', '755')\"",
+    "prepack": "yarn build"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">= 18"
+  },
+  "packageManager": "yarn@4.1.0",
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.3",
+    "axios": "^1.7.9",
+    "axios-retry": "^4.5.0",
+    "dotenv": "^17.2.0",
+    "p-limit": "^5.0.0",
+    "winston": "^3.17.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.8",
+    "semantic-release": "^24.2.7",
+    "semantic-release-yarn": "^3.0.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.2"
+  },
+  "stableVersion": "1.0.0"
+}