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

# 资源

> 将服务器上的数据和内容暴露给LLM使用

资源是模型上下文协议（MCP协议）中的核心原语，允许服务器暴露数据和内容，客户端可以读取这些资源并将其用作LLM交互的上下文。

<Note>
  资源设计为**应用程序控制**，意味着客户端应用程序可以决定如何以及何时使用它们。
  不同的MCP客户端可能会以不同的方式处理资源。例如：

  * Claude Desktop目前要求用户在使用资源之前明确选择资源
  * 其他客户端可能会基于启发式自动选择资源
  * 某些实现甚至可能允许AI模型本身决定使用哪些资源

  服务器作者在实现资源支持时应准备好处理这些交互模式。为了自动向模型暴露数据，服务器作者应使用**模型控制**的原语，例如[工具](./tools)。
</Note>

## 概述

资源代表MCP服务器希望向客户端提供的任何类型的数据。这可以包括：

* 文件内容
* 数据库记录
* API响应
* 实时系统数据
* 截图和图像
* 日志文件
* 以及其他

每个资源由唯一的URI标识，可以包含文本或二进制数据。

## 资源URI

资源使用以下格式的URI进行标识：

```
[协议]://[主机]/[路径]
```

例如：

* `file:///home/user/documents/report.pdf`
* `postgres://database/customers/schema`
* `screen://localhost/display1`

协议和路径结构由MCP服务器实现定义。服务器可以定义自己的自定义URI方案。

## 资源类型

资源可以包含两种类型的内容：

### 文本资源

文本资源包含UTF-8编码的文本数据。这些适用于：

* 源代码
* 配置文件
* 日志文件
* JSON/XML数据
* 纯文本

### 二进制资源

二进制资源包含base64编码的原始二进制数据。这些适用于：

* 图像
* PDF文件
* 音频文件
* 视频文件
* 其他非文本格式

## 资源发现

客户端可以通过两种主要方法发现可用资源：

### 直接资源

服务器通过`resources/list`端点暴露具体资源列表。每个资源包括：

```typescript theme={null}
{
  uri: string;           // 资源的唯一标识符
  name: string;          // 人类可读的名称
  description?: string;  // 可选描述
  mimeType?: string;     // 可选的MIME类型
}
```

### 资源模板

对于动态资源，服务器可以暴露[URI模板](https://datatracker.ietf.org/doc/html/rfc6570)，客户端可以使用这些模板构建有效的资源URI：

```typescript theme={null}
{
  uriTemplate: string;   // 遵循RFC 6570的URI模板
  name: string;          // 该类型的人类可读名称
  description?: string;  // 可选描述
  mimeType?: string;     // 所有匹配资源的可选MIME类型
}
```

## 读取资源

要读取资源，客户端使用资源URI发出`resources/read`请求。

服务器响应包含资源内容列表：

```typescript theme={null}
{
  contents: [
    {
      uri: string;        // 资源的URI
      mimeType?: string;  // 可选的MIME类型

      // 以下之一：
      text?: string;      // 对于文本资源
      blob?: string;      // 对于二进制资源（base64编码）
    }
  ]
}
```

<Tip>
  服务器可能会响应一个`resources/read`请求返回多个资源。例如，当读取目录时，可以返回目录中的文件列表。
</Tip>

## 资源更新

MCP通过两种机制支持资源的实时更新：

### 列表更改

服务器可以通过`notifications/resources/list_changed`通知客户端可用资源列表的更改。

### 内容更改

客户端可以订阅特定资源的更新：

1. 客户端发送`resources/subscribe`并附带资源URI
2. 当资源更改时，服务器发送`notifications/resources/updated`
3. 客户端可以使用`resources/read`获取最新内容
4. 客户端可以使用`resources/unsubscribe`取消订阅

## 示例实现

以下是一个在MCP服务器中实现资源支持的简单示例：

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const server = new Server({
      name: "example-server",
      version: "1.0.0"
    }, {
      capabilities: {
        resources: {}
      }
    });

    // 列出可用资源
    server.setRequestHandler(ListResourcesRequestSchema, async () => {
      return {
        resources: [
          {
            uri: "file:///logs/app.log",
            name: "Application Logs",
            mimeType: "text/plain"
          }
        ]
      };
    });

    // 读取资源内容
    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
      const uri = request.params.uri;

      if (uri === "file:///logs/app.log") {
        const logContents = await readLogFile();
        return {
          contents: [
            {
              uri,
              mimeType: "text/plain",
              text: logContents
            }
          ]
        };
      }

      throw new Error("Resource not found");
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    app = Server("example-server")

    @app.list_resources()
    async def list_resources() -> list[types.Resource]:
        return [
            types.Resource(
                uri="file:///logs/app.log",
                name="Application Logs",
                mimeType="text/plain"
            )
        ]

    @app.read_resource()
    async def read_resource(uri: AnyUrl) -> str:
        if str(uri) == "file:///logs/app.log":
            log_contents = await read_log_file()
            return log_contents

        raise ValueError("Resource not found")

    # 启动服务器
    async with stdio_server() as streams:
        await app.run(
            streams[0],
            streams[1],
            app.create_initialization_options()
        )
    ```
  </Tab>
</Tabs>

## 最佳实践

在实现资源支持时：

1. 使用清晰、描述性的资源名称和URI
2. 包含有用的描述以指导LLM理解
3. 在已知时设置适当的MIME类型
4. 为动态内容实现资源模板
5. 对频繁更改的资源使用订阅
6. 使用清晰的错误消息优雅地处理错误
7. 对于大型资源列表考虑分页
8. 在适当时缓存资源内容
9. 在处理之前验证URI
10. 记录您的自定义URI方案

## 安全考虑

在暴露资源时：

* 验证所有资源URI
* 实施适当的访问控制
* 清理文件路径以防止目录遍历
* 谨慎处理二进制数据
* 考虑对资源读取进行速率限制
* 审计资源访问
* 加密传输中的敏感数据
* 验证MIME类型
* 对长时间运行的读取实施超时
* 适当处理资源清理