gitlab_search_user
Search for GitLab users using partial details like name, email, or username. Retrieve user IDs, profiles, and activity status for team assignments or user management. Supports pagination for large result sets.
Instructions
Search for GitLab users based on partial information or search criteria.
This tool is useful when you don't have the exact username or ID, but need to find users based on name, email, or other search terms. Use this tool when you need to find users based on partial information or search queries.
Examples:
Find users by partial name: search_user("John Sm")
Search by email domain: search_user("@company.com")
Find users for team assignments
Returns user information including:
Basic details: ID, username, name, avatar
Public profile information
Activity status
For getting specific user details when you have exact ID/username, use 'gitlab_get_user' instead.
Parameters:
search: Search query (name, username, or email fragment)
per_page: Number of results per page (default: 20)
page: Page number for pagination (default: 1)
Example: Find users named "John"
{
"search": "John",
"per_page": 10
}
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination Type: integer Range: ≥1 Default: 1 Example: 3 (to get the third page of results) Note: Use with per_page to navigate large result sets | |
| per_page | No | Number of results per page Type: integer Range: 1-100 Default: 20 Example: 50 (for faster browsing) Tip: Use smaller values (10-20) for detailed operations, larger (50-100) for listing | |
| search | Yes | Search query (name, username, or email fragment) |
Implementation Reference
- src/mcp_gitlab/tool_handlers.py:660-667 (handler)The handler function that implements the core logic for the 'gitlab_search_user' tool. It extracts the search parameters from the input arguments and calls the GitLabClient's search_user method to perform the user search.def handle_search_user(client: GitLabClient, arguments: Optional[Dict[str, Any]]) -> Dict[str, Any]: """Handle searching for users""" search = require_argument(arguments, "search") per_page = get_argument(arguments, "per_page", DEFAULT_PAGE_SIZE) page = get_argument(arguments, "page", 1) return client.search_user(search=search, per_page=per_page, page=page)
- Defines the input schema and metadata for the 'gitlab_search_user' tool, specifying parameters like search_term (required), per_page, and page.name=TOOL_SEARCH_USER, description=desc.DESC_SEARCH_USER, inputSchema={ "type": "object", "properties": { "search_term": {"type": "string", "description": "Username or email to search for"}, "per_page": {"type": "integer", "description": desc.DESC_PER_PAGE, "default": DEFAULT_PAGE_SIZE, "minimum": 1, "maximum": MAX_PAGE_SIZE}, "page": {"type": "integer", "description": desc.DESC_PAGE_NUMBER, "default": 1, "minimum": 1} }, "required": ["search_term"] } ),
- src/mcp_gitlab/tool_handlers.py:1002-1097 (registration)Maps the tool name 'TOOL_SEARCH_USER' ('gitlab_search_user') to its handler function 'handle_search_user' in the central TOOL_HANDLERS dictionary used by the server.TOOL_HANDLERS = { # List tools TOOL_LIST_PROJECTS: handle_list_projects, TOOL_LIST_ISSUES: handle_list_issues, TOOL_LIST_MRS: handle_list_merge_requests, TOOL_LIST_BRANCHES: handle_list_branches, TOOL_LIST_PIPELINES: handle_list_pipelines, TOOL_LIST_USER_EVENTS: handle_get_user_events, TOOL_LIST_COMMITS: handle_get_commits, TOOL_LIST_REPOSITORY_TREE: handle_get_repository_tree, TOOL_LIST_TAGS: handle_get_tags, TOOL_LIST_RELEASES: handle_list_releases, TOOL_LIST_PROJECT_MEMBERS: handle_get_project_members, TOOL_LIST_PROJECT_HOOKS: handle_get_project_hooks, TOOL_LIST_GROUPS: handle_list_groups, TOOL_LIST_GROUP_PROJECTS: handle_list_group_projects, TOOL_LIST_SNIPPETS: handle_list_snippets, TOOL_LIST_PIPELINE_JOBS: handle_list_pipeline_jobs, TOOL_LIST_PROJECT_JOBS: handle_list_project_jobs, # Get tools TOOL_GET_PROJECT: handle_get_project, TOOL_GET_CURRENT_PROJECT: handle_get_current_project, TOOL_GET_MR_NOTES: handle_get_merge_request_notes, TOOL_GET_CURRENT_USER: handle_get_current_user, TOOL_GET_USER: handle_get_user, TOOL_GET_GROUP: handle_get_group, TOOL_GET_SNIPPET: handle_get_snippet, TOOL_DOWNLOAD_JOB_ARTIFACT: handle_download_job_artifact, TOOL_GET_ISSUE: handle_get_issue, TOOL_GET_MERGE_REQUEST: handle_get_merge_request, TOOL_GET_FILE_CONTENT: handle_get_file_content, TOOL_GET_COMMIT: handle_get_commit, TOOL_GET_COMMIT_DIFF: handle_get_commit_diff, TOOL_GET_MR_APPROVALS: handle_get_merge_request_approvals, TOOL_GET_MR_DISCUSSIONS: handle_get_merge_request_discussions, TOOL_GET_MR_CHANGES: handle_get_merge_request_changes, # Action tools TOOL_CREATE_SNIPPET: handle_create_snippet, TOOL_UPDATE_SNIPPET: handle_update_snippet, TOOL_UPDATE_MR: handle_update_merge_request, TOOL_CLOSE_MR: handle_close_merge_request, TOOL_MERGE_MR: handle_merge_merge_request, TOOL_REBASE_MR: handle_rebase_merge_request, TOOL_APPROVE_MR: handle_approve_merge_request, TOOL_ADD_ISSUE_COMMENT: handle_add_issue_comment, TOOL_ADD_MR_COMMENT: handle_add_merge_request_comment, TOOL_RESOLVE_DISCUSSION: handle_resolve_discussion, TOOL_CREATE_COMMIT: handle_create_commit, TOOL_CHERRY_PICK_COMMIT: handle_cherry_pick_commit, TOOL_COMPARE_REFS: handle_compare_refs, # Search tools TOOL_SEARCH_PROJECTS: handle_search_projects, TOOL_SEARCH_IN_PROJECT: handle_search_in_project, # AI and Advanced Tools TOOL_SUMMARIZE_MR: handle_summarize_merge_request, TOOL_SUMMARIZE_ISSUE: handle_summarize_issue, TOOL_SUMMARIZE_PIPELINE: handle_summarize_pipeline, TOOL_SMART_DIFF: handle_smart_diff, TOOL_SAFE_PREVIEW_COMMIT: handle_safe_preview_commit, TOOL_BATCH_OPERATIONS: handle_batch_operations, # Job and Artifact handlers TOOL_LIST_PIPELINE_JOBS: handle_list_pipeline_jobs, TOOL_DOWNLOAD_JOB_ARTIFACT: handle_download_job_artifact, TOOL_LIST_PROJECT_JOBS: handle_list_project_jobs, # User & Profile handlers TOOL_SEARCH_USER: handle_search_user, TOOL_GET_USER_DETAILS: handle_get_user_details, TOOL_GET_MY_PROFILE: handle_get_my_profile, TOOL_GET_USER_CONTRIBUTIONS_SUMMARY: handle_get_user_contributions_summary, TOOL_GET_USER_ACTIVITY_FEED: handle_get_user_activity_feed, # User's Issues & MRs handlers TOOL_GET_USER_OPEN_MRS: handle_get_user_open_mrs, TOOL_GET_USER_REVIEW_REQUESTS: handle_get_user_review_requests, TOOL_GET_USER_OPEN_ISSUES: handle_get_user_open_issues, TOOL_GET_USER_REPORTED_ISSUES: handle_get_user_reported_issues, TOOL_GET_USER_RESOLVED_ISSUES: handle_get_user_resolved_issues, # User's Code & Commits handlers TOOL_GET_USER_COMMITS: handle_get_user_commits, TOOL_GET_USER_MERGE_COMMITS: handle_get_user_merge_commits, TOOL_GET_USER_CODE_CHANGES_SUMMARY: handle_get_user_code_changes_summary, TOOL_GET_USER_SNIPPETS: handle_get_user_snippets, # User's Comments & Discussions handlers TOOL_GET_USER_ISSUE_COMMENTS: handle_get_user_issue_comments, TOOL_GET_USER_MR_COMMENTS: handle_get_user_mr_comments, TOOL_GET_USER_DISCUSSION_THREADS: handle_get_user_discussion_threads, TOOL_GET_USER_RESOLVED_THREADS: handle_get_user_resolved_threads, }
- src/mcp_gitlab/tool_definitions.py:830-841 (registration)Registers the 'gitlab_search_user' tool in the TOOLS list with its name, description, and input schema.name=TOOL_SEARCH_USER, description=desc.DESC_SEARCH_USER, inputSchema={ "type": "object", "properties": { "search_term": {"type": "string", "description": "Username or email to search for"}, "per_page": {"type": "integer", "description": desc.DESC_PER_PAGE, "default": DEFAULT_PAGE_SIZE, "minimum": 1, "maximum": MAX_PAGE_SIZE}, "page": {"type": "integer", "description": desc.DESC_PAGE_NUMBER, "default": 1, "minimum": 1} }, "required": ["search_term"] } ),
- src/mcp_gitlab/constants.py:251-251 (helper)Defines the constant TOOL_SEARCH_USER = 'gitlab_search_user' used throughout the codebase for consistent tool naming.TOOL_SEARCH_USER = "gitlab_search_user"