Hugging Face 的 LOGO

MCP 课程文档

理解 MCP 能力

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

理解 MCP 能力

MCP 服务器通过通信协议向客户端公开各种能力。这些能力分为四个主要类别，每个类别都有独特的特征和用例。让我们来探索构成 MCP 功能基础的这些核心原语。

在本节中，我们将以每种语言的框架无关函数的形式展示示例。这是为了专注于概念以及它们如何协同工作，而不是任何框架的复杂性。

在接下来的单元中，我们将展示这些概念如何在 MCP 特定代码中实现。

工具 (Tools)

工具是 AI 模型可以通过 MCP 协议调用的可执行函数或操作。

  • 控制：工具通常是模型控制的，这意味着 AI 模型 (LLM) 根据用户的请求和上下文决定何时调用它们。
  • 安全性：由于它们能够执行具有副作用的操作，工具执行可能很危险。因此，它们通常需要明确的用户批准。
  • 用例：发送消息、创建工单、查询 API、执行计算。

示例：一个用于获取给定位置当前天气数据的天气工具

python
javascript
def get_weather(location: str) -> dict:
    """Get the current weather for a specified location."""
    # Connect to weather API and fetch data
    return {
        "temperature": 72,
        "conditions": "Sunny",
        "humidity": 45
    }

资源 (Resources)

资源提供对数据源的只读访问，允许 AI 模型检索上下文而无需执行复杂的逻辑。

  • 控制：资源是应用程序控制的，这意味着宿主应用程序通常决定何时访问它们。
  • 性质：它们旨在用于数据检索，计算量最小，类似于 REST API 中的 GET 端点。
  • 安全性：由于它们是只读的，因此通常比工具呈现较低的安全风险。
  • 用例：访问文件内容、检索数据库记录、读取配置信息。

示例：提供文件内容访问的资源

python
javascript
def read_file(file_path: str) -> str:
    """Read the contents of a file at the specified path."""
    with open(file_path, 'r') as f:
        return f.read()

提示 (Prompts)

提示是预定义的模板或工作流，用于指导用户、AI 模型和服务器功能之间的交互。

  • 控制：提示是用户控制的，通常作为宿主应用程序 UI 中的选项呈现。
  • 目的：它们构造交互以优化可用工具和资源的使用。
  • 选择：用户通常在 AI 模型开始处理之前选择一个提示，为交互设置上下文。
  • 用例：常见工作流、专业任务模板、引导式交互。

示例：用于生成代码审查的提示模板

python
javascript
def code_review(code: str, language: str) -> list:
    """Generate a code review for the provided code snippet."""
    return [
        {
            "role": "system",
            "content": f"You are a code reviewer examining {language} code. Provide a detailed review highlighting best practices, potential issues, and suggestions for improvement."
        },
        {
            "role": "user",
            "content": f"Please review this {language} code:\n\n```{language}\n{code}\n```"
        }
    ]

抽样 (Sampling)

抽样允许服务器请求客户端（特别是宿主应用程序）执行 LLM 交互。

  • 控制：抽样是服务器发起的，但需要客户端/宿主协助。
  • 目的：它支持服务器驱动的代理行为以及潜在的递归或多步交互。
  • 安全性：与工具类似，抽样操作通常需要用户批准。
  • 用例：复杂的多步任务、自主代理工作流、交互式流程。

示例：服务器可能请求客户端分析它已处理的数据

python
javascript
def request_sampling(messages, system_prompt=None, include_context="none"):
    """Request LLM sampling from the client."""
    # In a real implementation, this would send a request to the client
    return {
        "role": "assistant",
        "content": "Analysis of the provided data..."
    }

抽样流程遵循以下步骤：

  1. 服务器向客户端发送 `sampling/createMessage` 请求
  2. 客户端审查请求并可以修改它
  3. 客户端从 LLM 抽样
  4. 客户端审查完成情况
  5. 客户端将结果返回给服务器

这种“人在回路”的设计确保用户保持对 LLM 看到和生成的内容的控制。在实施抽样时，提供清晰、结构良好的提示并包含相关上下文非常重要。

能力如何协同工作

让我们看看这些能力如何协同工作以实现复杂的交互。在下表中，我们概述了能力、控制者、控制方向以及其他一些详细信息。

能力 控制者 方向 副作用 需要批准 典型用例
工具 模型 (LLM) 客户端 → 服务器 是（潜在） 是 操作、API 调用、数据操作
资源 应用 客户端 → 服务器 否（只读） 通常不需要 数据检索、上下文收集
提示 用户 服务器 → 客户端 否 否（用户选择） 引导式工作流、专业模板
采样 服务器 服务器 → 客户端 → 服务器 间接 是 多步任务、代理行为

这些能力旨在以互补的方式协同工作

  1. 用户可以选择一个提示来启动一个专业工作流
  2. 该提示可能包含来自资源的上下文
  3. 在处理过程中，AI 模型可能会调用工具来执行特定操作
  4. 对于复杂操作，服务器可能会使用抽样请求额外的 LLM 处理

这些原语之间的区别为 MCP 交互提供了清晰的结构，使 AI 模型能够访问信息、执行操作并参与复杂的工作流，同时保持适当的控制边界。

发现过程

MCP 的主要功能之一是动态能力发现。当客户端连接到服务器时，它可以通过特定的列表方法查询可用的工具、资源和提示：

  • `tools/list`：发现可用的工具
  • `resources/list`：发现可用的资源
  • `prompts/list`：发现可用的提示

这种动态发现机制允许客户端适应每个服务器提供的特定功能，而无需硬编码服务器功能的知识。

结论

理解这些核心原语对于有效使用 MCP 至关重要。通过提供具有明确控制边界的不同类型能力，MCP 实现了 AI 模型和外部系统之间强大的交互，同时保持了适当的安全和控制机制。

在下一节中，我们将探讨 Gradio 如何与 MCP 集成，为这些功能提供易于使用的界面。

< > 在 GitHub 上更新

←通信协议 MCP SDK→