sonarqube-issue-mcp 0.0.1

package/README.md

@@ -0,0 +1,246 @@
+# SonarQube Issue MCP
+
+基于 SonarQube Web API 的 MCP 服务。你只需要传入一个 SonarQube 项目 dashboard URL，它就会返回当前待处理的：
+
+- `Security` 问题
+- `Reliability` 问题
+- `Security Hotspots`
+
+## MCP 配置示例
+
+这是一个 `stdio` MCP server，不是终端交互式 CLI。
+
+- 正常使用方式是让 MCP 客户端拉起它
+- 手工执行命令只适合调试，不会直接返回 issue 列表
+- 运行环境需要 Node.js `>= 20`
+- 机器需要满足以下任一条件：能直连公司内网 SonarQube、已经连上 VPN，或已通过 `SONAR_HTTP_PROXY` 配置可用代理
+
+### 方式一：使用 `npx`
+
+适合：
+
+- 想直接接入，不想全局安装
+- 希望开箱即用
+- 可以接受首次启动会从 npm 拉包
+
+```json
+{
+  "mcpServers": {
+    "sonarqube-issue": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "sonarqube-issue-mcp@0.1.0"
+      ],
+      "env": {
+        "SONAR_TOKEN": "your_sonar_token",
+        "SONAR_HTTP_PROXY": "http://127.0.0.1:7890"
+      }
+    }
+  }
+}
+```
+
+说明：
+
+- 推荐固定版本，不要长期使用裸 `latest`
+- `SONAR_HTTP_PROXY` 是可选的，只在 SonarQube API 需要走代理时配置
+- `npx` 首次启动会更慢，也依赖 npm registry 可用性
+
+### 方式二：全局安装后的命令
+
+适合：
+
+- 长期稳定在本机使用
+- 希望启动更快
+- 想避免每次启动都解析 `npx`
+
+先安装：
+
+```bash
+npm install -g sonarqube-issue-mcp
+```
+
+再在 MCP 客户端中配置：
+
+```json
+{
+  "mcpServers": {
+    "sonarqube-issue": {
+      "command": "sonarqube-issue-mcp",
+      "env": {
+        "SONAR_TOKEN": "your_sonar_token",
+        "SONAR_HTTP_PROXY": "http://127.0.0.1:7890"
+      }
+    }
+  }
+}
+```
+
+### 方式三：本地源码构建后的 `node dist/index.js`
+
+适合：
+
+- 你正在本地开发这个项目
+- 想用本地修改后的代码直接接入 MCP 客户端
+
+```json
+{
+  "mcpServers": {
+    "sonarqube-issue": {
+      "command": "node",
+      "args": [
+        "/Users/zzy/Project/Personal/farm-mcp/sonarqube-mcp/dist/index.js"
+      ],
+      "env": {
+        "SONAR_TOKEN": "your_sonar_token",
+        "SONAR_HTTP_PROXY": "http://127.0.0.1:7890"
+      }
+    }
+  }
+}
+```
+
+说明：
+
+- 这里不要写 `pnpm start`
+- `stdio` 类型的 MCP 一旦有额外 `stdout` 输出，就会在握手阶段失败
+
+## 环境变量
+
+必须：
+
+- `SONAR_TOKEN`: SonarQube token
+
+可选：
+
+- `SONAR_REQUEST_TIMEOUT_MS`: SonarQube 请求超时，默认 `20000`
+- `SONAR_RETRY_COUNT`: 请求重试次数，默认 `2`
+- `SONAR_HTTP_PROXY`: SonarQube Web API 可选代理，例如 `http://127.0.0.1:7890`
+
+## 能力范围
+
+- 输入固定为 SonarQube 项目链接，例如：
+
+```text
+https://sonarqube-uat.894577.com/dashboard?id=cold-wallet-frontend-0313&codeScope=overall
+```
+
+- 自动解析：
+  - `origin`
+  - `projectKey(id)`
+  - `branch`
+  - `pullRequest`
+- 默认只返回当前待处理问题：
+  - Security = `VULNERABILITY + resolved=false`
+  - Reliability = `BUG + resolved=false`
+  - Security Hotspots = `status=TO_REVIEW`
+- 支持单条问题详情查询
+
+## MCP Tools
+
+### `sonarqube_get_project_findings`
+
+输入：
+
+```json
+{
+  "projectUrl": "https://sonarqube-uat.894577.com/dashboard?id=cold-wallet-frontend-0313&codeScope=overall",
+  "detailLevel": "standard"
+}
+```
+
+返回：
+
+- 项目元信息
+- 总数汇总
+- `securityIssues`
+- `reliabilityIssues`
+- `securityHotspots`
+
+### `sonarqube_get_finding_detail`
+
+输入：
+
+```json
+{
+  "projectUrl": "https://sonarqube-uat.894577.com/dashboard?id=cold-wallet-frontend-0313&codeScope=overall",
+  "kind": "issue",
+  "key": "ISSUE-KEY"
+}
+```
+
+返回：
+
+- 单条问题标准化详情
+- 规则说明
+- comment / changelog / flows
+- SonarQube 深链
+
+## 源码开发与调试
+
+源码开发额外要求：
+
+- `pnpm`
+
+安装依赖：
+
+```bash
+pnpm install
+```
+
+开发：
+
+```bash
+pnpm dev
+```
+
+构建：
+
+```bash
+pnpm build
+```
+
+运行：
+
+```bash
+SONAR_TOKEN=your_token pnpm start
+```
+
+如果 SonarQube API 需要走代理：
+
+```bash
+SONAR_TOKEN=your_token \
+SONAR_HTTP_PROXY=http://127.0.0.1:7890 \
+pnpm start
+```
+
+源码方式说明：
+
+- 这条命令只适合本地烟雾测试，确认服务能启动
+- 这是一个 `stdio` MCP server，不是终端交互式 CLI；手工执行后不会直接返回 issue 列表
+- 不要在 MCP 客户端配置里使用 `pnpm start`
+- 如果要接入本地源码，请在 MCP 客户端里直接执行 `node dist/index.js`
+- `SONAR_HTTP_PROXY` 只作用于 SonarQube Web API 主链路
+
+## 测试
+
+运行所有测试：
+
+```bash
+pnpm test
+```
+
+当前测试覆盖：
+
+- URL 解析
+- 配置校验
+- 503 索引错误映射
+- 项目问题聚合
+- 单条 issue / hotspot 详情查询
+
+## 设计说明
+
+- 主链路只走 SonarQube Web API，不依赖前端页面结构
+- 对缺失 `SONAR_TOKEN`、401/403/404、503 索引中状态都会明确报错
+- 不做多版本 SonarQube 向后兼容层

