@azure-devops/mcp 0.1.0 → 0.2.0-preview-oauth

package/dist/shared/tool-validation.js

@@ -0,0 +1,92 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+/**
+ * Validates that a name conforms to Claude API requirements.
+ * Names must match pattern: ^[a-zA-Z0-9_.-]{1,64}$
+ * @param name The name to validate
+ * @returns Object with isValid boolean and error/reason message if invalid
+ */
+export function validateName(name) {
+    // Check length
+    if (name.length === 0) {
+        return { isValid: false, error: "Name cannot be empty", reason: "name cannot be empty" };
+    }
+    if (name.length > 64) {
+        return {
+            isValid: false,
+            error: `Name '${name}' is ${name.length} characters long, maximum allowed is 64`,
+            reason: `name is ${name.length} characters long, maximum allowed is 64`,
+        };
+    }
+    // Check pattern: only alphanumeric, underscore, dot, and hyphen allowed
+    const validPattern = /^[a-zA-Z0-9_.-]+$/;
+    if (!validPattern.test(name)) {
+        return {
+            isValid: false,
+            error: `Name '${name}' contains invalid characters. Only alphanumeric characters, underscores, dots, and hyphens are allowed`,
+            reason: "name contains invalid characters. Only alphanumeric characters, underscores, dots, and hyphens are allowed",
+        };
+    }
+    return { isValid: true };
+}
+/**
+ * Validates that a tool name conforms to Claude API requirements.
+ * @param toolName The tool name to validate
+ * @returns Object with isValid boolean and error message if invalid
+ */
+export function validateToolName(toolName) {
+    const result = validateName(toolName);
+    if (!result.isValid) {
+        return { isValid: false, error: result.error?.replace("Name", "Tool name") };
+    }
+    return result;
+}
+/**
+ * Validates that a parameter name conforms to Claude API requirements.
+ * @param paramName The parameter name to validate
+ * @returns Object with isValid boolean and error message if invalid
+ */
+export function validateParameterName(paramName) {
+    const result = validateName(paramName);
+    if (!result.isValid) {
+        return { isValid: false, error: result.error?.replace("Name", "Parameter name") };
+    }
+    return result;
+}
+/**
+ * Extracts tool names from tool constant definitions
+ * @param fileContent - The content of a TypeScript file
+ * @returns Array of tool names found
+ */
+export function extractToolNames(fileContent) {
+    const toolNames = [];
+    // Pattern to match tool constant definitions in tool objects
+    // This looks for patterns like: const SOMETHING_TOOLS = { ... } or const Test_Plan_Tools = { ... }
+    const toolsObjectPattern = /const\s+\w*[Tt][Oo][Oo][Ll][Ss]?\s*=\s*\{([^}]+)\}/g;
+    let toolsMatch;
+    while ((toolsMatch = toolsObjectPattern.exec(fileContent)) !== null) {
+        const objectContent = toolsMatch[1];
+        // Now extract individual tool definitions from within the object
+        const toolPattern = /^\s*[a-zA-Z_][a-zA-Z0-9_]*:\s*"([^"]+)"/gm;
+        let match;
+        while ((match = toolPattern.exec(objectContent)) !== null) {
+            toolNames.push(match[1]);
+        }
+    }
+    return toolNames;
+}
+/**
+ * Extracts parameter names from Zod schema definitions
+ * @param fileContent - The content of a TypeScript file
+ * @returns Array of parameter names found
+ */
+export function extractParameterNames(fileContent) {
+    const paramNames = [];
+    // Pattern to match parameter definitions like: paramName: z.string()
+    const paramPattern = /^\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*:\s*z\./gm;
+    let match;
+    while ((match = paramPattern.exec(fileContent)) !== null) {
+        paramNames.push(match[1]);
+    }
+    return paramNames;
+}

package/dist/tenant.js

