Azure DevOps MCP Server

Instructions

Implementation Reference

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

  Primary handler function implementing the get_repository_tree tool logic: fetches repository details, retrieves git items recursively, filters by depth, and constructs a tree structure with stats.

  export async function getRepositoryTree(
    connection: WebApi,
    options: GetRepositoryTreeOptions,
  ): Promise<RepositoryTreeResponse> {
    try {
      const gitApi = await connection.getGitApi();
  
      const repository = await gitApi.getRepository(
        options.repositoryId,
        options.projectId,
      );
      if (!repository || !repository.id) {
        throw new AzureDevOpsError(
          `Repository '${options.repositoryId}' not found in project '${options.projectId}'`,
        );
      }
  
      const defaultBranch = repository.defaultBranch;
      if (!defaultBranch) {
        throw new AzureDevOpsError('Default branch not found');
      }
      const branchRef = defaultBranch.replace('refs/heads/', '');
  
      const rootPath = options.path ?? '/';
      const items = await gitApi.getItems(
        repository.id,
        options.projectId,
        rootPath,
        VersionControlRecursionType.Full,
        true,
        false,
        false,
        false,
        {
          version: branchRef,
          versionType: GitVersionType.Branch,
        },
      );
  
      const treeItems: RepositoryTreeItem[] = [];
      const stats = { directories: 0, files: 0 };
  
      for (const item of items) {
        const path = item.path || '';
        if (path === rootPath || item.gitObjectType === GitObjectType.Bad) {
          continue;
        }
        const relative =
          rootPath === '/'
            ? path.replace(/^\//, '')
            : path.slice(rootPath.length + 1);
        const level = relative.split('/').length;
        if (options.depth && options.depth > 0 && level > options.depth) {
          continue;
        }
        const isFolder = !!item.isFolder;
        treeItems.push({
          name: relative.split('/').pop() || '',
          path,
          isFolder,
          level,
        });
        if (isFolder) stats.directories++;
        else stats.files++;
      }
  
      return {
        name: repository.name || options.repositoryId,
        tree: treeItems,
        stats,
      };
    } catch (error) {
      if (error instanceof AzureDevOpsError) {
        throw error;
      }
      throw new Error(
        `Failed to get repository tree: ${error instanceof Error ? error.message : String(error)}`,
      );
    }
  }

• src/features/repositories/schemas.ts:141-164 (schema)

  Zod input schema for validating arguments to the get_repository_tree tool.

  export const GetRepositoryTreeSchema = 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'),
    path: z
      .string()
      .optional()
      .default('/')
      .describe('Path within the repository to start from'),
    depth: z
      .number()
      .int()
      .min(0)
      .max(10)
      .optional()
      .default(0)
      .describe('Maximum depth to traverse (0 = unlimited)'),
  });

• src/features/repositories/tool-definitions.ts:46-51 (registration)

  MCP tool registration definition including name, description, and JSON schema derived from Zod schema.

  {
    name: 'get_repository_tree',
    description:
      'Displays a hierarchical tree view of files and directories within a single repository starting from an optional path',
    inputSchema: zodToJsonSchema(GetRepositoryTreeSchema),
  },

• src/features/repositories/index.ts:165-179 (handler)

  Dispatcher handler case in handleRepositoriesRequest that validates input with schema and invokes the specific getRepositoryTree handler.

  case 'get_repository_tree': {
    const args = GetRepositoryTreeSchema.parse(request.params.arguments);
    const result = await getRepositoryTree(connection, {
      ...args,
      projectId: args.projectId ?? defaultProject,
    });
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/features/repositories/types.ts:56-67 (schema)

  TypeScript interface defining input options for the getRepositoryTree handler function.

  export interface GetRepositoryTreeOptions {
    projectId: string;
    repositoryId: string;
    /**
     * Path within the repository to start from. Defaults to '/'
     */
    path?: string;
    /**
     * Maximum depth to traverse (0 = unlimited)
     */
    depth?: number;
  }