Azure İşlevleri için MCP aracı tetikleyicisi

Model İçerik Protokolü (MCP) sunucusunda araç uç noktalarını tanımlamak için MCP araç tetikleyicisini kullanın. İstemci dili modelleri ve aracıları, kod parçacıklarını depolama veya bunlara erişme gibi belirli görevleri gerçekleştirmek için araçları kullanabilir.

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

Örnek

Uyarı

C# için Azure İşlevleri MCP uzantısı yalnızca yalıtılmış çalışan modelini destekler.

Bu kod, adlandırılmış kod parçacığını blob depolamada kalıcı hale getirmeye çalışan adlı SaveSnippet bir aracı kullanıma sunan bir uç nokta oluşturur.

private const string BlobPath = "snippets/{mcptoolargs.snippetname}.json";

[Function(nameof(SaveSnippet))]
[BlobOutput(BlobPath)]
public string SaveSnippet(
    [McpToolTrigger("save_snippet", "Saves a code snippet into your snippet collection.")]
        ToolInvocationContext context,
    [McpToolProperty("snippetname", "The name of the snippet.", isRequired: true)]
        string name,
    [McpToolProperty("snippet", "The code snippet.", isRequired: true)]
        string snippet
)
{
    return snippet;
}

Bu kod, blob depolamadan ada göre kod parçacığı almaya çalışan adlı GetSnippet bir aracı kullanıma sunan bir uç nokta oluşturur.

private const string BlobPath = "snippets/{mcptoolargs.snippetname}.json";

[Function(nameof(GetSnippet))]
public object GetSnippet(
    [McpToolTrigger("get_snippets", "Gets code snippets from your snippet collection.")]
        ToolInvocationContext context,
    [BlobInput(BlobPath)] string snippetContent
)
{
    return snippetContent;
}

İşlevin GetSnippet araç özellikleri içinde Program.csyapılandırılır:

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights();

builder
    .ConfigureMcpTool("get_snippets")
    .WithProperty("snippetname", "string", "The name of the snippet.", required: true);

builder.Build().Run();

Tavsiye

Yukarıdaki örnekte hem hem de Program.cs işlevinde "get_snippets" aracının adı gibi şeyler için değişmez dizeler kullanılmıştır. Bunun yerine, öğeleri projenizde eşitlenmiş durumda tutmak için paylaşılan sabit dizeleri kullanmayı düşünün.

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

Bu kod, adlandırılmış kod parçacığını blob depolamada kalıcı hale getirmeye çalışan adlı SaveSnippets bir aracı kullanıma sunan bir uç nokta oluşturur.

@FunctionName("SaveSnippets")
@StorageAccount("AzureWebJobsStorage")
public String saveSnippet(
        @McpToolTrigger(
                name = "saveSnippets",
                description = "Saves a text snippet to your snippets collection."
        )
        String mcpToolInvocationContext,
        @McpToolProperty(
                name = "snippetName",
                propertyType = "string",
                description = "The name of the snippet.",
                required = true
        )
        String snippetName,
        @McpToolProperty(
                name = "snippet",
                propertyType = "string",
                description = "The content of the snippet.",
                required = true
        )
        String snippet,
        @BlobOutput(name = "outputBlob", path = "snippets/{mcptoolargs.snippetName}.json")
        OutputBinding<String> outputBlob,
        final ExecutionContext context
) {
    // Log the entire incoming JSON for debugging
    context.getLogger().info(mcpToolInvocationContext);

    // Log the snippet name and content
    context.getLogger().info("Saving snippet with name: " + snippetName);
    context.getLogger().info("Snippet content:\n" + snippet);

    // Write the snippet content to the output blob
    outputBlob.setValue(snippet);

    return "Successfully saved snippet '" + snippetName + "' with " + snippet.length() + " characters.";
}

Bu kod, blob depolamadan ada göre kod parçacığı almaya çalışan adlı GetSnippets bir aracı kullanıma sunan bir uç nokta oluşturur.

