مشغل أداة MCP لوظائف Azure

استخدم مشغل أداة MCP لتعريف نقاط نهاية الأداة في خادم بروتوكول محتوى النموذج (MCP ). يمكن لنماذج لغة العميل والوكلاء استخدام أدوات لتنفيذ مهام معينة، مثل تخزين أجزاء التعليمات البرمجية أو الوصول إليها.

للحصول على معلومات حول تفاصيل الإعداد والتكوين، راجع الاستعراض العام.

مثال

ملاحظة

بالنسبة إلى C#، يدعم ملحق Azure Functions MCP نموذج العامل المعزول فقط.

تنشئ هذه التعليمة البرمجية نقطة نهاية لعرض أداة تسمى SaveSnippet تحاول الاحتفاظ بمقتطف تعليمات برمجية مسمى لتخزين الكائن الثنائي كبير الحجم.

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 تحاول الاحتفاظ بمقتطف تعليمات برمجية مسمى لتخزين الكائن الثنائي كبير الحجم.

@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 تحاول الاحتفاظ بمقتطف تعليمات برمجية مسمى لتخزين الكائن الثنائي كبير الحجم.

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 تحاول الاحتفاظ بمقتطف تعليمات برمجية مسمى لتخزين الكائن الثنائي كبير الحجم.

@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 تحاول استرداد قصاصة برمجية بالاسم من تخزين كائن ثنائي كبير الحجم.

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

السمات

تستخدم McpToolTriggerAttribute مكتبات C# لتعريف مشغل الدالة.

تأخذ الدالة الإنشائية سمة المعلمات التالية:

المعلمة	الوصف
اسم الأدوات	(مطلوب) اسم الأداة التي يتم كشفها بواسطة نقطة نهاية مشغل MCP.
الوصف	(اختياري) وصف مألوف لنقطة نهاية الأداة للعملاء.

راجع الاستخدام لمعرفة كيفية تعريف خصائص نقطة النهاية كمعلمات إدخال.

تعليقات توضيحية

@McpToolTrigger ينشئ التعليق التوضيحي دالة تعرض نقطة نهاية أداة في خادم MCP البعيد.

يدعم الشرح خيارات التشكيل التالية:

المعلمة	الوصف
name	(مطلوب) اسم الأداة التي يتم كشفها بواسطة نقطة نهاية مشغل MCP.
الوصف	(اختياري) وصف مألوف لنقطة نهاية الأداة للعملاء.

@McpToolProperty يحدد التعليق التوضيحي الخصائص الفردية لأدواتك. يجب إضافة تعليق توضيحي لكل معلمة خاصية في الدالة باستخدام هذا التعليق التوضيحي.

@McpToolProperty يدعم التعليق التوضيحي خيارات التكوين التالية:

المعلمة	الوصف
name	(مطلوب) اسم خاصية الأداة التي تتعرض للعملاء.
نوع الخاصية	(مطلوب) نوع خاصية الأداة. الأنواع الصالحة هي: string، number، integer، boolean، . object
الوصف	(اختياري) وصف ما تقوم به خاصية الأداة.
مطلوب	(اختياري) إذا تم تعيينها إلى true، فإن خاصية الأداة مطلوبة كوسيطة لاستدعاءات الأداة. الإعدادات الافتراضية لـ false.

الديكور

ينطبق فقط على نموذج برمجة Python v2.

mcp_tool_trigger يتطلب مصمم الديكور الإصدار 1.24.0 أو أحدث من الحزمةazure-functions. يتم دعم خصائص مشغل MCP التالية في mcp_tool_trigger:

الخاصية	الوصف
arg_name	اسم المتغير (عادة context) المستخدم في التعليمات البرمجية للدالة للوصول إلى سياق التنفيذ.
tool_name	(مطلوب) اسم أداة خادم MCP التي تعرضها نقطة نهاية الدالة.
الوصف	وصف لأداة خادم MCP التي تعرضها نقطة نهاية الدالة.
tool_properties	تمثيل سلسلة JSON لكائن خاصية واحد أو أكثر يعرض خصائص الأداة للعملاء.

تكوين

يدعم المشغل خيارات الربط هذه، والتي تم تعريفها في التعليمات البرمجية الخاصة بك:

الخيارات	الوصف
النوع	يجب تعيينه إلى mcpToolTrigger. يستخدم فقط مع تعريفات عامة.
اسم الأداة	(مطلوب) اسم أداة خادم MCP التي تعرضها نقطة نهاية الدالة.
الوصف	وصف لأداة خادم MCP التي تعرضها نقطة نهاية الدالة.
خصائص الأدوات	صفيف من toolProperty الكائنات التي تعرض خصائص الأداة للعملاء.
الإخراجات الإضافية	عند تعريفه، يرسل إخراج الدالة إلى ربط آخر.
معالج	الأسلوب الذي يحتوي على التعليمات البرمجية للدالة الفعلية.

