zentao-mcp 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# zentao-mcp
+
+ZenTao 18.13 的只读 MCP 服务骨架（TypeScript）。
+
+## 功能
+- MCP Server（stdio）
+- 10 个工具：
+  - `zentao_health_check`
+  - `zentao_list_projects`
+  - `zentao_get_project`
+  - `zentao_list_executions`
+  - `zentao_list_stories`
+  - `zentao_get_story`
+  - `zentao_list_tasks`
+  - `zentao_get_task`
+  - `zentao_list_bugs`
+  - `zentao_get_bug`
+- `ZenTaoAuthClient`（Token 获取与缓存）
+- `ZenTaoApiClient`（端点封装、鉴权重试、错误映射）
+
+## 快速开始
+1. 复制配置文件：
+   - `.env.example` -> `.env`
+2. 安装依赖：
+   - `npm install`
+3. 类型检查：
+   - `npm run check`
+4. 运行测试：
+   - `npm run test`
+5. 构建：
+   - `npm run build`
+6. 启动（stdio）：
+   - `npm start`
+
+## Codex CLI 一段配置即用
+如果你已经把包发布到 npm（比如 `zentao-mcp`），同事只需在 `~/.codex/config.toml` 增加：
+
+```toml
+[mcp_servers.zentao]
+command = "npx"
+args = ["-y", "zentao-mcp"]
+env = {
+  ZENTAO_BASE_URL = "https://zentao.example.com",
+  ZENTAO_ACCOUNT = "your_account",
+  ZENTAO_PASSWORD = "your_password"
+}
+startup_timeout_sec = 60.0
+tool_timeout_sec = 60.0
+```
+
+然后重启 Codex CLI，即可直接自然语言使用，无需手动运行 `npm start`。
+
+## 发布与分发
+- 本地打包：`npm run pack:local`（会产出 `.tgz`）
+- 发布前构建：`npm run prepack`
+- 发布到 npm：`npm publish`（需先登录 npm）
+- 详细发布流程见：[docs/PUBLISH.md](./docs/PUBLISH.md)
+
+## 环境变量
+- `ZENTAO_BASE_URL`
+- `ZENTAO_ACCOUNT`
+- `ZENTAO_PASSWORD`
+- `ZENTAO_TIMEOUT_MS`（默认 `10000`）
+- `ZENTAO_TOKEN_TTL_MS`（默认 `3000000`）
+- `MCP_DEFAULT_PAGE`（默认 `1`）
+- `MCP_DEFAULT_LIMIT`（默认 `20`）
+- `MCP_MAX_LIMIT`（默认 `100`）
+
+## 多用户账号方式
+- 默认方式：使用进程环境变量（`.env`）作为账号配置。
+- 个人覆盖方式：每次工具调用可传入 `baseUrl/account/password`，优先级高于 `.env`。
+- 覆盖参数必须同时提供 3 个字段，缺失任一项会返回 `INVALID_ARGUMENT`。
+
+## 说明
+- 当前是首版骨架，4 类核心对象已包含字段标准化映射，并保留 `raw` 原始响应。
+- 测试覆盖了参数校验、scope 路由和错误码映射等关键路径。

package/dist/domain/errors.js

@@ -0,0 +1,21 @@
+export class ZenTaoApiError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, message, status, details) {
+        super(message);
+        this.name = "ZenTaoApiError";
+        this.code = code;
+        this.status = status;
+        this.details = details;
+    }
+}
+export function toErrorCode(status) {
+    if (status === 401)
+        return "AUTH_FAILED";
+    if (status === 403)
+        return "PERMISSION_DENIED";
+    if (status === 408 || status === 504)
+        return "UPSTREAM_TIMEOUT";
+    return "UPSTREAM_ERROR";
+}

package/dist/domain/mappers.js

