优化利内容管理系统MCP

Name: 优化利内容管理系统MCP
Author: first3things

作者：first3things4 星标更新：2025-10-13

安装使用来源：spider==github.com

项目介绍

技术文档摘要

Optimizely MCP Server

Optimizely CMS 的 Model Context Protocol (MCP) 服务器，为AI助手提供对Optimizely的GraphQL API和内容管理API的全面访问。

版本

当前版本: 2.0.0-beta 状态: 测试版 / 预发布

这是一个正在积极开发的版本，并且尚未成为候选发布版本。功能可能会发生变化，在生产使用前需要进行额外测试。

功能

核心能力

发现优先架构: 对内容类型或字段没有任何硬编码假设
动态模式内省: 运行时发现可用的内容类型和字段
统一内容检索: 通过一个调用获取任何内容（URL、键、GUID或搜索词）
视觉构建器支持: 完整支持具有组合结构的Optimizely视觉构建器页面
内容管理: 通过交互式向导创建和管理内容
智能字段映射: 基于模式的字段匹配并带有置信评分
GraphQL & CMA集成: 直接访问Graph API（读取）和内容管理API（写入）
智能缓存: 内置缓存以提高性能
类型安全: 全面支持TypeScript并带有运行时验证

API支持

Graph API: 快速内容检索、搜索和发现
内容管理API: 内容创建、更新和草稿访问
双重认证: 支持Graph（单个密钥、HMAC）和CMA（OAuth2）认证

安装

# 克隆仓库
git clone https://github.com/your-org/optimizely-mcp-server.git
cd optimizely-mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

配置

在项目根目录创建一个.env文件：

# 服务器配置
SERVER_NAME=optimizely-mcp-server
SERVER_VERSION=1.0.0
TRANSPORT=stdio

# Optimizely Graph配置
GRAPH_ENDPOINT=https://cg.optimizely.com/content/v2
GRAPH_AUTH_METHOD=single_key # 选项：single_key, hmac, basic, bearer, oidc
GRAPH_SINGLE_KEY=your-single-key
# 对于HMAC认证：
# GRAPH_APP_KEY=your-app-key
# GRAPH_SECRET_KEY=your-secret-key

# 内容管理API配置
CMA_BASE_URL=https://api.cms.optimizely.com/preview3
CMA_CLIENT_ID=your-client-id  # 在CMS中从设置 > API密钥获取
CMA_CLIENT_SECRET=your-client-secret
CMA_GRANT_TYPE=client_credentials
CMA_TOKEN_ENDPOINT=https://api.cms.optimizely.com/oauth/token
CMA_IMPERSONATE_USER=  # 可选：要模拟的用户邮箱（参见模拟部分）

# 可选配置
CACHE_TTL=300000 # 缓存TTL（毫秒，默认：5分钟）
LOG_LEVEL=info # 选项：debug, info, warn, error
MAX_RETRIES=3
TIMEOUT=30000

运行服务器

开发模式

# 使用热重载运行
npm run dev

# 使用调试日志运行
LOG_LEVEL=debug npm run dev

生产模式

# 构建并运行
npm run build
npm start

# 或直接运行
node dist/index.js

测试服务器

# 运行所有单元测试
npm test

# 运行带覆盖率的测试
npm run test:coverage

# 类型检查
npm run typecheck

# 代码检查
npm run lint

MCP服务器如何工作

MCP服务器通过**标准输入输出（stdio）**通信，而不是HTTP端口：

不需要端口 - 服务器不监听任何网络端口
基于进程 - Claude Desktop 将您的服务器作为子进程启动
JSON-RPC消息 - 通过stdin/stdout管道进行通信
安全 - 没有网络暴露，仅在Claude需要时运行

MCP客户端配置

Claude Desktop 设置

第一步：找到您的配置文件

在文本编辑器中打开配置文件：

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

对于Windows，您可以快速打开它：

notepad %APPDATA%\Claude\claude_desktop_config.json

第二步：添加服务器配置

{
  "mcpServers": {
    "optimizely": {
      "command": "node",
      "args": ["%USERPROFILE%\\path\\to\\optimizely-mcp-server\\dist\\index.js"],
      "env": {
        "LOG_LEVEL": "error",
        "GRAPH_ENDPOINT": "https://cg.optimizely.com/content/v2",
        "GRAPH_AUTH_METHOD": "single_key",
        "GRAPH_SINGLE_KEY": "your-key",
        "CMA_BASE_URL": "https://api.cms.optimizely.com/preview3/experimental",
        "CMA_CLIENT_ID": "your-client-id",
        "CMA_CLIENT_SECRET": "your-client-secret",
        "CMA_GRANT_TYPE": "client_credentials",
        "CMA_TOKEN_ENDPOINT": "https://api.cms.optimizely.com/oauth/token",
        "CMA_IMPERSONATE_USER": ""
      }
    }
  }
}

