search_projects

Instructions

Implementation Reference

• tool-handlers/project-management.ts:21-44 (handler)

  Handler for 'search_projects' tool: parses input with SearchProjectsSchema, calls searchProjectsFunc, returns JSON response.

  case "search_projects": {
    const args = types.SearchProjectsSchema.parse(request.params.arguments);
    const projects = await project.searchProjectsFunc(
      args.organizationId,
      args.name ?? undefined,
      args.status ?? undefined,
      args.createdAfter ?? undefined,
      args.createdBefore ?? undefined,
      args.creator ?? undefined,
      args.adminUserId ?? undefined,
      args.logicalStatus ?? undefined,
      args.advancedConditions ?? undefined,
      args.extraConditions ?? undefined,
      args.orderBy,
      args.page,
      args.perPage,
      args.sort,
      args.scenarioFilter ?? undefined,
      args.userId ?? undefined,
    );
    return {
      content: [{ type: "text", text: JSON.stringify(projects, null, 2) }],
    };
  }

• tool-registry/project-management.ts:12-16 (registration)

  Registers the 'search_projects' tool in getProjectManagementTools() with name, description, and input schema from types.SearchProjectsSchema.

  {
    name: "search_projects",
    description: "[Project Management] Search for Yunxiao Project List. A Project is a project management unit that includes work items and sprints, and it is different from a code repository (Repository).\n\nUse Cases:\n\nQuery projects I am involved in\nQuery projects I have created",
    inputSchema: zodToJsonSchema(types.SearchProjectsSchema),
  },

• operations/projex/types.ts:240-263 (schema)

  Zod schema SearchProjectsSchema defining input parameters for searching projects, including filters, pagination, and advanced conditions.

  export const SearchProjectsSchema = z.object({
    organizationId: z.string().describe("Organization ID"),
  
    // Simplified search parameters
    name: z.string().nullable().optional().describe("Text contained in project name"),
    status: z.string().nullish().optional().describe("Project status ID, multiple separated by commas"),
    createdAfter: z.string().nullable().optional().describe("Created not earlier than, format: YYYY-MM-DD"),
    createdBefore: z.string().nullable().optional().describe("Created not later than, format: YYYY-MM-DD"),
    creator: z.string().nullable().optional().describe("Creator"),
    adminUserId: z.string().nullable().optional().describe("Project administrator user ID, should use userId returned from getCurrentOrganizationInfoFunc or user-provided user ID, multiple IDs separated by commas"),
    logicalStatus: z.string().nullable().optional().describe("Logical status, e.g., NORMAL"),
  
    // Special filter for common scenarios
    scenarioFilter: z.enum(["manage", "participate", "favorite"]).nullable().optional().describe("Predefined filter scenarios: 'manage' (projects I manage), 'participate' (projects I participate in), 'favorite' (projects I favorited). Will be used to construct appropriate extraConditions. Requires userId from getCurrentOrganizationInfoFunc."),
    userId: z.string().nullable().optional().describe("User ID to use with scenarioFilter, should be the userId returned from getCurrentOrganizationInfoFunc"),
  
    // Advanced parameters
    advancedConditions: z.string().nullable().optional().describe("Advanced filter conditions, JSON format"),
    extraConditions: z.string().nullable().optional().describe("Additional filter conditions as JSON string. Should be constructed similar to the conditions parameter. For common scenarios: 1) For 'projects I manage': use fieldIdentifier 'project.admin' with the user ID; 2) For 'projects I participate in': use fieldIdentifier 'users' with the user ID; 3) For 'projects I favorited': use fieldIdentifier 'collectMembers' with the user ID. Example: JSON.stringify({conditionGroups:[[{className:'user',fieldIdentifier:'project.admin',format:'multiList',operator:'CONTAINS',value:[userId]}]]})"),
    orderBy: z.string().optional().default("gmtCreate").describe("Sort field, default is gmtCreate, supports: gmtCreate (creation time), name (name)"),
    page: z.number().int().default(1).optional().describe("Pagination parameter, page number"),
    perPage: z.number().int().default(20).optional().describe("Pagination parameter, page size, 0-200, default value is 20"),
    sort: z.string().optional().default("desc").describe("Sort order, default is desc, options: desc (descending), asc (ascending)"),
  });

• operations/projex/project.ts:55-126 (helper)

  Core implementation of searchProjectsFunc: builds search payload with conditions and extraConditions, POSTs to Yunxiao API /projects:search, parses array of projects with ProjectInfoSchema.

  export async function searchProjectsFunc(
    organizationId: string,
    name?: string,
    status?: string,
    createdAfter?: string,
    createdBefore?: string,
    creator?: string,
    adminUserId?: string, // Project administrator user ID
    logicalStatus?: string,
    advancedConditions?: string,
    extraConditions?: string, // Should be constructed using buildExtraConditions for common filters
    orderBy?: string, // Possible values: "gmtCreate", "name"
    page?: number,
    perPage?: number,
    sort?: string, // Possible values: "desc", "asc"
    scenarioFilter?: "manage" | "participate" | "favorite", // Common project filter scenarios
    userId?: string // User ID to use with scenarioFilter
  ): Promise<z.infer<typeof ProjectInfoSchema>[]> {
    const url = `/oapi/v1/projex/organizations/${organizationId}/projects:search`;
  
    const payload: Record<string, any> = {};
  
    if (scenarioFilter && userId) {
      extraConditions = buildExtraConditions(scenarioFilter, userId);
    }
  
    const conditions = buildProjectConditions({
      name,
      status,
      createdAfter,
      createdBefore,
      creator,
      adminUserId,
      logicalStatus,
      advancedConditions
    });
    
    if (conditions) {
      payload.conditions = conditions;
    }
  
    if (extraConditions) {
      payload.extraConditions = extraConditions;
    }
  
    if (orderBy) {
      payload.orderBy = orderBy;
    }
  
    if (page !== undefined) {
      payload.page = page;
    }
  
    if (perPage !== undefined) {
      payload.perPage = perPage;
    }
  
    if (sort) {
      payload.sort = sort;
    }
  
    const response = await yunxiaoRequest(url, {
      method: "POST",
      body: payload,
    });
  
    if (!Array.isArray(response)) {
      return [];
    }
  
    return response.map(project => ProjectInfoSchema.parse(project));
  }