package/bin/sonarqube-issue-mcp.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+/**
+ * CLI 启动包装器。
+ *
+ * @remarks
+ * npm / pnpm / yarn 在安装 `bin` 命令时会直接执行这个文件。
+ * 这里保持最薄的一层，只负责转交到已构建的 MCP 服务入口。
+ */
+import "../dist/index.js";

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 运行期配置，统一由环境变量解析得到。
+ *
+ * @remarks
+ * 当前实现只保留 SonarQube Web API 主链路配置，不再维护浏览器兜底相关选项。
+ */
+export interface AppConfig {
+    /** SonarQube 用户 token。 */
+    sonarToken: string;
+    /** 单次 SonarQube API 请求超时时间，单位毫秒。 */
+    sonarRequestTimeoutMs: number;
+    /** 可重试请求的最大重试次数。 */
+    sonarRetryCount: number;
+    /** SonarQube Web API 可选代理。 */
+    sonarHttpProxy: string | null;
+}
+/**
+ * 从环境变量加载完整配置。
+ *
+ * @param env - 运行时环境变量对象，默认使用 `process.env`。
+ * @returns 经过校验和规范化后的应用配置。
+ *
+ * 这里会在启动时完成校验，避免把配置错误拖到真正处理请求时才暴露。
+ *
+ * @throws {SonarQubeMcpError}
+ * 当必填项缺失、数值非法或代理地址格式错误时抛出。
+ */
+export declare function loadConfig(env?: NodeJS.ProcessEnv): AppConfig;

package/dist/config.js

