Триггер средства MCP для функций Azure

Используйте триггер средства MCP для определения конечных точек инструментов на сервере протокола содержимого модели (MCP ). Клиентские языковые модели и агенты могут использовать средства для выполнения определенных задач, таких как хранение или доступ к фрагментам кода.

Сведения об установке и настройке см. в обзорной статье.

Пример

Замечание

Для C#расширение MCP функций Azure поддерживает только изолированную рабочую модель.

Этот код создает конечную точку для предоставления средства с именем SaveSnippet , который пытается сохранить именованный фрагмент кода в хранилище 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;
}

Этот код создает конечную точку для предоставления средства с именем GetSnippet , который пытается получить фрагмент кода по имени из хранилища 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;
}

Свойства средства для GetSnippet функции настраиваются в 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();

Подсказка

В приведенном выше примере используются литеральные строки для таких вещей, как имя инструмента "get_snippets" в обоих Program.cs и функциях. Вместо этого следует использовать общие строки констант для синхронизации в проекте.

Полный пример кода см. в SnippetTool.cs.

Этот код создает конечную точку для предоставления средства с именем SaveSnippets , который пытается сохранить именованный фрагмент кода в хранилище 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.";
}

Этот код создает конечную точку для предоставления средства с именем GetSnippets , который пытается получить фрагмент кода по имени из хранилища 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.";
    }
}

Полный пример кода см. в Snippets.java.

Пример кода javaScript в настоящее время недоступен. Примеры TypeScript см. в общих руководствах с помощью Node.js.

Этот код создает конечную точку для предоставления средства с именем savesnippet , который пытается сохранить именованный фрагмент кода в хранилище 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,
});

Этот код обрабатывает savesnippet триггер:

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

Этот код создает конечную точку для предоставления средства с именем getsnippet , который пытается получить фрагмент кода по имени из хранилища 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,
});

Этот код обрабатывает getsnippet триггер:

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

Полный пример кода см. в snippetsMcpTool.ts.

Этот код использует mcp_tool_trigger декоратор для создания конечной точки для предоставления средства с именем save_snippet , который пытается сохранить именованный фрагмент кода в хранилище 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"

Этот код использует mcp_tool_trigger декоратор для создания конечной точки для предоставления средства с именем get_snippet , который пытается получить фрагмент кода по имени из хранилища 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

Полный пример кода см. в function_app.py.

Это важно

Расширение MCP в настоящее время не поддерживает приложения PowerShell.

Атрибуты

Библиотеки C# используются McpToolTriggerAttribute для определения триггера функции.

Конструктор атрибута принимает следующие параметры:

Параметр	Описание
ToolName	(Обязательно) имя средства, которое предоставляется конечной точкой триггера MCP.
Описание	(Необязательно) понятное описание конечной точки средства для клиентов.

Узнайте, как определить свойства конечной точки в качестве входных параметров.

Аннотации

Заметка @McpToolTrigger создает функцию, которая предоставляет конечную точку средства на удаленном сервере MCP.

Эта заметка поддерживает следующие параметры конфигурации:

Параметр	Описание
name	(Обязательно) имя средства, которое предоставляется конечной точкой триггера MCP.
описание	(Необязательно) понятное описание конечной точки средства для клиентов.

Заметка @McpToolProperty определяет отдельные свойства для инструментов. Каждый параметр свойства в функции должен быть аннотирован с помощью этой заметки.

Заметка @McpToolProperty поддерживает следующие параметры конфигурации:

Параметр	Описание
name	(Обязательно) имя свойства средства, которое предоставляется клиентам.
propertyType	(Обязательный) тип свойства средства. Допустимые типы: string, number, integer, booleanobject.
описание	(Необязательно) описание того, что делает свойство средства.
обязательный параметр	(Необязательно) если задано значение true, свойство средства требуется в качестве аргумента для вызовов инструментов. По умолчанию — false.

Декораторы

Применяется только к модели программирования Python версии 2.

Для mcp_tool_trigger декоратора требуется версия 1.24.0 или более поздняя azure-functions версия пакета. В следующих свойствах триггера MCP поддерживаются mcp_tool_triggerследующие свойства триггера MCP:

Недвижимость	Описание
arg_name	Имя переменной (обычно), contextиспользуемое в коде функции для доступа к контексту выполнения.
tool_name	(обязательно) Имя средства сервера MCP, предоставляемого конечной точкой функции.
описание	Описание средства сервера MCP, предоставляемого конечной точкой функции.
tool_properties	Строковое представление json одного или нескольких объектов свойств, предоставляющих свойства средства клиентам.

Конфигурация

Триггер поддерживает эти параметры привязки, определенные в коде:

Опции	Описание
тип	Необходимо задать значение mcpToolTrigger. Используется только с универсальными определениями.
toolName	(обязательно) Имя средства сервера MCP, предоставляемого конечной точкой функции.
описание	Описание средства сервера MCP, предоставляемого конечной точкой функции.
toolProperties	Массив toolProperty объектов, предоставляющих свойства средства клиентам.
extraOutputs	При определении отправляет выходные данные функции в другую привязку.
обработчик	Метод, содержащий фактический код функции.

Подробные примеры см. в разделе Примеры.

