Azure DevOps MCP Server

Instructions

Implementation Reference

• src/features/search/search-wiki/feature.ts:23-124 (handler)

  Core handler function that executes the wiki search using the Azure DevOps ALM search API, handling authentication, request preparation, and error wrapping.

  export async function searchWiki(
    connection: WebApi,
    options: SearchWikiOptions,
  ): Promise<WikiSearchResponse> {
    try {
      // Prepare the search request
      const searchRequest: WikiSearchRequest = {
        searchText: options.searchText,
        $skip: options.skip,
        $top: options.top,
        filters: options.projectId
          ? {
              Project: [options.projectId],
            }
          : {},
        includeFacets: options.includeFacets,
      };
  
      // Add custom filters if provided
      if (
        options.filters &&
        options.filters.Project &&
        options.filters.Project.length > 0
      ) {
        if (!searchRequest.filters) {
          searchRequest.filters = {};
        }
  
        if (!searchRequest.filters.Project) {
          searchRequest.filters.Project = [];
        }
  
        searchRequest.filters.Project = [
          ...(searchRequest.filters.Project || []),
          ...options.filters.Project,
        ];
      }
  
      // Get the authorization header from the connection
      const authHeader = await getAuthorizationHeader();
  
      // Extract organization and project from the connection URL
      const { organization, project } = extractOrgAndProject(
        connection,
        options.projectId,
      );
  
      // Make the search API request
      // If projectId is provided, include it in the URL, otherwise perform organization-wide search
      const searchUrl = options.projectId
        ? `https://almsearch.dev.azure.com/${organization}/${project}/_apis/search/wikisearchresults?api-version=7.1`
        : `https://almsearch.dev.azure.com/${organization}/_apis/search/wikisearchresults?api-version=7.1`;
  
      const searchResponse = await axios.post<WikiSearchResponse>(
        searchUrl,
        searchRequest,
        {
          headers: {
            Authorization: authHeader,
            'Content-Type': 'application/json',
          },
        },
      );
  
      return searchResponse.data;
    } catch (error) {
      // If it's already an AzureDevOpsError, rethrow it
      if (error instanceof AzureDevOpsError) {
        throw error;
      }
  
      // Handle axios errors
      if (axios.isAxiosError(error)) {
        const status = error.response?.status;
        const message = error.response?.data?.message || error.message;
  
        if (status === 404) {
          throw new AzureDevOpsResourceNotFoundError(
            `Resource not found: ${message}`,
          );
        } else if (status === 400) {
          throw new AzureDevOpsValidationError(
            `Invalid request: ${message}`,
            error.response?.data,
          );
        } else if (status === 401 || status === 403) {
          throw new AzureDevOpsPermissionError(`Permission denied: ${message}`);
        } else {
          // For other axios errors, wrap in a generic AzureDevOpsError
          throw new AzureDevOpsError(`Azure DevOps API error: ${message}`);
        }
  
        // This return is never reached but helps TypeScript understand the control flow
        return null as never;
      }
  
      // Otherwise, wrap it in a generic error
      throw new AzureDevOpsError(
        `Failed to search wiki: ${error instanceof Error ? error.message : String(error)}`,
      );
    }
  }

• src/features/search/schemas.ts:73-111 (schema)

  Zod schema for validating input arguments to the search_wiki tool.

  export const SearchWikiSchema = z.object({
    searchText: z.string().describe('The text to search for in wikis'),
    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({
        Project: z
          .array(z.string())
          .optional()
          .describe('Filter by project names'),
      })
      .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)'),
    includeFacets: z
      .boolean()
      .default(true)
      .describe('Whether to include faceting in results (default: true)'),
  });

• src/features/search/tool-definitions.ts:18-22 (registration)

  ToolDefinition object registering the search_wiki tool with its name, description, and input schema.

  {
    name: 'search_wiki',
    description: 'Search for content across wiki pages in a project',
    inputSchema: zodToJsonSchema(SearchWikiSchema),
  },

• src/features/search/index.ts:51-57 (registration)

  Dispatch handler in the search feature that routes search_wiki requests, parses arguments, calls the core handler, and formats the response.

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

• src/features/search/search-wiki/feature.ts:159-198 (helper)

  Helper function to obtain the authorization header for API calls using environment-based authentication.

  async function getAuthorizationHeader(): Promise<string> {
    try {
      // For PAT authentication, we can construct the header directly
      if (
        process.env.AZURE_DEVOPS_AUTH_METHOD?.toLowerCase() === 'pat' &&
        process.env.AZURE_DEVOPS_PAT
      ) {
        // For PAT auth, we can construct the Basic auth header directly
        const token = process.env.AZURE_DEVOPS_PAT;
        const base64Token = Buffer.from(`:${token}`).toString('base64');
        return `Basic ${base64Token}`;
      }
  
      // For Azure Identity / Azure CLI auth, we need to get a token
      // using the Azure DevOps resource ID
      // Choose the appropriate credential based on auth method
      const credential =
        process.env.AZURE_DEVOPS_AUTH_METHOD?.toLowerCase() === 'azure-cli'
          ? new AzureCliCredential()
          : new DefaultAzureCredential();
  
      // Azure DevOps resource ID for token acquisition
      const AZURE_DEVOPS_RESOURCE_ID = '499b84ac-1321-427f-aa17-267ca6975798';
  
      // Get token for Azure DevOps
      const token = await credential.getToken(
        `${AZURE_DEVOPS_RESOURCE_ID}/.default`,
      );
  
      if (!token || !token.token) {
        throw new Error('Failed to acquire token for Azure DevOps');
      }
  
      return `Bearer ${token.token}`;
    } catch (error) {
      throw new AzureDevOpsValidationError(
        `Failed to get authorization header: ${error instanceof Error ? error.message : String(error)}`,
      );
    }
  }