@@ -0,0 +1,90 @@
+import { SonarQubeMcpError } from "./errors.js";
+/**
+ * 从环境变量加载完整配置。
+ *
+ * @param env - 运行时环境变量对象，默认使用 `process.env`。
+ * @returns 经过校验和规范化后的应用配置。
+ *
+ * 这里会在启动时完成校验，避免把配置错误拖到真正处理请求时才暴露。
+ *
+ * @throws {SonarQubeMcpError}
+ * 当必填项缺失、数值非法或代理地址格式错误时抛出。
+ */
+export function loadConfig(env = process.env) {
+    const sonarToken = env.SONAR_TOKEN?.trim();
+    if (!sonarToken) {
+        throw new SonarQubeMcpError("CONFIG", "缺少 SONAR_TOKEN 环境变量，无法访问 SonarQube Web API。");
+    }
+    return {
+        sonarToken,
+        sonarRequestTimeoutMs: parsePositiveInteger(env.SONAR_REQUEST_TIMEOUT_MS, 20_000, "SONAR_REQUEST_TIMEOUT_MS"),
+        sonarRetryCount: parseNonNegativeInteger(env.SONAR_RETRY_COUNT, 2, "SONAR_RETRY_COUNT"),
+        sonarHttpProxy: parseOptionalProxyUrl(env.SONAR_HTTP_PROXY, "SONAR_HTTP_PROXY")
+    };
+}
+/**
+ * 解析正整数配置项。
+ *
+ * @param value - 原始环境变量值。
+ * @param fallback - 缺失时使用的默认值。
+ * @param key - 配置键名，用于错误提示。
+ * @returns 解析后的正整数。
+ * @throws {SonarQubeMcpError} 当值存在但不是正整数时抛出。
+ */
+function parsePositiveInteger(value, fallback, key) {
+    if (!value?.trim()) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new SonarQubeMcpError("CONFIG", `${key} 必须是正整数，当前值为 "${value}"。`);
+    }
+    return parsed;
+}
+/**
+ * 解析非负整数配置项。
+ *
+ * @param value - 原始环境变量值。
+ * @param fallback - 缺失时使用的默认值。
+ * @param key - 配置键名，用于错误提示。
+ * @returns 解析后的非负整数。
+ * @throws {SonarQubeMcpError} 当值存在但不是非负整数时抛出。
+ */
+function parseNonNegativeInteger(value, fallback, key) {
+    if (!value?.trim()) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new SonarQubeMcpError("CONFIG", `${key} 必须是非负整数，当前值为 "${value}"。`);
+    }
+    return parsed;
+}
+/**
+ * 校验可选代理地址，目前仅支持 http/https。
+ *
+ * @param value - 原始环境变量值。
+ * @param key - 配置键名，用于错误提示。
+ * @returns 规范化后的代理地址；如果未配置则返回 `null`。
+ * @throws {SonarQubeMcpError} 当代理地址不是合法的 http/https URL 时抛出。
+ */
+function parseOptionalProxyUrl(value, key) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return null;
+    }
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch (error) {
+        throw new SonarQubeMcpError("CONFIG", `${key} 不是合法 URL: "${trimmed}"。`, {
+            cause: error
+        });
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new SonarQubeMcpError("CONFIG", `${key} 目前只支持 http/https 代理，当前协议为 "${url.protocol}"。`);
+    }
+    return url.toString();
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAmBhD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,UAAU,GAAG,GAAG,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;IAC3C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,iBAAiB,CACzB,QAAQ,EACR,6CAA6C,CAC9C,CAAC;IACJ,CAAC;IAED,OAAO;QACL,UAAU;QACV,qBAAqB,EAAE,oBAAoB,CACzC,GAAG,CAAC,wBAAwB,EAC5B,MAAM,EACN,0BAA0B,CAC3B;QACD,eAAe,EAAE,uBAAuB,CACtC,GAAG,CAAC,iBAAiB,EACrB,CAAC,EACD,mBAAmB,CACpB;QACD,cAAc,EAAE,qBAAqB,CAAC,GAAG,CAAC,gBAAgB,EAAE,kBAAkB,CAAC;KAChF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,oBAAoB,CAC3B,KAAyB,EACzB,QAAgB,EAChB,GAAW;IAEX,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC;QACnB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,iBAAiB,CAAC,QAAQ,EAAE,GAAG,GAAG,iBAAiB,KAAK,IAAI,CAAC,CAAC;IAC1E,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,uBAAuB,CAC9B,KAAyB,EACzB,QAAgB,EAChB,GAAW;IAEX,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC;QACnB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,iBAAiB,CAAC,QAAQ,EAAE,GAAG,GAAG,kBAAkB,KAAK,IAAI,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,qBAAqB,CAC5B,KAAyB,EACzB,GAAW;IAEX,MAAM,OAAO,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,iBAAiB,CAAC,QAAQ,EAAE,GAAG,GAAG,eAAe,OAAO,IAAI,EAAE;YACtE,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IAED,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1D,MAAM,IAAI,iBAAiB,CACzB,QAAQ,EACR,GAAG,GAAG,+BAA+B,GAAG,CAAC,QAAQ,IAAI,CACtD,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AACxB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 统一错误码，便于 MCP 客户端按类别处理异常。
+ *
+ * @remarks
+ * 这些错误码覆盖配置、鉴权、网络、远端服务和输入校验等主要失败路径。
+ */
+export type SonarQubeMcpErrorCode = "CONFIG" | "VALIDATION" | "AUTH" | "FORBIDDEN" | "NOT_FOUND" | "INDEXING" | "REMOTE" | "NETWORK";
+/**
+ * MCP 内部统一错误对象。
+ *
+ * @remarks
+ * 所有底层异常最终都会被归一为这个类型，再转换成对用户可读的文本输出。
+ */
+export declare class SonarQubeMcpError extends Error {
+    readonly code: SonarQubeMcpErrorCode;
+    readonly status: number | null;
+    readonly details: unknown;
+    constructor(code: SonarQubeMcpErrorCode, message: string, options?: {
+        status?: number | null;
+        details?: unknown;
+        cause?: unknown;
+    });
+}
+/**
+ * 将任意异常收口为统一错误类型，避免上层反复判断。
+ *
+ * @param error - 原始异常对象。
+ * @returns 统一后的 `SonarQubeMcpError`。
+ */
+export declare function normalizeError(error: unknown): SonarQubeMcpError;
+/**
+ * 将统一错误渲染为 MCP 文本内容，方便客户端直接展示。
+ *
+ * @param error - 统一错误对象。
+ * @returns 适合在聊天窗口直接显示的多行文本。
+ */
+export declare function formatErrorForText(error: SonarQubeMcpError): string;