@@ -0,0 +1,219 @@
+function asObject(input) {
+    return input && typeof input === "object" ? input : undefined;
+}
+function asString(input) {
+    if (input === undefined || input === null)
+        return undefined;
+    if (typeof input === "object" || typeof input === "function" || typeof input === "symbol") {
+        return undefined;
+    }
+    const value = String(input).trim();
+    return value || undefined;
+}
+function asNumber(input) {
+    if (input === undefined || input === null || input === "")
+        return undefined;
+    const value = Number(input);
+    return Number.isFinite(value) ? value : undefined;
+}
+function asId(input) {
+    const value = asNumber(input);
+    return value ?? 0;
+}
+function pickString(source, ...keys) {
+    for (const key of keys) {
+        const value = asString(source[key]);
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
+function pickNumber(source, ...keys) {
+    for (const key of keys) {
+        const value = asNumber(source[key]);
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
+function asUserText(input) {
+    if (input === undefined || input === null)
+        return undefined;
+    if (Array.isArray(input)) {
+        const values = input.map((item) => asUserText(item)).filter(Boolean);
+        return values.length > 0 ? values.join(",") : undefined;
+    }
+    const objectValue = asObject(input);
+    if (!objectValue)
+        return asString(input);
+    return (pickString(objectValue, "account", "realname", "name", "username") ??
+        asString(objectValue.id));
+}
+function pickUserText(source, ...keys) {
+    for (const key of keys) {
+        const value = asUserText(source[key]);
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
+function unwrap(payload) {
+    const root = asObject(payload);
+    if (!root)
+        return payload;
+    if (root.data !== undefined)
+        return root.data;
+    return root;
+}
+function extractTotal(payload) {
+    const root = asObject(payload);
+    if (!root)
+        return undefined;
+    const unwrapped = asObject(unwrap(payload));
+    return (pickNumber(root, "total") ??
+        pickNumber(asObject(root.pager) ?? {}, "recTotal") ??
+        pickNumber(asObject(root.meta) ?? {}, "total") ??
+        pickNumber(unwrapped ?? {}, "total") ??
+        pickNumber(asObject(unwrapped?.pager) ?? {}, "recTotal") ??
+        pickNumber(asObject(unwrapped?.meta) ?? {}, "total"));
+}
+function extractListData(payload, preferredKeys) {
+    const root = unwrap(payload);
+    if (Array.isArray(root))
+        return root.map((item) => asObject(item)).filter(Boolean);
+    const record = asObject(root);
+    if (!record)
+        return [];
+    for (const key of preferredKeys) {
+        const value = record[key];
+        if (Array.isArray(value)) {
+            return value.map((item) => asObject(item)).filter(Boolean);
+        }
+        const mapLike = asObject(value);
+        if (mapLike)
+            return Object.values(mapLike).map((item) => asObject(item)).filter(Boolean);
+    }
+    for (const value of Object.values(record)) {
+        if (Array.isArray(value)) {
+            return value.map((item) => asObject(item)).filter(Boolean);
+        }
+    }
+    const values = Object.values(record);
+    if (values.length > 0 && values.every((value) => asObject(value))) {
+        return values.map((value) => value);
+    }
+    return [];
+}
+function extractDetailData(payload, preferredKeys) {
+    const root = unwrap(payload);
+    const record = asObject(root);
+    if (!record) {
+        if (Array.isArray(root) && root.length > 0)
+            return asObject(root[0]);
+        return undefined;
+    }
+    for (const key of preferredKeys) {
+        const value = record[key];
+        const detail = asObject(value);
+        if (detail)
+            return detail;
+        if (Array.isArray(value) && value.length > 0) {
+            const first = asObject(value[0]);
+            if (first)
+                return first;
+        }
+    }
+    return record;
+}
+function mapProject(source) {
+    return {
+        id: asId(source.id),
+        name: pickString(source, "name", "title") ?? "",
+        status: pickString(source, "status"),
+        startDate: pickString(source, "begin", "start", "startDate"),
+        endDate: pickString(source, "end", "endDate"),
+        owner: pickUserText(source, "PM", "pm", "owner"),
+    };
+}
+function mapStory(source) {
+    return {
+        id: asId(source.id),
+        title: pickString(source, "title", "name") ?? "",
+        status: pickString(source, "status"),
+        stage: pickString(source, "stage"),
+        priority: pickString(source, "pri", "priority"),
+        openedBy: pickUserText(source, "openedBy"),
+        assignedTo: pickUserText(source, "assignedTo"),
+    };
+}
+function mapTask(source) {
+    return {
+        id: asId(source.id),
+        title: pickString(source, "name", "title") ?? "",
+        status: pickString(source, "status"),
+        priority: pickString(source, "pri", "priority"),
+        assignedTo: pickUserText(source, "assignedTo"),
+        deadline: pickString(source, "deadline"),
+        estimateHours: pickNumber(source, "estimate"),
+        consumedHours: pickNumber(source, "consumed"),
+    };
+}
+function mapBug(source) {
+    return {
+        id: asId(source.id),
+        title: pickString(source, "title", "name") ?? "",
+        status: pickString(source, "status"),
+        severity: pickString(source, "severity"),
+        priority: pickString(source, "pri", "priority"),
+        openedBy: pickUserText(source, "openedBy"),
+        assignedTo: pickUserText(source, "assignedTo"),
+        resolvedBy: pickUserText(source, "resolvedBy"),
+    };
+}
+function mapExecution(source) {
+    return {
+        id: asId(source.id),
+        name: pickString(source, "name", "title") ?? "",
+        status: pickString(source, "status"),
+        startDate: pickString(source, "begin", "start", "startDate"),
+        endDate: pickString(source, "end", "endDate"),
+        projectId: pickNumber(source, "project", "projectId"),
+        owner: pickUserText(source, "PM", "owner"),
+    };
+}
+export function mapProjectList(payload) {
+    const items = extractListData(payload, ["projects", "projectList"]).map(mapProject);
+    return { items, total: extractTotal(payload) ?? items.length, raw: payload };
+}
+export function mapProjectDetail(payload) {
+    const detail = extractDetailData(payload, ["project", "projects"]);
+    return { item: detail ? mapProject(detail) : null, raw: payload };
+}
+export function mapStoryList(payload) {
+    const items = extractListData(payload, ["stories", "storyList"]).map(mapStory);
+    return { items, total: extractTotal(payload) ?? items.length, raw: payload };
+}
+export function mapStoryDetail(payload) {
+    const detail = extractDetailData(payload, ["story", "stories"]);
+    return { item: detail ? mapStory(detail) : null, raw: payload };
+}
+export function mapTaskList(payload) {
+    const items = extractListData(payload, ["tasks", "taskList"]).map(mapTask);
+    return { items, total: extractTotal(payload) ?? items.length, raw: payload };
+}
+export function mapTaskDetail(payload) {
+    const detail = extractDetailData(payload, ["task", "tasks"]);
+    return { item: detail ? mapTask(detail) : null, raw: payload };
+}
+export function mapBugList(payload) {
+    const items = extractListData(payload, ["bugs", "bugList"]).map(mapBug);
+    return { items, total: extractTotal(payload) ?? items.length, raw: payload };
+}
+export function mapBugDetail(payload) {
+    const detail = extractDetailData(payload, ["bug", "bugs"]);
+    return { item: detail ? mapBug(detail) : null, raw: payload };
+}
+export function mapExecutionList(payload) {
+    const items = extractListData(payload, ["executions", "executionList"]).map(mapExecution);
+    return { items, total: extractTotal(payload) ?? items.length, raw: payload };
+}

package/dist/domain/models.js

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

package/dist/domain/types.js

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

package/dist/index.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { createMcpServer } from "./server/mcpServer.js";
+async function main() {
+    const server = createMcpServer();
+    await server.start();
+}
+main().catch((error) => {
+    // eslint-disable-next-line no-console
+    console.error("[fatal] zentao-mcp failed to start:", error);
+    process.exit(1);
+});

package/dist/infra/config.js

@@ -0,0 +1,23 @@
+function readEnv(name) {
+    const value = process.env[name];
+    return value?.trim() ? value.trim() : undefined;
+}
+function readNumberEnv(name, fallback) {
+    const value = readEnv(name);
+    if (!value)
+        return fallback;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+export function loadConfig() {
+    return {
+        zentaoBaseUrl: readEnv("ZENTAO_BASE_URL") ?? "",
+        zentaoAccount: readEnv("ZENTAO_ACCOUNT") ?? "",
+        zentaoPassword: readEnv("ZENTAO_PASSWORD") ?? "",
+        zentaoTimeoutMs: readNumberEnv("ZENTAO_TIMEOUT_MS", 10_000),
+        zentaoTokenTtlMs: readNumberEnv("ZENTAO_TOKEN_TTL_MS", 3_000_000),
+        defaultPage: readNumberEnv("MCP_DEFAULT_PAGE", 1),
+        defaultLimit: readNumberEnv("MCP_DEFAULT_LIMIT", 20),
+        maxLimit: readNumberEnv("MCP_MAX_LIMIT", 100),
+    };
+}

package/dist/infra/logger.js

@@ -0,0 +1,15 @@
+function log(level, message, context) {
+    const payload = {
+        ts: new Date().toISOString(),
+        level,
+        message,
+        ...(context ?? {}),
+    };
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(payload));
+}
+export const logger = {
+    info: (message, context) => log("info", message, context),
+    warn: (message, context) => log("warn", message, context),
+    error: (message, context) => log("error", message, context),
+};

package/dist/infra/result.js

@@ -0,0 +1,22 @@
+export function buildRequestId() {
+    return `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+export function okResult(data, requestId, page, limit, total) {
+    return {
+        ok: true,
+        data,
+        meta: { requestId, page, limit, total },
+    };
+}
+export function errResult(code, message, requestId, details) {
+    return {
+        ok: false,
+        data: null,
+        meta: { requestId },
+        error: {
+            code,
+            message,
+            details,
+        },
+    };
+}

package/dist/server/authOverride.js

@@ -0,0 +1,43 @@
+import { ZenTaoApiError } from "../domain/errors.js";
+import { ZenTaoApiClient } from "../zentao/apiClient.js";
+import { ZenTaoAuthClient } from "../zentao/authClient.js";
+function readOptionalString(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = String(value).trim();
+    return text || undefined;
+}
+export function resolveAuthOverride(args) {
+    const baseUrl = readOptionalString(args.baseUrl);
+    const account = readOptionalString(args.account);
+    const password = readOptionalString(args.password);
+    const hasAny = Boolean(baseUrl || account || password);
+    if (!hasAny)
+        return null;
+    if (!baseUrl || !account || !password) {
+        throw new ZenTaoApiError("INVALID_ARGUMENT", "若使用个人账号，请同时提供 baseUrl/account/password");
+    }
+    return { baseUrl, account, password };
+}
+export function createApiClientResolver(defaultClient, config) {
+    const cache = new Map();
+    return (args) => {
+        const override = resolveAuthOverride(args);
+        if (!override)
+            return defaultClient;
+        const key = `${override.baseUrl}::${override.account}::${override.password}`;
+        const cached = cache.get(key);
+        if (cached)
+            return cached;
+        const authClient = new ZenTaoAuthClient({
+            baseUrl: override.baseUrl,
+            account: override.account,
+            password: override.password,
+            timeoutMs: config.zentaoTimeoutMs,
+            tokenTtlMs: config.zentaoTokenTtlMs,
+        });
+        const apiClient = new ZenTaoApiClient(override.baseUrl, config.zentaoTimeoutMs, authClient);
+        cache.set(key, apiClient);
+        return apiClient;
+    };
+}

package/dist/server/mcpServer.js

@@ -0,0 +1,40 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { loadConfig } from "../infra/config.js";
+import { logger } from "../infra/logger.js";
+import { ToolRegistry } from "./toolRegistry.js";
+import { ZenTaoApiClient } from "../zentao/apiClient.js";
+import { ZenTaoAuthClient } from "../zentao/authClient.js";
+import { executeCallTool, listToolsResult } from "./toolRuntime.js";
+import { createApiClientResolver } from "./authOverride.js";
+export function createMcpServer() {
+    const config = loadConfig();
+    const authClient = new ZenTaoAuthClient({
+        baseUrl: config.zentaoBaseUrl,
+        account: config.zentaoAccount,
+        password: config.zentaoPassword,
+        timeoutMs: config.zentaoTimeoutMs,
+        tokenTtlMs: config.zentaoTokenTtlMs,
+    });
+    const apiClient = new ZenTaoApiClient(config.zentaoBaseUrl, config.zentaoTimeoutMs, authClient);
+    const getApiClientForArgs = createApiClientResolver(apiClient, config);
+    const registry = new ToolRegistry({ apiClient, getApiClientForArgs, config });
+    const server = new Server({ name: "zentao-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => listToolsResult(registry));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const name = request.params.name;
+        const args = (request.params.arguments ?? {});
+        return executeCallTool(registry, name, args);
+    });
+    return {
+        start: async () => {
+            const transport = new StdioServerTransport();
+            await server.connect(transport);
+            logger.info("zentao_mcp_server_started", {
+                version: "0.1.0",
+                hasBaseUrl: Boolean(config.zentaoBaseUrl),
+            });
+        },
+    };
+}

package/dist/server/toolRegistry.js

@@ -0,0 +1,28 @@
+import { createBugTools } from "../tools/bugs.js";
+import { createExecutionTools } from "../tools/executions.js";
+import { createHealthCheckTool } from "../tools/healthCheck.js";
+import { createProjectTools } from "../tools/projects.js";
+import { createStoryTools } from "../tools/stories.js";
+import { createTaskTools } from "../tools/tasks.js";
+export class ToolRegistry {
+    tools = new Map();
+    constructor(context) {
+        const definitions = [
+            createHealthCheckTool(context),
+            ...createProjectTools(context),
+            ...createExecutionTools(context),
+            ...createStoryTools(context),
+            ...createTaskTools(context),
+            ...createBugTools(context),
+        ];
+        for (const tool of definitions) {
+            this.tools.set(tool.name, tool);
+        }
+    }
+    listTools() {
+        return [...this.tools.values()];
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+}

package/dist/server/toolRuntime.js

@@ -0,0 +1,46 @@
+import { ZenTaoApiError } from "../domain/errors.js";
+import { errResult } from "../infra/result.js";
+import { logger } from "../infra/logger.js";
+export function listToolsResult(registry) {
+    return {
+        tools: registry.listTools().map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        })),
+    };
+}
+export async function executeCallTool(registry, name, args) {
+    const tool = registry.get(name);
+    if (!tool) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(errResult("INVALID_ARGUMENT", `未知工具: ${name}`, `tool_${Date.now()}`), null, 2),
+                },
+            ],
+        };
+    }
+    logger.info("tool_call_started", { toolName: name });
+    try {
+        const result = await tool.handler(args);
+        logger.info("tool_call_finished", { toolName: name, ok: result.ok });
+        return {
+            isError: !result.ok,
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (error) {
+        const requestId = `tool_${Date.now()}`;
+        const result = error instanceof ZenTaoApiError
+            ? errResult(error.code, error.message, requestId, error.details)
+            : errResult("UPSTREAM_ERROR", "工具执行失败", requestId, { reason: String(error) });
+        logger.error("tool_call_failed", { toolName: name, reason: String(error) });
+        return {
+            isError: true,
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+}

package/dist/tools/bugs.js

@@ -0,0 +1,121 @@
+import { ZenTaoApiError } from "../domain/errors.js";
+import { mapBugDetail, mapBugList } from "../domain/mappers.js";
+import { errResult, okResult } from "../infra/result.js";
+import { postProcessList } from "./listPostProcess.js";
+import { asRecord, authInputSchemaProperties, readEnum, readPagination, readPositiveInt, readSortOrder, readString, } from "./common.js";
+export function createBugTools(context) {
+    return [createListBugsTool(context), createGetBugTool(context)];
+}
+function createListBugsTool(context) {
+    return {
+        name: "zentao_list_bugs",
+        description: "查询 Bug 列表（scope=product|project，占位版）",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...authInputSchemaProperties,
+                scope: { type: "string", enum: ["product", "project"] },
+                scopeId: { type: "integer", minimum: 1 },
+                page: { type: "integer", minimum: 1, default: 1 },
+                limit: { type: "integer", minimum: 1, maximum: 100, default: 20 },
+                status: { type: "string" },
+                severity: { type: "string" },
+                assignedTo: { type: "string" },
+                keyword: { type: "string" },
+                sortBy: {
+                    type: "string",
+                    enum: ["id", "title", "status", "severity", "priority", "assignedTo", "openedBy", "resolvedBy"],
+                },
+                sortOrder: { type: "string", enum: ["asc", "desc"], default: "asc" },
+            },
+            required: ["scope", "scopeId"],
+            additionalProperties: false,
+        },
+        handler: async (rawArgs) => {
+            const requestId = `bugs_${Date.now()}`;
+            const args = asRecord(rawArgs);
+            const { page, limit } = readPagination(args, context.config.defaultPage, context.config.defaultLimit, context.config.maxLimit);
+            try {
+                const apiClient = context.getApiClientForArgs(args);
+                const scope = readEnum(args, "scope", ["product", "project"]);
+                if (!scope)
+                    throw new ZenTaoApiError("INVALID_ARGUMENT", "参数 scope 不能为空");
+                const scopeId = readPositiveInt(args, "scopeId", true);
+                const payload = await apiClient.listBugs(scope, scopeId, {
+                    page,
+                    limit,
+                    status: readString(args, "status"),
+                    severity: readString(args, "severity"),
+                    assignedTo: readString(args, "assignedTo"),
+                    keyword: readString(args, "keyword"),
+                });
+                const mapped = mapBugList(payload);
+                const filteredItems = postProcessList({
+                    items: mapped.items,
+                    keyword: readString(args, "keyword"),
+                    keywordSelector: (item) => [item.title],
+                    equalsFilters: [
+                        { value: readString(args, "status"), selector: (item) => item.status },
+                        { value: readString(args, "severity"), selector: (item) => item.severity },
+                        { value: readString(args, "assignedTo"), selector: (item) => item.assignedTo },
+                    ],
+                    sortBy: readString(args, "sortBy"),
+                    sortOrder: readSortOrder(args) ?? "asc",
+                    sortSelectors: {
+                        id: (item) => item.id,
+                        title: (item) => item.title,
+                        status: (item) => item.status,
+                        severity: (item) => item.severity,
+                        priority: (item) => item.priority,
+                        assignedTo: (item) => item.assignedTo,
+                        openedBy: (item) => item.openedBy,
+                        resolvedBy: (item) => item.resolvedBy,
+                    },
+                });
+                const normalized = {
+                    ...mapped,
+                    items: filteredItems,
+                    filteredTotal: filteredItems.length,
+                };
+                return okResult(normalized, requestId, page, limit, mapped.total ?? filteredItems.length);
+            }
+            catch (error) {
+                if (error instanceof ZenTaoApiError) {
+                    return errResult(error.code, error.message, requestId, error.details);
+                }
+                return errResult("UPSTREAM_ERROR", "查询 Bug 列表失败", requestId, { reason: String(error) });
+            }
+        },
+    };
+}
+function createGetBugTool(context) {
+    return {
+        name: "zentao_get_bug",
+        description: "按 Bug ID 获取 Bug 详情（占位版）",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...authInputSchemaProperties,
+                bugId: { type: "integer", minimum: 1 },
+            },
+            required: ["bugId"],
+            additionalProperties: false,
+        },
+        handler: async (rawArgs) => {
+            const requestId = `bug_${Date.now()}`;
+            const args = asRecord(rawArgs);
+            try {
+                const apiClient = context.getApiClientForArgs(args);
+                const bugId = readPositiveInt(args, "bugId", true);
+                const payload = await apiClient.getBug(bugId);
+                return okResult(mapBugDetail(payload), requestId);
+            }
+            catch (error) {
+                if (error instanceof ZenTaoApiError) {
+                    return errResult(error.code, error.message, requestId, error.details);
+                }
+                return errResult("UPSTREAM_ERROR", "查询 Bug 详情失败", requestId, { reason: String(error) });
+            }
+        },
+    };
+}