@FunctionName("GetSnippets")
@StorageAccount("AzureWebJobsStorage")
public String getSnippet(
        @McpToolTrigger(
                name = "getSnippets",
                description = "Gets a text snippet from your snippets collection."
        )
        String mcpToolInvocationContext,
        @McpToolProperty(
                name = "snippetName",
                propertyType = "string",
                description = "The name of the snippet.",
                required = true
        )
        String snippetName,
        @BlobInput(name = "inputBlob", path = "snippets/{mcptoolargs.snippetName}.json")
        String inputBlob,
        final ExecutionContext context
) {
    // Log the entire incoming JSON for debugging
    context.getLogger().info(mcpToolInvocationContext);

    // Log the snippet name and the fetched snippet content from the blob
    context.getLogger().info("Retrieving snippet with name: " + snippetName);
    context.getLogger().info("Snippet content:");
    context.getLogger().info(inputBlob);

    // Return the snippet content or a not found message
    if (inputBlob != null && !inputBlob.trim().isEmpty()) {
        return inputBlob;
    } else {
        return "Snippet '" + snippetName + "' not found.";
    }
}

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

JavaScript için örnek kod şu anda kullanılamıyor. Node.jskullanarak genel yönergeler için TypeScript örneklerine bakın.

Bu kod, adlandırılmış kod parçacığını blob depolamada kalıcı hale getirmeye çalışan adlı savesnippet bir aracı kullanıma sunan bir uç nokta oluşturur.

import { app, InvocationContext, input, output, arg } from "@azure/functions";

app.mcpTool("saveSnippet", {
  toolName: SAVE_SNIPPET_TOOL_NAME,
  description: SAVE_SNIPPET_TOOL_DESCRIPTION,
  toolProperties: {
    [SNIPPET_NAME_PROPERTY_NAME]: arg.string().describe(SNIPPET_NAME_PROPERTY_DESCRIPTION),
    [SNIPPET_PROPERTY_NAME]: arg.string().describe(SNIPPET_PROPERTY_DESCRIPTION)
  },
  extraOutputs: [blobOutputBinding],
  handler: saveSnippet,
});

Bu kod tetikleyiciyi savesnippet işler:

export async function saveSnippet(
  _toolArguments: unknown,
  context: InvocationContext
): Promise<string> {
  console.info("Saving snippet");

  // Get snippet name and content from the tool arguments
  const mcptoolargs = context.triggerMetadata.mcptoolargs as {
    snippetname?: string;
    snippet?: string;
  };

  const snippetName = mcptoolargs?.snippetname;
  const snippet = mcptoolargs?.snippet;

  if (!snippetName) {
    return "No snippet name provided";
  }

  if (!snippet) {
    return "No snippet content provided";
  }

  // Save the snippet to blob storage using the output binding
  context.extraOutputs.set(blobOutputBinding, snippet);

  console.info(`Saved snippet: ${snippetName}`);
  return snippet;
}

Bu kod, blob depolamadan ada göre kod parçacığı almaya çalışan adlı getsnippet bir aracı kullanıma sunan bir uç nokta oluşturur.

import { app, InvocationContext, input, output, arg } from "@azure/functions";

app.mcpTool("getSnippet", {
  toolName: GET_SNIPPET_TOOL_NAME,
  description: GET_SNIPPET_TOOL_DESCRIPTION,
  toolProperties: {
    [SNIPPET_NAME_PROPERTY_NAME]: arg.string().describe(SNIPPET_NAME_PROPERTY_DESCRIPTION)
  },
  extraInputs: [blobInputBinding],
  handler: getSnippet,
});

Bu kod tetikleyiciyi getsnippet işler:

export async function getSnippet(
  _toolArguments: unknown,
  context: InvocationContext
): Promise<string> {
  console.info("Getting snippet");

  // Get snippet name from the tool arguments
  const mcptoolargs = context.triggerMetadata.mcptoolargs as {
    snippetname?: string;
  };
  const snippetName = mcptoolargs?.snippetname;

  console.info(`Snippet name: ${snippetName}`);

  if (!snippetName) {
    return "No snippet name provided";
  }

  // Get the content from blob binding - properly retrieving from extraInputs
  const snippetContent = context.extraInputs.get(blobInputBinding);

  if (!snippetContent) {
    return `Snippet '${snippetName}' not found`;
  }

  console.info(`Retrieved snippet: ${snippetName}`);
  return snippetContent as string;
}

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

Bu kod, blob depolamada mcp_tool_trigger adlandırılmış kod parçacığını kalıcı hale getirmeye çalışan adlı save_snippet bir aracı kullanıma sunan bir uç nokta oluşturmak için dekoratör kullanır.

