检索工作项支持分页

Change-Id: I2e54ddcd8655b74eac5d22c5726b91c84f6d8305

Author: 延枚

operations/projex/types.ts

@@ -313,6 +313,9 @@ export const SearchWorkitemsSchema = z.object({
   // Advanced parameters
   advancedConditions: z.string().nullable().optional().describe("Advanced filter conditions, JSON format"),
   orderBy: z.string().optional().default("gmtCreate").describe("Sort field, default is gmtCreate. Possible values: gmtCreate, subject, status, priority, assignedTo"),
+  sort: z.string().optional().default("desc").describe("Sort order, default is desc. Possible values: desc (descending), asc (ascending)"),
+  page: z.number().int().min(1).optional().describe("Page number, starting from 1. Default is 1"),
+  perPage: z.number().int().min(0).max(200).optional().describe("Number of items per page, range 0-200. Default is 20"),
   includeDetails: z.boolean().optional().describe("Set to true when you need work item descriptions/detailed content. This automatically fetches missing descriptions instead of requiring separate get_work_item calls. RECOMMENDED: Use includeDetails=true when user asks for 'detailed content', 'descriptions', or 'full information' of work items. This is more efficient than calling get_work_item multiple times. Default is false")
 });
 

operations/projex/workitem.ts

@@ -1,5 +1,8 @@
 import {RecordType, string, TypeOf, z, ZodString} from "zod";
