Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/search/search-code/feature.ts:26-122 (handler)

  Core handler function that executes the code search logic using Azure DevOps Code Search API, handles authentication, fetches results, and optionally enriches with file contents.

  export async function searchCode(
    connection: WebApi,
    options: SearchCodeOptions,
  ): Promise<CodeSearchResponse> {
    try {
      // When includeContent is true, limit results to prevent timeouts
      const top = options.includeContent
        ? Math.min(options.top || 10, 10)
        : options.top;
  
      // Get the project ID (either provided or default)
      const projectId =
        options.projectId || process.env.AZURE_DEVOPS_DEFAULT_PROJECT;
  
      if (!projectId) {
        throw new AzureDevOpsValidationError(
          'Project ID is required. Either provide a projectId or set the AZURE_DEVOPS_DEFAULT_PROJECT environment variable.',
        );
      }
  
      // Prepare the search request
      const searchRequest: CodeSearchRequest = {
        searchText: options.searchText,
        $skip: options.skip,
        $top: top, // Use limited top value when includeContent is true
        filters: {
          Project: [projectId],
          ...(options.filters || {}),
        },
        includeFacets: true,
        includeSnippet: options.includeSnippet,
      };
  
      // Get the authorization header from the connection
      const authHeader = await getAuthorizationHeader();
  
      // Extract organization from the connection URL
      const { organization } = extractOrgFromUrl(connection);
  
      // Make the search API request with the project ID
      const searchUrl = `https://almsearch.dev.azure.com/${organization}/${projectId}/_apis/search/codesearchresults?api-version=7.1`;
  
      const searchResponse = await axios.post<CodeSearchResponse>(
        searchUrl,
        searchRequest,
        {
          headers: {
            Authorization: authHeader,
            'Content-Type': 'application/json',
          },
        },
      );
  
      const results = searchResponse.data;
  
      // If includeContent is true, fetch the content for each result
      if (options.includeContent && results.results.length > 0) {
        await enrichResultsWithContent(connection, results.results);
      }
  
      return results;
    } catch (error) {
      if (error instanceof AzureDevOpsError) {
        throw error;
      }
  
      if (axios.isAxiosError(error)) {
        const status = error.response?.status;
        if (status === 404) {
          throw new AzureDevOpsResourceNotFoundError(
            'Repository or project not found',
            { cause: error },
          );
        }
        if (status === 400) {
          throw new AzureDevOpsValidationError(
            'Invalid search parameters',
            error.response?.data,
            { cause: error },
          );
        }
        if (status === 401) {
          throw new AzureDevOpsAuthenticationError('Authentication failed', {
            cause: error,
          });
        }
        if (status === 403) {
          throw new AzureDevOpsPermissionError(
            'Permission denied to access repository',
            { cause: error },
          );
        }
      }
  
      throw new AzureDevOpsError('Failed to search code', { cause: error });
    }
  }

• src/features/search/schemas.ts:7-68 (schema)

  Zod schema defining input validation and defaults for the search_code tool parameters.

  export const SearchCodeSchema = z
    .object({
      searchText: z.string().describe('The text to search for'),
      organizationId: z
        .string()
        .optional()
        .describe(`The ID or name of the organization (Default: ${defaultOrg})`),
      projectId: z
        .string()
        .optional()
        .describe(
          `The ID or name of the project to search in (Default: ${defaultProject}). If not provided, the default project will be used.`,
        ),
      filters: z
        .object({
          Repository: z
            .array(z.string())
            .optional()
            .describe('Filter by repository names'),
          Path: z.array(z.string()).optional().describe('Filter by file paths'),
          Branch: z
            .array(z.string())
            .optional()
            .describe('Filter by branch names'),
          CodeElement: z
            .array(z.string())
            .optional()
            .describe('Filter by code element types (function, class, etc.)'),
        })
        .optional()
        .describe('Optional filters to narrow search results'),
      top: z
        .number()
        .int()
        .min(1)
        .max(1000)
        .default(100)
        .describe('Number of results to return (default: 100, max: 1000)'),
      skip: z
        .number()
        .int()
        .min(0)
        .default(0)
        .describe('Number of results to skip for pagination (default: 0)'),
      includeSnippet: z
        .boolean()
        .default(true)
        .describe('Whether to include code snippets in results (default: true)'),
      includeContent: z
        .boolean()
        .default(true)
        .describe(
          'Whether to include full file content in results (default: true)',
        ),
    })
    .transform((data) => {
      return {
        ...data,
        organizationId: data.organizationId ?? defaultOrg,
        projectId: data.projectId ?? defaultProject,
      };
    });

• src/features/search/tool-definitions.ts:12-28 (registration)

  Tool definition registration for search_code, including name, description, and JSON schema derived from Zod schema.

  export const searchTools: ToolDefinition[] = [
    {
      name: 'search_code',
      description: 'Search for code across repositories in a project',
      inputSchema: zodToJsonSchema(SearchCodeSchema),
    },
    {
      name: 'search_wiki',
      description: 'Search for content across wiki pages in a project',
      inputSchema: zodToJsonSchema(SearchWikiSchema),
    },
    {
      name: 'search_work_items',
      description: 'Search for work items across projects in Azure DevOps',
      inputSchema: zodToJsonSchema(SearchWorkItemsSchema),
    },
  ];

• src/features/search/index.ts:44-50 (registration)

  Request handler switch case that parses arguments with schema and calls the searchCode handler for 'search_code' tool.

  case 'search_code': {
    const args = SearchCodeSchema.parse(request.params.arguments);
    const result = await searchCode(connection, args);
    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
    };
  }

• src/features/search/types.ts:4-17 (schema)

  TypeScript interface defining the options structure for the searchCode function, used in handler.

  export interface SearchCodeOptions {
    searchText: string;
    projectId?: string;
    filters?: {
      Repository?: string[];
      Path?: string[];
      Branch?: string[];
      CodeElement?: string[];
    };
    top?: number;
    skip?: number;
    includeSnippet?: boolean;
    includeContent?: boolean;
  }