Azure İşlevleri için MCP kaynak tetikleyicisi

Model Bağlam Protokolü (MCP) sunucusunda kaynak uç noktalarını tanımlamak için MCP kaynak tetikleyicisini kullanın. İstemciler, dosya içeriği, veritabanı şemaları veya API belgeleri gibi bağlam bilgilerine erişmek için kaynakları kullanabilir.

Kurulum ve yapılandırma ayrıntıları hakkında bilgi için genel bakışa bakın.

MCP kaynak tetikleyicisini kullanmaya ilişkin eksiksiz bir uçtan uca örnek için bkz. Azure İşlevleri kullanarak MCP Uygulamaları oluşturma.

Example

Uyarı

C# için Azure İşlevleri MCP uzantısı yalnızca isolated worker model destekler.

Bu ilk örnekte, MCP Uygulamalarının kullanıcı arabirimi öğesini uygulamak için kaynağın nasıl kullanılacağı gösterilmektedir.

Aşağıdaki kod, etkileşimli bir hava durumu gösterimini paketlenmiş HTML içeriği olarak sunan adlı Weather Widget kaynağı kullanıma sunmak için bir uç nokta oluşturur. Kaynak, bunun bir MCP Uygulama Kullanıcı Arabirimi kaynağı olduğunu belirtmek için düzenini kullanır ui:// .

// 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);
}

Bir araç, meta verilerinde öğesini işaret resourceUri ederek ui://weather/index.htmlbu kaynağa başvurabilir. Araç çağrıldığında, MCP konağı kaynağı getirir ve işler:

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

Kod örneğinin tamamı için bkz. WeatherFunction.cs.

Bu kod örneği, markdown dosyasını okuyan ve içeriğini düz metin olarak döndüren adlı readme kaynağı kullanıma sunan bir uç nokta oluşturur. İstemciler URI'yi file://readme.md kullanarak bu kaynağa erişebilir.

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

Bu örnekte, dosyasında aşağıdaki yönerge bulunduğundanassets, öğesini içeren readme adlı .csproj bir klasör derleme zamanında işlev uygulamasıyla birlikte gelir:

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

Kod örneğinin tamamı için bkz. Azure İşlevleri MCP Uzantısı deposu.

JavaScript için örnek kod şu anda kullanılamıyor. Genel yönergeler için TypeScript örneğine bakın.

Aşağıdaki kod, etkileşimli bir hava durumu görüntüsü sunan adlı Weather Widget bir kaynağı paketlenmiş HTML içeriği olarak kaydeder. Kaynak, bunun bir MCP Uygulama Kullanıcı Arabirimi kaynağı olduğunu belirtmek için düzenini kullanır ui:// .

// 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,
});

Aşağıdaki kod işleyicidir getWeatherWidget :

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

Bir araç, meta verilerinde bir resourceUri bildirerek bu kaynağa başvurabilir. Araç çağrıldığında, MCP konağı kaynağı getirir ve işler:

// 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,
});

Kod örneğinin tamamı için bkz. weatherMcpApp.ts.

Önemli

TypeScript için MCP kaynak tetikleyicisi paketin sürümünü veya sonraki bir sürümünü 4.12.0@azure/functions gerektirir.

Aşağıdaki kod, etkileşimli bir hava durumu görüntüsü sunan adlı Weather Widget bir kaynağı paketlenmiş HTML içeriği olarak kaydeder. Kaynak, bunun bir MCP Uygulama Kullanıcı Arabirimi kaynağı olduğunu belirtmek için düzenini kullanır ui:// .

# 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>"""

Bir araç, meta verilerinde öğesini işaret resourceUri ederek ui://weather/index.htmlbu kaynağa başvurabilir. Araç çağrıldığında, MCP konağı kaynağı getirir ve işler:

# 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)

Kod örneğinin tamamı için bkz. function_app.py.

Uyarı

Python için MCP kaynak tetikleyicisi, 2.0.0 paketinin azure-functions veya sonraki bir sürümünü gerektirir ve Python 3.13 veya üzerini kullanır.

