MCP resource trigger for Funções do Azure

Este primeiro exemplo mostra como usar recursos para implementar o elemento UI das Apps MCP.

O código seguinte cria um endpoint para expor um recurso nomeado Weather Widget que serve uma visualização meteorológica interativa como conteúdo HTML agrupado. O recurso usa o ui:// esquema para indicar que é um recurso da interface da aplicação MCP.

// Optional resource metadata
private const string ResourceMetadata = """
    {
        "ui": {
            "prefersBorder": true
        }
    }
    """;

[Function(nameof(GetWeatherWidget))]
public string GetWeatherWidget(
    [McpResourceTrigger(
        "ui://weather/index.html",
        "Weather Widget",
        MimeType = "text/html;profile=mcp-app",
        Description = "Interactive weather display for MCP Apps")]
    [McpMetadata(ResourceMetadata)]
        ResourceInvocationContext context)
{
    var file = Path.Combine(AppContext.BaseDirectory, "app", "dist", "index.html");
    return File.ReadAllText(file);
}

Uma ferramenta pode referenciar este recurso declarando a resourceUri nos seus metadados, apontando para ui://weather/index.html. Quando a ferramenta é invocada, o host MCP recupera o recurso e renderiza-o:

private const string ToolMetadata = """
    {
        "ui": {
            "resourceUri": "ui://weather/index.html"
        }
    }
    """;

[Function(nameof(GetWeather))]
public async Task<object> GetWeather(
    [McpToolTrigger(nameof(GetWeather), "Returns current weather for a location via Open-Meteo.")]
    [McpMetadata(ToolMetadata)]
        ToolInvocationContext context,
    [McpToolProperty("location", "City name to check weather for (e.g., Seattle, New York, Miami)")]
        string location)
{
    var result = await _weatherService.GetCurrentWeatherAsync(location);
    return result;
}

Para o exemplo completo do código, veja WeatherFunction.cs.

Este exemplo de código cria um endpoint para expor um recurso nomeado readme que lê um ficheiro markdown e devolve o seu conteúdo como texto simples. Os clientes podem aceder a este recurso usando o file://readme.md URI.

    private const string ReadmeMetadata = """
        {
            "author": "John Doe",
            "file": {
                "version": 1.0,
                "releaseDate": "2024-01-01"
            },
            "test": {
                "example": ["list", "of", "values"]
            }
        }
        """;

    [Function(nameof(GetTextResource))]
    public string GetTextResource(
        [McpResourceTrigger(
            "file://readme.md",
            "readme",
            Description = "Application readme file",
            MimeType = "text/plain")]
        [McpMetadata(ReadmeMetadata)]
        ResourceInvocationContext context)
    {
        _logger.LogInformation("Reading text resource from local file storage");
        var file = Path.Combine(AppContext.BaseDirectory, "assets", "readme.md");
        return File.ReadAllText(file);
    }

Neste exemplo, uma pasta chamada assets contendo o readme é incluída com a aplicação de funções em tempo de compilação porque a seguinte diretiva está presente no .csproj ficheiro:

<ItemGroup>
  <None Update="assets\**\*">
    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
  </None>
</ItemGroup>

Para o exemplo completo do código, veja o repositório Funções do Azure MCP Extension.

O código de exemplo para JavaScript não está disponível no momento. Consulte o exemplo do TypeScript para orientações gerais.

O código abaixo regista um recurso nomeado Weather Widget que serve uma visualização meteorológica interativa como conteúdo HTML agrupado. O recurso usa o ui:// esquema para indicar que é um recurso da interface da aplicação MCP.

// Constants for the Weather Widget resource
const WEATHER_WIDGET_URI = "ui://weather/index.html";
const WEATHER_WIDGET_NAME = "Weather Widget";
const WEATHER_WIDGET_DESCRIPTION = "Interactive weather display for MCP Apps";
const WEATHER_WIDGET_MIME_TYPE = "text/html;profile=mcp-app";

// Metadata for the resource 
const RESOURCE_METADATA = JSON.stringify({
  ui: {
    prefersBorder: true
  }
});

app.mcpResource("getWeatherWidget", {
  uri: WEATHER_WIDGET_URI,
  resourceName: WEATHER_WIDGET_NAME,
  description: WEATHER_WIDGET_DESCRIPTION,
  mimeType: WEATHER_WIDGET_MIME_TYPE,
  metadata: RESOURCE_METADATA,
  handler: getWeatherWidget,
});

O seguinte código é o getWeatherWidget handler:

export async function getWeatherWidget(
  resourceContext: unknown,
  context: InvocationContext
): Promise<string> {
  context.log("Getting weather widget");

  try {
    const filePath = path.join(__dirname, "..", "..", "..", "src", "app", "dist", "index.html");
    return fs.readFileSync(filePath, "utf-8");
  } catch (error) {
    context.log(`Error reading weather widget file: ${error}`);
    return `<!DOCTYPE html>
      <html>
      <head><title>Weather Widget</title></head>
      <body>
      <h1>Weather Widget</h1>
      <p>Widget content not found. Please ensure the app/dist/index.html file exists.</p>
      </body>
      </html>`;
  }
}

