@neosamon/jira-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,182 @@
+# Jira MCP Server
+
+一个基于 TypeScript/Node.js 的 Jira Model Context Protocol (MCP) Server，允许 AI 助手直接与 Jira 进行交互。
+
+## 功能
+
+- **查询 Issue**: 通过 Issue Key 获取 Issue 的详细信息，包括类型、状态、优先级、描述和评论
+- **创建评论**: 为指定的 Issue 添加评论
+
+## 环境变量配置
+
+在使用之前，需要设置以下环境变量：
+
+| 环境变量 | 必需 | 说明 | 示例 |
+|----------|------|------|------|
+| `JIRA_BASE_URL` | 是 | Jira 服务器地址（不要以斜杠结尾） | `https://your-jira.example.com` |
+| `JIRA_USERNAME` | 是 | Jira 用户名或邮箱 | `user@example.com` |
+| `JIRA_API_TOKEN` | 条件必需* | Jira API Token | `your-api-token-here` |
+| `JIRA_PASSWORD` | 条件必需* | Jira 密码 | `your-password` |
+| `JIRA_AUTH_TYPE` | 否 | 认证方式：`auto`（默认）、`token`、`password` | `auto` |
+
+**至少需要设置 `JIRA_API_TOKEN` 或 `JIRA_PASSWORD` 之一**
+
+### 认证方式说明
+
+本 MCP Server 支持两种认证方式：
+
+1. **API Token 认证（推荐）**: 更安全，可以随时撤销
+2. **密码认证**: 适用于不支持 API Token 的旧版本 Jira
+
+#### 认证方式选择逻辑
+
+```
+JIRA_AUTH_TYPE 环境变量
+│
+├─ "token" → 强制使用 API Token（忽略 JIRA_PASSWORD）
+├─ "password" → 强制使用密码（忽略 JIRA_API_TOKEN）
+└─ "auto" 或未设置
+   │
+   ├─ 如果设置了 JIRA_PASSWORD → 使用密码（优先）
+   └─ 否则 → 使用 API Token
+```
+
+#### 获取 Jira API Token
+
+1. 登录到您的 Jira 实例
+2. 进入 **Account Settings** > **Security** > **API Tokens**
+3. 点击 **Create API token**
+4. 复制生成的 Token 并设置为 `JIRA_API_TOKEN` 环境变量
+
+## 安装
+
+### 通过 npm 全局安装
+
+```bash
+npm install -g jira-mcp-server
+```
+
+### 使用 npx 运行（无需安装）
+
+```bash
+npx jira-mcp-server
+```
+
+### 从源码构建
+
+```bash
+# 克隆仓库
+git clone <repository-url>
+cd jira-mcp-server-ts
+
+# 安装依赖
+npm install
+
+# 构建
+npm run build
+
+# 运行
+node build/index.js
+```
+
+## 使用方法
+
+### 设置环境变量
+
+#### 使用 API Token 认证（推荐）
+
+```bash
+export JIRA_BASE_URL="https://your-jira.example.com"
+export JIRA_USERNAME="your-email@example.com"
+export JIRA_API_TOKEN="your-api-token"
+
+npx jira-mcp-server
+```
+
+#### 使用密码认证
+
+```bash
+export JIRA_BASE_URL="https://your-jira.example.com"
+export JIRA_USERNAME="your-email@example.com"
+export JIRA_PASSWORD="your-password"
+
+npx jira-mcp-server
+```
+
+#### 显式指定认证方式
+
+```bash
+# 强制使用 Token 认证
+export JIRA_AUTH_TYPE="token"
+export JIRA_API_TOKEN="your-api-token"
+
+# 强制使用密码认证
+export JIRA_AUTH_TYPE="password"
+export JIRA_PASSWORD="your-password"
+```
+
+## Claude Desktop 配置
+
+在 Claude Desktop 的配置文件中添加以下内容：
+
+### macOS
+
+配置文件路径: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+### Windows
+
+配置文件路径: `%APPDATA%\Claude\claude_desktop_config.json`
+
+### 配置内容
+
+#### 使用 API Token 认证（推荐）
+
+```json
+{
+  "mcpServers": {
+    "jira": {
+      "command": "jira-mcp-server",
+      "env": {
+        "JIRA_BASE_URL": "https://your-jira.example.com",
+        "JIRA_USERNAME": "your-email@example.com",
+        "JIRA_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+#### 使用密码认证
+
+```json
+{
+  "mcpServers": {
+    "jira": {
+      "command": "jira-mcp-server",
+      "env": {
+        "JIRA_BASE_URL": "https://your-jira.example.com",
+        "JIRA_USERNAME": "your-email@example.com",
+        "JIRA_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+如果使用 `npx`，可以将 `command` 改为 `"npx"`，并添加 `"args": ["jira-mcp-server"]`。
+
+## 使用示例
+
+配置完成后，您可以在 Claude 中使用以下命令：
+
+- "查询 Jira Issue PROJ-123 的详情"
+- "为 PROJ-123 添加评论：已完成代码审查"
+
+## 兼容性
+
+- **Node.js 版本**: 18 或更高版本
+- **Jira 版本**: 7.0.9+ (使用 REST API v2)
+
+## 许可证
+
+MIT License

package/build/index.js

@@ -0,0 +1,246 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+function loadConfig() {
+    const baseURL = process.env.JIRA_BASE_URL;
+    const username = process.env.JIRA_USERNAME;
+    const apiToken = process.env.JIRA_API_TOKEN;
+    const password = process.env.JIRA_PASSWORD;
+    const authType = (process.env.JIRA_AUTH_TYPE || "auto");
+    // 验证必需的环境变量
+    if (!baseURL) {
+        console.error("错误: JIRA_BASE_URL 环境变量是必需的");
+        console.error("请设置 Jira 服务器地址（如 https://your-jira.example.com）");
+        process.exit(1);
+    }
+    if (!username) {
+        console.error("错误: JIRA_USERNAME 环境变量是必需的");
+        console.error("请设置 Jira 用户名或邮箱");
+        process.exit(1);
+    }
+    // 验证认证凭据
+    if (!apiToken && !password) {
+        console.error("错误: 至少需要设置 JIRA_API_TOKEN 或 JIRA_PASSWORD 之一");
+        process.exit(1);
+    }
+    // 显式指定 Token 认证但未提供
+    if (authType === "token" && !apiToken) {
+        console.error("错误: 使用 Token 认证时 JIRA_API_TOKEN 是必需的");
+        process.exit(1);
+    }
+    // 显式指定密码认证但未提供
+    if (authType === "password" && !password) {
+        console.error("错误: 使用密码认证时 JIRA_PASSWORD 是必需的");
+        process.exit(1);
+    }
+    return { baseURL, username, apiToken, password, authType };
+}
+// ==================== HTTP 客户端 ====================
+// 根据 authType 确定使用哪种认证凭据
+function getAuthCredential(config) {
+    if (config.authType === "token") {
+        return config.apiToken;
+    }
+    if (config.authType === "password") {
+        return config.password;
+    }
+    // auto 模式：密码优先
+    return config.password || config.apiToken;
+}
+// 生成 Basic Auth 头
+function getBasicAuthHeader(username, credential) {
+    const credentials = Buffer.from(`${username}:${credential}`).toString("base64");
+    return `Basic ${credentials}`;
+}
+// HTTP 请求辅助函数
+async function makeJiraRequest(url, config, options) {
+    const credential = getAuthCredential(config);
+    const authHeader = getBasicAuthHeader(config.username, credential);
+    const headers = {
+        Authorization: authHeader,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...options?.headers,
+    };
+    try {
+        const response = await fetch(`${config.baseURL}${url}`, {
+            ...options,
+            headers,
+        });
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => "");
+            console.error(`Jira API error: ${response.status} - ${errorText}`);
+            return null;
+        }
+        return (await response.json());
+    }
+    catch (error) {
+        console.error("Error making Jira request:", error);
+        return null;
+    }
+}
+// ==================== Jira API 调用方法 ====================
+async function getIssue(config, issueKey) {
+    return makeJiraRequest(`/rest/api/2/issue/${issueKey}`, config);
+}
+async function addComment(config, issueKey, body) {
+    return makeJiraRequest(`/rest/api/2/issue/${issueKey}/comment`, config, {
+        method: "POST",
+        body: JSON.stringify({ body }),
+    });
+}
+// ==================== 输出格式化函数 ====================
+function formatComment(comment) {
+    const author = comment.author.displayName;
+    const created = comment.created;
+    const commentBody = comment.body || "(无内容)";
+    return `**${author}** - ${created}\n${commentBody}\n`;
+}
+function formatIssue(issue) {
+    const output = [];
+    // 标题
+    output.push(`## Issue: ${issue.key}\n`);
+    // 类型、状态、优先级
+    const typeName = issue.fields.issuetype?.name || "未知";
+    const statusName = issue.fields.status?.name || "未知";
+    const priorityName = issue.fields.priority?.name || "未设置";
+    output.push(`**类型**: ${typeName} | **状态**: ${statusName} | **优先级**: ${priorityName}\n`);
+    // 摘要
+    if (issue.fields.summary) {
+        output.push(`**摘要**: ${issue.fields.summary}\n`);
+    }
+    // 描述
+    if (issue.fields.description) {
+        let descText;
+        if (typeof issue.fields.description === "string") {
+            descText = issue.fields.description;
+        }
+        else if (issue.fields.description.__html) {
+            descText = issue.fields.description.__html;
+        }
+        else {
+            descText = String(issue.fields.description);
+        }
+        if (descText.trim()) {
+            output.push(`**描述**:\n${descText}\n`);
+        }
+    }
+    // 评论
+    if (issue.fields.comment?.comments && issue.fields.comment.comments.length > 0) {
+        const allComments = issue.fields.comment.comments;
+        const commentCount = allComments.length;
+        const commentsToShow = allComments.slice().reverse().slice(0, 50);
+        output.push(`**评论** (${commentCount} 条):\n`);
+        for (const comment of commentsToShow) {
+            output.push(formatComment(comment));
+        }
+        if (commentCount > 50) {
+            output.push(`*(还有 ${commentCount - 50} 条评论未显示)*\n`);
+        }
+    }
+    return output.join("");
+}
+function formatCreatedComment(issueKey, comment) {
+    const author = comment.author.displayName;
+    const created = comment.created;
+    const body = comment.body || "(无内容)";
+    // 预览（前 100 字符）
+    const preview = body.length > 100 ? `${body.substring(0, 100)}...` : body;
+    return `✓ 评论已创建\n\n` +
+        `**Issue**: ${issueKey}\n` +
+        `**评论 ID**: ${comment.id}\n` +
+        `**作者**: ${author}\n` +
+        `**创建时间**: ${created}\n` +
+        `**内容**: ${preview}`;
+}
+// ==================== MCP Server ====================
+// 创建 server 实例
+const server = new McpServer({
+    name: "jira",
+    version: "0.1.0",
+});
+// 注册 get_issue 工具
+server.registerTool("get_issue", {
+    title: "Get Jira Issue",
+    description: "Get detailed information about a Jira Issue including type, status, priority, description, and comments.",
+    inputSchema: {
+        issueKey: z.string().describe("Jira Issue Key (e.g., PROJ-123)"),
+    },
+}, async ({ issueKey }) => {
+    const config = loadConfig();
+    const issue = await getIssue(config, issueKey);
+    if (!issue) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `错误: 无法连接到 Jira 服务器或 Issue '${issueKey}' 不存在`,
+                },
+            ],
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: formatIssue(issue),
+            },
+        ],
+    };
+});
+// 注册 add_comment 工具
+server.registerTool("add_comment", {
+    title: "Add Comment to Issue",
+    description: "Add a comment to a Jira Issue.",
+    inputSchema: {
+        issueKey: z.string().describe("Jira Issue Key (e.g., PROJ-123)"),
+        body: z.string().describe("Comment content"),
+    },
+}, async ({ issueKey, body }) => {
+    // 验证 body 非空
+    if (!body || body.trim().length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "错误: 评论内容不能为空",
+                },
+            ],
+        };
+    }
+    const config = loadConfig();
+    const result = await addComment(config, issueKey, body);
+    if (!result) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `错误: 无法添加评论。请检查 Issue Key '${issueKey}' 是否存在，以及您是否有权限添加评论。`,
+                },
+            ],
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: formatCreatedComment(issueKey, result),
+            },
+        ],
+    };
+});
+// ==================== 服务器启动 ====================
+async function main() {
+    // 加载并验证配置
+    const config = loadConfig();
+    console.error(`Jira MCP Server 配置加载成功: ${config.baseURL} (认证方式: ${config.authType})`);
+    // 创建 stdio 传输
+    const transport = new StdioServerTransport();
+    // 连接服务器
+    await server.connect(transport);
+    console.error("Jira MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@neosamon/jira-mcp-server",
+  "version": "0.1.0",
+  "description": "Jira MCP Server - Model Context Protocol server for Jira integration",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "jira-mcp-server": "./build/index.js"
+  },
+  "files": ["build"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["mcp", "jira", "model-context-protocol"],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.24.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.2",
+    "typescript": "^5.9.3"
+  }
+}