Wyzwalacz narzędzia MCP dla usługi Azure Functions

Użyj wyzwalacza narzędzia MCP, aby zdefiniować punkty końcowe narzędzi na serwerze MCP (Model Content Protocol). Modele języka klienta i agenci mogą używać narzędzi do wykonywania określonych zadań, takich jak przechowywanie lub uzyskiwanie dostępu do fragmentów kodu.

Aby uzyskać informacje na temat konfiguracji i konfiguracji, zobacz omówienie.

Przykład

Uwaga / Notatka

W przypadku języka C# rozszerzenie MCP usługi Azure Functions obsługuje tylko izolowany model procesu roboczego.

Ten kod tworzy punkt końcowy w celu uwidocznienia narzędzia o nazwie SaveSnippet , które próbuje utrwalić nazwany fragment kodu w magazynie obiektów blob.

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

Ten kod tworzy punkt końcowy, aby uwidocznić narzędzie o nazwie GetSnippet , które próbuje pobrać fragment kodu według nazwy z magazynu obiektów blob.

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

Właściwości narzędzia dla GetSnippet funkcji są konfigurowane w pliku Program.cs:

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

Wskazówka

W powyższym przykładzie użyto ciągów literałów dla takich elementów, jak nazwa narzędzia "get_snippets" zarówno w funkcji Program.cs , jak i w funkcji. Rozważ użycie udostępnionych ciągów stałych, aby zachować synchronizację elementów w projekcie.

Aby zapoznać się z kompletnym przykładem kodu, zobacz SnippetTool.cs.

Ten kod tworzy punkt końcowy w celu uwidocznienia narzędzia o nazwie SaveSnippets , które próbuje utrwalić nazwany fragment kodu w magazynie obiektów blob.

@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.";
}

Ten kod tworzy punkt końcowy, aby uwidocznić narzędzie o nazwie GetSnippets , które próbuje pobrać fragment kodu według nazwy z magazynu obiektów blob.

@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.";
    }
}

Aby zapoznać się z kompletnym przykładem kodu, zobacz Snippets.java.

Przykładowy kod dla języka JavaScript nie jest obecnie dostępny. Zapoznaj się z przykładami języka TypeScript, aby uzyskać ogólne wskazówki dotyczące korzystania z Node.js.

Ten kod tworzy punkt końcowy w celu uwidocznienia narzędzia o nazwie savesnippet , które próbuje utrwalić nazwany fragment kodu w magazynie obiektów blob.

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

Ten kod obsługuje savesnippet wyzwalacz:

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

Ten kod tworzy punkt końcowy, aby uwidocznić narzędzie o nazwie getsnippet , które próbuje pobrać fragment kodu według nazwy z magazynu obiektów blob.

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

Ten kod obsługuje getsnippet wyzwalacz:

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

Aby zapoznać się z kompletnym przykładem kodu, zobacz snippetsMcpTool.ts.

Ten kod używa dekoratora mcp_tool_trigger do utworzenia punktu końcowego w celu uwidocznienia narzędzia o nazwie save_snippet , które próbuje utrwalić nazwany fragment kodu w magazynie obiektów blob.

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

Ten kod używa dekoratora mcp_tool_trigger do utworzenia punktu końcowego w celu uwidocznienia narzędzia o nazwie get_snippet , które próbuje pobrać fragment kodu według nazwy z magazynu obiektów blob.

@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

Aby zapoznać się z kompletnym przykładem kodu, zobacz function_app.py.

Ważne

Rozszerzenie MCP nie obsługuje obecnie aplikacji programu PowerShell.

Atrybuty

Biblioteki języka C# służą McpToolTriggerAttribute do definiowania wyzwalacza funkcji.

Konstruktor atrybutu przyjmuje następujące parametry:

Parametr	Opis
ToolName	(Wymagana) nazwa narzędzia, które jest udostępniane przez punkt końcowy wyzwalacza MCP.
Opis	(Opcjonalnie) przyjazny opis punktu końcowego narzędzia dla klientów.

Zobacz Użycie , aby dowiedzieć się, jak definiować właściwości punktu końcowego jako parametry wejściowe.

Adnotacje

Adnotacja @McpToolTrigger tworzy funkcję, która uwidacznia punkt końcowy narzędzia na zdalnym serwerze MCP.

Adnotacja obsługuje następujące opcje konfiguracji:

Parametr	Opis
name	(Wymagana) nazwa narzędzia, które jest udostępniane przez punkt końcowy wyzwalacza MCP.
opis	(Opcjonalnie) przyjazny opis punktu końcowego narzędzia dla klientów.