package/dist/errors.js

@@ -0,0 +1,67 @@
+/**
+ * MCP 内部统一错误对象。
+ *
+ * @remarks
+ * 所有底层异常最终都会被归一为这个类型，再转换成对用户可读的文本输出。
+ */
+export class SonarQubeMcpError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, message, options) {
+        super(message, options?.cause ? { cause: options.cause } : undefined);
+        this.name = "SonarQubeMcpError";
+        this.code = code;
+        this.status = options?.status ?? null;
+        this.details = options?.details ?? null;
+    }
+}
+/**
+ * 将任意异常收口为统一错误类型，避免上层反复判断。
+ *
+ * @param error - 原始异常对象。
+ * @returns 统一后的 `SonarQubeMcpError`。
+ */
+export function normalizeError(error) {
+    if (error instanceof SonarQubeMcpError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new SonarQubeMcpError("REMOTE", error.message, { cause: error });
+    }
+    return new SonarQubeMcpError("REMOTE", typeof error === "string" ? error : "发生了未知错误", { details: error });
+}
+/**
+ * 将统一错误渲染为 MCP 文本内容，方便客户端直接展示。
+ *
+ * @param error - 统一错误对象。
+ * @returns 适合在聊天窗口直接显示的多行文本。
+ */
+export function formatErrorForText(error) {
+    const lines = [
+        `错误代码: ${error.code}`,
+        `错误信息: ${error.message}`
+    ];
+    if (error.status !== null) {
+        lines.push(`HTTP 状态: ${error.status}`);
+    }
+    if (error.details !== null) {
+        lines.push(`错误详情: ${safeJson(error.details)}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * 错误详情可能包含循环引用，这里做一个安全序列化兜底。
+ *
+ * @param value - 需要输出的详情对象。
+ * @returns 可安全展示的字符串。
+ */
+function safeJson(value) {
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAgBA;;;;;GAKG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,IAAI,CAAwB;IAC5B,MAAM,CAAgB;IACtB,OAAO,CAAU;IAE1B,YACE,IAA2B,EAC3B,OAAe,EACf,OAIC;QAED,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACtE,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,IAAI,CAAC;QACtC,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC;IAC1C,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,YAAY,iBAAiB,EAAE,CAAC;QACvC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,IAAI,iBAAiB,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,OAAO,IAAI,iBAAiB,CAC1B,QAAQ,EACR,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,EAC7C,EAAE,OAAO,EAAE,KAAK,EAAE,CACnB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAwB;IACzD,MAAM,KAAK,GAAG;QACZ,SAAS,KAAK,CAAC,IAAI,EAAE;QACrB,SAAS,KAAK,CAAC,OAAO,EAAE;KACzB,CAAC;IAEF,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,YAAY,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,SAAS,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,36 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { createServer } from "./server.js";
+/**
+ * 进程入口：加载配置、挂接 stdio transport，并处理优雅退出。
+ *
+ * @returns 启动完成后的异步流程。
+ * @throws {SonarQubeMcpError | Error} 当配置或服务器初始化失败时抛出。
+ */
+async function main() {
+    const config = loadConfig();
+    const { server } = createServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    /**
+     * 统一资源清理逻辑。
+     *
+     * @remarks
+     * 当前仅需关闭 MCP 服务本身。
+     */
+    const cleanup = async () => {
+        await server.close();
+    };
+    process.on("SIGINT", () => {
+        void cleanup().finally(() => process.exit(0));
+    });
+    process.on("SIGTERM", () => {
+        void cleanup().finally(() => process.exit(0));
+    });
+    console.error("SonarQube Issue MCP server is running on stdio");
+}
+main().catch((error) => {
+    console.error("Failed to start SonarQube Issue MCP server:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;GAKG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,EAAE,MAAM,EAAE,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAExC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC;;;;;OAKG;IACH,MAAM,OAAO,GAAG,KAAK,IAAmB,EAAE;QACxC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;QACxB,KAAK,OAAO,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;QACzB,KAAK,OAAO,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,OAAO,CAAC,KAAK,CAAC,gDAAgD,CAAC,CAAC;AAClE,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,6CAA6C,EAAE,KAAK,CAAC,CAAC;IACpE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/project-ref.d.ts

@@ -0,0 +1,44 @@
+import type { ProjectRef } from "./types.js";
+/**
+ * 从 SonarQube dashboard URL 提取项目定位信息。
+ *
+ * @param projectUrl - 用户传入的 SonarQube 项目链接。
+ * @returns 规范化后的项目上下文。
+ *
+ * 这是整个 MCP 的唯一输入入口，因此这里会做严格校验，确保后续 API 请求有稳定上下文。
+ *
+ * @throws {SonarQubeMcpError}
+ * 当 URL 非法、协议不支持、路径不支持或缺少 `id` 参数时抛出。
+ */
+export declare function parseProjectUrl(projectUrl: string): ProjectRef;
+/**
+ * 将 branch / pullRequest 上下文透传到任意 SonarQube API 查询参数中。
+ *
+ * @param searchParams - 已有查询参数。
+ * @param projectRef - 解析后的项目上下文。
+ * @returns 追加了分支/PR 上下文的新查询参数对象。
+ */
+export declare function withProjectContext(searchParams: URLSearchParams, projectRef: ProjectRef): URLSearchParams;
+/**
+ * 构造项目级 SonarQube 浏览深链。
+ *
+ * @param projectRef - 解析后的项目上下文。
+ * @returns 指向项目 dashboard 的可点击链接。
+ */
+export declare function buildProjectBrowseUrl(projectRef: ProjectRef): string;
+/**
+ * 构造单条 issue 的 SonarQube 页面深链。
+ *
+ * @param projectRef - 解析后的项目上下文。
+ * @param issueKey - SonarQube issue key。
+ * @returns 指向 issue 详情面板的可点击链接。
+ */
+export declare function buildIssueBrowseUrl(projectRef: ProjectRef, issueKey: string): string;
+/**
+ * 构造单条 security hotspot 的 SonarQube 页面深链。
+ *
+ * @param projectRef - 解析后的项目上下文。
+ * @param hotspotKey - SonarQube hotspot key。
+ * @returns 指向 hotspot 详情面板的可点击链接。
+ */
+export declare function buildHotspotBrowseUrl(projectRef: ProjectRef, hotspotKey: string): string;