repo_search_commits
Search for specific commits in Azure DevOps repositories by project, repository, commit range, branch, or tag. Retrieve associated work items or links for detailed commit analysis.
Instructions
Searches for commits in a repository
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fromCommit | No | Starting commit ID | |
| includeLinks | No | Include commit links | |
| includeWorkItems | No | Include associated work items | |
| project | Yes | Project name or ID | |
| repository | Yes | Repository name or ID | |
| skip | No | Number of commits to skip | |
| toCommit | No | Ending commit ID | |
| top | No | Maximum number of commits to return | |
| version | No | The name of the branch, tag or commit to filter commits by | |
| versionType | No | The meaning of the version parameter, e.g., branch, tag or commit | Branch |
Implementation Reference
- src/tools/repos.ts:778-820 (handler)The asynchronous handler function that implements the core logic of the 'repo_search_commits' tool. It constructs a GitQueryCommitsCriteria object based on input parameters and calls gitApi.getCommits to retrieve matching commits from the specified repository and project.async ({ project, repository, fromCommit, toCommit, version, versionType, skip, top, includeLinks, includeWorkItems }) => { try { const connection = await connectionProvider(); const gitApi = await connection.getGitApi(); const searchCriteria: GitQueryCommitsCriteria = { fromCommitId: fromCommit, toCommitId: toCommit, includeLinks: includeLinks, includeWorkItems: includeWorkItems, }; if (version) { const itemVersion: GitVersionDescriptor = { version: version, versionType: GitVersionType[versionType as keyof typeof GitVersionType], }; searchCriteria.itemVersion = itemVersion; } const commits = await gitApi.getCommits( repository, searchCriteria, project, skip, // skip top ); return { content: [{ type: "text", text: JSON.stringify(commits, null, 2) }], }; } catch (error) { return { content: [ { type: "text", text: `Error searching commits: ${error instanceof Error ? error.message : String(error)}`, }, ], isError: true, }; } }
- src/tools/repos.ts:762-777 (schema)Zod input schema validating parameters for the 'repo_search_commits' tool, including project, repository, optional commit range, version with type (branch/tag/commit), pagination (skip/top), and flags for links and work items.{ project: z.string().describe("Project name or ID"), repository: z.string().describe("Repository name or ID"), fromCommit: z.string().optional().describe("Starting commit ID"), toCommit: z.string().optional().describe("Ending commit ID"), version: z.string().optional().describe("The name of the branch, tag or commit to filter commits by"), versionType: z .enum(gitVersionTypeStrings as [string, ...string[]]) .optional() .default(GitVersionType[GitVersionType.Branch]) .describe("The meaning of the version parameter, e.g., branch, tag or commit"), skip: z.number().optional().default(0).describe("Number of commits to skip"), top: z.number().optional().default(10).describe("Maximum number of commits to return"), includeLinks: z.boolean().optional().default(false).describe("Include commit links"), includeWorkItems: z.boolean().optional().default(false).describe("Include associated work items"), },
- src/tools/repos.ts:759-821 (registration)Registers the 'repo_search_commits' tool with the MCP server using server.tool(), referencing the name from REPO_TOOLS.search_commits, providing description, input schema, and handler function.server.tool( REPO_TOOLS.search_commits, "Searches for commits in a repository", { project: z.string().describe("Project name or ID"), repository: z.string().describe("Repository name or ID"), fromCommit: z.string().optional().describe("Starting commit ID"), toCommit: z.string().optional().describe("Ending commit ID"), version: z.string().optional().describe("The name of the branch, tag or commit to filter commits by"), versionType: z .enum(gitVersionTypeStrings as [string, ...string[]]) .optional() .default(GitVersionType[GitVersionType.Branch]) .describe("The meaning of the version parameter, e.g., branch, tag or commit"), skip: z.number().optional().default(0).describe("Number of commits to skip"), top: z.number().optional().default(10).describe("Maximum number of commits to return"), includeLinks: z.boolean().optional().default(false).describe("Include commit links"), includeWorkItems: z.boolean().optional().default(false).describe("Include associated work items"), }, async ({ project, repository, fromCommit, toCommit, version, versionType, skip, top, includeLinks, includeWorkItems }) => { try { const connection = await connectionProvider(); const gitApi = await connection.getGitApi(); const searchCriteria: GitQueryCommitsCriteria = { fromCommitId: fromCommit, toCommitId: toCommit, includeLinks: includeLinks, includeWorkItems: includeWorkItems, }; if (version) { const itemVersion: GitVersionDescriptor = { version: version, versionType: GitVersionType[versionType as keyof typeof GitVersionType], }; searchCriteria.itemVersion = itemVersion; } const commits = await gitApi.getCommits( repository, searchCriteria, project, skip, // skip top ); return { content: [{ type: "text", text: JSON.stringify(commits, null, 2) }], }; } catch (error) { return { content: [ { type: "text", text: `Error searching commits: ${error instanceof Error ? error.message : String(error)}`, }, ], isError: true, }; } } );
- src/tools/repos.ts:25-44 (registration)Defines the REPO_TOOLS constant object that maps the internal identifier 'search_commits' to the public tool name 'repo_search_commits' used in server.tool registration.const REPO_TOOLS = { list_repos_by_project: "repo_list_repos_by_project", list_pull_requests_by_repo: "repo_list_pull_requests_by_repo", list_pull_requests_by_project: "repo_list_pull_requests_by_project", list_branches_by_repo: "repo_list_branches_by_repo", list_my_branches_by_repo: "repo_list_my_branches_by_repo", list_pull_request_threads: "repo_list_pull_request_threads", list_pull_request_thread_comments: "repo_list_pull_request_thread_comments", get_repo_by_name_or_id: "repo_get_repo_by_name_or_id", get_branch_by_name: "repo_get_branch_by_name", get_pull_request_by_id: "repo_get_pull_request_by_id", create_pull_request: "repo_create_pull_request", update_pull_request: "repo_update_pull_request", update_pull_request_reviewers: "repo_update_pull_request_reviewers", reply_to_comment: "repo_reply_to_comment", create_pull_request_thread: "repo_create_pull_request_thread", resolve_comment: "repo_resolve_comment", search_commits: "repo_search_commits", list_pull_requests_by_commits: "repo_list_pull_requests_by_commits", };
- src/tools/repos.ts:757-757 (helper)Helper constant deriving string enum values from GitVersionType for use in the versionType schema enum of repo_search_commits.const gitVersionTypeStrings = Object.values(GitVersionType).filter((value): value is string => typeof value === "string");