Adnotacja @McpToolProperty definiuje poszczególne właściwości narzędzi. Każdy parametr właściwości w funkcji powinien być adnotacją z tą adnotacją.

Adnotacja @McpToolProperty obsługuje następujące opcje konfiguracji:

Parametr	Opis
name	(Wymagana) nazwa właściwości narzędzia, która jest widoczna dla klientów.
propertyType	(Wymagany) typ właściwości narzędzia. Prawidłowe typy to: string, , numberinteger, boolean, object.
opis	(Opcjonalnie) opis działania właściwości narzędzia.
Wymagane	(Opcjonalnie) jeśli ustawiono truewartość , właściwość narzędzia jest wymagana jako argument wywołań narzędzi. Wartość domyślna to false.

Dekoratorów

Dotyczy tylko modelu programowania w wersji 2 języka Python.

Dekorator mcp_tool_trigger wymaga wersji 1.24.0 lub nowszej azure-functions pakietu. Następujące właściwości wyzwalacza MCP są obsługiwane w systemie mcp_tool_trigger:

Majątek	Opis
arg_name	Nazwa zmiennej (zwykle context) używana w kodzie funkcji w celu uzyskania dostępu do kontekstu wykonywania.
tool_name	(Wymagane) Nazwa narzędzia serwera MCP uwidocznionego przez punkt końcowy funkcji.
opis	Opis narzędzia serwera MCP uwidocznionego przez punkt końcowy funkcji.
tool_properties	Ciąg JSON reprezentujący co najmniej jeden obiekt właściwości, który uwidacznia właściwości narzędzia klientom.

Konfiguracja

Wyzwalacz obsługuje te opcje powiązań, które są zdefiniowane w kodzie:

Opcje	Opis
typ	Musi być ustawione na mcpToolTrigger. Używane tylko z definicjami ogólnymi.
toolName	(Wymagane) Nazwa narzędzia serwera MCP uwidocznionego przez punkt końcowy funkcji.
opis	Opis narzędzia serwera MCP uwidocznionego przez punkt końcowy funkcji.
toolProperties	Tablica toolProperty obiektów, które uwidaczniają właściwości narzędzia klientom.
extraOutputs	Po zdefiniowaniu funkcja wysyła dane wyjściowe funkcji do innego powiązania.
obsługi	Metoda zawierająca rzeczywisty kod funkcji.

Zobacz sekcję Przykład, aby zapoznać się z kompletnymi przykładami.

Zastosowanie

Wyzwalacz narzędzia MCP może wiązać się z następującymi typami:

Typ	Opis
ToolInvocationContext	Obiekt reprezentujący wywołanie narzędzia, w tym nazwę narzędzia i argumenty wywołania.
Typy serializowalne w formacie JSON	Funkcje próbują deserializować argumenty narzędzi w zwykły typ obiektu CLR (POCO). Ten typ służy również do definiowania właściwości narzędzi. W przypadku powiązania z typem serializowalnym JSON można również dołączyć parametr typu ToolInvocationContext , aby uzyskać dostęp do informacji o wywołaniu narzędzia.

Właściwości narzędzia

Klienci MCP wywołują narzędzia z argumentami, aby zapewnić dane i kontekst operacji narzędzia. Klienci wiedzą, jak zbierać i przekazywać te argumenty na podstawie właściwości anonsowanych przez narzędzie w ramach protokołu. Dlatego należy zdefiniować właściwości narzędzia w kodzie funkcji.

Podczas definiowania właściwości narzędzia jest ona domyślnie opcjonalna, a klient może pominąć ją podczas wywoływania narzędzia. Należy jawnie oznaczyć właściwości jako wymagane, jeśli narzędzie nie może działać bez nich.

Uwaga / Notatka

Wcześniejsze wersje podglądu rozszerzenia MCP domyślnie wymagały wszystkich właściwości narzędzia. To zachowanie zmieniło się w wersji 1.0.0-preview.7, a teraz należy jawnie oznaczyć właściwości zgodnie z potrzebami.

W języku C#można zdefiniować właściwości narzędzi na kilka sposobów. Którego podejścia używasz, jest kwestią preferencji stylu kodu. Dostępne opcje:

• Funkcja przyjmuje parametry wejściowe przy użyciu atrybutu McpToolProperty .
• Typ niestandardowy definiuje się z właściwościami, a funkcja wiąże się z tym typem.
• Element służy FunctionsApplicationBuilder do definiowania właściwości w Program.cs pliku.