Aşağıdaki kod, etkileşimli bir hava durumu görüntüsü sunan adlı Weather Widget bir kaynağı paketlenmiş HTML içeriği olarak kaydeder. Kaynak, bunun bir MCP Uygulama Kullanıcı Arabirimi kaynağı olduğunu belirtmek için düzenini kullanır ui:// .

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");

    // Load the bundled HTML file from the CWD-relative path
    java.io.File file = new java.io.File("app/dist/index.html");
    if (file.exists()) {
        return java.nio.file.Files.readString(file.toPath(), StandardCharsets.UTF_8);
    }

    return "<html><body><p>Weather widget UI not found.</p></body></html>";
}

Bir araç, meta verilerinde öğesini işaret resourceUri ederek ui://weather/index.htmlbu kaynağa başvurabilir. Araç çağrıldığında, MCP konağı kaynağı getirir ve işler:

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

Kod örneğinin tamamı için bkz. WeatherFunction.java.

Önemli

MCP uzantısı şu anda PowerShell uygulamalarını desteklemez.

Özellikler

C# kitaplıkları işlev tetikleyicisini tanımlamak için kullanır McpResourceTriggerAttribute .

Özniteliğin oluşturucu aşağıdaki parametreleri alır:

Parametre Description
Urı (Gerekli) Kaynağın adresini tanımlayan URI. Örneğin, ui://weather/index.html statik kaynak URI'sini tanımlar.
ResourceName (Gerekli) MCP kaynak tetikleyici uç noktasının kullanıma açık olduğu kaynağın adı.

özniteliği aşağıdaki adlandırılmış özellikleri de destekler:

Mülkiyet Description
Açıklama (İsteğe bağlı) İstemciler için kaynak uç noktasının kolay açıklaması.
Başlık (İsteğe bağlı) MCP istemci arabirimlerinde görüntüleme amacıyla insan tarafından okunabilen bir başlık.
Mime Türü (İsteğe bağlı) Kaynak tarafından döndürülen içeriğin MIME türü. Örneğin, text/html;profile=mcp-app MCP Uygulama Kullanıcı Arabirimi kaynakları, text/plain düz metin veya application/json JSON verileri için.
Boyut (İsteğe bağlı) Kaynak içeriğinin bayt cinsinden boyutu.
Meta veriler (İsteğe bağlı) Kaynak için JSON serileştirilmiş meta veri dizesi. Meta verileri sağlamanın McpMetadata alternatif bir yolu olarak özniteliğini de kullanabilirsiniz.

Kaynaklar için daha fazla meta veri sağlamak için özniteliğini [McpMetadata] kullanabilirsiniz. bu meta veriler, istemcileri tarafından çağrıldığında resources/listher kaynağın meta alanına eklenir ve kaynak içeriğinin görüntülenme veya işlenme şeklini etkileyebilir.

Kaynak tetikleyicisinin işlevinize nasıl veri sağladığını öğrenmek için bkz. Kullanım .

Dekoratörler

Aşağıdaki MCP kaynak tetikleyicisi özellikleri üzerinde mcp_resource_triggerdesteklenir:

Mülkiyet Description
arg_name Tetikleyici yüküne erişmek için işlev kodunda kullanılan değişken adı (genellikle context).
Urı (Gerekli) Kaynak için benzersiz URI tanımlayıcısı. Mutlak bir URI olmalıdır.
resource_name (Gerekli) Kaynağın okunabilir adı.
başlık MCP istemci arabirimlerinde görüntüleme amacıyla isteğe bağlı bir başlık.
Açıklama İşlev uç noktası tarafından kullanıma sunulan MCP kaynağının açıklaması.
mime_type Kaynak tarafından döndürülen içeriğin MIME türü. Örneğin, text/html;profile=mcp-app MCP Uygulama Kullanıcı Arabirimi kaynakları için, text/plain düz metin için.
boyut Biliniyorsa, kaynak içeriğinin bayt cinsinden beklenen boyutu.
meta veriler Kaynak için ek meta verilerin JSON serileştirilmiş dizesi.

Uyarı

Dekoratörler yalnızca Python v2 programlama modelinde kullanılabilir.

Konfigürasyon

Tetikleyicinin bağlama seçeneklerini kodunuzda tanımlayın. Tetikleyici aşağıdaki seçenekleri destekler:

Seçenek Description
type mcpResourceTrigger olarak ayarlayın. Yalnızca genel tanımlarla kullanın.
Urı (Gerekli) İşlev uç noktasının kullanıma açık olduğu MCP kaynağının URI'sini. Mutlak bir URI olmalıdır.
Resourcename (Gerekli) İşlev uç noktasının kullanıma koyduğu MCP kaynağının okunabilir adı.
başlık MCP istemci arabirimlerinde görüntüleme amacıyla isteğe bağlı bir başlık.
Açıklama İşlev uç noktasının kullanıma sunan MCP kaynağının açıklaması.
Mimetype Kaynak tarafından döndürülen içeriğin MIME türü. Örneğin, text/html;profile=mcp-app.
boyut Biliniyorsa, kaynak içeriğinin bayt cinsinden beklenen boyutu.
meta veriler Kaynak için ek meta verilerin JSON serileştirilmiş dizesi.
kontrolcü Gerçek işlev kodunu içeren yöntem.

Özellikler

MCP kaynak tetikleyicisi @McpResourceTrigger tanımlamak için ek açıklamayı bir işlev parametresine uygulayın.

Ek @McpResourceTrigger açıklama aşağıdaki özellikleri destekler:

Mülkiyet Description
name Gerekli. Kaynak çağırma bağlam parametresinin bağlama adı.
uri Gerekli. MCP kaynağının URI'sini (örneğin, "file://readme.md" veya "ui://weather/index.html").
resourceName Gerekli. MCP kaynağının görünen adı.
title Optional. Görüntüleme amacıyla insan tarafından okunabilen bir başlık. Programlama tanımlayıcısı olan 'nin aksine resourceName, bu kullanıcı arabirimi sunusu için kolay bir etikettir.
description Optional. Bu kaynağın okunabilir bir açıklaması.
mimeType Optional. Kaynak içeriğinin MIME türü (örneğin, "text/plain", "text/html", "image/png"). "text/html;profile=mcp-app"
size Optional. Kaynağın bayt cinsinden boyutu. varsayılan değeri -1 (belirtilmedi).
dataType Optional. İşlevler çalışma zamanının parametre değerini nasıl ele alması gerektiğini tanımlar. Olası değerler: "" (varsayılan, parametre türüne seri durumdan çıkarma), "string", "binary".

Meta veri ek açıklaması

İsteğe bağlı olarak kaynağa rastgele JSON meta verileri eklemek için aynı parametreye @McpMetadata uygulayabilirsiniz@McpResourceTrigger. İstemciler çağırdığında _metabu meta veriler MCP protokollerinin resources/list alanında ortaya çıkar.

Ek @McpMetadata açıklama aşağıdaki özellikleri destekler:

Mülkiyet Description
name Gerekli. Bağlama parametresi adı. Aynı parametredeki name tetikleyici ek açıklamasının değeriyle eşleşmelidir.
json Gerekli. Geçerli bir JSON dizesi olarak meta veriler. Yazar bilgileri, sürüm numaraları, kullanıcı arabirimi ipuçları veya etiketler gibi rastgele anahtar-değer çiftlerini içerebilir.

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}")

Tam örnekler için Örnek bölümüne bakın.

Usage

MCP kaynak tetikleyicisi aşağıdaki türlere bağlanabilir:

Türü Description
ResourceInvocationContext Kaynak URI'si, oturum kimliği ve aktarım bilgileri de dahil olmak üzere kaynak isteğini temsil eden bir nesne.

türü ResourceInvocationContext aşağıdaki özellikleri sağlar:

Mülkiyet Türü Description
Urı string İstenen kaynağın URI'sini.
SessionId string? Geçerli kaynak çağrısıyla ilişkili oturum kimliği.
Taşıma Transport? Geçerli çağrı için taşıma bilgileri.

Dekoratör, mcp_resource_trigger MCP istemcisinden gelen kaynak isteğini temsil eden bir bağlam parametresine bağlanır. Tetikleyici şu türlere bağlanabilir: str, dict, veya bytes.

Kaynak işleyici işlevinin iki parametresi vardır:

Parametre Türü Description
iletiler T (varsayılan olarak unknown) MCP uzantısı tarafından geçirilen tetikleyici yükü. (Yukarıdaki örnek bu parametreyi resourceContextadlandırıyor.)
Bağlam InvocationContext Günlüğe kaydetme ve diğer çalışma zamanı bilgilerini sağlayan Azure İşlevleri çağırma bağlamı.