@app.mcp_tool_trigger(
    arg_name="context",
    tool_name="save_snippet",
    description="Save a snippet with a name.",
    tool_properties=tool_properties_save_snippets_json,
)
@app.blob_output(arg_name="file", connection="AzureWebJobsStorage", path=_BLOB_PATH)
def save_snippet(file: func.Out[str], context) -> str:
    content = json.loads(context)
    snippet_name_from_args = content["arguments"][_SNIPPET_NAME_PROPERTY_NAME]
    snippet_content_from_args = content["arguments"][_SNIPPET_PROPERTY_NAME]

    if not snippet_name_from_args:
        return "No snippet name provided"

    if not snippet_content_from_args:
        return "No snippet content provided"

    file.set(snippet_content_from_args)
    logging.info(f"Saved snippet: {snippet_content_from_args}")
    return f"Snippet '{snippet_content_from_args}' saved successfully"

Bu kod, blob depolamadan mcp_tool_trigger ada göre kod parçacığı almaya çalışan adlı get_snippet bir aracı kullanıma sunan bir uç nokta oluşturmak için dekoratör kullanır.

@app.mcp_tool_trigger(
    arg_name="context",
    tool_name="get_snippet",
    description="Retrieve a snippet by name.",
    tool_properties=tool_properties_get_snippets_json,
)
@app.blob_input(arg_name="file", connection="AzureWebJobsStorage", path=_BLOB_PATH)
def get_snippet(file: func.InputStream, context) -> str:
    """
    Retrieves a snippet by name from Azure Blob Storage.

    Args:
        file (func.InputStream): The input binding to read the snippet from Azure Blob Storage.
        context: The trigger context containing the input arguments.

    Returns:
        str: The content of the snippet or an error message.
    """
    snippet_content = file.read().decode("utf-8")
    logging.info(f"Retrieved snippet: {snippet_content}")
    return snippet_content

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

Önemli

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

Özellikler

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

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

Parametre	Açıklama
ToolName	(Gerekli) MCP tetikleyici uç noktası tarafından kullanıma sunulan aracın adı.
Açıklama	(İsteğe bağlı) istemciler için araç uç noktasının kolay açıklaması.

Uç noktanın özelliklerini giriş parametreleri olarak tanımlamayı öğrenmek için bkz. Kullanım .

Açıklamalar

Ek açıklama, @McpToolTrigger uzak MCP sunucunuzda bir araç uç noktasını kullanıma sunan bir işlev oluşturur.

Ek açıklama aşağıdaki yapılandırma seçeneklerini destekler:

Parametre	Açıklama
name	(Gerekli) MCP tetikleyici uç noktası tarafından kullanıma sunulan aracın adı.
Açıklama	(İsteğe bağlı) istemciler için araç uç noktasının kolay açıklaması.

Ek @McpToolProperty açıklama, araçlarınız için tek tek özellikleri tanımlar. İşlevinizdeki her özellik parametresine bu ek açıklama ek açıklama eklenmelidir.

Ek @McpToolProperty açıklama aşağıdaki yapılandırma seçeneklerini destekler:

Parametre	Açıklama
name	(Gerekli) istemcilere sunulan araç özelliğinin adı.
propertyType	Araç özelliğinin (Gerekli) türü. Geçerli türler şunlardır: string, number, integer, boolean, object.
Açıklama	(İsteğe bağlı) araç özelliğinin ne yaptığıyla ilgili açıklama.
Gerekli	(İsteğe bağlı) olarak ayarlanırsa truearaç özelliği, araç çağrıları için bağımsız değişken olarak gereklidir. Varsayılan olarak false değerini alır.

Dekoratörler

Yalnızca Python v2 programlama modeli için geçerlidir.

Dekoratörmcp_tool_trigger, paketin 1.24.0 veya sonraki bir sürümünü azure-functionsgerektirir. Aşağıdaki MCP tetikleyici özellikleri üzerinde mcp_tool_triggerdesteklenir:

Mülkiyet	Açıklama
arg_name	Yürütme bağlamını erişmek için işlev kodunda kullanılan değişken adı (genellikle context).
tool_name	(Gerekli) İşlev uç noktası tarafından kullanıma sunulan MCP sunucu aracının adı.
Açıklama	İşlev uç noktası tarafından kullanıma sunulan MCP sunucu aracının açıklaması.
tool_properties	Aracın özelliklerini istemcilere sunan bir veya daha fazla özellik nesnesinin JSON dize gösterimi.

