Skip to content

Commit e244658

Browse files
openhands-agentTiberriver256
openhands-agent
authored and
Tiberriver256
committed
feat: implement search_work_items handler with tests
1 parent 6d93d98 commit e244658

15 files changed

+1714
-1
lines changed

‎project-management/task-management/done.md

+15
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,21 @@
2121
- [x] Updated exports in projects/index.ts
2222
- **Completed**: April 2, 2025
2323
- **Pull Request**: [#111](https://github.com/Tiberriver256/mcp-server-azure-devops/pull/111)
24+
- [x] **Task 6.4**: Implement `search_work_items` handler with tests
25+
- **Role**: Full-Stack Developer
26+
- **Phase**: Completed
27+
- **Notes**:
28+
- Implemented a handler to search for work items in Azure DevOps projects
29+
- Used the Azure DevOps Work Item Search API
30+
- Added support for filtering, pagination, and proper error handling
31+
- Created unit and integration tests
32+
- **Sub-tasks**:
33+
- [x] Created the necessary types and schemas
34+
- [x] Implemented the search_work_items handler
35+
- [x] Wrote unit tests
36+
- [x] Wrote integration tests
37+
- [x] Updated server.ts to register the new tool
38+
- **Completed**: April 2, 2025
2439

2540
- [x] **Task 3.1**: Implement get_repository_details core functionality
2641
- **Role**: Full-Stack Developer

‎project-management/task-management/drafts/issue-104-create-test-plan-draft.md

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Azure DevOps Test Plans - create_test_plan Feature Research
2+
3+
## Overview of Test Plans in Azure DevOps
4+
Test Plans in Azure DevOps are used to organize and manage testing activities within a project. They provide a structured way to plan, organize, and track testing efforts. A test plan typically contains test suites and test cases that define what should be tested and how.
5+
6+
## API Endpoint for Creating Test Plans
7+
The API endpoint for creating a test plan in Azure DevOps is:
8+
9+
```
10+
POST https://dev.azure.com/{organization}/{project}/_apis/test/plans?api-version=5.0
11+
```
12+
13+
### Required Parameters:
14+
- **organization**: The name of the Azure DevOps organization.
15+
- **project**: Project ID or project name where the test plan will be created.
16+
- **api-version**: Version of the API to use (5.0).
17+
18+
### Request Body:
19+
The request body should contain a JSON object with the following properties:
20+
21+
- **name** (required): Name of the test plan.
22+
- **area** (optional): Area path to which the test plan belongs.
23+
- **iteration** (optional): Iteration path for the test plan.
24+
- **description** (optional): Description of the test plan.
25+
- **startDate** (optional): Start date for the test plan.
26+
- **endDate** (optional): End date for the test plan.
27+
- **state** (optional): State of the test plan.
28+
- **owner** (optional): Owner of the test plan.
29+
- **build** (optional): Build ID whose quality is tested by the tests in this plan.
30+
- **buildDefinition** (optional): The Build Definition that generates a build for this plan.
31+
- **releaseEnvironmentDefinition** (optional): Release Environment for deployment and running automated tests.
32+
- **testOutcomeSettings** (optional): Settings for test outcomes.
33+
34+
### Response:
35+
A successful operation returns a `200 OK` response with a `TestPlan` object containing details of the created test plan.
36+
37+
## Authentication:
38+
The API uses OAuth2 authentication with the following scopes:
39+
- **vso.test_write**: Grants the ability to read, create, and update test plans, cases, results, and other test management related artifacts.
40+
41+
## Examples:
42+
Here are some example scenarios for creating test plans:
43+
44+
1. **Basic Test Plan**:
45+
```json
46+
{
47+
"name": "Sprint 1 Testing"
48+
}
49+
```
50+
51+
2. **Test Plan with Area and Iteration**:
52+
```json
53+
{
54+
"name": "Release Testing",
55+
"area": {
56+
"name": "MyProject\\Quality assurance"
57+
},
58+
"iteration": "MyProject\\Release 1"
59+
}
60+
```
61+
62+
3. **Test Plan with Description and Dates**:
63+
```json
64+
{
65+
"name": "Feature X Testing",
66+
"description": "Testing plan for Feature X implementation",
67+
"startDate": "2023-06-01",
68+
"endDate": "2023-06-15"
69+
}
70+
```
71+
72+
## Implementation Considerations:
73+
1. The MCP Server handler for `create_test_plan` should accept all the relevant parameters with appropriate validation.
74+
2. All required fields must be provided and validated before making the API request.
75+
3. Authentication tokens should be properly managed and secured.
76+
4. Error handling should be implemented to handle various failure scenarios.
77+
5. The response should be appropriately formatted to provide clear information to the client.
78+
79+
## Next Steps:
80+
- Determine which parameters should be required vs. optional for the MCP Server handler
81+
- Define validation rules for each parameter
82+
- Design error handling approach
83+
- Implement authentication mechanism

‎project-management/task-management/drafts/issue-104-create-test-plan-final.md

+192
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# Azure DevOps Test Plans - create_test_plan Feature Implementation
2+
3+
## Feature Overview
4+
The `create_test_plan` feature will allow users to create test plans in Azure DevOps through the MCP Server. This feature enables teams to establish testing structures for their projects, organize test cases, and manage testing activities directly from their automation workflows.
5+
6+
## Background
7+
Test Plans in Azure DevOps provide a comprehensive solution for managing test activities within a project lifecycle. They serve as containers for test suites and test cases, allowing teams to plan and track testing progress. Test plans are particularly useful in structured testing methodologies and enable teams to:
8+
9+
1. Organize test cases in a hierarchical structure
10+
2. Track test execution progress
11+
3. Manage test configurations
12+
4. Associate tests with specific iterations and releases
13+
5. Generate test execution reports and metrics
14+
15+
## API Details
16+
17+
### Endpoint
18+
```
19+
POST https://dev.azure.com/{organization}/{project}/_apis/test/plans?api-version=5.0
20+
```
21+
22+
### Required Headers
23+
- `Content-Type: application/json`
24+
- `Authorization: Bearer {PAT or OAuth token}`
25+
26+
### Request Body Structure
27+
The request body is a JSON object containing test plan details:
28+
29+
```json
30+
{
31+
"name": "Test Plan Name",
32+
"area": {
33+
"name": "ProjectName\\AreaPath"
34+
},
35+
"iteration": "ProjectName\\IterationPath",
36+
"description": "Description of the test plan",
37+
"startDate": "YYYY-MM-DD",
38+
"endDate": "YYYY-MM-DD",
39+
"state": "Active",
40+
"owner": {
41+
"id": "ownerId"
42+
}
43+
}
44+
```
45+
46+
### Response Format
47+
A successful operation returns a `200 OK` response with a `TestPlan` object:
48+
49+
```json
50+
{
51+
"id": 123,
52+
"name": "Test Plan Name",
53+
"url": "https://dev.azure.com/organization/project/_apis/test/Plans/123",
54+
"project": {
55+
"id": "project-guid",
56+
"name": "ProjectName",
57+
"url": "https://dev.azure.com/organization/_apis/projects/ProjectName"
58+
},
59+
"area": {
60+
"id": "area-id",
61+
"name": "ProjectName\\AreaPath"
62+
},
63+
"description": "Description of the test plan",
64+
"startDate": "YYYY-MM-DDT00:00:00Z",
65+
"endDate": "YYYY-MM-DDT00:00:00Z",
66+
"iteration": "ProjectName\\IterationPath",
67+
"state": "Active",
68+
"revision": 1,
69+
"owner": {
70+
"id": "owner-guid",
71+
"displayName": "Owner Name",
72+
"uniqueName": "[email protected]",
73+
"url": "https://dev.azure.com/organization/_apis/Identities/owner-guid",
74+
"imageUrl": "https://dev.azure.com/organization/_api/_common/identityImage?id=owner-guid"
75+
},
76+
"rootSuite": {
77+
"id": "suite-id",
78+
"name": "Test Plan Name",
79+
"url": "https://dev.azure.com/organization/project/_apis/test/Plans/123/Suites/suite-id"
80+
}
81+
}
82+
```
83+
84+
## Authentication
85+
Azure DevOps API supports two primary authentication methods:
86+
1. **Personal Access Tokens (PAT)**: Generated in the user's Azure DevOps settings
87+
2. **OAuth 2.0**: For applications requiring delegated user access
88+
89+
For the MCP Server implementation, PAT is recommended for simplicity and security. The token requires the `vso.test_write` scope, which grants the ability to read, create, and update test plans and related artifacts.
90+
91+
## Implementation Requirements
92+
93+
### Handler Parameters
94+
The `create_test_plan` handler should accept the following parameters:
95+
96+
| Parameter | Type | Required | Description |
97+
|-----------|------|----------|-------------|
98+
| organization | string | Yes | Azure DevOps organization name |
99+
| project | string | Yes | Project ID or name where the test plan will be created |
100+
| name | string | Yes | Name of the test plan |
101+
| description | string | No | Description of the test plan |
102+
| area_path | string | No | Area path for the test plan |
103+
| iteration_path | string | No | Iteration path for the test plan |
104+
| start_date | string | No | Start date in ISO format (YYYY-MM-DD) |
105+
| end_date | string | No | End date in ISO format (YYYY-MM-DD) |
106+
| state | string | No | State of the test plan (e.g., "Active", "Inactive") |
107+
| owner_id | string | No | ID of the test plan owner |
108+
| access_token | string | Yes | Azure DevOps PAT with appropriate permissions |
109+
110+
### Handler Behavior
111+
The handler should:
112+
113+
1. Validate all required parameters
114+
2. Format optional parameters correctly when provided
115+
3. Construct the API request with proper authentication
116+
4. Send the request to the Azure DevOps API
117+
5. Process the response and return appropriate results
118+
6. Handle errors and provide meaningful error messages
119+
120+
### Error Handling
121+
The handler should handle the following error scenarios:
122+
123+
1. Missing required parameters
124+
2. Invalid parameter formats (e.g., invalid date format)
125+
3. Authentication failures
126+
4. API request failures
127+
5. Rate limiting issues
128+
6. Network connectivity problems
129+
130+
## Implementation Strategy
131+
132+
### Step 1: Create the Handler File
133+
Create a new file for the handler in the appropriate location within the project structure.
134+
135+
### Step 2: Parameter Validation
136+
Implement validation for all parameters, ensuring:
137+
- Required parameters are present
138+
- Dates are in valid ISO format
139+
- Strings have appropriate lengths and formats
140+
141+
### Step 3: Request Construction
142+
Construct the API request with:
143+
- Properly formatted URL with organization and project
144+
- Required headers including authentication
145+
- JSON request body with all provided parameters
146+
147+
### Step 4: API Interaction
148+
Implement the API call using appropriate HTTP client libraries, handling:
149+
- Request timeouts
150+
- Response parsing
151+
- Error detection and handling
152+
153+
### Step 5: Response Processing
154+
Process the API response to:
155+
- Extract relevant information
156+
- Format the response consistently with other MCP handlers
157+
- Include necessary metadata
158+
159+
## Security Considerations
160+
1. **Token Handling**: Never log or expose access tokens
161+
2. **Input Validation**: Validate all inputs to prevent injection attacks
162+
3. **Error Messages**: Ensure error messages don't expose sensitive information
163+
4. **Access Control**: Implement appropriate access controls for the handler
164+
165+
## Example Usage
166+
```javascript
167+
// Example client code using the handler
168+
const result = await client.handlers.create_test_plan({
169+
organization: "my-organization",
170+
project: "my-project",
171+
name: "Sprint 27 Testing",
172+
description: "Testing for Sprint 27 features",
173+
area_path: "my-project\\Quality",
174+
iteration_path: "my-project\\Sprint 27",
175+
start_date: "2023-07-01",
176+
end_date: "2023-07-15",
177+
access_token: "PAT_TOKEN"
178+
});
179+
180+
console.log(`Created test plan with ID: ${result.id}`);
181+
```
182+
183+
## Related Documentation
184+
- [Azure DevOps Test Plans REST API](https://learn.microsoft.com/en-us/rest/api/azure/devops/test/test-plans)
185+
- [Azure DevOps Authentication](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate)
186+
- [Test Plan Management Best Practices](https://learn.microsoft.com/en-us/azure/devops/test/new-test-plans-page)
187+
188+
## Implementation Timeline
189+
Estimated development time: 2-3 days, including:
190+
- Initial implementation: 1 day
191+
- Testing and validation: 1 day
192+
- Documentation and code review: 0.5-1 day

0 commit comments

Comments
 (0)