MCP kaynak tetikleyicisi, kaynak çağırma bağlamını bir işlev parametresine bağlar. Tetikleyici şu türlere bağlanabilir: String, veya byte[] ikili içerik için.

Kaynak URI'leri

MCP kaynakları, kaynağın adresini tanımlamak için URI'leri kullanır. URI, kaynağı benzersiz olarak tanımlar ve istemcilerin bunu istemek için kullandığı kaynaktır. Kullanıcı arabirimi kaynakları veya ui:// dosya tabanlı kaynaklar gibi file:// kaynağınıza uygun herhangi bir URI düzenini kullanabilirsiniz.

Kaynak meta verileri

McpMetadata Kaynaklar için ek meta veriler sağlamak için özniteliğini kullanın. MCP istemcileri bu meta verileri alır ve kaynak içeriğinin görüntülenme veya işlenme şeklini etkileyebilir.

Kaynaklar için ek meta veriler sağlamak için dekoratördeki parametresini metadata kullanınmcp_resource_trigger. Bu meta veriler, istemcileri çağırdığında metaher kaynağın resources/list alanına dahil edilen JSON serileştirilmiş bir dizedir. Kaynak içeriğinin görüntülenme veya işlenme şeklini etkileyebilir.

metadata Kaynaklar için ek meta veriler sağlamak için seçeneğini kullanın. Bu meta veriler, istemcileri çağırdığında metaher kaynağın resources/list alanına dahil edilen JSON serileştirilmiş bir dizedir. Kaynak içeriğinin görüntülenme veya işlenme şeklini etkileyebilir.

Kaynaklar için ek meta veriler sağlamak için ek açıklamayı @McpMetadata kullanın. Bu meta veriler, istemcileri çağırdığında metaher kaynağın resources/list alanına dahil edilen JSON serileştirilmiş bir dizedir. Kaynak içeriğinin görüntülenme veya işlenme şeklini etkileyebilir.

Dönüş türleri

MCP kaynak tetikleyicisi aşağıdaki dönüş türlerini destekler:

Türü Description
string MCP'de ReadResourceResultmetin içeriği olarak döndürülür.
byte[] MCP'de ReadResourceResultbase64 kodlu blob içeriği olarak döndürülür.

MCP kaynak tetikleyicisi aşağıdaki dönüş türlerini destekler:

Türü Description
str MCP'de ReadResourceResultmetin içeriği olarak döndürülür.
bytes MCP'de ReadResourceResultikili içerik olarak döndürülür.

İşlev, kaynak içeriğini (örneğin, HTML, JSON veya düz metin) içeren bir string döndürmelidir.

MCP kaynak tetikleyicisi aşağıdaki dönüş türlerini destekler:

Türü Description
String MCP'de ReadResourceResultmetin içeriği olarak döndürülür.
byte[] MCP'de ReadResourceResultbase64 kodlu ikili içerik olarak döndürülür. İkili içerik döndürülirken ek açıklamaya göre ayarlayın dataType = "binary" .

Kaynak bulma

Bir işlev uygulaması başlatıldığında, tüm kaynak tetikleyici işlevlerini MCP sunucusuna kaydeder. İstemciler MCP resources/list yöntemini çağırarak kullanılabilir kaynakları bulur. Bu yöntem her kaynağın URI'sini, adını, açıklamasını, MIME türünü, boyutunu ve meta verilerini döndürür (alan aracılığıyla meta ). İstemciler, kaynak URI'siyle çağırarak resources/read bir kaynağı okur.

Sessions

üzerindeki SessionIdResourceInvocationContext özelliği, isteği yapan MCP oturumunu tanımlar. Oturum başına durumu korumak veya kaynaklara hizmet ederken oturuma özgü mantık uygulamak için bu özelliği kullanın.

Daha fazla bilgi için bkz. Örnekler.

host.json ayarları

host.json dosyası, MCP tetikleyici davranışlarını denetleen ayarlar içerir. Kullanılabilir ayarlarla ilgili ayrıntılar için host.json ayarları bölümüne bakın.

Azure İşlevleriMCP aracı tetikleyicisi>

  • Last updated on