在Windows的JSON中，必须使用双反斜杠（\）。如果文件夹路径中有空格，这仍然有效，因为每个参数都是单独的JSON字符串。

Windows: %USERPROFILE% 扩展到您的主目录（例如，C:\Users\Alice）。如果Claude没有自动扩展它，请替换为您实际的路径（例如，C:\Users\Alice\path\to\optimizely-mcp-server\dist\index.js）。在PowerShell中，等效的是$env:USERPROFILE，但在这个JSON配置中应保留%USERPROFILE%或使用完整路径。
macOS/Linux: 等效快捷方式是~~或$HOME（例如，/Users/alice或/home/alice）。如果~~/$HOME没有正确展开，请替换为完整路径。

第三步：重启Claude Desktop

保存配置文件后：

完全退出Claude Desktop（不仅仅是关闭窗口）
再次启动Claude Desktop
Optimizely工具现在应该可用

第四步：验证是否正常工作

在一个新的Claude对话中尝试：

"你能列出可用的Optimizely工具吗？"
"使用健康检查工具来测试连接"

故障排除

如果服务器无法加载：

检查文件路径是否正确并且使用了适当的转义符（Windows上为\\）
确保您已经构建了项目（npm run build）
验证dist/index.js文件是否存在
检查Claude的日志是否有错误

其他MCP客户端

对于其他兼容MCP的客户端，使用stdio传输配置：

{
  "name": "optimizely",
  "transport": {
    "type": "stdio",
    "command": "node",
    "args": ["/path/to/optimizely-mcp-server/dist/index.js"]
  },
  "env": {
    // 如上所示的环境变量
  }
}

可用工具（总计14个）

🌟 核心发现与检索工具

这些工具使用Graph API动态发现您的CMS结构并检索内容，而无需硬编码假设。

help - 🚀 从这里开始！获取上下文感知的帮助并学习发现优先的工作流程
- 示例：help({})，help({"topic": "workflow"})
get - 🎯 统一工具 - 通过任何标识符在一次调用中获取内容
- 替代旧的search → locate → retrieve工作流程
- 自动发现字段并返回完整内容
- ✅ 支持具有完整组合结构的视觉构建器页面
- 示例：get({"identifier": "/"})，get({"identifier": "Article 4"})
discover - 动态查找内容类型和字段
- 不对您的CMS结构做出任何硬编码假设
- 示例：discover({"target": "types"})，discover({"target": "fields", "contentType": "ArticlePage"})
analyze - 内容类型的深度分析
- 了解字段、约束和默认值
- 示例：analyze({"contentType": "ArticlePage"})
search - 智能内容搜索，带有自动发现
- ⚠️ 注意：大多数情况下get更好
- 示例：search({"query": "mcp", "contentTypes": ["ArticlePage"]})
locate - 通过ID、键或路径查找特定内容
- ⚠️ 注意：大多数情况下get更好
- 示例：locate({"identifier": "/news/article-1"})
retrieve - 从内容管理API获取完整内容
- ⚠️ 注意：大多数情况下get更好（使用更快的Graph API）
- 仅当get建议这样做或您需要CMA特定数据时使用
- 示例：retrieve({"identifier": "12345"})

🔧 实用工具（3个）

health-check - 检查API连接性和服务器健康状况
get-config - 获取当前服务器配置（已清理）
get-documentation - 按类别获取可用工具的文档

🔧 内容管理工具（CMA API）

这些工具使用内容管理API进行写操作和详细内容访问：

content_creation_wizard - 带有发现功能的交互式内容创建
- 创建新内容必不可少
- 示例：content_creation_wizard({"step": "start"})
content-test-api - 测试CMA连接和端点
- 验证身份验证和权限
- 示例：content-test-api({})

注意：retrieve工具（在核心工具中列出）也使用CMA来访问草稿内容和版本历史。

⚠️ 已弃用的工具（即将移除）

这些Graph API发现工具是新discover工具的重复项，并将在未来版本中被移除：

graph-introspection - 使用discover代替
type-discover - 使用discover({"target": "types"})代替
type-match - 使用discover代替
content_type_analyzer - 使用analyze代替
graph_discover_types - 使用discover({"target": "types"})代替
graph_discover_fields - 使用discover({"target": "fields"})代替
graph-query - 使用get或search代替

