Sanity MCP Server

Sanity MCP 服务器

使用 Sanity 的 AI 驱动工具，革新您的内容运营。在您喜爱的 AI 编辑器中，通过自然语言对话创建、管理和探索您的内容。

Sanity MCP 服务器实现了模型上下文协议 (MCP) ，将您的 Sanity 项目与 Claude、Cursor 和 VS Code 等 AI 工具连接起来。它使 AI 模型能够理解您的内容结构并通过自然语言指令执行操作。

✨ 主要特点

• 🤖内容智能：让 AI 探索并理解您的内容库
• 🔄内容运营：通过自然语言指令自动执行任务
• 📊 Schema-Aware ：AI 尊重您的内容结构和验证规则
• 🚀发布管理：轻松规划和组织内容发布
• 🔍语义搜索：根据含义（而不仅仅是关键字）查找内容

目录

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

🔌 快速入门

先决条件

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

1. 使用架构清单部署您的 Sanity StudioMCP 服务器需要访问您的内容结构才能有效运行。请使用以下方法之一部署您的架构清单：
   # Option A: If you have the CLI installed globally npm install -g sanity cd /path/to/studio sanity schema deploy # Option B: Update your Studio cd /path/to/studio npm update sanity npx sanity schema deploy
   在没有 Sanity 登录的 CI 环境中运行时，您需要提供一个身份验证令牌：
   SANITY_AUTH_TOKEN=<token> sanity schema deploy

   [!NOTE] 架构部署需要 Sanity CLI 版本 3.88.1 或更新版本。

2. 获取您的 API 凭证
   • 项目 ID
   • 数据集名称
   • 具有适当权限的 API 令牌

此 MCP 服务器可与任何支持模型上下文协议 (MCP) 的应用程序一起使用。以下是一些常见示例：

• 克劳德桌面
• 游标 IDE
• Visual Studio 代码
• 定制 MCP 兼容应用程序

添加 Sanity MCP 服务器的配置

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

有关所有必需和可选环境变量的完整列表，请参阅配置部分。

此配置的具体位置取决于您的应用程序：

你不明白它是怎么工作的？请参阅Node.js 配置部分。

🛠️ 可用工具

上下文和设置

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

文档操作

• create_document – 根据指令创建包含 AI 生成内容的新文档
• update_document – 根据指令使用 AI 生成的内容更新现有文档
• patch_document - 应用直接修补操作来修改文档的特定部分，而无需使用 AI 生成
• transform_document – 转换文档内容，同时保留格式和结构，非常适合文本替换和样式更正
• 翻译文档——将文档内容翻译成另一种语言，同时保留格式和结构
• query_documents – 执行 GROQ 查询来搜索和检索内容
• document_action – 执行文档操作，例如发布、取消发布或删除文档

发布管理

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

版本管理

• create_version – 为特定版本创建文档版本
• discorn_version – 从版本中删除特定版本的文档
• mark_for_unpublish – 当特定版本发布时将文档标记为未发布

数据集管理

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

架构信息

• get_schema – 获取架构详细信息，包括完整架构或特定类型架构
• list_workspace_schemas – 获取所有可用工作区模式名称的列表

GROQ 支持

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

嵌入和语义搜索

• list_embeddings_indices – 列出所有可用的嵌入索引
• semantic_search – 对嵌入索引执行语义搜索

项目信息

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

⚙️ 配置

服务器采用以下环境变量：

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

🔑 API 令牌和权限

MCP 服务器需要相应的 API 令牌和权限才能正常运行。以下是您需要了解的信息：

1. 生成机器人令牌：
   • 转到项目管理控制台：设置 > API > 令牌
   • 点击“添加新令牌”
   • 为您的 MCP 服务器使用创建专用令牌
   • 安全存储令牌 - 它只显示一次！
2. 所需权限：
   • 根据您的使用情况，令牌需要适当的权限
   • 对于基本的读取操作： viewer角色就足够了
   • 对于内容管理：建议editor或developer角色
   • 对于高级操作（如管理数据集）：可能需要administrator角色
3. 数据集访问：
   • 公共数据集：未经身份验证的用户可读内容
   • 私有数据集：需要正确的令牌认证
   • 草稿和版本化内容：只有经过身份验证且拥有适当权限的用户才能访问
4. 安全最佳实践：
   • 对不同的环境（开发、准备、生产）使用不同的令牌
   • 永远不要将令牌提交到版本控制
   • 考虑使用环境变量进行令牌管理
   • 定期轮换代币以确保安全

👥 用户角色

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

• 开发人员：访问所有工具
• 编辑器：无需项目管理的以内容为中心的工具

Node.js 环境设置

Node 版本管理器用户须知：如果您使用nvm 、 mise 、 fnm 、 nvm-windows或类似工具，则需要按照以下设置步骤操作，以确保 MCP 服务器能够访问 Node.js。此设置步骤一次性完成，可节省您后续的故障排除时间。这是 MCP 服务器的一个持续存在的问题。

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

1. 首先，激活您喜欢的 Node.js 版本：
   # Using nvm nvm use 20 # or your preferred version # Using mise mise use node@20 # Using 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

   虽然使用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. 验证设置：
   # Should show your chosen Node version /usr/local/bin/node --version # macOS/Linux "C:\Program Files\nodejs\node.exe" --version # Windows

🤔 为什么需要这个？

MCP 服务器通过直接调用node和npx二进制文件来启动。使用 Node 版本管理器时，这些二进制文件在隔离环境中进行管理，系统应用程序无法自动访问。上面的符号链接在您的版本管理器和 MCP 服务器使用的系统路径之间建立了桥梁。

🔍 故障排除

如果你经常切换 Node 版本：

• 更改 Node 版本时记得更新符号链接
• 您可以创建一个 shell 别名或脚本来自动执行此操作：
  # Example alias for your .bashrc or .zshrc alias update-node-symlinks='sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx'

稍后删除符号链接：

💻 开发

安装依赖项：

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

构建服务器：

运行构建好的服务器：

调试

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

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