跳到主要内容

MCP 根目录

根目录（Roots）允许服务器询问客户端可以操作的文件系统边界。

什么是根目录？​

根目录定义了服务器可以访问的文件系统范围，帮助服务器了解客户端允许它访问哪些目录。

@app.list_roots()
async def list_roots():
    return [
        Root(
            uri="file:///home/user/projects",
            name="项目目录"
        )
    ]

使用场景​

  1. 文件系统操作：服务器需要知道可以读取哪些目录
  2. 路径验证：限制服务器只能访问特定目录
  3. 安全控制：防止服务器访问敏感目录

完整示例​

from mcp.types import Root
from mcp.server import Server

app = Server("file-server")

# 声明可用的根目录
@app.list_roots()
async def list_roots():
    return [
        Root(
            uri="file:///home/user/project",
            name="项目根目录"
        ),
        Root(
            uri="file:///home/user/data",
            name="数据目录"
        )
    ]

# 使用根目录进行路径验证
@app.read_resource()
async def read_resource(uri: str) -> list[TextContent]:
    # 获取允许的根目录
    roots = await session.list_roots()
    allowed_paths = [root.uri.replace("file://", "") for root in roots]
    
    # 验证路径是否在允许范围内
    file_path = uri.replace("file://", "")
    if not any(file_path.startswith(p) for p in allowed_paths):
        raise ValueError("Access denied: path outside allowed roots")
    
    return [TextContent(type="text", text=read_file(file_path))]

与工具的区别​

特性根目录 (Roots)工具 (Tools)
方向服务器查询客户端客户端调用服务器
用途定义访问边界执行操作
时机连接时声明运行时调用