@microsoft/agents-a365-tooling 0.1.0-preview.103

package/dist/esm/McpToolServerConfigurationService.d.ts

@@ -0,0 +1,143 @@
+import { TurnContext, Authorization } from '@microsoft/agents-hosting';
+import { OperationResult, IConfigurationProvider } from '@microsoft/agents-a365-runtime';
+import { MCPServerConfig, McpClientTool, ToolOptions } from './contracts';
+import { ChatHistoryMessage } from './models/index';
+import { ToolingConfiguration } from './configuration';
+/**
+ * Service responsible for discovering and normalizing MCP (Model Context Protocol)
+ * tool servers and producing configuration objects consumable by the Claude SDK.
+ */
+export declare class McpToolServerConfigurationService {
+    private readonly logger;
+    private readonly configProvider;
+    /**
+     * Construct a McpToolServerConfigurationService.
+     * @param configProvider Optional configuration provider. Defaults to defaultToolingConfigurationProvider if not specified.
+     */
+    constructor(configProvider?: IConfigurationProvider<ToolingConfiguration>);
+    /**
+     * Return MCP server definitions for the given agent. In development (NODE_ENV=Development) this reads the local ToolingManifest.json; otherwise it queries the remote tooling gateway.
+     *
+     * @deprecated Use the overload with TurnContext and Authorization parameters instead to enable x-ms-agentid header support and automatic token generation.
+     * @param agenticAppId The agentic app id for which to discover servers.
+     * @param authToken Bearer token used when querying the remote tooling gateway.
+     * @returns A promise resolving to an array of normalized MCP server configuration objects.
+     */
+    listToolServers(agenticAppId: string, authToken: string): Promise<MCPServerConfig[]>;
+    /**
+     * Return MCP server definitions for the given agent. In development (NODE_ENV=Development) this reads the local ToolingManifest.json; otherwise it queries the remote tooling gateway.
+     *
+     * @deprecated Use the overload with TurnContext and Authorization parameters instead to enable x-ms-agentid header support and automatic token generation.
+     * @param agenticAppId The agentic app id for which to discover servers.
+     * @param authToken Bearer token used when querying the remote tooling gateway.
+     * @param options Optional tool options when calling the gateway.
+     * @returns A promise resolving to an array of normalized MCP server configuration objects.
+     */
+    listToolServers(agenticAppId: string, authToken: string, options?: ToolOptions): Promise<MCPServerConfig[]>;
+    /**
+     * Return MCP server definitions for the given agent. In development (NODE_ENV=Development) this reads the local ToolingManifest.json; otherwise it queries the remote tooling gateway.
+     * This overload automatically resolves the agenticAppId from the TurnContext and generates the auth token if not provided.
+     *
+     * @param turnContext The TurnContext of the current request.
+     * @param authorization Authorization object for token exchange.
+     * @param authHandlerName The name of the auth handler to use for token exchange.
+     * @param authToken Optional bearer token. If not provided, will be auto-generated via token exchange.
+     * @param options Optional tool options when calling the gateway.
+     * @returns A promise resolving to an array of normalized MCP server configuration objects.
+     */
+    listToolServers(turnContext: TurnContext, authorization: Authorization, authHandlerName: string, authToken?: string, options?: ToolOptions): Promise<MCPServerConfig[]>;
+    /**
+     * Connect to the MCP server and return tools with names prefixed by the server name.
+     * Throws if the server URL is missing or the client fails to list tools.
+     */
+    getMcpClientTools(mcpServerName: string, mcpServerConfig: MCPServerConfig): Promise<McpClientTool[]>;
+    /**
+     * Sends chat history to the MCP platform for real-time threat protection.
+     *
+     * @param turnContext The turn context containing conversation information.
+     * @param chatHistoryMessages The chat history messages to send.
+     * @returns A Promise that resolves to an OperationResult indicating success or failure.
+     * @throws Error if turnContext or chatHistoryMessages is null/undefined.
+     * @throws Error if required turn context properties (Conversation.Id, Activity.Id, or Activity.Text) are null.
+     * @remarks
+     * HTTP exceptions (network errors, timeouts) are caught and logged but not rethrown.
+     * Instead, the method returns an OperationResult indicating whether the operation succeeded or failed.
+     * Callers can choose to inspect the result for error handling or ignore it if error details are not needed.
+     */
+    sendChatHistory(turnContext: TurnContext, chatHistoryMessages: ChatHistoryMessage[]): Promise<OperationResult>;
+    /**
+     * Sends chat history to the MCP platform for real-time threat protection.
+     *
+     * @param turnContext The turn context containing conversation information.
+     * @param chatHistoryMessages The chat history messages to send.
+     * @param options Optional tool options for sending chat history.
+     * @returns A Promise that resolves to an OperationResult indicating success or failure.
+     * @throws Error if turnContext or chatHistoryMessages is null/undefined.
+     * @throws Error if required turn context properties (Conversation.Id, Activity.Id, or Activity.Text) are null.
+     * @remarks
+     * HTTP exceptions (network errors, timeouts) are caught and logged but not rethrown.
+     * Instead, the method returns an OperationResult indicating whether the operation succeeded or failed.
+     * Callers can choose to inspect the result for error handling or ignore it if error details are not needed.
+     */
+    sendChatHistory(turnContext: TurnContext, chatHistoryMessages: ChatHistoryMessage[], options?: ToolOptions): Promise<OperationResult>;
+    /**
+     * Query the tooling gateway for MCP servers for the specified agent and normalize each entry's mcpServerUniqueName into a full URL using Utility.BuildMcpServerUrl.
+     * Throws an error if the gateway call fails.
+     *
+     * @param agenticAppId The agentic app id used by the tooling gateway to scope results.
+     * @param authToken Optional Bearer token to include in the Authorization header when calling the gateway.
+     * @param turnContext Optional TurnContext for extracting agent blueprint ID for request headers.
+     * @param options Optional tool options when calling the gateway.
+     * @throws Error when the gateway call fails or returns an unexpected payload.
+     */
+    private getMCPServerConfigsFromToolingGateway;
+    /**
+     * Read MCP servers from a local ToolingManifest.json file (development only).
+     * Searches process.cwd() and process.argv[1] for the manifest file.
+     *
+     * Reads MCP server configurations from ToolingManifest.json in the application's content root.
+     * The file should be located at: [ProjectRoot]/ToolingManifest.json
+     *
+     * Example ToolingManifest.json:
+     * {
+     *   "mcpServers": [
+     *     {
+     *       "mcpServerName": "mailMCPServerConfig",
+     *       "mcpServerUniqueName": "mcp_MailTools"
+     *     },
+     *     {
+     *       "mcpServerName": "sharePointMCPServerConfig",
+     *       "mcpServerUniqueName": "mcp_SharePointTools"
+     *     }
+     *   ]
+     * }
+     *
+     * Each server entry can optionally include a "url" field to specify a custom MCP server URL.
+     * If the "url" field is not provided, the URL will be automatically constructed using the server name.
+     * The server name is determined by using "mcpServerName" if present, otherwise "mcpServerUniqueName".
+     */
+    private getMCPServerConfigsFromManifest;
+    /**
+     * Detect if the process is running in a development scenario based on configuration.
+     *
+     * @returns {boolean} True when running in a development environment (NODE_ENV=Development).
+     */
+    private isDevScenario;
+    /**
+     * Gets the base URL for MCP platform from configuration.
+     */
+    private getMcpPlatformBaseUrl;
+    /**
+     * Construct the tooling gateway URL for a given agent identity.
+     */
+    private getToolingGatewayUrl;
+    /**
+     * Build the full URL for accessing a specific MCP server.
+     */
+    private buildMcpServerUrl;
+    /**
+     * Constructs the endpoint URL for sending chat history.
+     */
+    private getChatHistoryEndpoint;
+}
+//# sourceMappingURL=McpToolServerConfigurationService.d.ts.map