McpToolProperty atrybut

Można zdefiniować co najmniej jedną właściwość narzędzia, stosując McpToolProperty atrybut do parametrów stylu powiązania wejściowego w funkcji.

Typ McpToolPropertyAttribute obsługuje następujące właściwości:

Majątek	Opis
Nazwa_właściwości	Nazwa właściwości narzędzia, która jest widoczna dla klientów.
Opis	Opis właściwości narzędzia.
IsRequired (Wymagane)	(Opcjonalnie) Jeśli ustawiono truewartość , właściwość narzędzia jest wymagana jako argument wywołań narzędzi. Wartość domyślna to false.

Typ właściwości jest wnioskowany z typu parametru, do którego jest stosowany atrybut. Na przykład [McpToolProperty("snippetname", "The name of the snippet.", true)] string name definiuje wymaganą właściwość narzędzia o nazwie snippetname typu string w komunikatach MCP.

Te atrybuty są używane w narzędziu SaveSnippet w sekcji Przykłady.

Wiązanie z typem niestandardowym

Można zdefiniować co najmniej jedną właściwości narzędzia przez powiązanie ze zdefiniowanym typem zwykłego obiektu CLR (POCO). Właściwości tego typu są automatycznie widoczne jako właściwości narzędzia. Możesz użyć atrybutu [Description], aby podać opis każdej właściwości. Możesz wskazać, że właściwość jest wymagana przy użyciu słowa kluczowego required . Typ właściwości klasy w typie informacji używanym w komunikatach MCP.

W tym przykładzie użyto typu niestandardowego do zdefiniowania właściwości narzędzia dla SaveSnippet narzędzia:

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

Można zdefiniować co najmniej jedną właściwości narzędzia w pliku punktu wejścia (Program.cs) przy użyciu metody zwróconej McpToolBuilder przez metodę ConfigureMcpTool() w FunctionsApplicationBuilderpliku . W tym przykładzie wywoływana WithProperty jest metoda w konstruktorze GetSnippet narzędzia w celu ustawienia właściwości narzędzia:

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

Metodę WithProperty() można wywołać wiele razy, aby zdefiniować wiele właściwości narzędzia. Każde wywołanie elementu zawiera WithProperty() reprezentację ciągu typu właściwości MCP, który może nie odpowiadać bezpośrednio typowi CLR. Na przykład użyj polecenia "boolean" , aby zdefiniować właściwość logiczną, mimo że odpowiedni typ CLR to bool. Prawidłowe typy to: "string", , "number""integer", "boolean", "object".

Pełny przykład można znaleźć w Program.cs pliku .

W języku Java można zdefiniować właściwości narzędzia przy użyciu @McpToolProperty adnotacji dla poszczególnych parametrów funkcji. Każdy parametr reprezentujący właściwość narzędzia powinien być adnotacją z tą adnotacją, określając nazwę właściwości, typ, opis i to, czy jest to wymagane.

Te adnotacje można zobaczyć w przykładach.

Właściwości narzędzia można skonfigurować w polu definicji toolProperties wyzwalacza, który jest ciągiem reprezentującym tablicę ToolProperty obiektów.

Obiekt ma następującą ToolProperty strukturę:

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

Pola ToolProperty obiektu to:

Majątek	Opis
propertyName	Nazwa właściwości narzędzia, która jest widoczna dla klientów.
propertyType	Typ właściwości narzędzia. Prawidłowe typy to: string, , numberinteger, boolean, object. Zobacz, aby zapoznać się isArray z typami tablic.
opis	Opis właściwości narzędzia.
isRequired	(Opcjonalnie) Jeśli ustawiono truewartość , właściwość narzędzia jest wymagana jako argument wywołań narzędzi. Wartość domyślna to false.
isArray	(Opcjonalnie) Jeśli ustawiono truewartość , właściwość tool jest tablicą określonego typu właściwości. Wartość domyślna to false.

Możesz podać toolProperties pole jako tablicę obiektów ToolProperty lub użyć arg pomocników z do @azure/functions definiowania właściwości w sposób bardziej bezpieczny pod względem typu:

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

Aby uzyskać więcej informacji, zobacz Przykłady.

ustawienia pliku host.json

Plik host.json zawiera ustawienia kontrolujące zachowania wyzwalacza MCP. Aby uzyskać szczegółowe informacje dotyczące dostępnych ustawień, zobacz sekcję host.json settings (Ustawienia host.json).

Powiązane artykuły

Rozszerzenie Azure OpenAI dla usługi Azure Functions