Azure İşlevleri için MCP aracı tetikleyicisi

Model Bağlam 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 bu araçları kullanabilir.

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

MCP araç tetikleyicisini kullanmanın uçtan uca eksiksiz bir örneği için bkz. Azure İşlevleri kullanarak uzak MCP sunucusu oluşturma.

Example

Uyarı

C# için Azure İşlevleri MCP uzantısı yalnızca isolated worker model 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ılmaktadı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.",
                isRequired = true
        )
        String snippetName,
        @McpToolProperty(
                name = "snippet",
                propertyType = "string",
                description = "The content of the snippet.",
                isRequired = 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.",
                isRequired = 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	Description
ToolName	(Gerekli) MCP tetikleyici uç noktasının ortaya koyduğu 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çıklamayı @McpToolTrigger kullanarak uzak MCP sunucunuzda bir araç uç noktasını kullanıma sunan bir işlev oluşturun.

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

Parametre	Description
name	(Gerekli) MCP tetikleyici uç noktasının ortaya koyduğu aracın adı.
Açıklama	(İsteğe bağlı) istemciler için araç uç noktasının kolay açıklaması.

Araçlarınız için tek tek özellikleri tanımlamak için ek açıklamayı @McpToolProperty kullanın. Bu ek açıklamayla işlevinizdeki her özellik parametresine ek açıklama ekleyin.

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

Parametre	Description
name	(Gerekli) istemcilerin gördüğü 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.
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ünün bir dizisidir. Varsayılan olarak false değerini alır.

Dekoratörler

Uygulamalar yalnızca Python v2 programlama modeli.

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	Description
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ının kullanıma koyduğu 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

Tetikleyicinin bağlama seçeneklerini kodunuzda tanımlayın. Aşağıdaki tabloda her seçenek açıklanmaktadır:

Seçenek	Description
type	mcpToolTrigger olarak ayarlayın. Yalnızca genel tanımlarla kullanın.
toolName	(Gerekli) İşlev uç noktasının kullanıma açık olduğu MCP sunucu aracının adı.
Açıklama	İşlev uç noktasının kullanıma koyduğu 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.

Usage

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

Türü	Description
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, araç çağrı bilgilerine erişmek için isteğe bağlı olarak 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, bunu varsayılan olarak isteğe bağlı hale getirin. İstemci, aracı çağırırken bunu atlayabilir. Araç bunlar olmadan çalışamıyorsa özellikleri açıkça gerekli olarak işaretleyin.

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. Şimdi, ö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 parametreleri girerek McpToolProperty bir veya daha fazla araç özelliği tanımlayın.

Türü McpToolPropertyAttribute şu özellikleri destekler:

Mülkiyet	Description
PropertyName	İ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ımlayın. Bu türün özellikleri otomatik olarak araç özellikleri olarak kullanıma sunar. Her özellik için bir açıklama sağlamak için [Description] özniteliğini kullanın. anahtar sözcüğünü kullanarak bir özelliğin required gerekli olduğunu belirtin. Sınıf özellik türü, MCP iletilerinde kullanılan türü bildirir.

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

üzerinde yöntemi Program.cstarafından McpToolBuilder döndürülen kullanarak giriş noktası (ConfigureMcpTool()) dosyanızda bir FunctionsApplicationBuilder veya daha fazla araç özelliği tanımlayın. 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".

Java'da, tek tek işlev parametrelerinde @McpToolProperty ek açıklamasını kullanarak araç özelliklerini tanımlayın. Bu ek açıklamayla bir araç özelliğini temsil eden her parametreye açıklama ekleyin. Özellik adını, türünü, açıklamasını ve gerekli olup olmadığını belirtin.

Ö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	Description
Propertyname	İstemcilere açıkladığınız 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 ayarlar hakkında ayrıntılı bilgi için host.json ayarları bölümüne bakın.

İlgili makaleler

Azure İşlevleriAzure OpenAI uzantısı>