codebeamer-mcp

Instructions

Implementation Reference

• src/client/codebeamer-client.ts:227-260 (handler)

  The actual implementation of `listTrackerItems` in the Codebeamer client.

  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)

  Registration of the `list_tracker_items` tool in the MCP server.

  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 }] };
    },
  );