关键架构原则

发现优先设计

与传统集成硬编码内容类型和字段名称不同，此MCP服务器：

从不硬编码内容类型 - 不对“ArticlePage”、“StandardPage”等做出假设
从不硬编码字段映射 - 没有预定义路径如“SeoSettings.MetaTitle”
动态发现一切 - 使用内省来理解您的CMS
适应任何CMS配置 - 适用于自定义内容类型和字段

智能字段映射

服务器使用模式匹配和相似性评分来：

将用户友好的字段名称映射到实际CMS字段
自动处理嵌套属性
根据字段类型生成适当的默认值
提供映射的置信评分

视觉构建器支持

get工具完全支持Optimizely视觉构建器（以前称为视觉体验作曲家）页面：

功能

✅ 自动检测 - 通过接口（_IExperience）识别视觉构建器页面
✅ 完整的组合检索 - 单次调用返回完整结构
✅ 嵌套结构 - 处理网格、行、列和组件
✅ 组件内容 - 直接在组合中包含内联组件数据
✅ 递归深度 - 支持任意级别的嵌套

理解组件类型

视觉构建器组件有两种类型：

1. 内联组件（嵌入内容）

键：null或不存在
内容位置：直接存储在组合结构中
访问：内容已经在get响应中
示例：带有内容“欢迎来到我们的网站”的文本组件

{
  "component": {
    "_metadata": {
      "types": ["Text", "_Component"],
      "key": null  // ← NULL = 内联
    },
    "Content": "欢迎文字"  // ← 内容在这里
  }
}

重要：不要尝试单独检索内联组件 - 内容已经提供！

2. 引用组件（独立内容项）

键：有效的GUID（例如，“f7e7f5c9-1e77-4884-a8fc-a9c9ae56560c”）
内容位置：作为独立内容项存储在CMS中
访问：使用get({"identifier": "component-key"})检索完整详情
示例：共享组件如站点设置、可复用块

{
  "component": {
    "_metadata": {
      "types": ["ArticleList", "_Component"],
      "key": "f7e7f5c91e774884a8fca9c9ae56560c"  // ← 有键
    }
    // 可能包括基本字段，使用get()获取完整内容
  }
}

最佳实践

当处理视觉构建器页面时：

首先，使用get({"identifier": "/"})检索页面
检查组合结构中的组件
对于内联组件（无键）：内容已经在响应中 ✅
对于引用组件（有键）：使用get({"identifier": "key"})检索完整详情

示例用法

// 获取一个视觉构建器首页
get({"identifier": "/"})

// 返回包含内联内容的完整结构：
{
  "content": {
    "_metadata": { ... },
    "composition": {
      "nodes": [
        {
          "key": "grid-id",
          "displayName": "欢迎部分",
          "nodes": [
            {
              "component": {
                "_metadata": {
                  "types": ["Text"],
                  "key": null  // 内联 - 内容包含
                },
                "Content": "欢迎来到我们的网站"
              }
            },
            {
              "component": {
                "_metadata": {
                  "types": ["ArticleList"],
                  "key": "f7e7f5c9..."  // 引用 - 分别获取
                }
              }
            }
          ]
        }
      ]
    }
  }
}

已知限制

性能 - 由于嵌套结构，大型组合可能需要更长时间才能检索
引用组件详情 - 只有基础元数据；完整内容需要单独的get()调用
显示设置 - 当前实现未包含（如有需要可以添加）

重要说明

内容索引延迟

使用content_creation_wizard或其他创建工具创建新内容后：

CMA立即可用：内容可以通过retrieve工具立即访问
Graph API索引延迟：内容可能需要1-5分钟才能出现在Graph API结果中
工具行为：get和search工具使用Graph API，对于新创建的内容直到索引完成之前会返回“未找到”

最佳实践：创建内容后，等待几分钟再尝试使用get或search检索。或者，使用直接查询CMA的retrieve工具，它没有索引延迟。

草稿与发布内容

Graph API：仅返回已发布内容
CMA API：返回草稿和已发布内容
新内容：默认创建为草稿状态
若要使内容可通过get/search搜索，必须先将其发布

开发

项目结构

optimizely-mcp-server/
├── src/
│   ├── index.ts          # 服务器入口点
│   ├── register.ts       # 工具注册
│   ├── config.ts         # 配置管理
│   ├── clients/          # API客户端
│   │   ├── graph-client.ts
│   │   └── cma-client.ts
│   ├── logic/            # 工具实现
│   │   ├── utility/
│   │   ├── graph/
│   │   └── content/
│