Konfigürasyon

Tetikleyici, kodunuzda tanımlanan şu bağlama seçeneklerini destekler:

Seçenekler	Açıklama
türü	mcpToolTriggerolarak ayarlanmalıdır. Yalnızca genel tanımlarla kullanılır.
toolName	(Gerekli) İşlev uç noktası tarafından kullanıma sunulan MCP sunucu aracının adı.
Açıklama	İşlev uç noktası tarafından kullanıma sunulan MCP sunucu aracının açıklaması.
toolProperties	Aracın özelliklerini istemcilere sunan bir nesne dizisi toolProperty .
extraOutputs	Tanımlandığında, işlev çıkışını başka bir bağlamaya gönderir.
kontrolcü	Gerçek işlev kodunu içeren yöntem.

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

Kullanım

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

Türü	Açıklama
ToolInvocationContext	Aramanın araç adı ve bağımsız değişkenleri de dahil olmak üzere araç çağrısını temsil eden bir nesne.
JSON serileştirilebilir türler	İşlevler, araç bağımsız değişkenlerini düz eski bir CLR nesnesi (POCO) türüne seri durumdan çıkarma girişiminde bulunur. Bu tür, araç özelliklerini tanımlamak için de kullanılır. JSON serileştirilebilir bir türe bağlarken, isteğe bağlı olarak araç çağrı bilgilerine erişmek için ToolInvocationContext türünde bir parametre de ekleyebilirsiniz.

Araç özellikleri

MCP istemcileri, aracın işlemi için veri ve bağlam sağlamak üzere bağımsız değişkenler içeren araçları çağırır. İstemciler, aracın protokolün bir parçası olarak tanıtdığı özelliklere göre bu bağımsız değişkenleri toplamayı ve geçirmeyi bilir. Bu nedenle, işlev kodunuzda aracın özelliklerini tanımlamanız gerekir.

Bir araç özelliği tanımladığınızda, varsayılan olarak isteğe bağlıdır ve istemci aracı çağırırken bunu atlayabilir. Araç bunlar olmadan çalışamıyorsa özellikleri açıkça gerekli olarak işaretlemeniz gerekir.

Uyarı

MCP uzantısı önizlemesinin önceki sürümleri, varsayılan olarak tüm araç özelliklerini gerekli kildi. Bu davranış, sürümünden 1.0.0-preview.7itibaren değişti ve artık özellikleri açıkça gerektiği gibi işaretlemeniz gerekir.

C# dilinde, araçlarınız için özellikleri çeşitli yollarla tanımlayabilirsiniz. Hangi yaklaşımı kullandığınız, kod stili tercihi ile ilgili bir konudur. Seçenekler şunlardır:

• İşleviniz, özniteliğini McpToolProperty kullanarak giriş parametrelerini alır.
• Özellikleriyle özel bir tür tanımlarsınız ve işlev bu türe bağlanır.
• dosyanızda özellikleri tanımlamak için öğesini FunctionsApplicationBuilder kullanırsınız Program.cs .

McpToolProperty Öznitelik

özniteliğini işlevinizdeki bağlama stilindeki giriş parametrelerine uygulayarak McpToolProperty bir veya daha fazla araç özelliği tanımlayabilirsiniz.

Türü McpToolPropertyAttribute şu özellikleri destekler:

Mülkiyet	Açıklama
Özellik Adı	İstemcilere sunulan araç özelliğinin adı.
Açıklama	Araç özelliğinin ne yaptığının açıklaması.
IsRequired	(İsteğe bağlı) olarak ayarlanırsa truearaç özelliği, araç çağrıları için bağımsız değişken olarak gereklidir. Varsayılan olarak false değerini alır.

Özellik türü, özniteliğini uyguladığınız parametrenin türünden çıkarılır. Örneğin[McpToolProperty("snippetname", "The name of the snippet.", true)] string name, MCP iletilerinde türünde snippetname adlı string gerekli bir araç özelliğini tanımlar.

Araçta SaveSnippet kullanılan bu öznitelikleri Örnekler'de görebilirsiniz.

Özel türe bağlama

