Gatilho de recurso mcp para Azure Functions

Este primeiro exemplo mostra como usar o recurso para implementar o elemento de interface do usuário dos Aplicativos MCP.

O código a seguir cria um ponto de extremidade para expor um recurso nomeado Weather Widget que serve a uma exibição meteorológica interativa como conteúdo HTML agrupado. O recurso usa o ui:// esquema para indicar que é um recurso de interface do usuário do aplicativo 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 esse recurso declarando um resourceUri em seus metadados, apontando para ui://weather/index.html. Quando a ferramenta é invocada, o host MCP busca o recurso e o renderiza:

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 obter o exemplo de código completo, consulte WeatherFunction.cs.

Este exemplo de código cria um ponto de extremidade para expor um recurso chamado readme que lê um arquivo markdown e retorna seu conteúdo como texto sem formatação. Os clientes podem acessar esse 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 que contém o readme pacote é agrupada com o aplicativo de funções no momento do build porque a seguinte diretiva está presente no .csproj arquivo:

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

Para obter o exemplo de código completo, consulte o Azure Functions repositório de extensão MCP.

O código de exemplo para JavaScript não está disponível no momento. Consulte o exemplo de TypeScript para obter diretrizes gerais.

O código a seguir registra um recurso nomeado Weather Widget que serve a uma exibição meteorológica interativa como conteúdo HTML agrupado. O recurso usa o ui:// esquema para indicar que é um recurso de interface do usuário do aplicativo 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 manipulador:

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 esse recurso declarando um resourceUri em seus metadados. Quando a ferramenta é invocada, o host MCP busca o recurso e o renderiza:

// 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 obter o exemplo de código completo, consulte weatherMcpApp.ts.

O código a seguir registra um recurso nomeado Weather Widget que serve a uma exibição meteorológica interativa como conteúdo HTML agrupado. O recurso usa o ui:// esquema para indicar que é um recurso de interface do usuário do aplicativo 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 esse recurso declarando um resourceUri em seus metadados, apontando para ui://weather/index.html. Quando a ferramenta é invocada, o host MCP busca o recurso e o renderiza:

# 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 obter o exemplo de código completo, consulte function_app.py.

O código a seguir registra um recurso nomeado Weather Widget que serve a uma exibição meteorológica interativa como conteúdo HTML agrupado. O recurso usa o ui:// esquema para indicar que é um recurso de interface do usuário do aplicativo 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 esse recurso declarando um resourceUri em seus metadados, apontando para ui://weather/index.html. Quando a ferramenta é invocada, o host MCP busca o recurso e o renderiza:

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 obter o exemplo de código completo, consulte WeatherFunction.java.

Attributes

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

O construtor do atributo recebe os seguintes parâmetros:

O atributo também dá suporte às seguintes propriedades nomeadas:

Você pode usar o [McpMetadata] atributo para fornecer mais metadados para recursos. Esses metadados são incluídos no campo metadado de cada recurso quando os clientes chamam resources/liste podem influenciar como o conteúdo do recurso é exibido ou processado.

Consulte Uso para saber como o gatilho de recurso fornece dados para sua função.

Decoradores

As seguintes propriedades de gatilho de recurso do MCP têm suporte em mcp_resource_trigger:

Configuração

Defina as opções de associação do gatilho em seu código. O gatilho dá suporte às seguintes opções:

Attributes

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

A @McpResourceTrigger anotação dá suporte às seguintes propriedades:

Anotação de metadados

Opcionalmente, você pode aplicar @McpMetadata no mesmo parâmetro @McpResourceTrigger que anexar metadados JSON arbitrários ao recurso. Esses metadados são exibidos no campo do _meta protocolo MCP quando os clientes chamam resources/list.

A @McpMetadata anotação dá suporte às 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 de exemplo para obter exemplos completos.

Usage

O gatilho de recurso MCP pode ser associado aos seguintes tipos:

O ResourceInvocationContext tipo fornece as seguintes propriedades:

O mcp_resource_trigger decorador associa-se a um parâmetro de contexto que representa a solicitação de recurso do cliente MCP. O gatilho pode se associar aos seguintes tipos: str, dictou bytes.

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

O gatilho de recurso MCP associa o contexto de invocação de recurso a um parâmetro de função. O gatilho pode se associar aos seguintes tipos: Stringou byte[] para conteúdo binário.

URIs de recurso

Os recursos do MCP usam URIs para definir o endereço do recurso. O URI identifica exclusivamente o recurso e é o que os clientes usam para solicitá-lo. Você pode usar qualquer esquema de URI apropriado para seu recurso, como ui:// para recursos de interface do usuário ou file:// para recursos baseados em arquivo.

Metadados de recurso

Use o McpMetadata atributo para fornecer metadados extras para recursos. Os clientes MCP recebem esses metadados e isso pode afetar a forma como o conteúdo do recurso é exibido ou processado.

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

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

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

Tipos de retorno

O gatilho de recurso MCP dá suporte aos seguintes tipos de retorno:

O gatilho de recurso MCP dá suporte aos seguintes tipos de retorno:

A função deve retornar um string conteúdo de recurso que contenha (por exemplo, HTML, JSON ou texto sem formatação).

O gatilho de recurso MCP dá suporte aos seguintes tipos de retorno:

Descoberta de recursos

Quando um aplicativo de funções é iniciado, ele registra todas as funções de gatilho de recurso com o servidor MCP. Os clientes descobrem os recursos disponíveis chamando o método MCP resources/list . Esse método retorna o URI, o nome, a descrição, o tipo MIME, o tamanho e os metadados de cada recurso (por meio do meta campo). Os clientes leem um recurso chamando resources/read com o URI do recurso.

Sessions

A SessionId propriedade na ResourceInvocationContext qual identifica a sessão MCP que está fazendo a solicitação. Use essa propriedade para manter o estado por sessão ou aplicar a lógica específica da sessão ao servir recursos.

Para obter mais informações, consulte Exemplos.

configurações de host.json

O arquivo host.json contém configurações que controlam os comportamentos do gatilho MCP. Confira a seção Configurações de host.json para obter detalhes em relação às configurações disponíveis.