Sanity MCP 服务器

使用由 AI 驱动的工具来转换您的内容操作。通过您最喜欢的启用 AI 的编辑器中的自然语言对话来创建、管理和探索您的内容。

Sanity MCP 服务器实现了 Model Context Protocol，将您的 Sanity 项目与像 Claude、Cursor 和 VS Code 这样的 AI 工具连接起来。它使 AI 模型能够理解您的内容结构并通过自然语言指令执行操作。

✨ 主要功能

• 🤖 内容智能：让 AI 探索和理解您的内容库
• 🔄 内容操作：通过自然语言指令自动化任务
• 📊 模式感知：AI 尊重您的内容结构和验证规则
• 🚀 版本管理：轻松规划和组织内容发布
• 🔍 语义搜索：根据意义而不是仅仅关键词来查找内容

目录

• 🔌 快速开始
  • 前提条件
  • 为 Sanity MCP 服务器添加配置
• 🛠️ 可用工具
• ⚙️ 配置
  • 🔑 API 令牌和权限
  • 👥 用户角色
• 📦 Node.js 环境设置
  • 🛠 Node 版本管理器用户的快速设置
  • 🤔 为什么需要这样做？
  • 🔍 故障排除
• 💻 开发
  • 调试

🔌 快速开始

前提条件

在使用 MCP 服务器之前，您需要：

1. 部署带有模式清单的 Sanity Studio

   MCP 服务器需要访问您的内容结构才能有效工作。使用以下方法之一部署您的模式清单：

   # 选项 A：强制使用最新 CLI 版本（推荐）
   cd /path/to/studio
   SANITY_CLI_SCHEMA_STORE_ENABLED=true npx --ignore-existing sanity@latest schema deploy
   
   # 选项 B：如果您已全局安装了 CLI
   npm install -g sanity
   cd /path/to/studio
   SANITY_CLI_SCHEMA_STORE_ENABLED=true sanity schema deploy
   
   # 选项 C：首先更新您的 Studio
   cd /path/to/studio
   npm update sanity
   SANITY_CLI_SCHEMA_STORE_ENABLED=true npx sanity schema deploy
   

   [!NOTE]
   模式部署需要最新的 CLI 版本和 SANITY_CLI_SCHEMA_STORE_ENABLED 标志。此功能将在未来的版本中默认启用。

2. 获取您的 API 凭证

   • 项目 ID
   • 数据集名称
   • 具有适当权限的 API 令牌

此 MCP 服务器可以与支持 Model Context Protocol 的任何应用程序一起使用。以下是一些流行示例：

• Claude Desktop
• Cursor IDE
• Visual Studio Code
• 自定义兼容 MCP 的应用程序

为 Sanity MCP 服务器添加配置

要使用 Sanity MCP 服务器，请在应用程序的 MCP 设置中添加以下配置：

{
  "mcpServers": {
    "sanity": {
      "command": "npx",
      "args": ["-y", "@sanity/mcp-server@latest"],
      "env": {
        "SANITY_PROJECT_ID": "your-project-id",
        "SANITY_DATASET": "production",
        "SANITY_API_TOKEN": "your-sanity-api-token"
      }
    }
  }
}

此配置的确切位置取决于您的应用程序：

应用程序	配置位置
Claude Desktop	Claude Desktop 配置文件
Cursor	工作区或全局设置
VS Code	工作区或用户设置（取决于扩展）
自定义应用	请参考您应用的 MCP 集成文档

无法使其正常工作？请参阅Node.js 配置部分。

🛠️ 可用工具

上下文与设置

• get_initial_context – 重要：在使用任何其他工具之前必须调用，以初始化上下文并获取使用说明。
• get_sanity_config – 检索当前的 Sanity 配置（projectId, dataset, apiVersion 等）

文档操作

• create_document – 根据指令创建包含 AI 生成内容的新文档
• update_document – 根据指令更新现有文档的内容
• patch_document - 直接应用补丁操作修改文档的特定部分而不使用 AI 生成
• query_documents – 执行 GROQ 查询以搜索和检索内容
• document_action – 对文档执行操作，如发布、取消发布或删除文档

发布管理

• list_releases – 列出内容发布，可按状态过滤
• create_release – 创建新的内容发布
• edit_release – 更新现有发布的元数据
• schedule_release – 安排在特定时间发布
• release_action – 对发布执行操作（发布、归档、取消归档、取消安排、删除）

版本管理

• create_version – 为特定版本创建文档版本
• discard_version – 从发布中删除特定版本的文档
• mark_for_unpublish – 标记一个文档，在特定版本发布时取消发布

数据集管理

• get_datasets – 列出项目中的所有数据集
• create_dataset – 创建新的数据集
• update_dataset – 修改数据集设置

模式信息

• get_schema – 获取模式详细信息，可以是完整模式或特定类型
• list_schema_ids – 列出所有可用的模式 ID

GROQ 支持

• get_groq_specification – 获取 GROQ 语言规范摘要

Embeddings & 语义搜索

• list_embeddings_indices – 列出所有可用的 embeddings 索引
• semantic_search – 在 embeddings 索引上执行语义搜索

项目信息

• list_projects – 列出与您的帐户关联的所有 Sanity 项目
• get_project_studios – 获取链接到特定项目的 studio 应用程序

