SavantoAI

@savantoai/mcp-server

一个本地的 Model Context Protocol 服务，可将你的 Savanto AI 工作区提供给 Claude、ChatGPT、Cursor 以及任何兼容 MCP 的客户端使用 — 因此，你可以通过与自己的 AI 对话来配置、填充和运营商店的 AI 助手，而不必在仪表板中逐项点击。

功能

配置完成后，你的 Agent 会获得一组精选工具，它们与 Savanto REST API 相对应，涵盖完整的配置 → 观察 → 优化工作流：

类别	代表性工具	范围
工作区	list_workspaces, create_workspace, update_workspace, delete_workspace	tenant:admin
配置	get_workspace_settings, update_workspace_settings, 自定义域名 CRUD、discover_tools, generate_domain_config, validate_custom_domain, test_domain_connection, generate_color_scheme、聊天/搜索组件配置	config:admin
内容	upsert_product/upsert_post（以及 bulk_*, list_*, get_*, patch_*, delete_*）	admin:products, admin:posts
分类体系	upsert_taxonomy, bulk_upsert_taxonomies, list/get/delete_taxonomy	admin:taxonomies
提示词	upsert_prompt, list_prompts, search_prompts, delete_prompt（以及 bulk）	admin:prompts, prompts:read
Webhook	create_webhook, list/get/update/delete_webhook, test_webhook, get_webhook_stats	admin:webhooks
爬取	start_crawl, get_crawl_status/history/config, update_crawl_config	admin:posts
搜索	search_products, search_posts	search:products, search:posts
分析	get_search_analytics, get_chat_analytics, get_feedback_analytics, search_search_logs, list_feedback	tenant:admin, feedback:admin
会话线程	search_threads, get_thread, get_thread_messages, get_thread_analytics, delete_thread, bulk_delete_threads	threads:admin
聊天	chat	chat
诊断	whoami, get_tenant_usage	（无）/ tenant:admin

有两项设计确保客户端看到的工具界面安全且清晰：

• 启动时按范围控制 — 服务会探测 /tenant/whoami，只注册你的密钥实际可用的工具。Agent 永远不会看到会返回 403 的工具，而可发布的组件密钥几乎看不到任何工具。
• 带注解 — 每个工具都带有 MCP 提示（readOnlyHint、destructiveHint、idempotentHint），让客户端可以自动批准安全的读取操作，并标记具有破坏性的写入操作；此外，删除操作还需要明确设置 confirm: true。

服务还提供 Skills（MCP 提示词）——针对常见多工具工作流的分步操作手册：

• onboard-store-end-to-end – 创建工作区、导入内容、配置行为和品牌，并进行冒烟测试
• onboard-wordpress / onboard-shopify – 特定平台的引导流程
• configure-chat – 调整角色、特别说明和转接规则
• configure-custom-domain – 将自定义能力（订单跟踪、账户查询）连接到 MCP 服务 / REST API
• audit-and-improve – 观察→优化工作流：找出失败的聊天、无结果的搜索和负面反馈，并加以修复
• debug-empty-search – 诊断产品搜索为何没有返回结果
• migrate-from-competitor – 从其他聊天服务商导出的数据中批量导入

要求

• Node.js 20 或更高版本
• 一个 secret Savanto API 密钥（以 if_sk_… 开头）。请在仪表板的 API Keys 页面创建。

  可发布密钥（if_pk_…）供客户端使用，无法配置工作区 — 使用此类密钥时，服务将拒绝启动。

快速开始

无需全局安装 — 使用 npx 运行：

export SAVANTO_API_KEY=if_sk_your_key_here
npx -y @savantoai/mcp-server

指定一个非生产环境云端（暂存环境、本地开发环境）：

export SAVANTO_API_URL=http://localhost:3001

远程服务（预览）

除了上面的本地 stdio 服务，同一套工具也可以作为托管的 HTTP 服务运行，让客户端连接 URL，而不是启动 npx——无需本地安装 Node，也无需逐台机器配置。这是迈向一键“连接到 Claude/ChatGPT”（OAuth）接入的路径；目前使用你的密钥作为 Bearer 令牌进行身份验证。

# Each client authenticates per-request — there is NO server-wide key.
SAVANTO_API_URL=https://api.savanto.ai PORT=8080 npx -y -p @savantoai/mcp-server savanto-mcp-http