package/dist/esm/McpToolServerConfigurationService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpToolServerConfigurationService.d.ts","sourceRoot":"","sources":["../../src/McpToolServerConfigurationService.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAE,eAAe,EAAkB,sBAAsB,EAA2D,MAAM,gCAAgC,CAAC;AAClK,OAAO,EAAE,eAAe,EAA0B,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAClG,OAAO,EAAE,kBAAkB,EAAsB,MAAM,gBAAgB,CAAC;AAExE,OAAO,EAAE,oBAAoB,EAAuC,MAAM,iBAAiB,CAAC;AAK5F;;;GAGG;AACH,qBAAa,iCAAiC;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA+C;IAE9E;;;OAGG;gBACS,cAAc,CAAC,EAAE,sBAAsB,CAAC,oBAAoB,CAAC;IAIzE;;;;;;;OAOG;IACG,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAE1F;;;;;;;;OAQG;IACG,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAEjH;;;;;;;;;;OAUG;IACG,eAAe,CAAC,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IA8D7K;;;OAGG;IACG,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,eAAe,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IA8B1G;;;;;;;;;;;;OAYG;IACG,eAAe,CAAC,WAAW,EAAE,WAAW,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAEpH;;;;;;;;;;;;;OAaG;IACG,eAAe,CAAC,WAAW,EAAE,WAAW,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;IAyE3I;;;;;;;;;OASG;YACW,qCAAqC;IAsBnD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;YACW,+BAA+B;IAoC7C;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAIrB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAI7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;CAG/B"}

