STARWARCLOUD STARWAR.AI
返回市场
合理性-mcp-服务器

合理性-mcp-服务器

作者：sanity-io70 星标更新：2025-10-21
安装使用来源：spider==github.com

项目介绍

Sanity MCP Server <!-- omit in toc -->

[!NOTE] 此仓库已存档且不再积极维护。 我们现在推荐使用托管服务器 mcp.sanity.io，它提供流式HTTP传输、OAuth认证、持续更新的工具以及无需本地设置即可使用的生产级可靠性。

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

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

✨ 主要特性 <!-- omit in toc -->

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

目录 <!-- omit in toc -->

🔌 快速开始

远程服务器（首选）

托管在 mcp.sanity.io 的服务器支持现代流式HTTP传输和OAuth认证。将以下配置添加到您的MCP客户端中：

{
  "mcpServers": {
    "Sanity": {
      "url": "https://mcp.sanity.io",
      "type": "http"
    }
  }
}

远程服务器的好处：

  • 流式HTTP以获得更好的性能
  • OAuth进行安全认证（无需管理令牌）
  • 自动获取最新工具和功能
  • 不需要Node.js设置

请参阅 mcp.sanity.io 获取完整的安装说明，适用于Claude Code、Cursor和其他MCP客户端。

注意： 下面的本地服务器说明仅适用于自托管。此仓库已存档且不再维护。

本地服务器前提条件

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

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

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

    cd /path/to/studio
npm update sanity
npx sanity schema deploy

    在CI环境中运行而没有Sanity登录时，您需要提供一个认证令牌：

    SANITY_AUTH_TOKEN=<token> sanity schema deploy

[!NOTE] 模式部署需要Sanity CLI版本3.88.1或更高版本。

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

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

添加配置对于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",
        "MCP_USER_ROLE": "developer"
      }
    }
  }
}

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

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

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

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

🛠️ 可用工具

上下文及设置 <!-- omit in toc -->

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

文档操作 <!-- omit in toc -->

  • create_document – 根据指令创建具有AI生成内容的新文档
  • update_document – 根据指令更新现有文档的内容
  • patch_document - 对文档的特定部分应用直接修补操作，不使用AI生成
  • transform_document – 转换文档内容同时保留格式和结构，适合文本替换和样式修正
  • translate_document – 将文档内容翻译成另一种语言同时保留格式和结构
  • query_documents – 执行GROQ查询以搜索和检索内容
  • publish_document – 发布草稿文档使其生效
  • unpublish_document – 取消发布已发布的文档（将其移回草稿）
  • version_replace_document – 替换文档版本的内容来自另一个文档
  • version_discard_document – 从发布中丢弃文档版本（将其从发布中删除）
  • version_unpublish_document – 标记文档在发布运行时取消发布
  • delete_document – 永久删除文档及其所有草稿

发布管理 <!-- omit in toc -->

  • list_releases – 列出内容发布，可选按状态过滤
  • create_release – 创建新的内容发布
  • edit_release – 更新现有发布的元数据
  • schedule_release – 安排发布在特定时间发布
  • publish_release – 立即发布发布
  • archive_release – 归档不再活跃的发布
  • unarchive_release – 恢复归档的发布
  • unschedule_release – 移除已安排的发布时间
  • delete_release – 删除发布

版本管理 <!-- omit in toc -->

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

数据集管理 <!-- omit in toc -->

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

模式信息 <!-- omit in toc -->

  • get_schema – 获取模式详情，可以是完整模式或特定类型
  • list_workspace_schemas – 获取所有可用工作区模式名称的列表

GROQ支持 <!-- omit in toc -->

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

嵌入式及语义搜索 <!-- omit in toc -->

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

项目信息 <!-- omit in toc -->

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

⚙️ 配置

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

变量描述必需
SANITY_API_TOKEN您的Sanity API令牌✅
SANITY_PROJECT_ID您的Sanity项目ID✅
SANITY_DATASET要使用的数据集✅
MCP_USER_ROLE决定工具访问级别（开发者或编辑者）✅
SANITY_API_HOSTAPI主机（默认为https://api.sanity.io）❌
MAX_TOOL_TOKEN_OUTPUT工具响应的最大令牌输出（默认为50000）。根据您的模型上下文限制进行调整。更高的限制可能会因过多数据而污染对话上下文❌

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

🔑 API令牌和权限

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

生成API令牌

从终端：

npx sanity tokens add "MCP Server" --role <role>

或者从管理：

  • 在您的工作室根目录运行 npx sanity manage
  • 在您的项目管理控制台中：设置 > API > 令牌
  • 单击“添加新令牌”
  • 为您的MCP服务器使用创建专用令牌（例如 mcp-server）
  • 安全存储令牌——它只会显示一次！

所需权限

令牌需要基于您的使用情况的适当权限

  • 对于读取操作： viewer 角色足够
  • 对于变更操作： 推荐 editor 或 developer 角色
  • 对于项目更改（如管理数据集）：可能需要 administrator 角色

数据集访问

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

安全最佳实践

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

👥 用户角色

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

  • 开发者：访问所有工具
  • 编辑者：专注于内容的工具，无项目管理

📦 Node.js环境设置

[!IMPORTANT] 对于Node版本管理器用户
如果您使用 nvm、mise、fnm、nvm-windows 或类似工具，您需要按照下面的步骤设置，以确保MCP服务器可以访问Node.js。这是一个一次性设置，可以节省您以后的故障排查时间。这是一个 正在进行的问题 与MCP服务器。

🛠 快速设置用于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 需要谨慎，但在这种情况下是安全的，因为：

    • 我们只是创建指向您已安装和信任的二进制文件的符号链接
    • 目标目录（/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）
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_API_HOST=https://api.sanity.io \
 -e SANITY_DATASET=<ds> \
 -e MCP_USER_ROLE=developer \
node build/index.js

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