Uma ferramenta pode referenciar este recurso declarando a resourceUri nos seus metadados. Quando a ferramenta é invocada, o host MCP recupera o recurso e renderiza-o:

// Metadata for the tool (as valid JSON string)
const TOOL_METADATA = JSON.stringify({
  ui: {
    resourceUri: "ui://weather/index.html"
  }
});

app.mcpTool("getWeather", {
  toolName: "GetWeather",
  description: "Returns current weather for a location via Open-Meteo.",
  toolProperties: {
    location: arg.string().describe("City name to check weather for (e.g., Seattle, New York, Miami)")
  },
  metadata: TOOL_METADATA,
  handler: getWeather,
});

Para o exemplo completo do código, veja weatherMcpApp.ts.

O código seguinte regista um recurso nomeado Weather Widget que serve como um ecrã meteorológico interativo como conteúdo HTML agrupado. O recurso usa o ui:// esquema para indicar que é um recurso da interface da aplicação MCP.

# Constants for the Weather Widget resource
WEATHER_WIDGET_URI = "ui://weather/index.html"
WEATHER_WIDGET_NAME = "Weather Widget"
WEATHER_WIDGET_DESCRIPTION = "Interactive weather display for MCP Apps"
WEATHER_WIDGET_MIME_TYPE = "text/html;profile=mcp-app"

# Metadata for the resource 
RESOURCE_METADATA = '{"ui": {"prefersBorder": true}}'

@app.mcp_resource_trigger(
    arg_name="context",
    uri=WEATHER_WIDGET_URI,
    resource_name=WEATHER_WIDGET_NAME,
    description=WEATHER_WIDGET_DESCRIPTION,
    mime_type=WEATHER_WIDGET_MIME_TYPE,
    metadata=RESOURCE_METADATA
)
def get_weather_widget(context) -> str:
    """Get the weather widget HTML content."""
    logging.info("Getting weather widget")

    current_dir = Path(__file__).parent
    file_path = current_dir / "app" / "dist" / "index.html"

    if file_path.exists():
        return file_path.read_text(encoding="utf-8")
    else:
        logging.warning(f"Weather widget file not found at: {file_path}")
        return """<!DOCTYPE html>
        <html>
        <head><title>Weather Widget</title></head>
        <body>
        <h1>Weather Widget</h1>
        <p>Widget content not found. Please ensure the app/index.html file exists.</p>
        </body>
        </html>"""

Uma ferramenta pode referenciar este recurso declarando a resourceUri nos seus metadados, apontando para ui://weather/index.html. Quando a ferramenta é invocada, o host MCP recupera o recurso e renderiza-o:

# Metadata for the tool
TOOL_METADATA = '{"ui": {"resourceUri": "ui://weather/index.html"}}'

@app.mcp_tool(metadata=TOOL_METADATA)
@app.mcp_tool_property(arg_name="location", description="City name to check weather for (e.g., Seattle, New York, Miami)")
def get_weather(location: str) -> Dict[str, Any]:
    """Returns current weather for a location via Open-Meteo."""
    logging.info(f"Getting weather for location: {location}")

    result = weather_service.get_current_weather(location)
    return json.dumps(result)

Para o exemplo completo do código, veja function_app.py.

O código seguinte regista um recurso nomeado Weather Widget que serve como um ecrã meteorológico interativo como conteúdo HTML agrupado. O recurso usa o ui:// esquema para indicar que é um recurso da interface da aplicação MCP.

private static final String RESOURCE_METADATA = """
        {
            "ui": {
                "prefersBorder": true
            }
        }
        """;

@FunctionName("GetWeatherWidget")
public String getWeatherWidget(
        @McpResourceTrigger(
                name = "context",
                uri = "ui://weather/index.html",
                resourceName = "Weather Widget",
                title = "Weather Widget",
                description = "Interactive weather display for MCP Apps",
                mimeType = "text/html;profile=mcp-app")
        @McpMetadata(
                name = "context",
                json = RESOURCE_METADATA)
        String context,
        final ExecutionContext executionContext) {

    executionContext.getLogger().info("GetWeatherWidget: serving weather widget UI");

    return java.nio.file.Files.readString(file.toPath(), StandardCharsets.UTF_8);
}

Uma ferramenta pode referenciar este recurso declarando a resourceUri nos seus metadados, apontando para ui://weather/index.html. Quando a ferramenta é invocada, o host MCP recupera o recurso e renderiza-o:

private static final String TOOL_METADATA = """
        {
            "ui": {
                "resourceUri": "ui://weather/index.html"
            }
        }
        """;

@FunctionName("GetWeather")
public String getWeather(
        @McpToolTrigger(
                name = "GetWeather",
                description = "Returns current weather for a location via Open-Meteo.")
        @McpMetadata(
                name = "GetWeather",
                json = TOOL_METADATA)
        String context,
        @McpToolProperty(
                name = "location",
                propertyType = "string",
                description = "City name to check weather for (e.g., Seattle, New York, Miami)")
        String location,
        final ExecutionContext executionContext) {

    executionContext.getLogger().info("GetWeather: looking up weather for '" + location + "'");

    Object result = weatherService.getCurrentWeather(location);

    return MAPPER.writeValueAsString(result);
}