package/dist/esm/McpToolServerConfigurationService.js

@@ -0,0 +1,270 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+import fs from 'fs';
+import path from 'path';
+import axios from 'axios';
+import { OperationResult, OperationError, AgenticAuthenticationService, Utility as RuntimeUtility } from '@microsoft/agents-a365-runtime';
+import { Utility } from './Utility';
+import { defaultToolingConfigurationProvider } from './configuration';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+/**
+ * Service responsible for discovering and normalizing MCP (Model Context Protocol)
+ * tool servers and producing configuration objects consumable by the Claude SDK.
+ */
+export class McpToolServerConfigurationService {
+    /**
+     * Construct a McpToolServerConfigurationService.
+     * @param configProvider Optional configuration provider. Defaults to defaultToolingConfigurationProvider if not specified.
+     */
+    constructor(configProvider) {
+        this.logger = console;
+        this.configProvider = configProvider ?? defaultToolingConfigurationProvider;
+    }
+    async listToolServers(agenticAppIdOrTurnContext, authTokenOrAuthorization, optionsOrAuthHandlerName, authTokenOrOptions, options) {
+        // Detect which signature is being used based on the type of the first parameter
+        if (typeof agenticAppIdOrTurnContext === 'string') {
+            // LEGACY PATH: listToolServers(agenticAppId, authToken, options?)
+            const agenticAppId = agenticAppIdOrTurnContext;
+            // Runtime validation for legacy signature parameters
+            if (typeof authTokenOrAuthorization !== 'string') {
+                throw new Error('authToken must be a string when using the legacy listToolServers(agenticAppId, authToken) signature');
+            }
+            const authToken = authTokenOrAuthorization;
+            const toolOptions = optionsOrAuthHandlerName;
+            return await (this.isDevScenario()
+                ? this.getMCPServerConfigsFromManifest()
+                : this.getMCPServerConfigsFromToolingGateway(agenticAppId, authToken, undefined, toolOptions));
+        }
+        else {
+            // NEW PATH: listToolServers(turnContext, authorization, authHandlerName, authToken?, options?)
+            const turnContext = agenticAppIdOrTurnContext;
+            // Runtime validation for new signature parameters
+            if (typeof authTokenOrAuthorization === 'string') {
+                throw new Error('authorization must be an Authorization object when using the new listToolServers(turnContext, authorization, authHandlerName) signature');
+            }
+            if (typeof optionsOrAuthHandlerName !== 'string') {
+                throw new Error('authHandlerName must be a string when using the new listToolServers(turnContext, authorization, authHandlerName) signature');
+            }
+            const authorization = authTokenOrAuthorization;
+            const authHandlerName = optionsOrAuthHandlerName;
+            let authToken = authTokenOrOptions;
+            const toolOptions = options;
+            // Auto-generate token if not provided
+            if (!authToken) {
+                const scopes = [this.configProvider.getConfiguration().mcpPlatformAuthenticationScope];
+                authToken = await AgenticAuthenticationService.GetAgenticUserToken(authorization, authHandlerName, turnContext, scopes);
+                if (!authToken) {
+                    throw new Error('Failed to obtain authentication token from token exchange');
+                }
+            }
+            // Note: Token validation (format/expiration) is performed inside getMCPServerConfigsFromToolingGateway()
+            // to avoid duplicate validation (it's also called by the legacy path)
+            // Resolve agenticAppId from TurnContext
+            const agenticAppId = RuntimeUtility.ResolveAgentIdentity(turnContext, authToken);
+            return await (this.isDevScenario()
+                ? this.getMCPServerConfigsFromManifest()
+                : this.getMCPServerConfigsFromToolingGateway(agenticAppId, authToken, turnContext, toolOptions));
+        }
+    }
+    /**
+     * Connect to the MCP server and return tools with names prefixed by the server name.
+     * Throws if the server URL is missing or the client fails to list tools.
+     */
+    async getMcpClientTools(mcpServerName, mcpServerConfig) {
+        if (!mcpServerConfig) {
+            throw new Error('Invalid MCP Server Configuration');
+        }
+        if (!mcpServerConfig.url) {
+            throw new Error('MCP Server URL cannot be null or empty');
+        }
+        const transport = new StreamableHTTPClientTransport(new URL(mcpServerConfig.url), {
+            requestInit: {
+                headers: mcpServerConfig.headers
+            }
+        });
+        const mcpClient = new Client({
+            name: mcpServerName + ' Client',
+            version: '1.0',
+        });
+        await mcpClient.connect(transport);
+        const toolsObj = await mcpClient.listTools();
+        await mcpClient.close();
+        return toolsObj.tools;
+    }
+    async sendChatHistory(turnContext, chatHistoryMessages, options) {
+        if (!turnContext) {
+            throw new Error('turnContext is required');
+        }
+        if (!chatHistoryMessages) {
+            throw new Error('chatHistoryMessages is required');
+        }
+        // Extract required information from turn context
+        const conversationId = turnContext.activity?.conversation?.id;
+        if (!conversationId) {
+            throw new Error('Conversation ID is required but not found in turn context');
+        }
+        const messageId = turnContext.activity?.id;
+        if (!messageId) {
+            throw new Error('Message ID is required but not found in turn context');
+        }
+        const userMessage = turnContext.activity?.text;
+        if (!userMessage) {
+            throw new Error('User message is required but not found in turn context');
+        }
+        // Get the endpoint URL
+        const endpoint = this.getChatHistoryEndpoint();
+        this.logger.info(`Sending chat history to endpoint: ${endpoint}`);
+        // Create the request payload
+        const request = {
+            conversationId,
+            messageId,
+            userMessage,
+            chatHistory: chatHistoryMessages
+        };
+        try {
+            const headers = Utility.GetToolRequestHeaders(undefined, turnContext, options);
+            await axios.post(endpoint, request, {
+                headers: {
+                    ...headers,
+                    'Content-Type': 'application/json'
+                },
+                timeout: 10000 // 10 seconds timeout
+            });
+            this.logger.info('Successfully sent chat history to MCP platform');
+            return OperationResult.success;
+        }
+        catch (err) {
+            const error = err;
+            if (axios.isAxiosError(err)) {
+                if (err.code === 'ECONNABORTED' || err.code === 'ETIMEDOUT') {
+                    this.logger.error(`Request timeout sending chat history to '${endpoint}': ${error.message}`);
+                }
+                else {
+                    this.logger.error(`HTTP error sending chat history to '${endpoint}': ${error.message}`);
+                }
+            }
+            else {
+                this.logger.error(`Failed to send chat history to '${endpoint}': ${error.message}`);
+            }
+            return OperationResult.failed(new OperationError(error));
+        }
+    }
+    /**
+     * Query the tooling gateway for MCP servers for the specified agent and normalize each entry's mcpServerUniqueName into a full URL using Utility.BuildMcpServerUrl.
+     * Throws an error if the gateway call fails.
+     *
+     * @param agenticAppId The agentic app id used by the tooling gateway to scope results.
+     * @param authToken Optional Bearer token to include in the Authorization header when calling the gateway.
+     * @param turnContext Optional TurnContext for extracting agent blueprint ID for request headers.
+     * @param options Optional tool options when calling the gateway.
+     * @throws Error when the gateway call fails or returns an unexpected payload.
+     */
+    async getMCPServerConfigsFromToolingGateway(agenticAppId, authToken, turnContext, options) {
+        // Validate the authentication token
+        Utility.ValidateAuthToken(authToken);
+        const configEndpoint = this.getToolingGatewayUrl(agenticAppId);
+        try {
+            const response = await axios.get(configEndpoint, {
+                headers: Utility.GetToolRequestHeaders(authToken, turnContext, options),
+                timeout: 10000 // 10 seconds timeout
+            });
+            return (response.data) || [];
+        }
+        catch (err) {
+            const error = err;
+            throw new Error(`Failed to read MCP servers from endpoint: ${error.code || 'UNKNOWN'} ${error.message || 'Unknown error'}`);
+        }
+    }
+    /**
+     * Read MCP servers from a local ToolingManifest.json file (development only).
+     * Searches process.cwd() and process.argv[1] for the manifest file.
+     *
+     * Reads MCP server configurations from ToolingManifest.json in the application's content root.
+     * The file should be located at: [ProjectRoot]/ToolingManifest.json
+     *
+     * Example ToolingManifest.json:
+     * {
+     *   "mcpServers": [
+     *     {
+     *       "mcpServerName": "mailMCPServerConfig",
+     *       "mcpServerUniqueName": "mcp_MailTools"
+     *     },
+     *     {
+     *       "mcpServerName": "sharePointMCPServerConfig",
+     *       "mcpServerUniqueName": "mcp_SharePointTools"
+     *     }
+     *   ]
+     * }
+     *
+     * Each server entry can optionally include a "url" field to specify a custom MCP server URL.
+     * If the "url" field is not provided, the URL will be automatically constructed using the server name.
+     * The server name is determined by using "mcpServerName" if present, otherwise "mcpServerUniqueName".
+     */
+    async getMCPServerConfigsFromManifest() {
+        let manifestPath = path.join(process.cwd(), 'ToolingManifest.json');
+        if (!fs.existsSync(manifestPath)) {
+            this.logger.warn(`ToolingManifest.json not found at ${manifestPath}, checking argv[1] location.`);
+            manifestPath = path.join(path.dirname(process.argv[1] || ''), 'ToolingManifest.json');
+        }
+        if (!fs.existsSync(manifestPath)) {
+            this.logger.warn(`ToolingManifest.json not found at ${manifestPath}`);
+            return [];
+        }
+        try {
+            const jsonContent = fs.readFileSync(manifestPath, 'utf-8');
+            const manifestData = JSON.parse(jsonContent);
+            const mcpServers = manifestData.mcpServers || [];
+            return mcpServers.map((s) => {
+                // Use mcpServerName if available, otherwise fall back to mcpServerUniqueName
+                const serverName = s.mcpServerName || s.mcpServerUniqueName;
+                if (!serverName) {
+                    throw new Error('Either mcpServerName or mcpServerUniqueName must be provided in manifest entry');
+                }
+                return {
+                    mcpServerName: serverName,
+                    url: s.url || this.buildMcpServerUrl(serverName),
+                    headers: s.headers
+                };
+            });
+        }
+        catch (err) {
+            const error = err;
+            this.logger.error(`Error reading or parsing ToolingManifest.json: ${error.message || 'Unknown error'}`);
+            return [];
+        }
+    }
+    /**
+     * Detect if the process is running in a development scenario based on configuration.
+     *
+     * @returns {boolean} True when running in a development environment (NODE_ENV=Development).
+     */
+    isDevScenario() {
+        return this.configProvider.getConfiguration().useToolingManifest;
+    }
+    /**
+     * Gets the base URL for MCP platform from configuration.
+     */
+    getMcpPlatformBaseUrl() {
+        return this.configProvider.getConfiguration().mcpPlatformEndpoint;
+    }
+    /**
+     * Construct the tooling gateway URL for a given agent identity.
+     */
+    getToolingGatewayUrl(agenticAppId) {
+        return `${this.getMcpPlatformBaseUrl()}/agents/${agenticAppId}/mcpServers`;
+    }
+    /**
+     * Build the full URL for accessing a specific MCP server.
+     */
+    buildMcpServerUrl(serverName) {
+        return `${this.getMcpPlatformBaseUrl()}/agents/servers/${serverName}/`;
+    }
+    /**
+     * Constructs the endpoint URL for sending chat history.
+     */
+    getChatHistoryEndpoint() {
+        return `${this.getMcpPlatformBaseUrl()}/agents/real-time-threat-protection/chat-message`;
+    }
+}
+//# sourceMappingURL=McpToolServerConfigurationService.js.map

