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

package/dist/auth.js

@@ -0,0 +1,74 @@
+import { AzureCliCredential, ChainedTokenCredential, DefaultAzureCredential } from "@azure/identity";
+import { PublicClientApplication } from "@azure/msal-node";
+import open from "open";
+const scopes = ["499b84ac-1321-427f-aa17-267ca6975798/.default"];
+class OAuthAuthenticator {
+    static clientId = "0d50963b-7bb9-4fe7-94c7-a99af00b5136";
+    static defaultAuthority = "https://login.microsoftonline.com/common";
+    accountId;
+    publicClientApp;
+    constructor(tenantId) {
+        this.accountId = null;
+        this.publicClientApp = new PublicClientApplication({
+            auth: {
+                clientId: OAuthAuthenticator.clientId,
+                authority: tenantId ? `https://login.microsoftonline.com/${tenantId}` : OAuthAuthenticator.defaultAuthority,
+            },
+        });
+    }
+    async getToken() {
+        let authResult = null;
+        if (this.accountId) {
+            try {
+                authResult = await this.publicClientApp.acquireTokenSilent({
+                    scopes,
+                    account: this.accountId,
+                });
+            }
+            catch (error) {
+                authResult = null;
+            }
+        }
+        if (!authResult) {
+            authResult = await this.publicClientApp.acquireTokenInteractive({
+                scopes,
+                openBrowser: async (url) => {
+                    open(url);
+                },
+            });
+            this.accountId = authResult.account;
+        }
+        if (!authResult.accessToken) {
+            throw new Error("Failed to obtain Azure DevOps OAuth token.");
+        }
+        return authResult.accessToken;
+    }
+}
+function createAuthenticator(type, tenantId) {
+    switch (type) {
+        case "azcli":
+        case "env":
+            if (type !== "env") {
+                process.env.AZURE_TOKEN_CREDENTIALS = "dev";
+            }
+            let credential = new DefaultAzureCredential(); // CodeQL [SM05138] resolved by explicitly setting AZURE_TOKEN_CREDENTIALS
+            if (tenantId) {
+                // Use Azure CLI credential if tenantId is provided for multi-tenant scenarios
+                const azureCliCredential = new AzureCliCredential({ tenantId });
+                credential = new ChainedTokenCredential(azureCliCredential, credential);
+            }
+            return async () => {
+                const result = await credential.getToken(scopes);
+                if (!result) {
+                    throw new Error("Failed to obtain Azure DevOps token. Ensure you have Azure CLI logged or use interactive type of authentication.");
+                }
+                return result.token;
+            };
+        default:
+            const authenticator = new OAuthAuthenticator(tenantId);
+            return () => {
+                return authenticator.getToken();
+            };
+    }
+}
+export { createAuthenticator };

package/dist/domains.js

@@ -0,0 +1 @@
+export {};

package/dist/http.js

@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import express from "express";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { serverBuildAndConnect } from "./server.js";
+import { packageVersion } from "./version.js";
+const app = express();
+app.use(express.json());
+app.post('/mcp/:orgName', async (req, res) => {
+    // In stateless mode, create a new instance of transport and server for each request
+    // to ensure complete isolation. A single instance would cause request ID collisions
+    // when multiple clients connect concurrently.
+    try {
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        const server = await serverBuildAndConnect(req.params.orgName, transport);
+        res.on('close', () => {
+            transport.close();
+            server.close();
+        });
+        await transport.handleRequest(req, res, req.body);
+    }
+    catch (error) {
+        console.error('Error handling MCP request:', error);
+        if (!res.headersSent) {
+            res.status(500).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32603,
+                    message: 'Internal server error',
+                },
+                id: null,
+            });
+        }
+    }
+});
+app.get('/mcp/:orgName', async (req, res) => {
+    console.log('Received GET MCP request');
+    res.writeHead(405).end(JSON.stringify({
+        jsonrpc: "2.0",
+        error: {
+            code: -32000,
+            message: "Method not allowed."
+        },
+        id: null
+    }));
+});
+const PORT = 3000;
+app.listen(PORT, () => {
+    console.log(`Azure DevOps MCP Server with http transport listening on port ${PORT}. Version: ${packageVersion}`);
+});

package/dist/index.js

@@ -4,46 +4,79 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import * as azdev from "azure-devops-node-api";
-import { DefaultAzureCredential } from "@azure/identity";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { createAuthenticator } from "./auth.js";
+import { getOrgTenant } from "./org-tenants.js";
 import { configurePrompts } from "./prompts.js";
 import { configureAllTools } from "./tools.js";