Para o exemplo completo do código, veja WeatherFunction.java.

Attributes

As bibliotecas C# são usadas McpResourceTriggerAttribute para definir o gatilho de função.

O construtor do atributo usa os seguintes parâmetros:

O atributo também suporta as seguintes propriedades nomeadas:

Podes usar o [McpMetadata] atributo para fornecer mais metadados aos recursos. Estes metadados são incluídos no campo meta de cada recurso quando os clientes chamam resources/list, e podem influenciar a forma como o conteúdo do recurso é exibido ou processado.

Consulte Utilização para saber como o disparador de recurso fornece dados à sua função.

Decoradores

As seguintes propriedades de disparo de recurso MCP são suportadas em:mcp_resource_trigger

Configuração

Defina as opções de vinculação do gatilho no seu código. O gatilho suporta as seguintes opções:

Attributes

Aplicar a @McpResourceTrigger anotação a um parâmetro de função para definir um gatilho de recurso MCP.

A @McpResourceTrigger anotação suporta as seguintes propriedades:

Anotação de metadados

Podes, opcionalmente, aplicar @McpMetadata no mesmo parâmetro que @McpResourceTrigger para anexar metadados JSON arbitrários ao recurso. Estes metadados são apresentados no campo do _meta protocolo MCP quando os clientes chamam resources/list.

A @McpMetadata anotação suporta as seguintes propriedades:

Exemplo:

@McpResourceTrigger(
        name = "context",
        uri = "file://readme.md",
        resourceName = "readme",
        description = "Application readme file",
        mimeType = "text/plain")
@McpMetadata(
        name = "context",
        json = "{\"author\": \"John Doe\", \"version\": 1.0}")

Consulte a seção Exemplo para obter exemplos completos.

Usage

O disparador de recurso MCP pode ser ligado aos seguintes tipos:

O ResourceInvocationContext tipo fornece as seguintes propriedades:

O mcp_resource_trigger decorador liga-se a um parâmetro de contexto que representa o pedido de recurso do cliente MCP. O gatilho pode ligar-se aos seguintes tipos: str, dict, ou bytes.

A função de gestor de recursos tem dois parâmetros:

O disparador de recurso MCP liga o contexto de invocação de recurso a um parâmetro de função. O gatilho pode ligar-se aos seguintes tipos: String, ou byte[] para conteúdo binário.

URIs de recursos

Os recursos MCP utilizam URIs para definir o endereço do recurso. O URI identifica de forma única o recurso e é o que os clientes usam para o solicitar. Pode usar qualquer esquema de URI apropriado para o seu recurso, como ui:// para recursos de interface ou file:// para recursos baseados em ficheiros.

Metadados de recursos

Use o McpMetadata atributo para fornecer metadados extra para os recursos. Os clientes MCP recebem estes metadados, o que pode afetar a forma como o conteúdo do recurso é exibido ou processado.

Para fornecer metadados extra para os recursos, use o metadata parâmetro no mcp_resource_trigger decorador. Estes metadados são uma cadeia serializada em JSON incluída no meta campo de cada recurso quando os clientes chamam resources/list. Pode afetar a forma como o conteúdo do recurso é exibido ou processado.

Use a metadata opção para fornecer metadados extra para os recursos. Estes metadados são uma cadeia serializada em JSON incluída no meta campo de cada recurso quando os clientes chamam resources/list. Pode afetar a forma como o conteúdo do recurso é exibido ou processado.

Use a @McpMetadata anotação para fornecer metadados extra para os recursos. Estes metadados são uma cadeia serializada em JSON incluída no meta campo de cada recurso quando os clientes chamam resources/list. Pode afetar a forma como o conteúdo do recurso é exibido ou processado.

Tipos de devolução

O gatilho de recurso MCP suporta os seguintes tipos de retorno:

O gatilho de recurso MCP suporta os seguintes tipos de retorno:

A função deve devolver a string contendo o conteúdo do recurso (por exemplo, HTML, JSON ou texto simples).

O gatilho de recurso MCP suporta os seguintes tipos de retorno:

Descoberta de recursos

Quando uma aplicação de funções inicia, regista todas as funções de disparo de recursos no servidor MCP. Os clientes encontram recursos disponíveis ligando ao método MCP resources/list . Este método devolve o URI, nome, descrição, tipo MIME, tamanho e metadados de cada recurso (através do meta campo). Os clientes leem um recurso ligando resources/read com o URI do recurso.

Sessions

A SessionId propriedade em ResourceInvocationContext identifica a sessão MCP que faz o pedido. Use esta propriedade para manter o estado por sessão ou aplicar lógica específica da sessão ao servir recursos.

Para obter mais informações, consulte Exemplos.

configurações host.json

O arquivo host.json contém configurações que controlam comportamentos de gatilho MCP. Consulte a seção Configurações de host.json para obter detalhes sobre as configurações disponíveis.