@@ -0,0 +1,73 @@
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+const CACHE_FILE = path.join(os.homedir(), '.ado_orgs.cache');
+const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 1 week in milliseconds
+async function loadCache() {
+    try {
+        const cacheData = await fs.readFile(CACHE_FILE, 'utf-8');
+        return JSON.parse(cacheData);
+    }
+    catch (error) {
+        // Cache file doesn't exist or is invalid, return empty cache
+        return {};
+    }
+}
+async function saveCache(cache) {
+    try {
+        await fs.writeFile(CACHE_FILE, JSON.stringify(cache, null, 2), 'utf-8');
+    }
+    catch (error) {
+        console.warn('Failed to save cache:', error);
+    }
+}
+async function fetchTenantFromApi(orgName) {
+    const url = `https://vssps.dev.azure.com/${orgName}`;
+    try {
+        const response = await fetch(url, { method: 'HEAD' });
+        if (response.status !== 404) {
+            throw new Error(`Expected status 404, got ${response.status}`);
+        }
+        const tenantId = response.headers.get('x-vss-resourcetenant');
+        if (!tenantId) {
+            throw new Error('x-vss-resourcetenant header not found in response');
+        }
+        return tenantId;
+    }
+    catch (error) {
+        throw new Error(`Failed to fetch tenant for organization ${orgName}: ${error}`);
+    }
+}
+function isCacheEntryExpired(entry) {
+    return Date.now() - entry.refreshedOn > CACHE_TTL_MS;
+}
+export async function getOrgTenant(orgName) {
+    // Load cache
+    const cache = await loadCache();
+    // Check if tenant is cached and not expired
+    const cachedEntry = cache[orgName];
+    if (cachedEntry && !isCacheEntryExpired(cachedEntry)) {
+        return cachedEntry.tenantId;
+    }
+    // Try to fetch fresh tenant from API
+    try {
+        const tenantId = await fetchTenantFromApi(orgName);
+        // Cache the fresh result
+        cache[orgName] = {
+            tenantId,
+            refreshedOn: Date.now()
+        };
+        await saveCache(cache);
+        return tenantId;
+    }
+    catch (error) {
+        // If we have an expired cache entry, return it as fallback
+        if (cachedEntry) {
+            console.error(`Failed to fetch fresh tenant for ADO org ${orgName}, using expired cache entry:`, error);
+            return cachedEntry.tenantId;
+        }
+        // No cache entry available, re-throw the error
+        console.error(`Failed to fetch tenant for ADO org ${orgName}:`, error);
+        return undefined;
+    }
+}

package/dist/tools/advanced-security.js