package/dist/esm/McpToolServerConfigurationService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpToolServerConfigurationService.js","sourceRoot":"","sources":["../../src/McpToolServerConfigurationService.ts"],"names":[],"mappings":"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"}

package/dist/esm/Utility.d.ts

@@ -0,0 +1,106 @@
+import { TurnContext } from '@microsoft/agents-hosting';
+import { IConfigurationProvider } from '@microsoft/agents-a365-runtime';
+import { ToolOptions } from './contracts';
+import { ToolingConfiguration } from './configuration';
+export declare class Utility {
+    static readonly HEADER_CHANNEL_ID = "x-ms-channel-id";
+    static readonly HEADER_SUBCHANNEL_ID = "x-ms-subchannel-id";
+    static readonly HEADER_USER_AGENT = "User-Agent";
+    /** Header name for sending the agent identifier to MCP platform for logging/analytics. */
+    static readonly HEADER_AGENT_ID = "x-ms-agentid";
+    /**
+     * Compose standard headers for MCP tooling requests.
+     * Includes Authorization bearer token when provided, and optionally includes channel and subchannel identifiers for routing.
+     *
+     * @param authToken Bearer token for Authorization header.
+     * @param turnContext Optional TurnContext object from which channel and subchannel IDs are extracted.
+     * @param options Optional ToolOptions object for additional request configuration.
+     * @returns A headers record suitable for HTTP requests.
+     */
+    static GetToolRequestHeaders(authToken?: string, turnContext?: TurnContext, options?: ToolOptions): Record<string, string>;
+    /**
+     * Resolves the best available agent identifier for the x-ms-agentid header.
+     * Priority: TurnContext.agenticAppBlueprintId > token claims (xms_par_app_azp > appid > azp) > application name
+     *
+     * Note: This differs from RuntimeUtility.ResolveAgentIdentity() which resolves the agenticAppId
+     * for URL construction. This method resolves the identifier specifically for the x-ms-agentid header.
+     *
+     * @param authToken The authentication token to extract claims from.
+     * @param turnContext Optional TurnContext to extract agent blueprint ID from.
+     * @returns Agent ID string or undefined if not available.
+     */
+    private static resolveAgentIdForHeader;
+    /**
+     * Validates a JWT authentication token.
+     * Checks that the token is a valid JWT and is not expired.
+     *
+     * @param authToken - The JWT token to validate.
+     * @throws Error if the token is invalid or expired.
+     */
+    static ValidateAuthToken(authToken: string | undefined): void;
+    /**
+     * Private helper to validate a JWT authentication token.
+     * Checks that the token is a valid JWT and is not expired.
+     *
+     * @param authToken - The JWT token to validate.
+     * @throws Error if the token is invalid or expired.
+     */
+    private static validateAuthToken;
+    /**
+     * Construct the tooling gateway URL for a given agent identity.
+     * This endpoint is used to discover MCP servers associated with the specified agent identity.
+     *
+     * Example:
+     *   Utility.GetToolingGatewayForDigitalWorker(agenticAppId)
+     *   // => "https://agent365.svc.cloud.microsoft/agents/{agenticAppId}/mcpServers"
+     *
+     * @param agenticAppId - The unique identifier for the agent identity.
+     * @param configProvider - Optional configuration provider. Defaults to defaultToolingConfigurationProvider.
+     * @returns A fully-qualified URL pointing at the tooling gateway for the agent.
+     * @deprecated This method is for internal use only. Use McpToolServerConfigurationService.listToolServers() instead.
+     */
+    static GetToolingGatewayForDigitalWorker(agenticAppId: string, configProvider?: IConfigurationProvider<ToolingConfiguration>): string;
+    /**
+     * Get the base URL used to query MCP environments.
+     *
+     * @param configProvider - Optional configuration provider. Defaults to defaultToolingConfigurationProvider.
+     * @returns The base MCP environments URL.
+     * @deprecated This method is for internal use only. Use McpToolServerConfigurationService instead.
+     */
+    static GetMcpBaseUrl(configProvider?: IConfigurationProvider<ToolingConfiguration>): string;
+    /**
+     * Build the full URL for accessing a specific MCP server.
+     *
+     * Example:
+     *   Utility.BuildMcpServerUrl('MyServer')
+     *   // => "https://agent365.svc.cloud.microsoft/agents/servers/MyServer/"
+     *
+     * @param serverName - The MCP server resource name.
+     * @param configProvider - Optional configuration provider. Defaults to defaultToolingConfigurationProvider.
+     * @returns The fully-qualified MCP server URL including trailing slash.
+     * @deprecated This method is for internal use only. Use McpToolServerConfigurationService instead.
+    */
+    static BuildMcpServerUrl(serverName: string, configProvider?: IConfigurationProvider<ToolingConfiguration>): string;
+    /**
+     * Gets the base URL for MCP platform from configuration.
+     *
+     * @param configProvider - Optional configuration provider. Defaults to defaultToolingConfigurationProvider.
+     * @returns The base URL for MCP platform.
+     * @deprecated This method is for internal use only. Use ToolingConfiguration.mcpPlatformEndpoint instead.
+     */
+    private static getMcpPlatformBaseUrl;
+    /**
+     * Constructs the endpoint URL for sending chat history to the MCP platform for real-time threat protection.
+     *
+     * @param configProvider - Optional configuration provider. Defaults to defaultToolingConfigurationProvider.
+     * @returns An absolute URL that tooling components can use to send or retrieve chat messages for
+     * real-time threat protection scenarios.
+     * @remarks
+     * Call this method when constructing HTTP requests that need to access the chat-message history
+     * for real-time threat protection. The returned URL already includes the MCP platform base address
+     * and the fixed path segment `/agents/real-time-threat-protection/chat-message`.
+     * @deprecated This method is for internal use only. Use McpToolServerConfigurationService.sendChatHistory() instead.
+     */
+    static GetChatHistoryEndpoint(configProvider?: IConfigurationProvider<ToolingConfiguration>): string;
+}
+//# sourceMappingURL=Utility.d.ts.map

