@neosamon/jira-mcp-server 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wuyan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,7 +5,10 @@
 ## 功能
 
 - **查询 Issue**: 通过 Issue Key 获取 Issue 的详细信息，包括类型、状态、优先级、描述和评论
+- **搜索 Issues**: 使用 JQL (Jira Query Language) 批量搜索 Issues
 - **创建评论**: 为指定的 Issue 添加评论
+- **字段发现**: 探测 Issue 的所有可用字段，用于配置自定义字段映射
+- **自定义字段**: 支持通过环境变量配置，提取 Jira 自定义字段
 
 ## 环境变量配置
 
@@ -48,35 +51,48 @@ JIRA_AUTH_TYPE 环境变量
 3. 点击 **Create API token**
 4. 复制生成的 Token 并设置为 `JIRA_API_TOKEN` 环境变量
 
+### 自定义字段配置（可选）
+
+Jira 实例通常包含自定义字段（如测试步骤、预期结果、代码分支等）。要提取这些字段，需要配置字段映射。
+
+#### 配置步骤
+
+1. **使用字段发现工具**找出目标字段的 ID：
+
+   ```
+   "使用 get_issue_fields 工具查看 Issue PROJ-123 的所有字段"
+   ```
+
+2. **配置环境变量**将字段名映射到字段 ID：
+
+   ```bash
+   export JIRA_FIELD_TEST_STEP="customfield_10206"
+   export JIRA_FIELD_EXPECTED_RESULT="customfield_10208"
+   export JIRA_FIELD_ACTUAL_RESULT="customfield_10210"
+   export JIRA_FIELD_CODE_BRANCH="customfield_10300"
+   ```
+
+3. **重启服务器**，`get_issue` 工具将自动包含配置的自定义字段
+
+#### 字段映射规则
+
+- 环境变量格式：`JIRA_FIELD_<NAME>=<field_id>`
+- 字段名会自动转换为驼峰命名（如 `JIRA_FIELD_TEST_STEP` → `testStep`）
+- 未配置的字段不会出现在输出中
+- 字段不存在或为空时显示 `N/A`
+
 ## 安装
 
 ### 通过 npm 全局安装
 
 ```bash
-npm install -g jira-mcp-server
+npm install -g @neosamon/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
+npx @neosamon/jira-mcp-server
 ```
 
 ## 使用方法
@@ -90,7 +106,7 @@ 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
+npx @neosamon/jira-mcp-server
 ```
 
 #### 使用密码认证
@@ -100,7 +116,7 @@ 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
+npx @neosamon/jira-mcp-server
 ```
 
 #### 显式指定认证方式
