Desencadenador de recursos MCP para Azure Functions

En este primer ejemplo se muestra cómo usar el recurso para implementar el elemento de interfaz de usuario de APLICACIONES MCP.

El código siguiente crea un punto de conexión para exponer un recurso denominado Weather Widget que sirve una presentación meteorológica interactiva como contenido HTML agrupado. El recurso usa el ui:// esquema para indicar que es un recurso de interfaz de usuario de aplicación de 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);
}

Una herramienta puede hacer referencia a este recurso declarando en resourceUri sus metadatos, apuntando a ui://weather/index.html. Cuando se invoca la herramienta, el host de MCP captura el recurso y lo representa:

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 obtener el ejemplo de código completo, vea WeatherFunction.cs.

En este ejemplo de código se crea un punto de conexión para exponer un recurso denominado readme que lee un archivo markdown y devuelve su contenido como texto sin formato. Los clientes pueden acceder a este recurso mediante el 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);
    }

En este ejemplo, una carpeta denominada assets que contiene readme se agrupa con la aplicación de funciones en tiempo de compilación porque la siguiente directiva está presente en el .csproj archivo:

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

Para obtener el ejemplo de código completo, consulte el repositorio de extensión MCP de Azure Functions.

El código de ejemplo para JavaScript no está disponible actualmente. Consulte el ejemplo de TypeScript para obtener instrucciones generales.

El código siguiente registra un recurso denominado Weather Widget que sirve una presentación meteorológica interactiva como contenido HTML agrupado. El recurso usa el ui:// esquema para indicar que es un recurso de interfaz de usuario de aplicación de 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,
});

El código siguiente es el getWeatherWidget controlador:

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>`;
  }
}

Una herramienta puede hacer referencia a este recurso declarando un resourceUri elemento en sus metadatos. Cuando se invoca la herramienta, el host de MCP captura el recurso y lo representa:

// 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 obtener el ejemplo de código completo, vea weatherMcpApp.ts.

El código siguiente registra un recurso denominado Weather Widget que sirve una presentación meteorológica interactiva como contenido HTML agrupado. El recurso usa el ui:// esquema para indicar que es un recurso de interfaz de usuario de aplicación de 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>"""

Una herramienta puede hacer referencia a este recurso declarando en resourceUri sus metadatos, apuntando a ui://weather/index.html. Cuando se invoca la herramienta, el host de MCP captura el recurso y lo representa:

# 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 obtener el ejemplo de código completo, vea function_app.py.

El código siguiente registra un recurso denominado Weather Widget que sirve una presentación meteorológica interactiva como contenido HTML agrupado. El recurso usa el ui:// esquema para indicar que es un recurso de interfaz de usuario de aplicación de 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);
}

Una herramienta puede hacer referencia a este recurso declarando en resourceUri sus metadatos, apuntando a ui://weather/index.html. Cuando se invoca la herramienta, el host de MCP captura el recurso y lo representa:

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 obtener el ejemplo de código completo, vea WeatherFunction.java.

Attributes

Las bibliotecas de C# usan McpResourceTriggerAttribute para definir el desencadenador de función.

El constructor del atributo toma los parámetros siguientes:

El atributo también admite las siguientes propiedades con nombre:

Puede usar el [McpMetadata] atributo para proporcionar más metadatos para los recursos. Estos metadatos se incluyen en el meta campo de cada recurso cuando los clientes llaman a resources/listy pueden influir en cómo se muestra o procesa el contenido del recurso.

Consulte Uso para obtener información sobre cómo el desencadenador de recursos proporciona datos a la función.

Elementos Decorator

Las siguientes propiedades del desencadenador de recursos MCP se admiten en mcp_resource_trigger:

Configuración

Defina las opciones de enlace del desencadenador en el código. El desencadenador admite las siguientes opciones:

Attributes

Aplique la @McpResourceTrigger anotación a un parámetro de función para definir un desencadenador de recursos MCP.

La @McpResourceTrigger anotación admite las siguientes propiedades:

Anotación de metadatos

Opcionalmente, puede aplicar @McpMetadata en el mismo parámetro que @McpResourceTrigger para adjuntar metadatos JSON arbitrarios al recurso. Estos metadatos se muestran en el campo del _meta protocolo MCP cuando los clientes llaman a resources/list.

La @McpMetadata anotación admite las siguientes propiedades:

Example:

@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 la sección de ejemplos para ver ejemplos completos.

Usage

El desencadenador de recursos MCP puede enlazarse a los siguientes tipos:

El ResourceInvocationContext tipo proporciona las siguientes propiedades:

El mcp_resource_trigger decorador se enlaza a un parámetro de contexto que representa la solicitud de recursos del cliente MCP. El desencadenador puede enlazarse a los siguientes tipos: str, dicto bytes.

La función de controlador de recursos tiene dos parámetros:

El desencadenador de recursos MCP enlaza el contexto de invocación de recursos a un parámetro de función. El desencadenador puede enlazarse a los siguientes tipos: Stringo byte[] para el contenido binario.

URI de recursos

Los recursos de MCP usan URI para definir la dirección del recurso. El URI identifica de forma única el recurso y es lo que los clientes usan para solicitarlo. Puede usar cualquier esquema de URI adecuado para el recurso, como ui:// para los recursos de la interfaz de usuario o file:// para los recursos basados en archivos.

Metadatos de recursos

Use el McpMetadata atributo para proporcionar metadatos adicionales para los recursos. Los clientes de MCP reciben estos metadatos y pueden afectar a cómo se muestra o procesa el contenido del recurso.

Para proporcionar metadatos adicionales para los recursos, use el metadata parámetro en el mcp_resource_trigger decorador. Estos metadatos son una cadena serializada por JSON incluida en el meta campo de cada recurso cuando los clientes llaman a resources/list. Puede afectar a cómo se muestra o procesa el contenido del recurso.

Use la metadata opción para proporcionar metadatos adicionales para los recursos. Estos metadatos son una cadena serializada por JSON incluida en el meta campo de cada recurso cuando los clientes llaman a resources/list. Puede afectar a cómo se muestra o procesa el contenido del recurso.

Use la @McpMetadata anotación para proporcionar metadatos adicionales para los recursos. Estos metadatos son una cadena serializada por JSON incluida en el meta campo de cada recurso cuando los clientes llaman a resources/list. Puede afectar a cómo se muestra o procesa el contenido del recurso.

Tipos de retorno

El desencadenador de recursos MCP admite los siguientes tipos de valor devuelto:

El desencadenador de recursos MCP admite los siguientes tipos de valor devuelto:

La función debe devolver un string elemento que contenga el contenido del recurso (por ejemplo, HTML, JSON o texto sin formato).

El desencadenador de recursos MCP admite los siguientes tipos de valor devuelto:

Detección de recursos

Cuando se inicia una aplicación de funciones, registra todas las funciones del desencadenador de recursos con el servidor MCP. Los clientes detectan los recursos disponibles llamando al método MCP resources/list . Este método devuelve el URI, el nombre, la descripción, el tipo MIME, el tamaño y los metadatos de cada recurso (a través del meta campo). Los clientes leen un recurso llamando resources/read a con el URI del recurso.

Sessions

La SessionId propiedad de ResourceInvocationContext identifica la sesión de MCP que realiza la solicitud. Use esta propiedad para mantener el estado por sesión o aplicar lógica específica de la sesión al atender recursos.

Para más información, consulte Ejemplos.

configuración de host.json

El archivo host.json contiene la configuración que controla los comportamientos del desencadenador MCP. Consulte la sección de configuración de host.json para más información sobre las opciones de configuración disponibles.