⚙️ 配置

服务器接受以下环境变量：

变量	描述	必需
SANITY_API_TOKEN	您的 Sanity API 令牌	✅
SANITY_PROJECT_ID	您的 Sanity 项目 ID	✅
SANITY_DATASET	要使用的数据集	✅
SANITY_API_HOST	API 主机（默认为 https://api.sanity.io）	❌
MCP_USER_ROLE	决定工具访问级别（开发人员或编辑者）	❌

[!WARNING]
使用 AI 与生产数据集
当使用具有写入权限的令牌配置 MCP 服务器以访问生产数据集时，请注意，AI 可以执行创建、更新或删除内容等破坏性操作。如果您使用的是只读令牌，则无需担心。尽管我们正在积极开发防护措施，但您仍应谨慎行事，并考虑使用开发/暂存数据集来测试需要写入权限的 AI 操作。

🔑 API 令牌和权限

MCP 服务器需要适当的 API 令牌和权限才能正常运行。以下是您需要了解的内容：

1. 生成机器人令牌：

   • 转到您的项目管理控制台：设置 > API > 令牌
   • 点击“添加新令牌”
   • 为您的 MCP 服务器使用创建专用令牌
   • 安全存储令牌 - 它只会显示一次！

2. 所需权限：

   • 令牌需要根据您的使用情况具备适当的权限
   • 对于基本读取操作：viewer 角色足够
   • 对于内容管理：建议使用 editor 或 developer 角色
   • 对于高级操作（如管理数据集）：可能需要 administrator 角色

3. 数据集访问：

   • 公共数据集：未认证用户可读取内容
   • 私有数据集：需要正确的令牌认证
   • 草稿和版本化内容：仅限具有适当权限的认证用户访问

4. 安全最佳实践：

   • 为不同环境（开发、暂存、生产）使用不同的令牌
   • 不要将令牌提交到版本控制系统
   • 考虑使用环境变量进行令牌管理
   • 定期轮换令牌以提高安全性

👥 用户角色

服务器支持两种用户角色：

• developer: 访问所有工具
• editor: 专注于内容的工具，不包括项目管理

📦 Node.js 环境设置

对于 Node 版本管理器用户的重要提示：如果你使用 nvm、mise、fnm、nvm-windows 或类似的工具，你需要按照下面的步骤进行设置，以确保 MCP 服务器可以访问 Node.js。这是一次性设置，可以为你以后节省故障排除的时间。这是一个 持续存在的问题。

🛠 Node 版本管理器用户的快速设置

1. 首先，激活你首选的 Node.js 版本：

   # 使用 nvm
   nvm use 20   # 或者你偏好的版本
   
   # 使用 mise
   mise use node@20
   
   # 使用 fnm
   fnm use 20
   

2. 然后，创建必要的符号链接（选择你的操作系统）：

   在 macOS/Linux 上：

   sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx
   

   [!NOTE]
   虽然通常使用 sudo 需要谨慎，但在这种情况下是安全的，因为：

   • 我们只是为现有的 Node.js 二进制文件创建符号链接
   • 目标目录 (/usr/local/bin) 是用户安装程序的标准系统位置
   • 符号链接仅指向你已安装并信任的二进制文件
   • 你可以轻松地使用 sudo rm 删除这些符号链接

   在 Windows 上（以管理员身份运行 PowerShell）：

   New-Item -ItemType SymbolicLink -Path "C:\Program Files\nodejs\node.exe" -Target (Get-Command node).Source -Force
   New-Item -ItemType SymbolicLink -Path "C:\Program Files\nodejs\npx.cmd" -Target (Get-Command npx).Source -Force
   

3. 验证设置：

   # 应该显示你选择的 Node 版本
   /usr/local/bin/node --version  # macOS/Linux
   "C:\Program Files\nodejs\node.exe" --version  # Windows
   

🤔 为什么需要这样做？

MCP 服务器通过直接调用 node 和 npx 二进制文件来启动。当你使用 Node 版本管理器时，这些二进制文件是在隔离环境中管理的，并且不会自动对系统应用程序可用。上述符号链接在你的版本管理器和 MCP 服务器使用的系统路径之间创建了一个桥梁。

🔍 故障排除

如果你经常切换 Node 版本：

• 在更改 Node 版本时记得更新你的符号链接
• 你可以创建一个 shell 别名或脚本来自动化这个过程：

  # 用于 .bashrc 或 .zshrc 的示例别名
  alias update-node-symlinks='sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx'
  

要在以后删除符号链接：

# macOS/Linux
sudo rm /usr/local/bin/node /usr/local/bin/npx

# Windows (PowerShell as Admin)
Remove-Item "C:\Program Files\nodejs\node.exe", "C:\Program Files\nodejs\npx.cmd"

💻 开发

安装依赖项：

pnpm install

在开发模式下构建和运行：

pnpm run dev

构建服务器：

pnpm run build

运行已构建的服务器：

pnpm start

调试

对于调试，你可以使用 MCP 检查器：

npx @modelcontextprotocol/inspector -e SANITY_API_TOKEN=<token> -e SANITY_PROJECT_ID=<project_id> -e SANITY_DATASET=<ds> -e MCP_USER_ROLE=developer node path/to/build/index.js

这将提供一个 Web 界面，用于检查和测试可用的工具。