Tanımladığınız düz eski bir CLR nesnesi (POCO) türüne bağlayarak bir veya daha fazla araç özelliği tanımlayabilirsiniz. Bu türün özellikleri otomatik olarak araç özellikleri olarak sunulur. Her özellik için bir açıklama sağlamak için [Description] özniteliğini kullanabilirsiniz. Anahtar sözcüğünü kullanarak bir özelliğin required gerekli olduğunu belirtebilirsiniz. MCP iletilerinde kullanılan bilgi türündeki sınıf özelliği türü.

Bu örnekte, aracın araç özelliklerini tanımlamak için SaveSnippet özel bir tür kullanılır:

public class SaveSnippetRequest
{
    [Description("The name of the snippet.")]
    public required string SnippetName { get; set; }

    [Description("The code snippet.")]
    public required string Snippet { get; set; }            
}

private const string BlobPath = "snippets/{mcptoolargs.snippetname}.json";

[Function(nameof(SaveSnippet))]
[BlobOutput(BlobPath)]
public string SaveSnippet(
    [McpToolTrigger("save_snippet", "Saves a code snippet into your snippet collection.")] SaveSnippetRequest request,
        ToolInvocationContext context
)
{
    return request.Snippet;
}

FunctionsApplicationBuilder

giriş noktası (Program.cs) dosyanızda, üzerinde McpToolBuilderyöntemi tarafından ConfigureMcpTool() döndürülen bir kullanarak bir FunctionsApplicationBuilder veya daha fazla araç özelliği tanımlayabilirsiniz. Bu örnekte aracının WithProperty özelliklerini ayarlamak için GetSnippet oluşturucuda yöntemi çağrılır:

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder
    .ConfigureMcpTool("get_snippets")
    .WithProperty("snippetname", "string", "The name of the snippet.", required: true);

// other configuration

builder.Build().Run();

Aracın birden çok özelliğini tanımlamak için yöntemini birden çok kez çağırabilirsiniz WithProperty() . için yapılan her çağrı WithProperty() , DOĞRUDAN bir CLR türüne karşılık gelen MCP özellik türünün dize gösterimini içerir. Örneğin, ilgili CLR türü olsa "boolean"bile boole özelliğini tanımlamak için kullanınbool. Geçerli türler şunlardır: "string", "number", "integer", "boolean", "object".

Tam örnek için dosyayaProgram.cs bakın.

Java'da, bağımsız işlev parametrelerinde ek açıklamayı @McpToolProperty kullanarak araç özelliklerini tanımlarsınız. Bir araç özelliğini temsil eden her parametreye, özellik adı, türü, açıklaması ve gerekli olup olmadığı belirterek bu ek açıklamayla ek açıklama eklenmelidir.

Örneklerde kullanılan bu ek açıklamaları görebilirsiniz.

Bir nesne dizisinin toolProperties dize gösterimi olan tetikleyici tanımının ToolProperty alanında araç özelliklerini yapılandırabilirsiniz.

Bir ToolProperty nesne şu yapıya sahiptir:

{
    "propertyName": "Name of the property",
    "propertyType": "Type of the property",
    "description": "Optional property description",
    "isRequired": true|false,
    "isArray": true|false
}

Nesnenin ToolProperty alanları şunlardır:

Mülkiyet	Açıklama
propertyName	İstemcilere sunulan araç özelliğinin adı.
propertyType	Araç özelliğinin türü. Geçerli türler şunlardır: string, number, integer, boolean, object. Dizi türleri için bkz isArray .
Açıklama	Araç özelliğinin ne yaptığının açıklaması.
isRequired	(İsteğe bağlı) olarak ayarlanırsa truearaç özelliği, araç çağrıları için bağımsız değişken olarak gereklidir. Varsayılan olarak false değerini alır.
isArray	(İsteğe bağlı) olarak ayarlanırsa true, araç özelliği belirtilen özellik türünde bir dizidir. Varsayılan olarak false değerini alır.

Alanı toolProperties nesneler dizisi ToolProperty olarak sağlayabilir veya arg yardımcı maddeleri @azure/functions kullanarak özellikleri daha tür açısından güvenli bir şekilde tanımlayabilirsiniz:

  toolProperties: {
    [SNIPPET_NAME_PROPERTY_NAME]: arg.string().describe(SNIPPET_NAME_PROPERTY_DESCRIPTION)
  }

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.

İlgili makaleler

Azure İşlevleri için Azure OpenAI uzantısı