Использование

Триггер средства MCP может привязаться к следующим типам:

Тип	Описание
ToolInvocationContext	Объект, представляющий вызов средства, включая имя и аргументы средства для вызова.
Сериализуемые в JSON типы	Функции пытаются десериализировать аргументы инструмента в обычный тип объекта CLR (POCO). Этот тип также используется для определения свойств инструмента. При привязке к сериализуемому типу JSON можно также включить параметр типа ToolInvocationContext для доступа к сведениям о вызове средства.

Свойства инструмента

Клиенты MCP вызывают средства с аргументами для предоставления данных и контекста для операции средства. Клиенты знают, как собирать и передавать эти аргументы на основе свойств, которые средство объявляет в рамках протокола. Поэтому необходимо определить свойства средства в коде функции.

При определении свойства средства это необязательно по умолчанию, и клиент может опустить его при вызове средства. Если средство не может работать без них, необходимо явно пометить свойства.

Замечание

Более ранние версии предварительного просмотра расширения MCP сделали все свойства инструментов, необходимые по умолчанию. Это поведение изменилось по состоянию на версию 1.0.0-preview.7, и теперь необходимо явно пометить свойства по мере необходимости.

В C#можно определить свойства для инструментов несколькими способами. Какой подход используется, является вопросом предпочтения стиля кода. Варианты следующие:

• Функция принимает входные параметры с помощью атрибута McpToolProperty .
• Вы определяете пользовательский тип со свойствами, а функция привязывается к такому типу.
• Вы используете FunctionsApplicationBuilder для определения свойств в Program.cs файле.

атрибут McpToolProperty

Вы можете определить одно или несколько свойств средства, применяя McpToolProperty атрибут к входным параметрам стиля привязки в функции.

Тип McpToolPropertyAttribute поддерживает следующие свойства:

Недвижимость	Описание
PropertyName (ИмяСвойства)	Имя свойства средства, которое предоставляется клиентам.
Описание	Описание того, что делает свойство средства.
IsRequired	(Необязательно) Если задано значение true, свойство средства требуется в качестве аргумента для вызовов инструментов. По умолчанию — false.

Тип свойства выводится из типа параметра, к которому применяется атрибут. Например [McpToolProperty("snippetname", "The name of the snippet.", true)] string name , определяет необходимое свойство средства с именем snippetname типа string в сообщениях MCP.

Эти атрибуты можно увидеть в средстве SaveSnippet в примерах.

Привязка к пользовательскому типу

Вы можете определить одно или несколько свойств инструмента, привязав его к определенному типу объекта CLR (POCO). Свойства этого типа автоматически предоставляются в качестве свойств средства. Атрибут [Description] можно использовать для предоставления описания для каждого свойства. Можно указать, что свойство требуется с помощью ключевого required слова. Тип свойства класса в типе информирования, используемом в сообщениях MCP.

В этом примере используется пользовательский тип для определения свойств инструмента:SaveSnippet

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

Вы можете определить одно или несколько свойств средства в файле точки входа (Program.cs) с помощью возвращаемого McpToolBuilder методом ConfigureMcpTool()FunctionsApplicationBuilder. В этом примере вызывается WithProperty метод построителя для средства, GetSnippet чтобы задать свойства средства:

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

Метод можно вызывать WithProperty() несколько раз, чтобы определить несколько свойств для средства. Каждый вызов WithProperty() включает строковое представление типа свойства MCP, которое может не соответствовать непосредственно типу СРЕДЫ CLR. Например, используйте "boolean" для определения логического свойства, даже если соответствующий тип CLR имеет значение bool. Допустимые типы: "string", "number", "integer", "boolean""object".

Полный пример см. в Program.cs файле.

В Java вы определяете свойства средства с помощью заметки @McpToolProperty для отдельных параметров функции. Каждый параметр, представляющий свойство средства, должен быть аннотирован с помощью этой заметки, указывая имя свойства, тип, описание и необходимость.

Эти заметки можно увидеть в примерах.

Свойства средства можно настроить в поле определения toolProperties триггера, которое представляет собой строковое представление массива ToolProperty объектов.

Объект ToolProperty имеет эту структуру:

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

Поля ToolProperty объекта:

Недвижимость	Описание
propertyName	Имя свойства средства, которое предоставляется клиентам.
propertyType	Тип свойства средства. Допустимые типы: string, number, integer, booleanobject. См isArray . сведения о типах массивов.
описание	Описание того, что делает свойство средства.
isRequired	(Необязательно) Если задано значение true, свойство средства требуется в качестве аргумента для вызовов инструментов. По умолчанию — false.
isArray	(Необязательно) Если задано значение true, свойство инструмента является массивом указанного типа свойства. По умолчанию — false.

Вы можете предоставить toolProperties поле в виде массива ToolProperty объектов или использовать arg помощники из @azure/functions для определения свойств более безопасно для типов:

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

Дополнительные сведения см. в примерах .

Параметры файла host.json

Файл host.json содержит параметры, управляющие поведением триггеров MCP. Дополнительные сведения о доступных настройках см. в разделе Настройка host.json.

Связанные статьи

Расширение Azure OpenAI для Функции Azure