> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.developerdoc.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 理解 MCP 服务器

MCP server 是通过标准化协议接口向 AI 应用暴露特定能力的程序。

常见例子包括用于访问文档的文件系统服务器、用于查询数据的数据库服务器、用于代码管理的 GitHub 服务器、用于团队沟通的 Slack 服务器，以及用于日程安排的日历服务器。

## 核心服务器能力

服务器通过三个构建块提供功能：

| 能力            | 说明                                                             | 示例                         | 由谁控制 |
| ------------- | -------------------------------------------------------------- | -------------------------- | ---- |
| **Tools**     | LLM 可以主动调用的函数，并根据用户请求决定何时使用。Tool 可以写入数据库、调用外部 API、修改文件或触发其他逻辑。 | 搜索航班<br />发送消息<br />创建日历事件 | 模型   |
| **Resources** | 被动数据源，为上下文提供只读信息访问，例如文件内容、数据库 schema 或 API 文档。                 | 检索文档<br />访问知识库<br />读取日历  | 应用   |
| **Prompts**   | 预构建的指令模板，用来告诉模型如何配合特定 tools 和 resources 工作。                    | 规划假期<br />总结会议<br />起草邮件   | 用户   |

下面使用一个假设场景说明这些能力各自的作用，以及它们如何协同工作。

### Tools

Tools 让 AI 模型能够执行动作。每个 tool 都定义一个具体操作，并带有类型化输入和输出。模型会根据上下文请求执行 tool。

#### Tools 如何工作

Tools 是由 schema 定义、可供 LLM 调用的接口。MCP 使用 JSON Schema 进行校验。每个 tool 执行一个单一操作，并具有清晰定义的输入和输出。Tool 执行前可能需要用户同意，这有助于确保用户仍然控制模型采取的动作。

**协议操作：**

| 方法           | 用途     | 返回值              |
| ------------ | ------ | ---------------- |
| `tools/list` | 发现可用工具 | 带 schema 的工具定义数组 |
| `tools/call` | 执行特定工具 | 工具执行结果           |

**工具定义示例：**

```typescript theme={null}
{
  name: "searchFlights",
  description: "Search for available flights",
  inputSchema: {
    type: "object",
    properties: {
      origin: { type: "string", description: "Departure city" },
      destination: { type: "string", description: "Arrival city" },
      date: { type: "string", format: "date", description: "Travel date" }
    },
    required: ["origin", "destination", "date"]
  }
}
```

#### 示例：旅行预订

Tools 让 AI 应用能够代表用户执行动作。在旅行规划场景中，AI 应用可能使用多个 tools 来帮助预订假期：

**航班搜索**

```
searchFlights(origin: "NYC", destination: "Barcelona", date: "2024-06-15")
```

查询多家航空公司并返回结构化航班选项。

**日历占用**

```
createCalendarEvent(title: "Barcelona Trip", startDate: "2024-06-15", endDate: "2024-06-22")
```

在用户日历中标记旅行日期。

**邮件通知**

```
sendEmail(to: "team@work.com", subject: "Out of Office", body: "...")
```

向同事发送自动外出通知。

#### 用户交互模型

Tools 由模型控制，这意味着 AI 模型可以自动发现并调用它们。不过，MCP 通过多种机制强调人工监督。

出于信任和安全考虑，应用可以通过多种机制实现用户控制，例如：

* 在 UI 中展示可用 tools，让用户定义某个 tool 是否应在特定交互中可用。
* 针对单次 tool 执行显示审批对话框。
* 针对某些安全操作设置预批准权限。
* 活动日志展示所有 tool 执行及其结果。

### Resources

Resources 为信息提供结构化访问，AI 应用可以检索这些信息并作为上下文提供给模型。

#### Resources 如何工作

Resources 暴露来自文件、API、数据库或任何其他来源的数据，供 AI 理解上下文。应用可以直接访问这些信息，并决定如何使用它们，例如选择相关片段、使用 embeddings 搜索，或将全部数据传给模型。

每个 resource 都有唯一 URI（例如 `file:///path/to/document.md`），并声明其 MIME type，以便进行适当的内容处理。

