Skip to content

Implement get_repository_details core functionality #109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Tiberriver256 merged 2 commits into from
Apr 2, 2025
Merged

Implement get_repository_details core functionality #109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4a7a266
feat: implement get_repository_details core functionality
openhands-agent Apr 2, 2025
52f7b3d
docs: update task status for get_repository_details
openhands-agent Apr 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 160 additions & 0 deletions docs/tools/repositories.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,165 @@

This document describes the tools available for working with Azure DevOps Git repositories.

## get_repository_details

Gets detailed information about a specific Git repository, including optional branch statistics and refs.

### Description

The `get_repository_details` tool retrieves comprehensive information about a specific Git repository in Azure DevOps. It can optionally include branch statistics (ahead/behind counts, commit information) and repository refs (branches, tags). This is useful for tasks like branch management, policy configuration, and repository statistics tracking.

### Parameters

```json
{
"projectId": "MyProject", // Required: The ID or name of the project
"repositoryId": "MyRepo", // Required: The ID or name of the repository
"includeStatistics": true, // Optional: Whether to include branch statistics (default: false)
"includeRefs": true, // Optional: Whether to include repository refs (default: false)
"refFilter": "heads/", // Optional: Filter for refs (e.g., "heads/" or "tags/")
"branchName": "main" // Optional: Name of specific branch to get statistics for
}
```

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `projectId` | string | Yes | The ID or name of the project containing the repository |
| `repositoryId` | string | Yes | The ID or name of the repository to get details for |
| `includeStatistics` | boolean | No | Whether to include branch statistics (default: false) |
| `includeRefs` | boolean | No | Whether to include repository refs (default: false) |
| `refFilter` | string | No | Optional filter for refs (e.g., "heads/" or "tags/") |
| `branchName` | string | No | Name of specific branch to get statistics for (if includeStatistics is true) |

### Response

The tool returns a `RepositoryDetails` object containing:

- `repository`: The basic repository information (same as returned by `get_repository`)
- `statistics` (optional): Branch statistics if requested
- `refs` (optional): Repository refs if requested

Example response:

```json
{
"repository": {
"id": "repo-guid",
"name": "MyRepository",
"url": "https://dev.azure.com/organization/MyProject/_apis/git/repositories/MyRepository",
"project": {
"id": "project-guid",
"name": "MyProject",
"url": "https://dev.azure.com/organization/_apis/projects/project-guid"
},
"defaultBranch": "refs/heads/main",
"size": 25478,
"remoteUrl": "https://dev.azure.com/organization/MyProject/_git/MyRepository",
"sshUrl": "git@ssh.dev.azure.com:v3/organization/MyProject/MyRepository",
"webUrl": "https://dev.azure.com/organization/MyProject/_git/MyRepository"
},
"statistics": {
"branches": [
{
"name": "refs/heads/main",
"aheadCount": 0,
"behindCount": 0,
"isBaseVersion": true,
"commit": {
"commitId": "commit-guid",
"author": {
"name": "John Doe",
"email": "john.doe@example.com",
"date": "2023-01-01T12:00:00Z"
},
"committer": {
"name": "John Doe",
"email": "john.doe@example.com",
"date": "2023-01-01T12:00:00Z"
},
"comment": "Initial commit"
}
}
]
},
"refs": {
"value": [
{
"name": "refs/heads/main",
"objectId": "commit-guid",
"creator": {
"displayName": "John Doe",
"id": "user-guid"
},
"url": "https://dev.azure.com/organization/MyProject/_apis/git/repositories/repo-guid/refs/heads/main"
}
],
"count": 1
}
}
```

### Error Handling

The tool may throw the following errors:

- General errors: If the API call fails or other unexpected errors occur
- Authentication errors: If the authentication credentials are invalid or expired
- Permission errors: If the authenticated user doesn't have permission to access the repository
- ResourceNotFound errors: If the specified project or repository doesn't exist

Error messages will be formatted as text and provide details about what went wrong.

### Example Usage

```typescript
// Basic example - just repository info
const repoDetails = await mcpClient.callTool('get_repository_details', {
projectId: 'MyProject',
repositoryId: 'MyRepo'
});
console.log(repoDetails);

// Example with branch statistics
const repoWithStats = await mcpClient.callTool('get_repository_details', {
projectId: 'MyProject',
repositoryId: 'MyRepo',
includeStatistics: true
});
console.log(repoWithStats);

// Example with refs filtered to branches
const repoWithBranches = await mcpClient.callTool('get_repository_details', {
projectId: 'MyProject',
repositoryId: 'MyRepo',
includeRefs: true,
refFilter: 'heads/'
});
console.log(repoWithBranches);

// Example with all options
const fullRepoDetails = await mcpClient.callTool('get_repository_details', {
projectId: 'MyProject',
repositoryId: 'MyRepo',
includeStatistics: true,
includeRefs: true,
refFilter: 'heads/',
branchName: 'main'
});
console.log(fullRepoDetails);
```

### Implementation Details

This tool uses the Azure DevOps Node API's Git API to retrieve repository details:

1. It gets a connection to the Azure DevOps WebApi client
2. It calls the `getGitApi()` method to get a handle to the Git API
3. It retrieves the basic repository information using `getRepository()`
4. If requested, it retrieves branch statistics using `getBranches()`
5. If requested, it retrieves repository refs using `getRefs()`
6. The combined results are returned to the caller

## list_repositories

Lists all Git repositories in a specific project.
Expand Down Expand Up @@ -118,4 +277,5 @@ This tool uses the Azure DevOps Node API's Git API to retrieve repositories:
### Related Tools

- `get_repository`: Get details of a specific repository
- `get_repository_details`: Get detailed information about a repository including statistics and refs
- `list_projects`: List all projects in the organization (to find project IDs)
18 changes: 18 additions & 0 deletions project-management/task-management/done.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,23 @@
## Completed Tasks

- [x] **Task 3.1**: Implement get_repository_details core functionality
- **Role**: Full-Stack Developer
- **Phase**: Completed
- **Notes**:
- Implemented a handler to fetch detailed information about a specific Git repository in Azure DevOps
- Added support for repository metadata, branch statistics, and refs information
- Created unit tests and integration tests
- Updated documentation
- **Sub-tasks**:
- [x] Created schema for get_repository_details
- [x] Implemented core functionality to fetch repository details
- [x] Added support for branch statistics
- [x] Added support for repository refs
- [x] Wrote unit tests
- [x] Wrote integration tests
- [x] Updated documentation
- **Completed**: April 2, 2025

- [x] **Task 2.8**: Allow `get_work_item` to default to 'Expand All' when no specific fields are requested. There isn't usually enough information on the default Get_work_item response now.
- **Role**: Full-Stack Developer
- **Phase**: Completed
Expand Down
Loading