راجع قسم Example للحصول على أمثلة كاملة.

الاستخدام

يمكن ربط مشغل أداة MCP بالأنواع التالية:

النوع	الوصف
استدعاء الأدواتContext	كائن يمثل استدعاء الأداة، بما في ذلك اسم الأداة ووسيطات الاستدعاء.
‏‏أنواع قابلة للتسلسل إلى JSON	تحاول الدالات إلغاء تسلسل وسيطات الأداة إلى نوع كائن CLR (POCO) قديم عادي. يستخدم هذا النوع أيضا لتعريف خصائص الأداة. عند الربط بنوع JSON قابل للتسلسل، يمكنك اختياريا أيضا تضمين معلمة من النوع ToolInvocationContext للوصول إلى معلومات استدعاء الأداة.

خصائص الأداة

يستدعي عملاء MCP أدوات مع وسيطات لتوفير البيانات والسياق لعملية الأداة. يعرف العملاء كيفية جمع هذه الوسيطات وتمريرها استنادا إلى الخصائص التي تعلن عنها الأداة كجزء من البروتوكول. لذلك تحتاج إلى تعريف خصائص الأداة في التعليمات البرمجية للدالة.

عند تعريف خاصية أداة، تكون اختيارية بشكل افتراضي، ويمكن للعميل حذفها عند استدعاء الأداة. تحتاج إلى وضع علامة صريح على الخصائص على أنها مطلوبة إذا لم تتمكن الأداة من العمل بدونها.

ملاحظة

جعلت الإصدارات السابقة من معاينة ملحق MCP جميع خصائص الأداة المطلوبة بشكل افتراضي. تم تغيير هذا السلوك اعتبارا من الإصدار 1.0.0-preview.7، والآن يجب عليك وضع علامة صريح على الخصائص على أنها مطلوبة.

في C#، يمكنك تعريف خصائص أدواتك بعدة طرق. النهج الذي تستخدمه هو مسألة تفضيل نمط التعليمات البرمجية. الخيارات هي:

• تأخذ الدالة معلمات الإدخال باستخدام السمة McpToolProperty .
• يمكنك تعريف نوع مخصص مع الخصائص، وتربط الدالة بهذا النوع.
• يمكنك استخدام FunctionsApplicationBuilder لتعريف الخصائص في الملف الخاص بك Program.cs .

McpToolProperty صفة

يمكنك تعريف خاصية أداة واحدة أو أكثر عن طريق تطبيق السمة McpToolProperty لإدخال معلمات نمط الربط في الدالة الخاصة بك.

McpToolPropertyAttribute يدعم النوع هذه الخصائص:

الخاصية	الوصف
اسم الخاصية	اسم خاصية الأداة التي تتعرض للعملاء.
الوصف	وصف ما تقوم به خاصية الأداة.
مطلوب	(اختياري) إذا تم تعيينها إلى true، فإن خاصية الأداة مطلوبة كوسيطة لاستدعاءات الأداة. الإعدادات الافتراضية لـ false.

يتم استنتاج نوع الخاصية من نوع المعلمة التي تقوم بتطبيق السمة عليها. على سبيل المثال [McpToolProperty("snippetname", "The name of the snippet.", true)] string name يعرف خاصية أداة مطلوبة تسمى snippetname من النوع string في رسائل MCP.

يمكنك مشاهدة هذه السمات المستخدمة في SaveSnippet الأداة في الأمثلة.

الربط بنوع مخصص

يمكنك تعريف خاصية أداة واحدة أو أكثر عن طريق الربط بنوع كائن CLR (POCO) قديم عادي تقوم بتعريفه. يتم عرض خصائص هذا النوع تلقائيا كخصائص أداة. يمكنك استخدام السمة [الوصف] لتوفير وصف لكل خاصية. يمكنك الإشارة إلى أن خاصية مطلوبة باستخدام 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 هي:

الخاصية	الوصف
اسم الخاصية	اسم خاصية الأداة التي تتعرض للعملاء.
نوع الخاصية	نوع خاصية الأداة. الأنواع الصالحة هي: string، number، integer، boolean، . object راجع isArray أنواع الصفائف.
الوصف	وصف ما تقوم به خاصية الأداة.
مطلوب	(اختياري) إذا تم تعيينها إلى 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. راجع إعدادات مضيف.json قسم للحصول على تفاصيل حول الإعدادات المتوفرة.

المقالات ذات الصلة

ملحق Azure OpenAI ل Azure Functions