-import {buildUrl, yunxiaoRequest} from "../../common/utils.js";
+import {buildUrl, yunxiaoRequest, getYunxiaoApiBaseUrl, getCurrentSessionToken} from "../../common/utils.js";
+import { createYunxiaoError } from "../../common/errors.js";
+import { getUserAgent } from "universal-user-agent";
+import { VERSION } from "../../common/version.js";
 import {
   WorkItemSchema,
   FilterConditionSchema,
@@ -27,6 +30,21 @@ export async function getWorkItemFunc(
   return WorkItemSchema.parse(response);
 }
 
+// 定义分页信息类型
+export interface PaginationInfo {
+  page: number;
+  perPage: number;
+  totalPages: number;
+  total: number;
+  nextPage: number | null;
+  prevPage: number | null;
+}
+
+export interface SearchWorkitemsResult {
+  items: z.infer<typeof WorkItemSchema>[];
+  pagination?: PaginationInfo;
+}
+
 export async function searchWorkitemsFunc(
   organizationId: string,
   category: string,
@@ -51,8 +69,11 @@ export async function searchWorkitemsFunc(
   updateStatusAtBefore?: string,
   advancedConditions?: string,
   orderBy: string = "gmtCreate",
+  sort: string = "desc",
+  page?: number,
+  perPage?: number,
   includeDetails: boolean = false // 新增参数：是否自动补充缺失的description等详细信息
-): Promise<z.infer<typeof WorkItemSchema>[]> {
+): Promise<SearchWorkitemsResult> {
   // 处理assignedTo为"self"的情况，自动获取当前用户ID
   let finalAssignedTo = assignedTo;
   let finalCreator = creator;
@@ -111,17 +132,83 @@ export async function searchWorkitemsFunc(
   }
 
   payload.orderBy = orderBy;
+  
+  // 添加分页和排序参数
+  if (sort) {
+    payload.sort = sort;
+  }
+  if (page !== undefined) {
+    payload.page = page;
+  }
+  if (perPage !== undefined) {
+    payload.perPage = perPage;
+  }
 
-  const response = await yunxiaoRequest(url, {
+  // 使用 fetch 直接获取响应，以便读取响应头中的分页信息
+  const isAbsolute = url.startsWith("http://") || url.startsWith("https://");
+  const fullUrl = isAbsolute ? url : `${getYunxiaoApiBaseUrl()}${url.startsWith("/") ? url : `/${url}`}`;
+  
+  const requestHeaders: Record<string, string> = {
+    "Accept": "application/json",
+    "Content-Type": "application/json",
+    "User-Agent": `modelcontextprotocol/servers/alibabacloud-devops-mcp-server/v${VERSION} ${getUserAgent()}`,
+  };
+
+  const token = getCurrentSessionToken();
+  if (token) {
+    requestHeaders["x-yunxiao-token"] = token;
+  }
+
+  const response = await fetch(fullUrl, {
     method: "POST",
-    body: payload,
-  });
+    headers: requestHeaders,
+    body: JSON.stringify(payload),
+  } as RequestInit);
+
+  if (!response.ok) {
+    const responseBody = await response.json().catch(() => ({}));
+    throw createYunxiaoError(
+      response.status,
+      responseBody,
+      fullUrl,
+      "POST",
+      requestHeaders,
+      payload
+    );
+  }
 
-  if (!Array.isArray(response)) {
-    return [];
+  const responseBody = await response.json();
+  
+  // 从响应头中提取分页信息
+  const pagination: PaginationInfo | undefined = (() => {
+    const xPage = response.headers.get("x-page");
+    const xPerPage = response.headers.get("x-per-page");
+    const xTotalPages = response.headers.get("x-total-pages");
+    const xTotal = response.headers.get("x-total");
+    const xNextPage = response.headers.get("x-next-page");
+    const xPrevPage = response.headers.get("x-prev-page");
+
+    if (xPage && xPerPage && xTotalPages && xTotal) {
+      return {
+        page: parseInt(xPage, 10),
+        perPage: parseInt(xPerPage, 10),
+        totalPages: parseInt(xTotalPages, 10),
+        total: parseInt(xTotal, 10),
+        nextPage: xNextPage ? parseInt(xNextPage, 10) : null,
+        prevPage: xPrevPage ? parseInt(xPrevPage, 10) : null,
+      };
+    }
+    return undefined;
+  })();
+
+  if (!Array.isArray(responseBody)) {
+    return {
+      items: [],
+      pagination,
+    };
   }
 
-  const workItems = response.map(workitem => WorkItemSchema.parse(workitem));
+  const workItems = responseBody.map(workitem => WorkItemSchema.parse(workitem));
 
   // 如果需要补充详细信息，使用分批并发方式获取
   if (includeDetails) {
@@ -135,7 +222,7 @@ export async function searchWorkitemsFunc(
       const descriptionMap = await batchGetWorkItemDetails(organizationId, itemsNeedingDetails);
 
       // 更新workItems中的description
-      return workItems.map(item => {
+      const updatedItems = workItems.map(item => {
         if (descriptionMap.has(item.id)) {
           return {
             ...item,
@@ -144,10 +231,18 @@ export async function searchWorkitemsFunc(
         }
         return item;
       });
+
+      return {
+        items: updatedItems,
+        pagination,
+      };
     }
   }
 
-  return workItems;
+  return {
+    items: workItems,
+    pagination,
+  };
 }
 
 // 分批并发获取工作项详情

package.json

@@ -1,6 +1,6 @@
 {
   "name": "alibabacloud-devops-mcp-server",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "MCP Server for using the alibabacloud-devops API: allows AI assistants to directly participate in development collaboration, helping teams optimize development processes and improve efficiency.",
   "type": "module",
   "license": "Apache-2.0",

tool-handlers/project-management.ts

@@ -127,7 +127,7 @@ export const handleProjectManagementTools = async (request: any) => {
 
     case "search_workitems": {
       const args = types.SearchWorkitemsSchema.parse(request.params.arguments);
-      const workItems = await workitem.searchWorkitemsFunc(
+      const result = await workitem.searchWorkitemsFunc(
         args.organizationId,
         args.category,
         args.spaceId,
@@ -151,10 +151,13 @@ export const handleProjectManagementTools = async (request: any) => {
         args.updateStatusAtBefore ?? undefined,
         args.advancedConditions ?? undefined,
         args.orderBy ?? "gmtCreate",
+        args.sort ?? "desc",
+        args.page,
+        args.perPage,
         args.includeDetails ?? false
       );
       return {
-        content: [{ type: "text", text: JSON.stringify(workItems, null, 2) }],
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
       };
     }