Skip to content
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.

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

Implement get_project_details core functionality #101

Closed
8 tasks
Tiberriver256 opened this issue Apr 1, 2025 · 0 comments · Fixed by #111, #115 or #116
Closed
8 tasks

Implement get_project_details core functionality #101

Tiberriver256 opened this issue Apr 1, 2025 · 0 comments · Fixed by #111, #115 or #116

Comments

@Tiberriver256
Copy link
Owner

Tiberriver256 commented Apr 1, 2025

Overview

Implement a handler for the get_project_details functionality, which will fetch comprehensive information about a specific Azure DevOps project, including metadata, process information, work item types, fields, and team information.

Background

Advanced project management operations in Azure DevOps require detailed project information beyond basic metadata. Clients need a comprehensive view of a project, including its capabilities (such as process template & version control), work item structure, and teams. This handler will provide a single endpoint for retrieving all relevant project details.

Requirements

Core Functionality

The get_project_details handler should:

  1. Retrieve a specific project by ID or name from the Azure DevOps organization
  2. Include detailed project information such as:
    • Basic project metadata (id, name, url, etc.)
    • Process information (which process the project follows)
    • Work item types available in the project
    • Work item type hierarchy and organization
    • Fields applicable to each work item type
    • Project teams
  3. Accept parameters for customizing the level of detail returned
  4. Handle errors gracefully, with appropriate status codes and error messages

API Details

Primary Endpoint

GET https://dev.azure.com/{organization}/_apis/projects/{projectId}?api-version=7.1

Process and Work Item Type Endpoints

GET https://dev.azure.com/{organization}/_apis/work/processes/{processId}/workitemtypes?$expand=States&api-version=7.1

Secondary Endpoints (for additional details)

GET https://dev.azure.com/{organization}/_apis/projects/{projectId}/teams?api-version=7.1

Parameters

Parameter Type Required Description
projectId string Yes The ID or name of the project to retrieve
includeProcess boolean No Include process information in the project result
includeWorkItemTypes boolean No Include work item types and their structure
includeFields boolean No Include field information for work item types
includeTeams boolean No Include associated teams in the project result
expandTeamIdentity boolean No Expand identity information in the team objects

Expected Response Format

{
  "id": "project-guid",
  "name": "Project Name",
  "description": "Project description",
  "url": "https://dev.azure.com/organization/Project%20Name",
  "state": "wellFormed",
  "revision": 123,
  "visibility": "private",
  "lastUpdateTime": "2023-01-01T12:00:00.000Z",
  "capabilities": {
    "versioncontrol": {
      "sourceControlType": "Git"
    },
    "processTemplate": {
      "templateName": "Agile",
      "templateTypeId": "template-guid"
    }
  },
  "process": {
    "name": "Agile",
    "workItemTypes": [
      {
        "name": "User Story",
        "description": "Tracks user requirements",
        "states": [
          {
            "name": "New",
            "stateCategory": "Proposed"
          },
          {
            "name": "Active",
            "stateCategory": "InProgress"
          },
          {
            "name": "Resolved",
            "stateCategory": "InProgress"
          },
          {
            "name": "Closed",
            "stateCategory": "Completed"
          }
        ],
        "fields": [
          {
            "name": "Title",
            "referenceName": "System.Title",
            "type": "string",
            "required": true
          },
          {
            "name": "Description",
            "referenceName": "System.Description",
            "type": "html"
          }
        ]
      },
      {
        "name": "Bug",
        "description": "Tracks defects in the product"
      },
      {
        "name": "Task",
        "description": "Tracks work that needs to be done"
      }
    ],
    "hierarchyInfo": {
      "portfolioBacklogs": [
        {
          "name": "Epics",
          "workItemTypes": ["Epic"]
        },
        {
          "name": "Features",
          "workItemTypes": ["Feature"]
        }
      ],
      "requirementBacklog": {
        "name": "Stories",
        "workItemTypes": ["User Story", "Bug"]
      },
      "taskBacklog": {
        "name": "Tasks",
        "workItemTypes": ["Task"]
      }
    }
  },
  "defaultTeam": {
    "id": "team-guid",
    "name": "Project Team",
    "url": "https://dev.azure.com/organization/_apis/projects/project-guid/teams/team-guid"
  },
  "teams": [
    {
      "id": "team-guid-1",
      "name": "Team 1",
      "description": "First team",
      "url": "https://dev.azure.com/organization/_apis/projects/project-guid/teams/team-guid-1",
      "identityUrl": "https://vssps.dev.azure.com/organization/_apis/Identities/team-guid-1"
    },
    {
      "id": "team-guid-2",
      "name": "Team 2",
      "description": "Second team",
      "url": "https://dev.azure.com/organization/_apis/projects/project-guid/teams/team-guid-2",
      "identityUrl": "https://vssps.dev.azure.com/organization/_apis/Identities/team-guid-2"
    }
  ]
}

Implementation Notes

Project Structure Changes

The handler should be implemented in:

  • src/features/projects/get-project-details/feature.ts - Core implementation
  • src/features/projects/get-project-details/schema.ts - Request/response schema
  • src/features/projects/get-project-details/index.ts - Export

The handler should be registered in src/server.ts with the name mcp_azuredevops_get_project_details.

Error Handling

The handler should handle the following error scenarios:

  • Project not found (404)
  • Authentication errors (401)
  • Permission errors (403)
  • Other API errors (with appropriate status codes)

Error messages should be descriptive and follow existing error message patterns.

Security Considerations

The handler must respect Azure DevOps permissions and only return project information that the authenticated user has access to view.

Example Usage

// Basic usage
const projectDetails = await mcpClient.callTool('mcp_azuredevops_get_project_details', {
  projectId: 'MyProject'
});

// With additional options
const detailedProject = await mcpClient.callTool('mcp_azuredevops_get_project_details', {
  projectId: 'MyProject',
  includeProcess: true,
  includeWorkItemTypes: true,
  includeFields: true,
  includeTeams: true,
  expandTeamIdentity: true
});

Resources

Acceptance Criteria

  • Implement a handler that retrieves detailed project information
  • Include process information in the response
  • Include work item types, states, and fields when requested
  • Provide information about the work item hierarchy (portfolio, requirements, tasks)
  • Return associated teams when requested
  • Handle all error scenarios gracefully
  • Write unit and integration tests for the new handler
  • Update documentation with the new handler details
Tiberriver256 pushed a commit that referenced this issue Apr 2, 2025
Implements handler for detailed project information including process, work item types, and teams.

Closes #101
Tiberriver256 pushed a commit that referenced this issue Apr 2, 2025
Implements handler for detailed project information including process, work item types, and teams.

Closes #101
Tiberriver256 pushed a commit that referenced this issue Apr 2, 2025
Implements handler for detailed project information including process, work item types, and teams.

Closes #101
Tiberriver256 pushed a commit that referenced this issue Apr 2, 2025
Implements handler for detailed project information including process, work item types, and teams.

Closes #101
Tiberriver256 pushed a commit that referenced this issue Apr 2, 2025
Implements handler for detailed project information including process, work item types, and teams.

Closes #101
Tiberriver256 pushed a commit that referenced this issue Apr 2, 2025
Implements handler for detailed project information including process, work item types, and teams.

Closes #101
Tiberriver256 pushed a commit that referenced this issue Apr 2, 2025
Implements handler for detailed project information including process, work item types, and teams.

Closes #101
Tiberriver256 pushed a commit that referenced this issue Apr 2, 2025
Implements handler for detailed project information including process, work item types, and teams.

Closes #101
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment