get_issue_by_id

Instructions

Implementation Reference

• src/services/mantisApi.ts:240-248 (handler)

  Core handler function that fetches the specific issue by ID from the Mantis API endpoint `/issues/${issueId}`, with logging and caching via cachedRequest.

  async getIssueById(issueId: number): Promise<Issue> {
    log.info('獲取問題詳情', { issueId });
    
    const cacheKey = `issue-${issueId}`;
    
    return this.cachedRequest<Issue>(cacheKey, () => {
      return this.api.get(`/issues/${issueId}`);
    });
  }

• src/server.ts:157-169 (registration)

  MCP tool registration using McpServer.tool, defining the tool name, description, input schema (issueId), and handler that wraps mantisApi.getIssueById with configuration check and JSON serialization.

  server.tool(
    "get_issue_by_id",
    "根據 ID 獲取 Mantis 問題詳情",
    {
      issueId: z.number().describe("問題 ID"),
    },
    async ({ issueId }) => {
      return withMantisConfigured("get_issue_by_id", async () => {
        const issue = await mantisApi.getIssueById(issueId);
        return JSON.stringify(issue, null, 2);
      });
    }
  );

• src/services/mantisApi.ts:5-41 (schema)

  TypeScript interface defining the structure of the Issue object returned by the getIssueById handler, serving as output schema.

  export interface Issue {
    id: number;
    summary: string;
    description: string;
    status: {
      id: number;
      name: string;
    };
    project: {
      id: number;
      name: string;
    };
    category: {
      id: number;
      name: string;
    };
    reporter: {
      id: number;
      name: string;
      email: string;
    };
    handler?: {
      id: number;
      name: string;
      email: string;
    };
    priority?: {
      id: number;
      name: string;
    };
    severity?: {
      id: number;
      name: string;
    };
    created_at: string;
    updated_at: string;
  }

• src/server.ts:160-162 (schema)

  Zod input schema for the tool, validating the issueId parameter.

  {
    issueId: z.number().describe("問題 ID"),
  },

• src/server.ts:22-101 (helper)

  Helper function used by all tools to check Mantis configuration, execute the core action, handle errors, and format MCP-compliant responses.

  async function withMantisConfigured<T>(
    toolName: string,
    action: () => Promise<T>
  ): Promise<{
    [x: string]: unknown;
    content: Array<{
      [x: string]: unknown;
      type: "text";
      text: string;
    }>;
    _meta?: { [key: string]: unknown } | undefined;
    isError?: boolean | undefined;
  }> {
    try {
      // 檢查是否已配置 Mantis API
      if (!isMantisConfigured()) {
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(
                {
                  error: "Mantis API 尚未配置",
                  message: "請在環境變數中設定 MANTIS_API_URL 和 MANTIS_API_KEY"
                },
                null,
                2
              ),
            },
          ],
          isError: true
        };
      }
  
      // 執行工具邏輯
      const result = await action();
      return {
        content: [
          {
            type: "text",
            text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
          },
        ],
      };
    } catch (error) {
      // 處理錯誤情況
      let errorMessage = `執行 ${toolName} 時發生錯誤`;
      let logData: LogData = { tool: toolName };
  
      if (error instanceof MantisApiError) {
        errorMessage = `Mantis API 錯誤: ${error.message}`;
        if (error.statusCode) {
          errorMessage += ` (HTTP ${error.statusCode})`;
          logData = { ...logData, statusCode: error.statusCode };
        }
        log.error(errorMessage, { ...logData, error: error.message });
      } else if (error instanceof Error) {
        errorMessage = error.message;
        log.error(errorMessage, { ...logData, error: error.stack });
      } else {
        log.error(errorMessage, { ...logData, error });
      }
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                error: errorMessage,
              },
              null,
              2
            ),
          },
        ],
        isError: true
      };
    }
  }