sonarqube-issue-mcp 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,207 @@
+/**
+ * 控制返回结果是否补充规则说明等重字段。
+ *
+ * @remarks
+ * - `standard`: 只返回常规排查字段
+ * - `full`: 额外返回规则描述、修复建议等扩展字段
+ */
+export type DetailLevel = "standard" | "full";
+/**
+ * MCP 详情查询目前支持的实体类型。
+ *
+ * @remarks
+ * `issue` 对应 SonarQube 的常规 issue，`hotspot` 对应 Security Hotspot。
+ */
+export type FindingKind = "issue" | "hotspot";
+/**
+ * 将 SonarQube 原始问题重新映射为 MCP 输出侧的稳定分类。
+ *
+ * @remarks
+ * 这里不沿用 SonarQube 的所有类型，而是只暴露本项目当前关心的三类：
+ * Security、Reliability、Security Hotspot。
+ */
+export type FindingCategory = "security" | "reliability" | "security-hotspot";
+/**
+ * 从 SonarQube dashboard URL 中解析出的项目定位信息。
+ *
+ * @remarks
+ * 这是后续所有 SonarQube API 请求共享的上下文载体。
+ */
+export interface ProjectRef {
+    /** SonarQube 服务根地址，例如 `https://sonarqube.example.com`。 */
+    origin: string;
+    /** 项目标识，对应 dashboard URL 中的 `id` 参数。 */
+    projectKey: string;
+    /** 可选分支名；community 版通常为空。 */
+    branch: string | null;
+    /** 可选 PR 编号；community 版通常为空。 */
+    pullRequest: string | null;
+    /** 用户原始传入的 dashboard URL。 */
+    dashboardUrl: string;
+}
+/**
+ * SonarQube 返回的行列范围信息。
+ *
+ * @remarks
+ * 与编辑器中的高亮区间或 Sonar 页面中的定位区域一一对应。
+ */
+export interface TextRange {
+    /** 高亮区域起始行号。 */
+    startLine: number;
+    /** 高亮区域结束行号。 */
+    endLine: number;
+    /** 起始列偏移。 */
+    startOffset: number;
+    /** 结束列偏移。 */
+    endOffset: number;
+}
+/**
+ * SonarQube 新版 issue impacts 字段中的单条影响描述。
+ *
+ * @remarks
+ * 新版规则/问题模型会用 `softwareQuality + severity` 组合表达影响级别。
+ */
+export interface FindingImpact {
+    /** 受影响的软件质量维度，例如 `SECURITY`。 */
+    softwareQuality: string;
+    /** 该质量维度下的严重程度。 */
+    severity: string;
+}
+/**
+ * 项目级基础信息，供 MCP 汇总和详情接口复用。
+ *
+ * @remarks
+ * 这部分字段被设计成稳定结构，方便客户端直接缓存或展示。
+ */
+export interface ProjectInfo {
+    /** 项目 key。 */
+    key: string;
+    /** 项目名称。 */
+    name: string;
+    /** SonarQube 组件限定符，例如 `TRK`。 */
+    qualifier: string | null;
+    /** 当前查询绑定的分支。 */
+    branch: string | null;
+    /** 当前查询绑定的 PR。 */
+    pullRequest: string | null;
+    /** 用户原始传入的 dashboard URL。 */
+    dashboardUrl: string;
+    /** 标准化后的项目浏览链接。 */
+    browseUrl: string;
+    /** SonarQube 服务版本。 */
+    serverVersion: string;
+}
+/**
+ * MCP 对单条问题的统一摘要结构。
+ *
+ * @remarks
+ * 这里刻意把 issue 与 hotspot 归一成一套字段，方便上层 LLM 或客户端统一消费。
+ */
+export interface FindingSummary {
+    /** 问题唯一 key。 */
+    key: string;
+    /** 底层实体类型。 */
+    kind: FindingKind;
+    /** MCP 归一化后的业务分类。 */
+    category: FindingCategory;
+    /** SonarQube 规则 key。 */
+    ruleKey: string;
+    /** 规则展示名。 */
+    ruleName: string | null;
+    /** 问题主消息。 */
+    message: string;
+    /** 当前状态。 */
+    status: string;
+    /** 当前处理结论；未设置时为空。 */
+    resolution: string | null;
+    /** 统一后的严重度。 */
+    severity: string | null;
+    /** Hotspot 风险概率。 */
+    vulnerabilityProbability: string | null;
+    /** 新版质量模型 impacts 列表。 */
+    impacts: FindingImpact[];
+    /** Clean Code 属性。 */
+    cleanCodeAttribute: string | null;
+    /** 相对文件路径。 */
+    file: string | null;
+    /** 问题所在行号。 */
+    line: number | null;
+    /** 更精细的文本范围。 */
+    textRange: TextRange | null;
+    /** 作者信息。 */
+    author: string | null;
+    /** 负责人信息。 */
+    assignee: string | null;
+    /** 规则或问题标签。 */
+    tags: string[];
+    /** 创建时间。 */
+    createdAt: string;
+    /** 最后更新时间。 */
+    updatedAt: string;
+    /** 指向 SonarQube 页面的深链。 */
+    sonarUrl: string;
+    /** 规则描述文本。 */
+    ruleDescription: string | null;
+    /** Hotspot 风险说明。 */
+    riskDescription: string | null;
+    /** Hotspot 修复建议。 */
+    fixRecommendations: string | null;
+    /** Hotspot 漏洞说明。 */
+    vulnerabilityDescription: string | null;
+}
+/**
+ * 项目级汇总统计信息。
+ *
+ * @remarks
+ * 所有计数都基于当前 MCP 固定查询口径计算，而不是 Sonar 页面的全部历史数据。
+ */
+export interface ProjectFindingsSummary {
+    /** Security 问题数量。 */
+    securityIssueCount: number;
+    /** Reliability 问题数量。 */
+    reliabilityIssueCount: number;
+    /** Security Hotspots 数量。 */
+    securityHotspotCount: number;
+    /** 三类问题总数。 */
+    totalFindings: number;
+    /** 当前结果生成时使用的详情级别。 */
+    detailLevel: DetailLevel;
+}
+/**
+ * `sonarqube_get_project_findings` 的结构化返回体。
+ *
+ * @remarks
+ * 三个数组已按服务层预定义规则完成排序，可直接展示或继续追问。
+ */
+export interface ProjectFindingsResult {
+    /** 项目基础信息。 */
+    project: ProjectInfo;
+    /** 数量汇总。 */
+    summary: ProjectFindingsSummary;
+    /** Security 问题列表。 */
+    securityIssues: FindingSummary[];
+    /** Reliability 问题列表。 */
+    reliabilityIssues: FindingSummary[];
+    /** Security Hotspot 列表。 */
+    securityHotspots: FindingSummary[];
+}
+/**
+ * `sonarqube_get_finding_detail` 的结构化返回体。
+ *
+ * @remarks
+ * `raw` 保留底层 SonarQube 返回，便于出现歧义时做问题排查。
+ */
+export interface FindingDetail {
+    /** 项目基础信息。 */
+    project: ProjectInfo;
+    /** 统一摘要。 */
+    summary: FindingSummary;
+    /** 问题评论；issue 与 hotspot 的原始结构不同，因此保留为原始数组。 */
+    comments: unknown[];
+    /** issue/hotspot 的历史变更记录。 */
+    changelog: unknown[];
+    /** SonarQube 提供的 execution/data flow。 */
+    flows: unknown[];
+    /** 调试与追查问题时使用的原始 API 返回。 */
+    raw: unknown;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "sonarqube-issue-mcp",
+  "version": "0.0.1",
+  "description": "基于 SonarQube 项目链接查询 Security、Reliability 和 Security Hotspots 问题的 MCP 服务。",
+  "type": "module",
+  "bin": {
+    "sonarqube-issue-mcp": "./bin/sonarqube-issue-mcp.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx watch src/index.ts",
+    "prepack": "pnpm build",
+    "prepublishOnly": "pnpm test && pnpm build",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.27.1",
+    "undici": "7.24.4",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "25.5.0",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
+    "vitest": "4.1.0"
+  }
+}