Squarespace MCP服务器
Squarespace的综合模型上下文协议（MCP）服务器，可与Squarespace平台完全集成，用于网站管理、电子商务运营、内容创建和分析。
概述
此MCP服务器使AI助手能够通过一组丰富的 67工具 涵盖所有主要平台功能。它采用TypeScript和官方MCP SDK构建，通过OAuth2身份验证、自动令牌刷新、分页、错误处理和重试逻辑，为Squarespace的v1.0 API提供类型安全、可靠的访问。
特性
🛍️ 完整的API覆盖范围（67个工具）
商务-订单（8个工具）
- 按日期范围、状态、电子邮件列出、搜索和过滤订单
- 获取包含行项目和履行情况的详细订单信息
- 创建订单（用于从外部来源导入）
- 使用可选的发货通知和跟踪功能完成订单
- 在订单中添加内部注释
- 获取待处理订单和最近订单
商业-产品（10个工具）
- 列出所有带页码的产品
- 获取包含变体和图像的详细产品信息
- 创建具有变体的新产品
- 更新产品（名称、描述、定价、搜索引擎优化）
- 删除产品
- 创建、更新和删除产品变体
- 按名称或标签搜索产品
- 按标签筛选产品
商业-库存（5个工具）
- 获取变体的库存水平
- 更新库存数量
- 按相对金额调整库存
- 检查低库存商品（可配置阈值）
- 列出缺货商品
商务-交易（3个工具）
- 获取订单的所有交易记录
- 处理退款
- 获取交易摘要（已付款总额、退款总额、净额）
配置文件（7个工具）
- 列出所有个人资料（客户、订阅者、捐赠者）
- 获取详细的个人资料信息
- 列出有购买历史的客户
- 列出邮件列表订阅者
- 捐助者名单
- 通过电子邮件搜索个人资料
- 通过终身价值获得顶级客户
Webhooks（7个工具）
- 列出所有webhook订阅
- 获取webhook详细信息
- 为事件创建新的Webhook（order.Create、investory.update等）
- 更新webhook配置
- 删除webhooks
- 发送测试通知
- 旋转webhook机密以确保安全
页面和网站（8个工具）
- 获取网站信息
- 列出并获取收藏
- 列出、获取、创建、更新和删除页面
- 管理页面SEO设置
表格（5个工具）
- 列出所有表单
- 通过字段获取表单详细信息
- 列出带有过滤功能的表单提交
- 获取具体的提交详细信息
- 将表单提交导出为CSV
博客（9个工具）
- 列出所有博客收藏
- 获取博客详细信息
- 按页码列出博客文章
- 获取特定博客文章
- 创建新博客文章
- 更新博客文章
- 删除博客文章
- 发布和取消发布帖子
分析（5个工具）
- 获取收入指标（总收入、订单数、AOV）
- 按收入获得最畅销的产品
- 获取每日销售明细
- 获取月度收入汇总
- 获取年度收入摘要
🎨 15个React MCP应用程序（深色主题）
所有应用程序都是基于Vite的独立React应用程序，主题为深色：
- 订单仪表板 -订单管理和履行
- 产品经理 -产品目录管理
- 库存跟踪 -实时库存监控
- 客户档案 -客户LTV和历史
- 分析仪表板 -收入和销售见解
- 博客编辑器 -博客帖子管理
- 表单查看器 -表单提交和导出
- Webhook管理器 -Webhook配置和测试
- 页面管理 -网站页面管理
- 批量编辑器 -批量产品更新
- SEO优化 -SEO设置和优化
- 报告 -生成并下载报告
- 运输经理 -履行跟踪
- 折扣经理 -折扣码管理
- 设置 -服务器和API配置
🔒 企业级功能
- OAuth2身份验证 -使用刷新令牌完全支持OAuth2
- 自动令牌刷新 -到期前无缝续订代币
- 重试逻辑 -针对速率限制和错误的指数回退自动重试
- 分页支持 -高效处理大型数据集
- 错误处理 -包含详细信息的全面错误消息
- 类型安全 -所有API实体的完整TypeScript类型
- 费率限制管理 -内置速率限制处理
安装
npm install @mcpengine/squarespace-server或者从源代码安装：
cd servers/squarespace
npm install
npm run build配置
环境变量
服务器至少需要Squarespace访问令牌：
export SQUARESPACE_ACCESS_TOKEN="your_access_token_here"对于具有自动令牌刷新功能的长期访问：
export SQUARESPACE_ACCESS_TOKEN="your_access_token"
export SQUARESPACE_REFRESH_TOKEN="your_refresh_token"
export SQUARESPACE_CLIENT_ID="your_client_id"
export SQUARESPACE_CLIENT_SECRET="your_client_secret"MCP配置
添加到MCP设置文件(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"mcpServers": {
"squarespace": {
"command": "squarespace-mcp",
"env": {
"SQUARESPACE_ACCESS_TOKEN": "your_access_token",
"SQUARESPACE_REFRESH_TOKEN": "your_refresh_token",
"SQUARESPACE_CLIENT_ID": "your_client_id",
"SQUARESPACE_CLIENT_SECRET": "your_client_secret"
}
}
}
}获取Squarespace API凭据
1.注册您的OAuth应用程序
向Squarespace提交请求以注册您的OAuth应用程序：
- Squarespace开发者门户
- 提供：应用程序名称、图标、重定向URI、术语和隐私链接
您将收到：
client_idclient_secret
2.OAuth流程
实现OAuth2授权代码流：
- 授权URL:
https://login.squarespace.com/api/1/login/oauth/provider/authorize?
client_id=YOUR_CLIENT_ID&
redirect_uri=YOUR_REDIRECT_URI&
scope=website.orders,website.products,website.inventory&
state=RANDOM_STATE&
access_type=offline- 代币兑换：
curl -X POST https://login.squarespace.com/api/1/login/oauth/provider/tokens \
-H "Authorization: Basic BASE64(client_id:client_secret)" \
-H "Content-Type: application/json" \
-d '{
"grant_type": "authorization_code",
"code": "AUTHORIZATION_CODE",
"redirect_uri": "YOUR_REDIRECT_URI"
}'API范围
请求这些范围以实现完整功能：
website.orders-读取和管理订单website.orders.read-只读订单访问website.products-管理产品website.products.read-只读产品访问website.inventory-管理库存website.inventory.read-只读库存访问website.transactions.read-读取交易数据
使用示例
列出最近的订单
{
"name": "squarespace_list_orders",
"arguments": {
"modifiedAfter": "2024-01-01T00:00:00Z",
"fulfillmentStatus": "PENDING"
}
}创建产品
{
"name": "squarespace_create_product",
"arguments": {
"product": {
"type": "PHYSICAL",
"storePageId": "store_page_id",
"name": "New Product",
"description": "Product description",
"variants": [{
"sku": "SKU-001",
"pricing": {
"basePrice": {
"value": "29.99",
"currency": "USD"
}
},
"stock": {
"quantity": 100,
"unlimited": false
}
}]
}
}
}完成订单
{
"name": "squarespace_fulfill_order",
"arguments": {
"orderId": "order_id_here",
"shouldSendNotification": true,
"shipments": [{
"carrierName": "USPS",
"trackingNumber": "1234567890",
"trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=1234567890"
}]
}
}获取收入分析
{
"name": "squarespace_get_revenue_metrics",
"arguments": {
"startDate": "2024-01-01T00:00:00Z",
"endDate": "2024-01-31T23:59:59Z"
}
}检查低库存商品
{
"name": "squarespace_check_low_stock",
"arguments": {
"threshold": 10
}
}建筑
squarespace/
├── src/
│ ├── clients/
│ │ └── squarespace.ts # API client with auth & retry logic
│ ├── types/
│ │ └── index.ts # Complete TypeScript types
│ ├── tools/
│ │ ├── commerce-orders.ts # Order management tools
│ │ ├── commerce-products.ts # Product management tools
│ │ ├── commerce-inventory.ts# Inventory management tools
│ │ ├── commerce-transactions.ts # Transaction tools
│ │ ├── profiles.ts # Customer/subscriber tools
│ │ ├── webhooks.ts # Webhook management tools
│ │ ├── pages.ts # Page management tools
│ │ ├── forms.ts # Form submission tools
│ │ ├── blog.ts # Blog management tools
│ │ └── analytics.ts # Analytics tools
│ ├── ui/
│ │ └── react-app/ # 15 React MCP apps
│ ├── server.ts # MCP server implementation
│ └── main.ts # Entry point
├── package.json
├── tsconfig.json
└── README.mdAPI 参考
完整文档： Squarespace开发人员文档
速率限制
Squarespace对每个端点实施不同的速率限制，冷却时间为1分钟。客户端通过重试逻辑自动处理速率限制。
网络钩子
订阅实时事件：
order.create-已创建新订单order.update-订单已更新transaction.create-新交易transaction.update-交易已更新inventory.update-库存已更改product.create-产品创建product.update-产品更新product.delete-产品已删除
发展
构建
npm run build类型检查
npm run type-check发展模式
npm run dev故障排除
身份验证错误
- 401未经授权：令牌过期或无效-刷新令牌
- 403禁止：作用域不足-请求其他权限
- 令牌刷新失败：验证客户端凭据是否正确
速率限制
- 429请求太多：内置重试会自动处理此问题
- 在批量操作之间实施延迟，以获得最佳性能
常见问题
- 缺少环境变量：确保
SQUARESPACE_ACCESS_TOKEN已设置 - TypeScript错误：运行
npm run type-check诊断 - 模组分辨率：验证
package.json有"type": "module"
贡献
欢迎投稿！拜托：
- 遵循现有代码结构
- 为新工具添加测试
- 更新文档
- 提交前运行类型检查
许可证
MIT许可证-有关详细信息，请参阅许可证文件
支持
更新日志
v1.0.0（2024-02-12）
- 初始版本
- 67个工具，涵盖Squarespace的所有主要功能
- 15款深色主题的React MCP应用
- 具有自动刷新功能的OAuth2身份验证
- 全面的错误处理和重试逻辑
- 完全支持TypeScript