Resources 支持两种发现模式：

* **Direct Resources** - 指向特定数据的固定 URI。示例：`calendar://events/2024` - 返回 2024 年的日历可用性。
* **Resource Templates** - 带参数的动态 URI，用于灵活查询。示例：
  * `travel://activities/{city}/{category}` - 按城市和类别返回活动。
  * `travel://activities/barcelona/museums` - 返回巴塞罗那的所有博物馆。

Resource Templates 包含 title、description 和预期 MIME type 等元数据，使其可发现且具备自描述性。

**协议操作：**

| 方法                         | 用途                    | 返回值                    |
| -------------------------- | --------------------- | ---------------------- |
| `resources/list`           | 列出可用 direct resources | resource 描述符数组         |
| `resources/templates/list` | 发现 resource templates | resource template 定义数组 |
| `resources/read`           | 检索 resource 内容        | 带元数据的 resource 数据      |
| `resources/subscribe`      | 监控 resource 变化        | 订阅确认                   |

#### 示例：获取旅行规划上下文

继续旅行规划示例，resources 为 AI 应用提供对相关信息的访问：

* **日历数据**（`calendar://events/2024`）- 检查用户是否有空。
* **旅行文档**（`file:///Documents/Travel/passport.pdf`）- 访问重要文档。
* **历史行程**（`trips://history/barcelona-2023`）- 参考过去的旅行和偏好。

AI 应用会检索这些 resources，并决定如何处理它们：可以使用 embeddings 或关键词搜索选择部分数据，也可以将原始数据直接传给模型。

在这个例子中，应用会向模型提供日历数据、天气信息和旅行偏好，使其能够检查可用日期、查询天气模式，并参考过去的旅行偏好。

**Resource Template 示例：**

```json theme={null}
{
  "uriTemplate": "weather://forecast/{city}/{date}",
  "name": "weather-forecast",
  "title": "Weather Forecast",
  "description": "Get weather forecast for any city and date",
  "mimeType": "application/json"
}

{
  "uriTemplate": "travel://flights/{origin}/{destination}",
  "name": "flight-search",
  "title": "Flight Search",
  "description": "Search available flights between cities",
  "mimeType": "application/json"
}
```

这些 templates 支持灵活查询。对于天气数据，用户可以访问任意城市/日期组合的预报。对于航班，用户可以搜索任意两个机场之间的路线。当用户把 `origin` 机场输入为 `"NYC"`，并开始在 `destination` 机场输入 `"Bar"` 时，系统可以建议 `"Barcelona (BCN)"` 或 `"Barbados (BGI)"`。

#### 参数补全

动态 resources 支持参数补全。例如：

* 为 `weather://forecast/{city}` 输入 `"Par"` 时，可能建议 `"Paris"` 或 `"Park City"`。
* 为 `flights://search/{airport}` 输入 `"JFK"` 时，可能建议 `"JFK - John F. Kennedy International"`。

系统可以帮助发现有效值，而不要求用户知道精确格式。

#### 用户交互模型

Resources 由应用驱动，因此应用在检索、处理和展示可用上下文时有很高灵活性。常见交互模式包括：

* 使用树形或列表视图，以类似文件夹的结构浏览 resources。
* 使用搜索和过滤界面查找特定 resources。
* 基于启发式规则或 AI 选择自动包含上下文，或提供智能建议。
* 使用手动或批量选择界面包含一个或多个 resources。

应用可以自由选择适合自身需求的界面模式来实现 resource 发现。协议不强制特定 UI 模式，因此可以实现带预览能力的 resource 选择器、基于当前对话上下文的智能建议、用于包含多个 resources 的批量选择，或与现有文件浏览器和数据浏览器集成。

### Prompts

Prompts 提供可复用模板。它们允许 MCP server 作者为某个领域提供参数化 prompt，或展示如何最好地使用这个 MCP server。

#### Prompts 如何工作

