Sanity

Sanity Agent Toolkit

为 AI Agent 提供资源，助其更好地使用 Sanity 构建。支持 Cursor、Claude Code、Codex、VS Code、Lovable、v0、Replit、OpenCode，以及任何兼容 MCP 或 Agent Skills 的编辑器或 Agent。

功能

• MCP 服务： 直接访问 Sanity 项目（内容、数据集、发布、架构）和 Agent 规则。
• Agent 技能： 提供全面的最佳实践技能，涵盖 Sanity 开发、内容建模、SEO/AEO 和实验。包含 25 个集成／主题指南和 26 条针对性最佳实践规则。
• Agent 插件： 为任何兼容 Agent Plugins 的客户端提供 plugin.json、skills/ 和 mcp.json 组件。
• Claude Code 插件： 为 Claude Code 用户提供 MCP 服务、Agent 技能和斜杠命令。可在 Anthropic 官方插件市场获取。
• Cursor 插件： 在 Cursor Marketplace 提供 MCP 服务、Agent 技能和命令。
• Codex 插件： 为 OpenAI Codex 用户提供 MCP 服务和 Agent 技能。

开始使用

根据你希望 Agent 如何与 Sanity 协作，选择相应方式：

1. MCP 服务 — 让 Agent 随时获取最新规则，并全面访问 Sanity 项目。无需维护本地文件。适用于 Cursor、VS Code、Claude Code、Lovable、v0、Replit、OpenCode 和其他兼容 MCP 的客户端。
2. Agent 技能 — 安装涵盖 Sanity、内容建模、SEO/AEO 和实验的最佳实践技能。适用于 Cursor、Claude Code 和任何兼容 Agent Skills 的 Agent。
3. 插件 — 为 Cursor、Claude Code 或任何兼容 Agent Plugins 的客户端安装 Sanity 插件。整合 MCP 服务、Agent 技能和命令。
4. 手动安装 — 在本地复制技能参考文件，以供离线使用。你需要自行更新这些文件。

选项 1：安装 MCP 服务（推荐）

通过 MCP 服务，让 Agent 直接访问 Sanity 项目和始终保持最新的 Agent 规则。

通过 Sanity CLI 快速安装

在终端中运行，自动检测并为 Cursor、Claude Code 和 VS Code 配置 MCP：

npx sanity@latest mcp configure

使用你已登录的 CLI 用户进行身份验证，无需手动配置令牌或 OAuth。

客户端专属说明

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

claude mcp add Sanity -t http https://mcp.sanity.io --scope user

codex mcp add Sanity --url https://mcp.sanity.io

[mcp_servers.Sanity]
url = "https://mcp.sanity.io"

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

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sanity": {
      "type": "remote",
      "url": "https://mcp.sanity.io",
      "oauth": {}
    }
  }
}

{
  "mcpServers": {
    "Sanity": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.sanity.io", "--transport", "http-only"]
    }
  }
}

授权与故障排除

手动配置 MCP 默认使用 OAuth。你也可以在 MCP 配置中设置 Authorization: Bearer <token> 标头，改用令牌身份验证。如果通过 CLI 设置后身份验证失败，请重新运行 npx sanity@latest mcp configure 并重启 MCP 客户端。若遇到 OAuth 重置问题，Cursor 提供 Cursor: Clear All MCP Tokens，VS Code 提供 Authentication: Remove Dynamic Authentication Providers。

有关授权选项和故障排除，请参阅 Sanity MCP 文档。

选项 2：安装 Agent Skills

安装适用于任何兼容 Agent Skills 的 Agent 的最佳实践技能。

npx skills add sanity-io/agent-toolkit

插件安装方法请参阅选项 3。

选项 3：安装插件

安装 Sanity 插件，以获取 MCP 服务、Agent 技能和命令。 可从 Claude Code marketplace、Cursor Marketplace 获取，也可从此仓库以 Agent Plugin 的形式安装。

Claude Code