@@ -135,7 +151,8 @@ export JIRA_PASSWORD="your-password"
 {
   "mcpServers": {
     "jira": {
-      "command": "jira-mcp-server",
+      "command": "npx",
+      "args": ["@neosamon/jira-mcp-server"],
       "env": {
         "JIRA_BASE_URL": "https://your-jira.example.com",
         "JIRA_USERNAME": "your-email@example.com",
@@ -152,7 +169,8 @@ export JIRA_PASSWORD="your-password"
 {
   "mcpServers": {
     "jira": {
-      "command": "jira-mcp-server",
+      "command": "npx",
+      "args": ["@neosamon/jira-mcp-server"],
       "env": {
         "JIRA_BASE_URL": "https://your-jira.example.com",
         "JIRA_USERNAME": "your-email@example.com",
@@ -163,15 +181,47 @@ export JIRA_PASSWORD="your-password"
 }
 ```
 
-如果使用 `npx`，可以将 `command` 改为 `"npx"`，并添加 `"args": ["jira-mcp-server"]`。
+## Claude CLI 配置
+
+### 基于项目添加
+```bash
+claude mcp add jira --transport stdio \
+    --env JIRA_BASE_URL="https://your-jira.example.com" \
+    --env JIRA_USERNAME="your-email@example.com" \
+    --env JIRA_PASSWORD="your-password" \
+    -- npx @neosamon/jira-mcp-server
+```
+
+### 全局添加
+```bash
+claude mcp add jira --scope user --transport stdio \
+    --env JIRA_BASE_URL="https://your-jira.example.com" \
+    --env JIRA_USERNAME="your-email@example.com" \
+    --env JIRA_PASSWORD="your-password" \
+    -- npx @neosamon/jira-mcp-server
+```
 
 ## 使用示例
 
 配置完成后，您可以在 Claude 中使用以下命令：
 
+### 基本功能
+
 - "查询 Jira Issue PROJ-123 的详情"
 - "为 PROJ-123 添加评论：已完成代码审查"
 
+### 字段发现
+
+- "使用 get_issue_fields 工具查看 Issue PROJ-123 的所有可用字段"
+- "列出 PROJ-123 的字段，帮我找出测试步骤对应的字段 ID"
+
+### JQL 搜索
+
+- "搜索分配给我的所有进行中任务"
+- "查找项目 PROJ 中所有高优先级的 Bug"
+- "列出本周创建的所有 Issues"
+- "搜索状态为 Open 且优先级为 High 的 Issues"
+
 ## 兼容性
 
 - **Node.js 版本**: 18 或更高版本

package/build/index.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -35,6 +36,21 @@ function loadConfig() {
     }
     return { baseURL, username, apiToken, password, authType };
 }
+// 加载自定义字段映射配置
+function loadFieldMapping() {
+    const mapping = {};
+    const prefix = "JIRA_FIELD_";
+    for (const [key, value] of Object.entries(process.env)) {
+        if (key.startsWith(prefix) && value) {
+            // 将 JIRA_FIELD_TEST_STEP 转换为 testStep (驼峰命名)
+            const fieldName = key.substring(prefix.length)
+                .toLowerCase()
+                .replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+            mapping[fieldName] = value;
+        }
+    }
+    return mapping;
+}
 // ==================== HTTP 客户端 ====================
 // 根据 authType 确定使用哪种认证凭据
 function getAuthCredential(config) {
@@ -90,13 +106,58 @@ async function addComment(config, issueKey, body) {
     });
 }
 // ==================== 输出格式化函数 ====================
+/**
+ * 格式化字段值用于显示
+ * 根据值的类型采用不同的展示策略
+ */
+function formatFieldValue(value) {
+    // null 或 undefined
+    if (value === null || value === undefined) {
+        return "N/A";
+    }
+    // 字符串类型 - 截断过长内容
+    if (typeof value === "string") {
+        if (value.length <= 50) {
+            return value;
+        }
+        return `${value.substring(0, 50)}...`;
+    }
+    // 数组类型
+    if (Array.isArray(value)) {
+        return `[Array] (${value.length} items)`;
+    }
+    // 对象类型
+    if (typeof value === "object") {
+        // 提取 name 属性（如用户、状态等）
+        if ("name" in value && typeof value.name === "string") {
+            return value.name;
+        }
+        // 提取 value 属性（如选项字段）
+        if ("value" in value && typeof value.value === "string") {
+            return value.value;
+        }
+        // 其他复杂对象 - JSON 序列化
+        try {
+            const jsonStr = JSON.stringify(value);
+            if (jsonStr.length <= 50) {
+                return jsonStr;
+            }
+            return `${jsonStr.substring(0, 50)}...`;
+        }
+        catch {
+            return "[Object]";
+        }
+    }
+    // 数字、布尔等基本类型
+    return String(value);
+}
 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) {
+function formatIssue(issue, fieldMapping) {
     const output = [];
     // 标题
     output.push(`## Issue: ${issue.key}\n`);
@@ -125,6 +186,16 @@ function formatIssue(issue) {
             output.push(`**描述**:\n${descText}\n`);
         }
     }
+    // 自定义字段
+    if (fieldMapping && Object.keys(fieldMapping).length > 0) {
+        output.push(`**自定义字段**:\n`);
+        for (const [fieldName, fieldId] of Object.entries(fieldMapping)) {
+            const fieldValue = issue.fields[fieldId];
+            const displayValue = formatFieldValue(fieldValue);
+            output.push(`- **${fieldName}**: ${displayValue}\n`);
+        }
+        output.push(`\n`);
+    }
     // 评论
     if (issue.fields.comment?.comments && issue.fields.comment.comments.length > 0) {
         const allComments = issue.fields.comment.comments;
@@ -168,6 +239,7 @@ server.registerTool("get_issue", {
     },
 }, async ({ issueKey }) => {
     const config = loadConfig();
+    const fieldMapping = loadFieldMapping();
     const issue = await getIssue(config, issueKey);
     if (!issue) {
         return {
@@ -183,7 +255,7 @@ server.registerTool("get_issue", {
         content: [
             {
                 type: "text",
-                text: formatIssue(issue),
+                text: formatIssue(issue, fieldMapping),
             },
         ],
     };
@@ -229,6 +301,150 @@ server.registerTool("add_comment", {
         ],
     };
 });
+// 注册 get_issue_fields 工具
+server.registerTool("get_issue_fields", {
+    title: "Get Issue Fields",
+    description: "Get all available fields for a Jira Issue. This helps discover custom field IDs for configuration.",
+    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}' 不存在`,
+                },
+            ],
+        };
+    }
+    // 遍历所有字段并格式化
+    const fieldsList = [];
+    for (const [fieldId, fieldValue] of Object.entries(issue.fields)) {
+        fieldsList.push({
+            fieldId,
+            valuePreview: formatFieldValue(fieldValue),
+        });
+    }
+    // 格式化输出
+    const output = `## Issue ${issueKey} - 字段列表\n\n` +
+        `共找到 ${fieldsList.length} 个字段:\n\n` +
+        fieldsList.map(f => `- **${f.fieldId}**: ${f.valuePreview}`).join("\n");
+    return {
+        content: [
+            {
+                type: "text",
+                text: output,
+            },
+        ],
+    };
+});
+// 注册 search_issues 工具
+server.registerTool("search_issues", {
+    title: "Search Issues with JQL",
+    description: "Search for Jira Issues using JQL (Jira Query Language). Returns a list of matching Issues with Key, Summary, and Status.",
+    inputSchema: {
+        jql: z.string().describe("JQL query string (e.g., project = PROJ AND status = 'In Progress')"),
+        maxResults: z.number().optional().describe("Maximum number of results to return (default: 50, max: 100)"),
+    },
+}, async ({ jql, maxResults = 50 }) => {
+    // 参数验证
+    if (!jql || jql.trim().length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "错误: JQL 查询不能为空",
+                },
+            ],
+        };
+    }
+    // 验证 maxResults
+    const limit = Math.min(Math.max(1, Math.floor(maxResults)), 100);
+    if (limit !== maxResults) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `错误: maxResults 必须是 1-100 之间的整数，已请求: ${maxResults}`,
+                },
+            ],
+        };
+    }
+    const config = loadConfig();
+    // 调用 Jira API 搜索
+    const credential = getAuthCredential(config);
+    const authHeader = getBasicAuthHeader(config.username, credential);
+    try {
+        const url = new URL(`${config.baseURL}/rest/api/2/search`);
+        url.searchParams.set("jql", jql);
+        url.searchParams.set("maxResults", String(limit));
+        url.searchParams.set("fields", "key,summary,status");
+        const searchResponse = await fetch(url.toString(), {
+            headers: {
+                Authorization: authHeader,
+                Accept: "application/json",
+            },
+        });
+        if (!searchResponse.ok) {
+            const errorText = await searchResponse.text();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Jira 查询失败: ${searchResponse.status}\n${errorText}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const data = await searchResponse.json();
+        const issues = data.issues || [];
+        // 格式化结果
+        if (issues.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `未找到匹配的 Issues\n\nJQL: ${jql}`,
+                    },
+                ],
+            };
+        }
+        const total = data.total || issues.length;
+        const output = `## 搜索结果\n\n` +
+            `**JQL**: ${jql}\n` +
+            `**找到**: ${total} 个 Issues (显示 ${issues.length} 个)\n\n` +
+            issues.map((issue) => {
+                const key = issue.key;
+                const summary = issue.fields?.summary || "无摘要";
+                const status = issue.fields?.status?.name || "未知";
+                return `- **${key}**: ${summary} [${status}]`;
+            }).join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: output,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `搜索失败: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
 // ==================== 服务器启动 ====================
 async function main() {
     // 加载并验证配置

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@neosamon/jira-mcp-server",
-  "version": "0.1.0",
+  "version": "0.2.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"],
+  "files": [
+    "build"
+  ],
   "engines": {
     "node": ">=18"
   },
@@ -15,7 +17,11 @@
     "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
     "prepublishOnly": "npm run build"
   },
-  "keywords": ["mcp", "jira", "model-context-protocol"],
+  "keywords": [
+    "mcp",
+    "jira",
+    "model-context-protocol"
+  ],
   "author": "",
   "license": "MIT",
   "dependencies": {