Prompts 是结构化模板，用来定义预期输入和交互模式。它们由用户控制，需要显式调用，而不是自动触发。Prompts 可以感知上下文，引用可用 resources 和 tools 来创建完整工作流。与 resources 类似，prompts 支持参数补全，帮助用户发现有效参数值。

**协议操作：**

| 方法             | 用途           | 返回值              |
| -------------- | ------------ | ---------------- |
| `prompts/list` | 发现可用 prompts | prompt 描述符数组     |
| `prompts/get`  | 检索 prompt 详情 | 带参数的完整 prompt 定义 |

#### 示例：简化工作流

Prompts 为常见任务提供结构化模板。在旅行规划上下文中：

**“Plan a vacation” prompt：**

```json theme={null}
{
  "name": "plan-vacation",
  "title": "Plan a vacation",
  "description": "Guide through vacation planning process",
  "arguments": [
    { "name": "destination", "type": "string", "required": true },
    { "name": "duration", "type": "number", "description": "days" },
    { "name": "budget", "type": "number", "required": false },
    { "name": "interests", "type": "array", "items": { "type": "string" } }
  ]
}
```

相比非结构化自然语言输入，prompt 系统支持：

1. 选择 `"Plan a vacation"` 模板。
2. 输入结构化参数：Barcelona、7 days、\$3000、\["beaches", "architecture", "food"]。
3. 基于模板一致地执行工作流。

#### 用户交互模型

Prompts 由用户控制，需要显式调用。协议允许实现者自由设计适合自身应用的自然交互界面。关键原则包括：

* 易于发现可用 prompts。
* 清晰描述每个 prompt 做什么。
* 自然地输入参数，并进行校验。
* 透明展示 prompt 底层模板。

应用通常通过多种 UI 模式暴露 prompts，例如：

* Slash commands（输入 `"/"` 查看 `/plan-vacation` 等可用 prompts）。
* 命令面板，支持搜索访问。
* 针对常用 prompts 的专用 UI 按钮。
* 根据上下文建议相关 prompts 的菜单。

## 组合多个服务器

当多个服务器通过统一接口协同工作、组合各自的专门能力时，MCP 的真正价值会体现出来。

### 示例：多服务器旅行规划

设想一个个性化 AI 旅行规划应用，它连接了三个服务器：

* **Travel Server** - 处理航班、酒店和行程。
* **Weather Server** - 提供气候数据和天气预报。
* **Calendar/Email Server** - 管理日程和沟通。

#### 完整流程

1. **用户使用参数调用 prompt：**

   ```json theme={null}
   {
     "prompt": "plan-vacation",
     "arguments": {
       "destination": "Barcelona",
       "departure_date": "2024-06-15",
       "return_date": "2024-06-22",
       "budget": 3000,
       "travelers": 2
     }
   }
   ```

2. **用户选择要包含的 resources：**
   * `calendar://my-calendar/June-2024` (from Calendar Server)
   * `travel://preferences/europe` (from Travel Server)
   * `travel://past-trips/Spain-2023` (from Travel Server)

3. **AI 使用 tools 处理请求：**

   AI 首先读取所有已选择 resources 来收集上下文：从日历中识别可用日期，从旅行偏好中了解首选航空公司和酒店类型，并从历史旅行中发现用户过去喜欢的地点。

   利用这些上下文，AI 随后执行一系列 tools：

   * `searchFlights()` - 查询从 NYC 到 Barcelona 的航班。
   * `checkWeather()` - 检索旅行日期的天气预报。

   然后 AI 使用这些信息创建预订并执行后续步骤，在必要时请求用户批准：

   * `bookHotel()` - 查找指定预算内的酒店。
   * `createCalendarEvent()` - 将行程添加到用户日历。
   * `sendEmail()` - 发送包含行程详情的确认邮件。

**结果：** 通过多个 MCP server，用户完成了针对自己日程定制的巴塞罗那旅行调研和预订。“Plan a Vacation” prompt 指导 AI 跨不同服务器组合 Resources（日历可用性和旅行历史）与 Tools（搜索航班、预订酒店、更新日历），从而收集上下文并执行预订。原本可能需要数小时的任务，通过 MCP 在几分钟内完成。