Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/repositories/get-repository-details/feature.ts:17-95 (handler)

  The core handler function implementing the get_repository_details tool. Fetches repository details from Azure DevOps Git API, optionally including branch statistics and refs.

  export async function getRepositoryDetails(
    connection: WebApi,
    options: GetRepositoryDetailsOptions,
  ): Promise<RepositoryDetails> {
    try {
      const gitApi = await connection.getGitApi();
  
      // Get the basic repository information
      const repository = await gitApi.getRepository(
        options.repositoryId,
        options.projectId,
      );
  
      if (!repository) {
        throw new AzureDevOpsResourceNotFoundError(
          `Repository '${options.repositoryId}' not found in project '${options.projectId}'`,
        );
      }
  
      // Initialize the response object
      const response: RepositoryDetails = {
        repository,
      };
  
      // Get branch statistics if requested
      if (options.includeStatistics) {
        let baseVersionDescriptor = undefined;
  
        // If a specific branch name is provided, create a version descriptor for it
        if (options.branchName) {
          baseVersionDescriptor = {
            version: options.branchName,
            versionType: GitVersionType.Branch,
          };
        }
  
        const branchStats = await gitApi.getBranches(
          repository.id || '',
          options.projectId,
          baseVersionDescriptor,
        );
  
        response.statistics = {
          branches: branchStats || [],
        };
      }
  
      // Get repository refs if requested
      if (options.includeRefs) {
        const filter = options.refFilter || undefined;
        const refs = await gitApi.getRefs(
          repository.id || '',
          options.projectId,
          filter,
        );
  
        if (refs) {
          response.refs = {
            value: refs,
            count: refs.length,
          };
        } else {
          response.refs = {
            value: [],
            count: 0,
          };
        }
      }
  
      return response;
    } catch (error) {
      if (error instanceof AzureDevOpsError) {
        throw error;
      }
      throw new Error(
        `Failed to get repository details: ${error instanceof Error ? error.message : String(error)}`,
      );
    }
  }

• src/features/repositories/schemas.ts:22-52 (schema)

  Zod schema defining the input parameters for the get_repository_details tool.

  export const GetRepositoryDetailsSchema = z.object({
    projectId: z
      .string()
      .optional()
      .describe(`The ID or name of the project (Default: ${defaultProject})`),
    organizationId: z
      .string()
      .optional()
      .describe(`The ID or name of the organization (Default: ${defaultOrg})`),
    repositoryId: z.string().describe('The ID or name of the repository'),
    includeStatistics: z
      .boolean()
      .optional()
      .default(false)
      .describe('Whether to include branch statistics'),
    includeRefs: z
      .boolean()
      .optional()
      .default(false)
      .describe('Whether to include repository refs'),
    refFilter: z
      .string()
      .optional()
      .describe('Optional filter for refs (e.g., "heads/" or "tags/")'),
    branchName: z
      .string()
      .optional()
      .describe(
        'Name of specific branch to get statistics for (if includeStatistics is true)',
      ),
  });

• src/features/repositories/tool-definitions.ts:25-29 (registration)

  Tool definition registration including name, description, and input schema for get_repository_details.

    name: 'get_repository_details',
    description:
      'Get detailed information about a repository including statistics and refs',
    inputSchema: zodToJsonSchema(GetRepositoryDetailsSchema),
  },

• src/features/repositories/index.ts:89-102 (registration)

  Request handler switch case that parses arguments and invokes the getRepositoryDetails handler for 'get_repository_details' tool calls.

  case 'get_repository_details': {
    const args = GetRepositoryDetailsSchema.parse(request.params.arguments);
    const result = await getRepositoryDetails(connection, {
      projectId: args.projectId ?? defaultProject,
      repositoryId: args.repositoryId,
      includeStatistics: args.includeStatistics,
      includeRefs: args.includeRefs,
      refFilter: args.refFilter,
      branchName: args.branchName,
    });
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }

• src/features/repositories/types.ts:19-40 (helper)

  TypeScript interfaces for input options and output response of the get_repository_details tool.

  export interface GetRepositoryDetailsOptions {
    projectId: string;
    repositoryId: string;
    includeStatistics?: boolean;
    includeRefs?: boolean;
    refFilter?: string;
    branchName?: string;
  }
  
  /**
   * Repository details response
   */
  export interface RepositoryDetails {
    repository: GitRepository;
    statistics?: {
      branches: GitBranchStats[];
    };
    refs?: {
      value: GitRef[];
      count: number;
    };
  }