{"record":{"id":"4d419e44b77695c0","repo":"flipped-aurora/gin-vue-admin","slug":"id","errorCode":null,"errorMessage":" 参数是必需的,且至少包含一个ID","messagePattern":" 参数是必需的,且至少包含一个ID","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/mcp/org_common.go","lineNumber":262,"sourceCode":"\t\t}\n\t\t// hint 仅是加速命中的优化;username 为 LIKE 模糊匹配且只查首页,未命中(名不匹配或\n\t\t// 命中过多致目标不在首页)时不误报,回退全量翻页扫描兜底\n\t}\n\n\tfound, _, err := scanUsersByIDs(ctx, []uint{userID})\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tif user, ok := found[userID]; ok {\n\t\treturn &user, nil\n\t}\n\treturn nil, fmt.Errorf(\"未找到 ID 为 %d 的用户(已扫描前 %d 条,大用户量场景请传 username 参数精确定位)\", userID, orgUserScanMaxPages*orgUserScanPageSize)\n}\n\n// requireNonEmptyList 语义化的必填列表校验\nfunc requireNonEmptyList(ids []uint, name string) error {\n\tif len(ids) == 0 {\n\t\treturn errors.New(name + \" 参数是必需的,且至少包含一个ID\")\n\t}\n\treturn nil\n}\n\n// parseOptionalPositiveInt 解析可选的正整数分页参数,兼容数字与字符串两种形式\n// (与本工具集\"数字参数兼容字符串\"的既定设计一致);缺省或非法时返回 def\nfunc parseOptionalPositiveInt(v any, def int) int {\n\tswitch value := v.(type) {\n\tcase float64:\n\t\tif value >= 1 {\n\t\t\treturn int(value)\n\t\t}\n\tcase string:\n\t\tif n, err := strconv.Atoi(strings.TrimSpace(value)); err == nil && n >= 1 {\n\t\t\treturn n\n\t\t}\n\t}\n\treturn def","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/flipped-aurora/gin-vue-admin/blob/3136500ef380842b0eb6c4daa87c3f8a47fcf9e0/server/mcp/org_common.go#L244-L280","documentation":"requireNonEmptyList in server/mcp/org_common.go is the shared semantic validation for required ID-list parameters in the org toolset. It returns this error whenever the parsed []uint slice is empty, i.e. the list parameter was omitted, was not a valid array, or contained no usable IDs. The message interpolates the parameter name, so the actual text reads e.g. 'userIds 参数是必需的,且至少包含一个ID'.","triggerScenarios":"Calling any org MCP tool that takes a required ID list (e.g. userIds, deptIds for delete/batch operations) with an empty array []; omitting the list key entirely; passing a value that parseUintList failed to accept so the resulting slice is empty.","commonSituations":"Batch scripts that collected zero IDs due to an upstream filter returning nothing; clients sending {} or a comma-separated string instead of a JSON array of IDs; template-generated calls where the list placeholder was left empty.","solutions":["Populate the list parameter with at least one positive integer ID","Send the IDs as a JSON array of numbers (or numeric strings accepted by parseUintList), not a CSV string","Verify upstream data actually contains the IDs you intend to pass (an empty source list means there is nothing to operate on)","Read the parameter name embedded in the error message to confirm which list was empty"],"exampleFix":"// before\nargs := map[string]interface{}{ \"userIds\": []uint{} }\n// after\nargs := map[string]interface{}{ \"userIds\": []uint{7, 9} }","handlingStrategy":"validation","validationCode":"func validIDList(args map[string]interface{}, key string) ([]uint, error) {\n  raw, ok := args[key].([]interface{})\n  if !ok || len(raw) == 0 {\n    return nil, fmt.Errorf(\"%s must be a non-empty array of IDs\", key)\n  }\n  ids := make([]uint, 0, len(raw))\n  for _, v := range raw {\n    n, ok := toUint(v)\n    if !ok || n == 0 {\n      return nil, fmt.Errorf(\"%s contains an invalid ID: %v\", key, v)\n    }\n    ids = append(ids, n)\n  }\n  return ids, nil\n}","typeGuard":"func nonEmptyUintList(v interface{}) bool {\n  l, ok := v.([]interface{})\n  return ok && len(l) > 0\n}","tryCatchPattern":"if err := requireNonEmptyList(ids, \"userIds\"); err != nil {\n  return fmt.Errorf(\"nothing to operate on: %w\", err)\n}","preventionTips":["Check that the source query actually produced IDs before building the call","Always pass JSON arrays, never CSV strings or single numbers","Log the payload when a list is empty to catch upstream filter bugs","Keep the required-list rule in the tool's input schema so clients validate early"],"tags":["mcp","parameter-validation","go","empty-list"],"backgroundTag":"missing-required-parameter","analyzedSha":"3136500ef380842b0eb6c4daa87c3f8a47fcf9e0","analyzedAt":"2026-08-31T13:50:02.721Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}