服务会在 /mcp 挂载 MCP 端点，并在 /healthz 提供存活探测。客户端通过 Authorization: Bearer if_sk_… 发送密钥；工具集的访问范围受该密钥所属租户限制，与 stdio 服务完全相同。将支持远程（Streamable HTTP）服务的 MCP 客户端指向 https://your-host/mcp，并提供该 Bearer 令牌。

目前的身份验证方式是直接使用密钥。未来版本会改用通过 OAuth 签发、限定租户范围的令牌，让客户无需处理密钥即可连接——替换后，传输层和工具层都不会改变。

客户端配置

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "savanto": {
      "command": "npx",
      "args": ["-y", "@savantoai/mcp-server"],
      "env": {
        "SAVANTO_API_KEY": "if_sk_your_key_here"
      }
    }
  }
}

重启 Claude Desktop。你应该会在消息栏看到一个锤子/工具图标；Savanto 工具会列在那里。

Cursor

在 Cursor 设置 → 功能 → Model Context Protocol → 添加新的 MCP 服务：

{
  "savanto": {
    "command": "npx",
    "args": ["-y", "@savantoai/mcp-server"],
    "env": { "SAVANTO_API_KEY": "if_sk_your_key_here" }
  }
}

Cline / Roo / 其他 VS Code Agent

将以下内容添加到扩展的 MCP 配置中（通常是 ~/.cline 或类似目录下的 JSON 文件）：

{
  "mcpServers": {
    "savanto": {
      "command": "npx",
      "args": ["-y", "@savantoai/mcp-server"],
      "env": { "SAVANTO_API_KEY": "if_sk_your_key_here" }
    }
  }
}

OpenAI Agents / Responses API

from openai import OpenAI
from mcp import StdioServerParameters

server = StdioServerParameters(
    command="npx",
    args=["-y", "@savantoai/mcp-server"],
    env={"SAVANTO_API_KEY": "if_sk_your_key_here"},
)

本地 MCP Inspector（用于调试）

npx @modelcontextprotocol/inspector npx @savantoai/mcp-server

Inspector 会提供一个 Web UI，让你查看工具列表、直接调用工具并监视请求/响应负载——在将服务交给 Agent 之前，用它确认密钥配置正确非常方便。

提示词示例

在 MCP 客户端中注册服务后，可以试试：

“为 acme-store 创建一个新的 Savanto 工作区，抓取 https://acme.test，设定户外探险风格，并将组件的品牌色设为 #0a7d2c。”（端到端接入）

“查看 acme-store 过去 30 天的情况——访客搜索了哪些没有结果的内容？哪些对话尚未解决？然后添加内容来解决最常见的几个问题。”（观察→改进循环）

“为 acme-store 添加订单跟踪功能，连接到我们位于 https://mcp.acme.test/orders 的 MCP 服务，验证并测试后再启用。”（自定义域名）

“为什么这段对话收到差评？”——调用 list_feedback，阅读对话内容，并提出改进方案。

Agent 会自动选择合适的工具（客户端也可以自动批准只读工具）。你也可以显式调用 Skill——例如，在 Claude Desktop 中输入 /onboard-store-end-to-end 或 /audit-and-improve，即可启动完整的操作流程。

环境变量

变量	默认值	用途
SAVANTO_API_KEY	（必需）	你的密钥 API 密钥（if_sk_…）。
SAVANTO_API_URL	https://api.savanto.ai	用于覆盖暂存环境/本地开发环境的地址。

安全性

• 始终为每个 Agent / 机器使用单独的 API 密钥，这样撤销一个密钥时不会影响其他密钥。API 密钥页面会记录每个密钥最后使用的时间戳。
• 密钥通过环境变量传递，绝不会写入日志。服务启动时会在 stderr 输出一行身份横幅，显示租户 ID 和权限范围列表，不包含任何密钥。
• 服务通过 stdio 运行，不会开放网络端口。它只会与指定的 Savanto API 主机通信。
• delete_workspace 要求在工具调用中明确提供 confirm: true 参数，以防止因幻觉而执行破坏性操作。

本地开发

在仓库根目录运行：

npm install
npm run build --workspace=@savantoai/mcp-server
SAVANTO_API_KEY=if_sk_… SAVANTO_API_URL=http://localhost:3001 node sdks/mcp/dist/stdio.js

运行测试：

npm run test --workspace=@savantoai/mcp-server

License

MIT. See LICENSE.