McpToolServerConfigurationService Classe

Fornece serviços para gestão de configuração de servidores de ferramentas MCP.

Este serviço trata da descoberta e configuração de servidores de ferramentas MCP (Model Context Protocol) a partir de múltiplas fontes:

• Desenvolvimento: Ficheiros ToolingManifest.json locais
• Produção: Endpoints de gateway de ferramentas remotas

Construtor

McpToolServerConfigurationService()

Parâmetros

Name	Description
logger	Default value: None

Métodos

__init__	Inicialize o Serviço de Configuração do Servidor de Ferramentas MCP.
__new__
list_tool_servers	Obtém a lista de servidores MCP configurados para o agente. Quando authorization, auth_handler_name, e turn_context são todos fornecidos, tokens OAuth por audiência são adquiridos para cada servidor após a descoberta: Os servidores V1 (sem audience campo) partilham o token ATG partilhado (uma exchange). Os servidores V2 recebem cada um um token com escopo para o seu próprio GUID de audiência.
send_chat_history	Envia o histórico de chat para a plataforma MCP para proteção contra ameaças em tempo real. Note Mesmo que chat_history_messages esteja vazio, o pedido será enviado na mesma para a plataforma MCP. Isto garante a mensagem do utilizador a partir de turn_context.activity.text está corretamente registado para proteção contra ameaças em tempo real.

__init__

Inicialize o Serviço de Configuração do Servidor de Ferramentas MCP.

__init__(logger: Logger | None = None)

Parâmetros

Name	Description
logger	Logger | None Instância do logger para operações de registo. Se não for nenhum, cria um novo logger. Default value: None

__new__

__new__(**kwargs)

list_tool_servers

Obtém a lista de servidores MCP configurados para o agente.

Quando authorization, auth_handler_name, e turn_context são todos fornecidos, tokens OAuth por audiência são adquiridos para cada servidor após a descoberta:

• Os servidores V1 (sem audience campo) partilham o token ATG partilhado (uma exchange).
• Os servidores V2 recebem cada um um token com escopo para o seu próprio GUID de audiência.

async list_tool_servers(agentic_app_id: str, auth_token: str | None = None, options: ToolOptions | None = None, authorization: Authorization | None = None, auth_handler_name: str | None = None, turn_context: TurnContext | None = None) -> List[MCPServerConfig]

Parâmetros

Name	Description
agentic_app_id Necessário	str ID de aplicação agente para o agente.
auth_token	str | None Token de autenticação usado para descoberta de gateway. Default value: None
options	ToolOptions | None Instância opcional ToolOptions contendo parâmetros opcionais. Default value: None
authorization	Authorization | None Contexto opcional de autorização para troca de tokens por audiência. Default value: None
auth_handler_name	str | None Nome opcional do handler de autenticação usado com authorization. Default value: None
turn_context	TurnContext | None TurnContext opcional usado com authorization. Default value: None

Devoluções

Tipo	Description
List[MCPServerConfig]	Devolve a lista de servidores MCP configurados, cada um com um Authorization cabeçalho associado quando é fornecido o contexto de autenticação.

Exceções

Tipo	Description
ValueError	Se os parâmetros exigidos forem inválidos ou vazios.
Exception	Se houver um erro a comunicar com o gateway de ferramentas ou uma troca de tokens por audiência falhar.

send_chat_history

Envia o histórico de chat para a plataforma MCP para proteção contra ameaças em tempo real.

Note

Mesmo que chat_history_messages esteja vazio, o pedido será enviado na mesma para

a plataforma MCP. Isto garante a mensagem do utilizador a partir de turn_context.activity.text

está corretamente registado para proteção contra ameaças em tempo real.

async send_chat_history(turn_context: TurnContext, chat_history_messages: List[ChatHistoryMessage], options: ToolOptions | None = None) -> OperationResult

Parâmetros

Name	Description
turn_context Necessário	TurnContext TurnContext do SDK Agents que contém informação de conversa. Deve ter uma atividade válida com conversation.id, activity.id e activity.text.
chat_history_messages Necessário	List[ChatHistoryMessage] Lista de objetos ChatHistoryMessage que representam o histórico da conversa. Pode estar vazia – uma lista vazia ainda enviará um pedido para a plataforma MCP com histórico de chat vazio.
options	ToolOptions | None Instância opcional ToolOptions contendo parâmetros opcionais. Default value: None

Devoluções

Tipo	Description
<xref:OperationResult>	Um Resultado da Operação que indica sucesso ou fracasso. Em caso de sucesso, devolve OperationResult.success(). Em caso de falha, devolve OperationResult.failed() com os detalhes do erro.

Exceções

Tipo	Description
ValueError	Se turn_context for Nenhum, chat_history_messages é Nenhum, turn_context.atividade for Nenhum, ou qualquer um dos campos exigidos (conversation.id, activity.id, activity.text) está em falta ou está vazio.

Exemplos

>>> from datetime import datetime, timezone
>>> from microsoft_agents_a365.tooling.models import ChatHistoryMessage
>>>
>>> history = [
...     ChatHistoryMessage("msg-1", "user", "Hello", datetime.now(timezone.utc)),
...     ChatHistoryMessage("msg-2", "assistant", "Hi!", datetime.now(timezone.utc))
... ]
>>>
>>> service = McpToolServerConfigurationService()
>>> result = await service.send_chat_history(turn_context, history)
>>> if result.succeeded:
...     print("Chat history sent successfully")