Search Items (cbQL)

Instructions

Implementation Reference

• src/tools/items.ts:42-45 (handler)

  The handler function for the search_items tool. It calls client.searchItems(query, page, pageSize) and formats the result using formatItemList.

  async ({ query, page, pageSize }) => {
    const result = await client.searchItems(query, page, pageSize);
    return { content: [{ type: "text", text: formatItemList(result) }] };
  },

• src/tools/items.ts:15-40 (schema)

  Input schema (Zod) for the search_items tool: query (string), page (int, min 1, default 1), pageSize (int, min 1, max 50, default 25).

  {
    title: "Search Items (cbQL)",
    description:
      "Search Codebeamer items using cbQL query language. " +
      "Examples: " +
      "'tracker.id IN (42) AND status.name = \"Open\"', " +
      "'summary LIKE \"login bug\"', " +
      "'priority.name = \"High\" AND assignedTo.name = \"john.doe\"', " +
      "'project.id IN (1) AND modifiedAt >= -1w'. " +
      "Use get_tracker to see available fields for a tracker.",
    inputSchema: {
      query: z.string().describe("cbQL query string"),
      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/tools/items.ts:13-46 (registration)

  Registration of the search_items tool via server.registerTool(). Called from registerItemTools() which is invoked in src/index.ts.

  server.registerTool(
    "search_items",
    {
      title: "Search Items (cbQL)",
      description:
        "Search Codebeamer items using cbQL query language. " +
        "Examples: " +
        "'tracker.id IN (42) AND status.name = \"Open\"', " +
        "'summary LIKE \"login bug\"', " +
        "'priority.name = \"High\" AND assignedTo.name = \"john.doe\"', " +
        "'project.id IN (1) AND modifiedAt >= -1w'. " +
        "Use get_tracker to see available fields for a tracker.",
      inputSchema: {
        query: z.string().describe("cbQL query string"),
        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 ({ query, page, pageSize }) => {
      const result = await client.searchItems(query, page, pageSize);
      return { content: [{ type: "text", text: formatItemList(result) }] };
    },
  );

• src/client/codebeamer-client.ts:291-301 (helper)

  The client.searchItems() method that performs the actual HTTP GET request to /items/query with queryString, page, pageSize params.

  async searchItems(
    queryString: string,
    page: number,
    pageSize: number,
  ): Promise<CbItem[]> {
    const raw = await this.http.get<unknown>("/items/query", {
      params: { queryString, page, pageSize },
      resource: "item query",
    });
    return toArray(raw);
  }

• src/index.ts:40-40 (registration)

  Invocation of registerItemTools(server, client) in the main entry point, which triggers registration of all item tools including search_items.

  registerItemTools(server, client);