Sanity 插件已列入 Anthropic 官方插件市场。启动 Claude Code 时，官方市场（claude-plugins-official）会预先注册；你无需添加自定义市场。

在 Claude Code 中安装：

/plugin install sanity@claude-plugins-official

如果找不到插件，请刷新市场目录并重试：

/plugin marketplace update claude-plugins-official

然后运行 /reload-plugins，即可激活插件，无需重启。

替代方式：交互式安装

1. 运行 /plugin 并打开 Discover 选项卡
2. 搜索 Sanity
3. 确认前，查看插件将安装的内容——命令、技能、钩子和 MCP 服务（Anthropic 建议在安装前检查插件权限和来源）
4. 选择安装范围：
   • User（默认）：此计算机上的所有项目
   • Project：通过 .claude/settings.json 与协作者共享
   • Local：仅此代码仓库
5. 运行 /reload-plugins，即可激活插件，无需重启

**验证安装：**询问 Claude Code：“你可以使用哪些技能？”

你应该会看到列出的 Sanity 技能。

**开始使用：**用自然语言提问，技能会自动激活：

帮我在 Sanity 中创建一个博客文章架构

检查我的 GROQ 查询和 Next.js Visual Editing 设置

或者运行 /sanity，探索所有功能。

Cursor

在 Cursor 聊天中运行以下命令，从 Cursor Marketplace 安装：

/add-plugin sanity

**验证安装：**询问 Cursor：“你可以使用哪些技能？”

你应该会看到列出的 Sanity 技能。

**开始使用：**用自然语言提问，技能会自动激活：

帮我在 Sanity 中创建一个博客文章架构

检查我的 GROQ 查询和 Next.js Visual Editing 设置

Codex

1. 添加 Sanity 市场：

codex plugin marketplace add sanity-io/agent-toolkit

2. 从 Codex 的插件目录安装插件（选择 Sanity Agent Toolkit 市场，然后安装 Sanity）。

3. 重启 Codex。询问“你可以使用哪些技能？”进行验证——你应该会看到列出的 Sanity 技能。

选项 4：手动安装

在本地安装技能参考资料，让编辑器了解 Sanity 最佳实践：

1. 将 skills/sanity-best-practices/ 复制到你的项目中。
2. （推荐）将 AGENTS.md 复制到项目根目录，作为知识路由器。

功能

MCP 工具

连接 MCP 后，你的 AI 可以使用以下工具：

• query_documents — 直接运行 GROQ 查询
• create_documents — 根据结构化内容创建草稿文档，或在提供发布 ID 时创建文档版本
• patch_documents — 对现有文档进行精准编辑；已发布的文档通过创建或更新草稿来编辑
• publish_documents / unpublish_documents — 管理文档生命周期
• deploy_schema / get_schema — 部署由 MCP 管理的架构并检查已部署的架构
• deploy_studio — 部署绑定到 MCP 管理架构的托管 Studio
• create_release / list_releases — 创建和查看内容发布
• create_version — 为发布创建版本文档
• generate_image / transform_image — AI 图像生成和编辑
• whoami — 验证已认证的 Sanity 用户
• get_project_studios — 列出关联到某个项目的 Studio 应用
• search_docs / read_docs — 搜索和阅读 Sanity 文档
• list_sanity_rules / get_sanity_rules — 按需加载 Agent 规则
• give_feedback — 报告 MCP 工具错误、缺少的功能、令人困惑的输出或文档问题

MCP 管理的架构优先于由 Studio 部署的架构和旧版架构解析。如果使用 deploy_schema 部署架构更改，请使用 deploy_studio 重新部署所有匹配的 MCP 管理 Studio，以便其采用最新架构。generate_image、transform_image，以及带有 instruction 的 create_version 会消耗 Sanity AI 点数。

请参阅可用工具完整列表。

Agent 技能

Claude Code、Cursor、GitHub Copilot 等 Agent 可自动发现和使用的最佳实践技能。技能遵循 Agent Skills 格式。安装方法请参阅选项 2。

入门流程