-import { userAgent } from "./utils.js";
+import { UserAgentComposer } from "./useragent.js";
 import { packageVersion } from "./version.js";
-const args = process.argv.slice(2);
-if (args.length === 0) {
-    console.error("Usage: mcp-server-azuredevops <organization_name>");
-    process.exit(1);
-}
-export const orgName = args[0];
-const orgUrl = "https://dev.azure.com/" + orgName;
-async function getAzureDevOpsToken() {
-    process.env.AZURE_TOKEN_CREDENTIALS = "dev";
-    const credential = new DefaultAzureCredential(); // CodeQL [SM05138] resolved by explicitly setting AZURE_TOKEN_CREDENTIALS
-    const token = await credential.getToken("499b84ac-1321-427f-aa17-267ca6975798/.default");
-    return token;
-}
-async function getAzureDevOpsClient() {
-    const token = await getAzureDevOpsToken();
-    const authHandler = azdev.getBearerHandler(token.token);
-    const connection = new azdev.WebApi(orgUrl, authHandler, undefined, {
-        productName: "AzureDevOps.MCP",
-        productVersion: packageVersion,
-        userAgent: userAgent
+import { DomainsManager } from "./shared/domains.js";
+// Parse command line arguments using yargs
+const argv = yargs(hideBin(process.argv))
+    .scriptName("mcp-server-azuredevops")
+    .usage("Usage: $0 <organization> [options]")
+    .version(packageVersion)
+    .command("$0 <organization> [options]", "Azure DevOps MCP Server", (yargs) => {
+    yargs.positional("organization", {
+        describe: "Azure DevOps organization name",
+        type: "string",
+        demandOption: true,
     });
-    return connection;
+})
+    .option("domains", {
+    alias: "d",
+    describe: "Domain(s) to enable: 'all' for everything, or specific domains like 'repositories builds work'. Defaults to 'all'.",
+    type: "string",
+    array: true,
+    default: "all",
+})
+    .option("authentication", {
+    alias: "a",
+    describe: "Type of authentication to use. Supported values are 'interactive', 'azcli' and 'env' (default: 'interactive')",
+    type: "string",
+    choices: ["interactive", "azcli", "env"],
+    default: "interactive",
+})
+    .option("tenant", {
+    alias: "t",
+    describe: "Azure tenant ID (optional, applied when using 'interactive' and 'azcli' type of authentication)",
+    type: "string",
+})
+    .help()
+    .parseSync();
+export const orgName = argv.organization;
+const orgUrl = "https://dev.azure.com/" + orgName;
+const domainsManager = new DomainsManager(argv.domains);
+export const enabledDomains = domainsManager.getEnabledDomains();
+function getAzureDevOpsClient(getAzureDevOpsToken, userAgentComposer) {
+    return async () => {
+        const accessToken = await getAzureDevOpsToken();
+        const authHandler = azdev.getBearerHandler(accessToken);
+        const connection = new azdev.WebApi(orgUrl, authHandler, undefined, {
+            productName: "AzureDevOps.MCP",
+            productVersion: packageVersion,
+            userAgent: userAgentComposer.userAgent,
+        });
+        return connection;
+    };
 }
 async function main() {
-    console.error("Starting Azure DevOps MCP Server...");
     const server = new McpServer({
         name: "Azure DevOps MCP Server",
-        version: "1.0.0",
+        version: packageVersion,
     });
+    const userAgentComposer = new UserAgentComposer(packageVersion);
+    server.server.oninitialized = () => {
+        userAgentComposer.appendMcpClientInfo(server.server.getClientVersion());
+    };
+    const tenantId = (await getOrgTenant(orgName)) ?? argv.tenant;
+    const authenticator = createAuthenticator(argv.authentication, tenantId);
     configurePrompts(server);
-    configureAllTools(server, getAzureDevOpsToken, getAzureDevOpsClient);
+    configureAllTools(server, authenticator, getAzureDevOpsClient(authenticator, userAgentComposer), () => userAgentComposer.userAgent, enabledDomains);
     const transport = new StdioServerTransport();
-    console.error("Connecting server to transport...");
     await server.connect(transport);
-    console.error("Azure DevOps MCP Server running on stdio");
 }
 main().catch((error) => {
     console.error("Fatal error in main():", error);

package/dist/org-tenants.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 trySavingCache(cache) {
+    try {
+        await fs.writeFile(CACHE_FILE, JSON.stringify(cache, null, 2), "utf-8");
+    }
+    catch (error) {
+        console.error("Failed to save org tenants 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 result
+        cache[orgName] = {
+            tenantId,
+            refreshedOn: Date.now(),
+        };
+        await trySavingCache(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, log and return empty result
+        console.error(`Failed to fetch tenant for ADO org ${orgName}:`, error);
+        return undefined;
+    }
+}

package/dist/orgtenants.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 trySavingCache(cache) {
+    try {
+        await fs.writeFile(CACHE_FILE, JSON.stringify(cache, null, 2), 'utf-8');
+    }
+    catch (error) {
+        console.error('Failed to save org tenants 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 result
+        cache[orgName] = {
+            tenantId,
+            refreshedOn: Date.now()
+        };
+        await trySavingCache(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, log and return empty result
+        console.error(`Failed to fetch tenant for ADO org ${orgName}:`, error);
+        return undefined;
+    }
+}

package/dist/prompts.js

@@ -1,22 +1,47 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 import { z } from "zod";
-import { REPO_TOOLS } from "./tools/repos.js";
+import { CORE_TOOLS } from "./tools/core.js";
+import { WORKITEM_TOOLS } from "./tools/work-items.js";
 function configurePrompts(server) {
-    server.prompt("relevant_pull_requests", "Presents the list of relevant pull requests for a given repository.", { repositoryId: z.string() }, ({ repositoryId }) => ({
+    server.prompt("Projects", "Lists all projects in the Azure DevOps organization.", {}, () => ({
         messages: [
             {
                 role: "user",
                 content: {
                     type: "text",
-                    text: String.raw `
-# Prerequisites
-1. Unless already provided, ask user for the project name
-2. Unless already provided, use '${REPO_TOOLS.list_repos_by_project}' tool to get a summarized response of the repositories in this project and ask user to select one
-
-# Task
-Find all pull requests for repository ${repositoryId} using '${REPO_TOOLS.list_pull_requests_by_repo}' tool and summarize them in a table.
-Include the following columns: ID, Title, Status, Created Date, Author and Reviewers.`,
+                    text: String.raw `
+# Task
+Use the '${CORE_TOOLS.list_projects}' tool to retrieve all 'wellFormed' projects in the current Azure DevOps organization.
+Present the results in alphabetical order in a table with the following columns: Name and ID.`,
+                },
+            },
+        ],
+    }));
+    server.prompt("Teams", "Retrieves all teams for a given Azure DevOps project.", { project: z.string() }, ({ project }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: String.raw `
+  # Task
+  Use the '${CORE_TOOLS.list_project_teams}' tool to retrieve all teams for the project '${project}'.
+  Present the results in alphabetical order in a table with the following columns: Name and Id`,
+                },
+            },
+        ],
+    }));
+    server.prompt("getWorkItem", "Retrieves details for a specific Azure DevOps work item by ID.", { id: z.string().describe("The ID of the work item to retrieve."), project: z.string().describe("The name or ID of the Azure DevOps project.") }, ({ id, project }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: String.raw `
+  # Task
+  Use the '${WORKITEM_TOOLS.get_work_item}' tool to retrieve details for the work item with ID '${id}' in project '${project}'.
+  Present the following fields: ID, Title, State, Assigned To, Work Item Type, Description or Repro Steps, and Created Date.`,
                 },
             },
         ],

package/dist/server.js

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as azdev from "azure-devops-node-api";
+import { DefaultAzureCredential } from "@azure/identity";
+import { configurePrompts } from "./prompts.js";
+import { configureAllTools } from "./tools.js";
+import { userAgent } from "./utils.js";
+import { packageVersion } from "./version.js";
+async function getAzureDevOpsToken() {
+    process.env.AZURE_TOKEN_CREDENTIALS = "dev";
+    const credential = new DefaultAzureCredential(); // CodeQL [SM05138] resolved by explicitly setting AZURE_TOKEN_CREDENTIALS
+    const token = await credential.getToken("499b84ac-1321-427f-aa17-267ca6975798/.default");
+    return token;
+}
+async function getAzureDevOpsClient(orgUrl) {
+    const token = await getAzureDevOpsToken();
+    const authHandler = azdev.getBearerHandler(token.token);
+    const connection = new azdev.WebApi(orgUrl, authHandler, undefined, {
+        productName: "AzureDevOps.MCP",
+        productVersion: packageVersion,
+        userAgent: userAgent
+    });
+    return connection;
+}
+export async function serverBuildAndConnect(orgName, transport) {
+    const server = new McpServer({
+        name: "Azure DevOps MCP Server",
+        version: packageVersion,
+    });
+    const orgUrl = "https://dev.azure.com/" + orgName;
+    configurePrompts(server);
+    configureAllTools(server, () => orgName, getAzureDevOpsToken, () => getAzureDevOpsClient(orgUrl));
+    await server.connect(transport);
+    return server;
+}

package/dist/shared/domains.js

@@ -0,0 +1,122 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+/**
+ * Available Azure DevOps MCP domains
+ */
+export var Domain;
+(function (Domain) {
+    Domain["ADVANCED_SECURITY"] = "advanced-security";
+    Domain["BUILDS"] = "builds";
+    Domain["CORE"] = "core";
+    Domain["RELEASES"] = "releases";
+    Domain["REPOSITORIES"] = "repositories";
+    Domain["SEARCH"] = "search";
+    Domain["TEST_PLANS"] = "test-plans";
+    Domain["WIKI"] = "wiki";
+    Domain["WORK"] = "work";
+    Domain["WORK_ITEMS"] = "work-items";
+})(Domain || (Domain = {}));
+export const ALL_DOMAINS = "all";
+/**
+ * Manages domain parsing and validation for Azure DevOps MCP server tools
+ */
+export class DomainsManager {
+    static AVAILABLE_DOMAINS = Object.values(Domain);
+    enabledDomains;
+    constructor(domainsInput) {
+        this.enabledDomains = new Set();
+        const normalizedInput = DomainsManager.parseDomainsInput(domainsInput);
+        this.parseDomains(normalizedInput);
+    }
+    /**
+     * Parse and validate domains from input
+     * @param domainsInput - Either "all", single domain name, array of domain names, or undefined (defaults to "all")
+     */
+    parseDomains(domainsInput) {
+        if (!domainsInput) {
+            this.enableAllDomains();
+            return;
+        }
+        if (Array.isArray(domainsInput)) {
+            this.handleArrayInput(domainsInput);
+            return;
+        }
+        this.handleStringInput(domainsInput);
+    }
+    handleArrayInput(domainsInput) {
+        if (domainsInput.length === 0 || domainsInput.includes(ALL_DOMAINS)) {
+            this.enableAllDomains();
+            return;
+        }
+        if (domainsInput.length === 1 && domainsInput[0] === ALL_DOMAINS) {
+            this.enableAllDomains();
+            return;
+        }
+        const domains = domainsInput.map((d) => d.trim().toLowerCase());
+        this.validateAndAddDomains(domains);
+    }
+    handleStringInput(domainsInput) {
+        if (domainsInput === ALL_DOMAINS) {
+            this.enableAllDomains();
+            return;
+        }
+        const domains = [domainsInput.trim().toLowerCase()];
+        this.validateAndAddDomains(domains);
+    }
+    validateAndAddDomains(domains) {
+        const availableDomainsAsStringArray = Object.values(Domain);
+        domains.forEach((domain) => {
+            if (availableDomainsAsStringArray.includes(domain)) {
+                this.enabledDomains.add(domain);
+            }
+            else if (domain === ALL_DOMAINS) {
+                this.enableAllDomains();
+            }
+            else {
+                console.error(`Error: Specified invalid domain '${domain}'. Please specify exactly as available domains: ${Object.values(Domain).join(", ")}`);
+            }
+        });
+        if (this.enabledDomains.size === 0) {
+            this.enableAllDomains();
+        }
+    }
+    enableAllDomains() {
+        Object.values(Domain).forEach((domain) => this.enabledDomains.add(domain));
+    }
+    /**
+     * Check if a specific domain is enabled
+     * @param domain - Domain name to check
+     * @returns true if domain is enabled
+     */
+    isDomainEnabled(domain) {
+        return this.enabledDomains.has(domain);
+    }
+    /**
+     * Get all enabled domains
+     * @returns Set of enabled domain names
+     */
+    getEnabledDomains() {
+        return new Set(this.enabledDomains);
+    }
+    /**
+     * Get list of all available domains
+     * @returns Array of available domain names
+     */
+    static getAvailableDomains() {
+        return Object.values(Domain);
+    }
+    /**
+     * Parse domains input from string or array to a normalized array of strings
+     * @param domainsInput - Domains input to parse
+     * @returns Normalized array of domain strings
+     */
+    static parseDomainsInput(domainsInput) {
+        if (!domainsInput) {
+            return [];
+        }
+        if (typeof domainsInput === "string") {
+            return domainsInput.split(",").map((d) => d.trim().toLowerCase());
+        }
+        return domainsInput.map((d) => d.trim().toLowerCase());
+    }
+}