aps_issues_get_comments

Instructions

Implementation Reference

• src/index.ts:1391-1416 (handler)

  The main handler function for the aps_issues_get_comments tool. It validates project_id and issue_id, converts the project ID format, builds optional query parameters (limit, offset, sort_by), calls the APS Issues API to GET comments, and returns the summarized result.

  // ── aps_issues_get_comments ─────────────────────────────────
  if (name === "aps_issues_get_comments") {
    const projectId = args.project_id as string;
    const issueId = args.issue_id as string;
    const e1 = validateIssuesProjectId(projectId);
    if (e1) return fail(e1);
    const e2 = validateIssueId(issueId);
    if (e2) return fail(e2);
  
    const pid = toIssuesProjectId(projectId);
    const region = args.region as string | undefined;
    const t = await token();
  
    const query: Record<string, string> = {};
    if (args.limit != null) query.limit = String(Math.min(Math.max(Number(args.limit) || 100, 1), 100));
    if (args.offset != null) query.offset = String(args.offset);
    if (args.sort_by) query.sortBy = args.sort_by as string;
  
    const raw = await apsDmRequest(
      "GET",
      `construction/issues/v1/projects/${pid}/issues/${issueId}/comments`,
      t,
      { query, headers: issuesHeaders(region) },
    );
    return json(summarizeComments(raw));
  }

• src/index.ts:715-752 (schema)

  The input schema definition for the aps_issues_get_comments tool. Defines required parameters (project_id, issue_id) and optional parameters (limit, offset, sort_by, region) with their types and descriptions.

  // 16 ── aps_issues_get_comments
  {
    name: "aps_issues_get_comments",
    description:
      "Get all comments for a specific issue. " +
      "Returns a compact list: comment id, body, author, date.",
    inputSchema: {
      type: "object" as const,
      properties: {
        project_id: {
          type: "string",
          description: "Project ID – accepts with or without 'b.' prefix.",
        },
        issue_id: {
          type: "string",
          description: "Issue UUID.",
        },
        limit: {
          type: "number",
          description: "Max comments to return. Optional.",
        },
        offset: {
          type: "number",
          description: "Pagination offset. Optional.",
        },
        sort_by: {
          type: "string",
          description: "Sort field (e.g. 'createdAt' or '-createdAt'). Optional.",
        },
        region: {
          type: "string",
          enum: ["US", "EMEA", "AUS", "CAN", "DEU", "IND", "JPN", "GBR"],
          description: "Data centre region. Defaults to US.",
        },
      },
      required: ["project_id", "issue_id"],
    },
  },

• src/index.ts:715-752 (registration)

  The tool is registered as entry #16 in the TOOLS array (lines 141-994). The server registers all tools via ListToolsRequestSchema at line 1588.

  // 16 ── aps_issues_get_comments
  {
    name: "aps_issues_get_comments",
    description:
      "Get all comments for a specific issue. " +
      "Returns a compact list: comment id, body, author, date.",
    inputSchema: {
      type: "object" as const,
      properties: {
        project_id: {
          type: "string",
          description: "Project ID – accepts with or without 'b.' prefix.",
        },
        issue_id: {
          type: "string",
          description: "Issue UUID.",
        },
        limit: {
          type: "number",
          description: "Max comments to return. Optional.",
        },
        offset: {
          type: "number",
          description: "Pagination offset. Optional.",
        },
        sort_by: {
          type: "string",
          description: "Sort field (e.g. 'createdAt' or '-createdAt'). Optional.",
        },
        region: {
          type: "string",
          enum: ["US", "EMEA", "AUS", "CAN", "DEU", "IND", "JPN", "GBR"],
          description: "Data centre region. Defaults to US.",
        },
      },
      required: ["project_id", "issue_id"],
    },
  },

• src/aps-issues-helpers.ts:201-220 (helper)

  The summarizeComments helper function that processes the raw API response for issue comments. It extracts pagination info and maps each comment to an IssueCommentSummary (id, body, createdBy, createdAt).

  /** Summarise issue comments response. */
  export function summarizeComments(raw: unknown): {
    pagination: { limit: number; offset: number; totalResults: number };
    comments: IssueCommentSummary[];
  } {
    const r = raw as Record<string, unknown> | undefined;
    const pagination = extractPagination(r);
    const results = Array.isArray(r?.results)
      ? (r!.results as Record<string, unknown>[])
      : [];
  
    const comments: IssueCommentSummary[] = results.map((c) => ({
      id: c.id as string,
      body: (c.body as string) ?? "",
      createdBy: (c.createdBy as string) ?? "",
      createdAt: (c.createdAt as string) ?? "",
    }));
  
    return { pagination, comments };
  }

• src/aps-issues-helpers.ts:48-53 (helper)

  The IssueCommentSummary type definition used by the summarizeComments helper.

  export interface IssueCommentSummary {
    id: string;
    body: string;
    createdBy: string;
    createdAt: string;
  }