package/dist/esm/Utility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Utility.d.ts","sourceRoot":"","sources":["../../src/Utility.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAExD,OAAO,EAA6B,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAEnG,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAuC,MAAM,iBAAiB,CAAC;AAE5F,qBAAa,OAAO;IAClB,gBAAuB,iBAAiB,qBAAqB;IAC7D,gBAAuB,oBAAoB,wBAAwB;IACnE,gBAAuB,iBAAiB,gBAAgB;IACxD,0FAA0F;IAC1F,gBAAuB,eAAe,kBAAkB;IAExD;;;;;;;;OAQG;WACW,qBAAqB,CACjC,SAAS,CAAC,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,WAAW,EACzB,OAAO,CAAC,EAAE,WAAW,GACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IA+BzB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAsBtC;;;;;;OAMG;WACW,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAIpE;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAqChC;;;;;;;;;;;;OAYG;WACW,iCAAiC,CAC7C,YAAY,EAAE,MAAM,EACpB,cAAc,CAAC,EAAE,sBAAsB,CAAC,oBAAoB,CAAC,GAC5D,MAAM;IAIT;;;;;;OAMG;WACW,aAAa,CAAC,cAAc,CAAC,EAAE,sBAAsB,CAAC,oBAAoB,CAAC,GAAG,MAAM;IAIlG;;;;;;;;;;;MAWE;WACY,iBAAiB,CAC7B,UAAU,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,sBAAsB,CAAC,oBAAoB,CAAC,GAC5D,MAAM;IAKT;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAKpC;;;;;;;;;;;OAWG;WACW,sBAAsB,CAAC,cAAc,CAAC,EAAE,sBAAsB,CAAC,oBAAoB,CAAC,GAAG,MAAM;CAG5G"}