@@ -0,0 +1,108 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { AlertType, AlertValidityStatus, Confidence, Severity, State } from "azure-devops-node-api/interfaces/AlertInterfaces.js";
+import { z } from "zod";
+import { getEnumKeys, mapStringArrayToEnum, mapStringToEnum } from "../utils.js";
+const ADVSEC_TOOLS = {
+    get_alerts: "advsec_get_alerts",
+    get_alert_details: "advsec_get_alert_details",
+};
+function configureAdvSecTools(server, _, connectionProvider) {
+    server.tool(ADVSEC_TOOLS.get_alerts, "Retrieve Advanced Security alerts for a repository.", {
+        project: z.string().describe("The name or ID of the Azure DevOps project."),
+        repository: z.string().describe("The name or ID of the repository to get alerts for."),
+        alertType: z
+            .enum(getEnumKeys(AlertType))
+            .optional()
+            .describe("Filter alerts by type. If not specified, returns all alert types."),
+        states: z
+            .array(z.enum(getEnumKeys(State)))
+            .optional()
+            .describe("Filter alerts by state. If not specified, returns alerts in any state."),
+        severities: z
+            .array(z.enum(getEnumKeys(Severity)))
+            .optional()
+            .describe("Filter alerts by severity level. If not specified, returns alerts at any severity."),
+        ruleId: z.string().optional().describe("Filter alerts by rule ID."),
+        ruleName: z.string().optional().describe("Filter alerts by rule name."),
+        toolName: z.string().optional().describe("Filter alerts by tool name."),
+        ref: z.string().optional().describe("Filter alerts by git reference (branch). If not provided and onlyDefaultBranch is true, only includes alerts from default branch."),
+        onlyDefaultBranch: z.boolean().optional().default(true).describe("If true, only return alerts found on the default branch. Defaults to true."),
+        confidenceLevels: z
+            .array(z.enum(getEnumKeys(Confidence)))
+            .optional()
+            .default(["high", "other"])
+            .describe("Filter alerts by confidence levels. Only applicable for secret alerts. Defaults to both 'high' and 'other'."),
+        validity: z
+            .array(z.enum(getEnumKeys(AlertValidityStatus)))
+            .optional()
+            .describe("Filter alerts by validity status. Only applicable for secret alerts."),
+        top: z.number().optional().default(100).describe("Maximum number of alerts to return. Defaults to 100."),
+        orderBy: z.enum(["id", "firstSeen", "lastSeen", "fixedOn", "severity"]).optional().default("severity").describe("Order results by specified field. Defaults to 'severity'."),
+        continuationToken: z.string().optional().describe("Continuation token for pagination."),
+    }, async ({ project, repository, alertType, states, severities, ruleId, ruleName, toolName, ref, onlyDefaultBranch, confidenceLevels, validity, top, orderBy, continuationToken }) => {
+        try {
+            const connection = await connectionProvider();
+            const alertApi = await connection.getAlertApi();
+            const isSecretAlert = !alertType || alertType.toLowerCase() === "secret";
+            const criteria = {
+                ...(alertType && { alertType: mapStringToEnum(alertType, AlertType) }),
+                ...(states && { states: mapStringArrayToEnum(states, State) }),
+                ...(severities && { severities: mapStringArrayToEnum(severities, Severity) }),
+                ...(ruleId && { ruleId }),
+                ...(ruleName && { ruleName }),
+                ...(toolName && { toolName }),
+                ...(ref && { ref }),
+                ...(onlyDefaultBranch !== undefined && { onlyDefaultBranch }),
+                ...(isSecretAlert && confidenceLevels && { confidenceLevels: mapStringArrayToEnum(confidenceLevels, Confidence) }),
+                ...(isSecretAlert && validity && { validity: mapStringArrayToEnum(validity, AlertValidityStatus) }),
+            };
+            const result = await alertApi.getAlerts(project, repository, top, orderBy, criteria, undefined, // expand parameter
+            continuationToken);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error fetching Advanced Security alerts: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool(ADVSEC_TOOLS.get_alert_details, "Get detailed information about a specific Advanced Security alert.", {
+        project: z.string().describe("The name or ID of the Azure DevOps project."),
+        repository: z.string().describe("The name or ID of the repository containing the alert."),
+        alertId: z.number().describe("The ID of the alert to retrieve details for."),
+        ref: z.string().optional().describe("Git reference (branch) to filter the alert."),
+    }, async ({ project, repository, alertId, ref }) => {
+        try {
+            const connection = await connectionProvider();
+            const alertApi = await connection.getAlertApi();
+            const result = await alertApi.getAlert(project, alertId, repository, ref, undefined // expand parameter
+            );
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error fetching alert details: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+export { ADVSEC_TOOLS, configureAdvSecTools };

package/dist/tools/advsec.js

@@ -0,0 +1,108 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { AlertType, AlertValidityStatus, Confidence, Severity, State } from "azure-devops-node-api/interfaces/AlertInterfaces.js";
+import { z } from "zod";
+import { getEnumKeys, mapStringArrayToEnum, mapStringToEnum } from "../utils.js";
+const ADVSEC_TOOLS = {
+    get_alerts: "advsec_get_alerts",
+    get_alert_details: "advsec_get_alert_details",
+};
+function configureAdvSecTools(server, tokenProvider, connectionProvider) {
+    server.tool(ADVSEC_TOOLS.get_alerts, "Retrieve Advanced Security alerts for a repository.", {
+        project: z.string().describe("The name or ID of the Azure DevOps project."),
+        repository: z.string().describe("The name or ID of the repository to get alerts for."),
+        alertType: z
+            .enum(getEnumKeys(AlertType))
+            .optional()
+            .describe("Filter alerts by type. If not specified, returns all alert types."),
+        states: z
+            .array(z.enum(getEnumKeys(State)))
+            .optional()
+            .describe("Filter alerts by state. If not specified, returns alerts in any state."),
+        severities: z
+            .array(z.enum(getEnumKeys(Severity)))
+            .optional()
+            .describe("Filter alerts by severity level. If not specified, returns alerts at any severity."),
+        ruleId: z.string().optional().describe("Filter alerts by rule ID."),
+        ruleName: z.string().optional().describe("Filter alerts by rule name."),
+        toolName: z.string().optional().describe("Filter alerts by tool name."),
+        ref: z.string().optional().describe("Filter alerts by git reference (branch). If not provided and onlyDefaultBranch is true, only includes alerts from default branch."),
+        onlyDefaultBranch: z.boolean().optional().default(true).describe("If true, only return alerts found on the default branch. Defaults to true."),
+        confidenceLevels: z
+            .array(z.enum(getEnumKeys(Confidence)))
+            .optional()
+            .default(["high", "other"])
+            .describe("Filter alerts by confidence levels. Only applicable for secret alerts. Defaults to both 'high' and 'other'."),
+        validity: z
+            .array(z.enum(getEnumKeys(AlertValidityStatus)))
+            .optional()
+            .describe("Filter alerts by validity status. Only applicable for secret alerts."),
+        top: z.number().optional().default(100).describe("Maximum number of alerts to return. Defaults to 100."),
+        orderBy: z.enum(["id", "firstSeen", "lastSeen", "fixedOn", "severity"]).optional().default("severity").describe("Order results by specified field. Defaults to 'severity'."),
+        continuationToken: z.string().optional().describe("Continuation token for pagination."),
+    }, async ({ project, repository, alertType, states, severities, ruleId, ruleName, toolName, ref, onlyDefaultBranch, confidenceLevels, validity, top, orderBy, continuationToken }) => {
+        try {
+            const connection = await connectionProvider();
+            const alertApi = await connection.getAlertApi();
+            const isSecretAlert = !alertType || alertType.toLowerCase() === "secret";
+            const criteria = {
+                ...(alertType && { alertType: mapStringToEnum(alertType, AlertType) }),
+                ...(states && { states: mapStringArrayToEnum(states, State) }),
+                ...(severities && { severities: mapStringArrayToEnum(severities, Severity) }),
+                ...(ruleId && { ruleId }),
+                ...(ruleName && { ruleName }),
+                ...(toolName && { toolName }),
+                ...(ref && { ref }),
+                ...(onlyDefaultBranch !== undefined && { onlyDefaultBranch }),
+                ...(isSecretAlert && confidenceLevels && { confidenceLevels: mapStringArrayToEnum(confidenceLevels, Confidence) }),
+                ...(isSecretAlert && validity && { validity: mapStringArrayToEnum(validity, AlertValidityStatus) }),
+            };
+            const result = await alertApi.getAlerts(project, repository, top, orderBy, criteria, undefined, // expand parameter
+            continuationToken);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error fetching Advanced Security alerts: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool(ADVSEC_TOOLS.get_alert_details, "Get detailed information about a specific Advanced Security alert.", {
+        project: z.string().describe("The name or ID of the Azure DevOps project."),
+        repository: z.string().describe("The name or ID of the repository containing the alert."),
+        alertId: z.number().describe("The ID of the alert to retrieve details for."),
+        ref: z.string().optional().describe("Git reference (branch) to filter the alert."),
+    }, async ({ project, repository, alertId, ref }) => {
+        try {
+            const connection = await connectionProvider();
+            const alertApi = await connection.getAlertApi();
+            const result = await alertApi.getAlert(project, alertId, repository, ref, undefined // expand parameter
+            );
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error fetching alert details: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+export { ADVSEC_TOOLS, configureAdvSecTools };

package/dist/tools/auth.js

@@ -1,14 +1,16 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
-async function getCurrentUserDetails(tokenProvider, connectionProvider) {
+import { apiVersion } from "../utils.js";
+async function getCurrentUserDetails(tokenProvider, connectionProvider, userAgentProvider) {
     const connection = await connectionProvider();
     const url = `${connection.serverUrl}/_apis/connectionData`;
-    const token = (await tokenProvider()).token;
+    const token = await tokenProvider();
     const response = await fetch(url, {
         method: "GET",
         headers: {
-            Authorization: `Bearer ${token}`,
+            "Authorization": `Bearer ${token}`,
             "Content-Type": "application/json",
+            "User-Agent": userAgentProvider(),
         },
     });
     const data = await response.json();
@@ -17,4 +19,44 @@ async function getCurrentUserDetails(tokenProvider, connectionProvider) {
     }
     return data;
 }
-export { getCurrentUserDetails };
+/**
+ * Searches for identities using Azure DevOps Identity API
+ */
+async function searchIdentities(identity, tokenProvider, connectionProvider, userAgentProvider) {
+    const token = await tokenProvider();
+    const connection = await connectionProvider();
+    const orgName = connection.serverUrl.split("/")[3];
+    const baseUrl = `https://vssps.dev.azure.com/${orgName}/_apis/identities`;
+    const params = new URLSearchParams({
+        "api-version": apiVersion,
+        "searchFilter": "General",
+        "filterValue": identity,
+    });
+    const response = await fetch(`${baseUrl}?${params}`, {
+        headers: {
+            "Authorization": `Bearer ${token}`,
+            "Content-Type": "application/json",
+            "User-Agent": userAgentProvider(),
+        },
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`HTTP ${response.status}: ${errorText}`);
+    }
+    return await response.json();
+}
+/**
+ * Gets the user ID from email or unique name using Azure DevOps Identity API
+ */
+async function getUserIdFromEmail(userEmail, tokenProvider, connectionProvider, userAgentProvider) {
+    const identities = await searchIdentities(userEmail, tokenProvider, connectionProvider, userAgentProvider);
+    if (!identities || identities.value?.length === 0) {
+        throw new Error(`No user found with email/unique name: ${userEmail}`);
+    }
+    const firstIdentity = identities.value[0];
+    if (!firstIdentity.id) {
+        throw new Error(`No ID found for user with email/unique name: ${userEmail}`);
+    }
+    return firstIdentity.id;
+}
+export { getCurrentUserDetails, getUserIdFromEmail, searchIdentities };