List Tracker Items

Instructions

Implementation Reference

• src/client/codebeamer-client.ts:256-289 (handler)

  The actual handler/implementation that calls the Codebeamer API to list tracker items. It first tries the /items/query endpoint with a cbQL filter, and if empty, falls back to /trackers/{trackerId}/items for debug information.

  async listTrackerItems(
    trackerId: number,
    page: number,
    pageSize: number,
  ): Promise<{ items: CbItem[]; debug?: string }> {
    const raw = await this.http.get<unknown>("/items/query", {
      params: { queryString: `tracker.id IN (${trackerId})`, page, pageSize },
      resource: `items for tracker ${trackerId}`,
    });
    const items = toArray<CbItem>(raw);
    if (items.length > 0) return { items };
  
    // Items empty — also try the direct endpoint so we can show raw debug info
    let rawDirect: unknown;
    try {
      rawDirect = await this.http.get<unknown>(`/trackers/${trackerId}/items`, {
        params: { page, pageSize },
        resource: `items for tracker ${trackerId} (direct)`,
      });
    } catch {
      rawDirect = null;
    }
    const rawObj = raw as Record<string, unknown> | null;
    const directObj = rawDirect as Record<string, unknown> | null;
    const queryTotal = rawObj?.["total"] ?? "?";
    const directTotal = directObj?.["total"] ?? "?";
    const directItems = toArray<CbItem>(rawDirect);
    const debug =
      `API vrátilo total=${queryTotal} pro cbQL query a total=${directTotal} pro přímý endpoint.\n` +
      `Pokud je total=0, Codebeamer říká že tam žádné itemy nejsou (špatný tracker ID, chybí oprávnění nebo prázdný tracker).\n` +
      `query: ${JSON.stringify(raw).slice(0, 300)}\n` +
      `direct: ${JSON.stringify(rawDirect).slice(0, 300)}`;
    return { items: directItems, debug };
  }

• src/tools/items.ts:48-84 (registration)

  The tool registration using server.registerTool() with the name 'list_tracker_items', input schema, and handler callback.

  server.registerTool(
    "list_tracker_items",
    {
      title: "List Tracker Items",
      description:
        "List all items in a specific Codebeamer tracker with pagination. " +
        "Returns a table with item IDs, summaries, statuses, and priorities.",
      inputSchema: {
        trackerId: z
          .number()
          .int()
          .positive()
          .describe("Numeric tracker ID"),
        page: z
          .number()
          .int()
          .min(1)
          .default(1)
          .describe("Page number (starts at 1)"),
        pageSize: z
          .number()
          .int()
          .min(1)
          .max(50)
          .default(25)
          .describe("Items per page (max 50)"),
      },
    },
    async ({ trackerId, page, pageSize }) => {
      const { items, debug } = await client.listTrackerItems(trackerId, page, pageSize);
      let text = formatItemList(items);
      if (items.length === 0 && debug) {
        text += `\n\n---\n**Debug (raw API responses):**\n\`\`\`\n${debug}\n\`\`\``;
      }
      return { content: [{ type: "text", text }] };
    },
  );

• src/tools/items.ts:55-74 (schema)

  Input schema for list_tracker_items: trackerId (positive int), page (min 1, default 1), pageSize (min 1, max 50, default 25). All defined using Zod.

  inputSchema: {
    trackerId: z
      .number()
      .int()
      .positive()
      .describe("Numeric tracker ID"),
    page: z
      .number()
      .int()
      .min(1)
      .default(1)
      .describe("Page number (starts at 1)"),
    pageSize: z
      .number()
      .int()
      .min(1)
      .max(50)
      .default(25)
      .describe("Items per page (max 50)"),
  },

• src/client/codebeamer-client.ts:186-202 (helper)

  toArray helper used by listTrackerItems to normalize API responses (handles both arrays and paginated objects with 'items' or 'itemRefs' keys).

  function toArray<T>(response: unknown): T[] {
    if (Array.isArray(response)) return response as T[];
    if (response && typeof response === "object") {
      const obj = response as Record<string, unknown>;
      if (Array.isArray(obj["items"])) return obj["items"] as T[];
      if (Array.isArray(obj["itemRefs"])) return obj["itemRefs"] as T[];
      // Generic fallback: find first array-valued key
      for (const key of Object.keys(obj)) {
        if (Array.isArray(obj[key])) {
          console.error(`[codebeamer-mcp] Using response key "${key}" instead of "items"`);
          return obj[key] as T[];
        }
      }
      console.error("[codebeamer-mcp] No array found in response:", JSON.stringify(obj).slice(0, 300));
    }
    return [];
  }

• src/index.ts:38-40 (helper)

  Top-level registration entry point where registerItemTools is called at server startup.

  registerProjectTools(server, client);
  registerTrackerTools(server, client);
  registerItemTools(server, client);