入门指南分为三个阶段：

1. Studio 与架构 — 设置 Sanity Studio 并定义内容模型
2. 内容 — 导入现有内容，或通过 MCP 生成占位内容
3. 前端 — 集成到应用中（因框架而异）

只需说：“开始使用 Sanity”，即可开始。

斜杠命令（Claude Code）

仓库结构

注意： skills/sanity-best-practices/references/ 中的参考文件是 Sanity MCP 服务 list_sanity_rules / get_sanity_rules 工具的权威内容。每个文件都必须包含有效的 name 和 description frontmatter — 规则名称由文件名派生（例如，nextjs.md → nextjs）。

sanity-io/agent-toolkit/
├── AGENTS.md                      # Knowledge router & agent behavior
├── README.md                      # This file
├── plugin.json                    # Portable Agent Plugins v1 manifest
├── mcp.json                       # Portable Agent Plugins v1 MCP configuration
├── .agents/plugins/               # Codex marketplace
│   └── marketplace.json           # Codex marketplace metadata
├── .claude-plugin/                # Claude Code plugin configuration (distributed via claude-plugins-official)
│   ├── plugin.json                # Plugin manifest (name: sanity)
│   └── marketplace.json           # Marketplace manifest for repo-based discovery
├── .codex-plugin/                 # Codex plugin configuration
│   └── plugin.json                # Codex plugin manifest
├── .cursor-plugin/                # Cursor plugin configuration (distributed via cursor.com/marketplace)
│   ├── marketplace.json           # Cursor marketplace metadata
│   └── plugin.json                # Per-plugin manifest
├── .mcp.json                      # Legacy client MCP compatibility configuration
├── assets/                        # Plugin branding
│   └── logo.svg                   # Sanity logo for marketplace display
├── commands/                      # Agent commands
│   ├── sanity.md                  # /sanity help
│   ├── sanity-review.md           # /sanity-review
│   ├── typegen.md                 # /typegen
│   └── deploy-schema.md           # /deploy-schema
├── scripts/                       # Validation and CI scripts
│   ├── validate-agent-plugin.mjs  # Validate manifests against the v1 JSON Schemas
│   └── validate-cursor-plugin.mjs # Cursor plugin validator
└── skills/                        # Agent skills (agentskills.io format)
    ├── sanity-best-practices/     # Comprehensive Sanity skill
    │   ├── SKILL.md               # Skill definition and quick reference
    │   └── references/            # Canonical content (25 guides)
    │       ├── get-started.md     # Onboarding guide
    │       ├── nextjs.md          # Next.js integration
    │       ├── groq.md            # GROQ patterns & performance
    │       ├── schema.md          # Schema design & validation
    │       └── ...                # See SKILL.md for full index
    ├── content-modeling-best-practices/      # Modeling guidance + topic references
    ├── seo-aeo-best-practices/               # SEO/AEO guidance + topic references
    ├── content-experimentation-best-practices/ # Experiment design + stats references
    ├── sanity-singletons/                    # First-class singleton documents (Studio 6.17+)
    └── sanity-form-component-suspense/       # Suspense boundaries for custom form components

所有技能都使用 references/ 存放按需加载的详细内容。sanity-best-practices 的参考文件也是 MCP 服务中 Sanity 规则的权威来源。

资源

• 创建 Sanity 账户
• Sanity 文档
• GROQ 语言参考
• 可视化编辑指南
• Sanity TypeGen
• MCP 服务文档
• Agent Plugins 规范
• Blueprints 基础设施即代码

贡献

发现了更好的模式？缺少某个框架或最佳实践？阅读贡献指南，了解技能的工作方式以及如何做出优质贡献，然后：

1. Fork 仓库。
2. 使用 npm install 安装依赖项。
3. 在 skills/<skill-name>/ 中进行更改。
4. 运行 npm run validate:all，检查技能和插件是否有效。
5. 提交 PR。

支持

• Sanity 社区（Discord）
• GitHub 问题

许可证： MIT