SFCC MCP Server

用于与Salesforce Commerce Cloud (SFCC) API交互的模型上下文协议(MCP)服务器。

特性

• 基于endpoints.json配置动态注册端点
• 自动处理路径和查询参数
• 支持GET和POST请求
• 使用客户端凭证流进行OCAPI认证
• 支持SFCC数据API端点，包括产品搜索
• 远程模式：基于HTTP的服务器，带有OAuth认证
• 会话配置：每个会话可以使用不同的SFCC凭证和API端点
• 多租户支持：多个客户端可以同时连接到不同的SFCC实例
• 自动化部署：通过GitHub Actions集成到Google App Engine的部署
• 版本管理：自动化的版本控制和部署工作流程

安装

# 安装依赖
npm install

# 构建服务器
npm run build

配置

在项目根目录创建一个.env文件，并包含以下变量：

# SFCC API配置
SFCC_API_BASE=https://your-instance.api.commercecloud.salesforce.com/

# 管理API凭证（客户端凭证流）
SFCC_ADMIN_CLIENT_ID=your_admin_client_id
SFCC_ADMIN_CLIENT_SECRET=your_admin_client_secret

OCAPI配置

要使用SFCC数据API，您需要在SFCC中配置具有适当权限的API客户端：

API客户端

1. 在SFCC账户管理器中，转到API客户端
2. 创建一个新的API客户端或编辑现有的API客户端
3. 配置OAuth设置：
   • OAuth客户端ID：(您的客户端ID)
   • OAuth客户端密钥：(您的客户端密钥)
   • 默认范围：包括所需端点所需的范围
   • 令牌端点认证方法：client_secret_post
4. 配置API客户端角色：
   • 分配适当的访问所需数据的角色

商务经理

1. 在SFCC商务经理中，转到管理 > 站点开发 > 开放商业API设置
2. 查看ocapi-bm-config.json以获取配置示例

VSCode中的MCP配置

1. 打开命令面板 (Ctrl/Cmd + Shift + P)
2. 输入"MCP"并选择MCP: 添加服务器...
3. 选择命令（stdio）手动安装
4. 输入node <full-path-to-your>/build/index.js作为命令（提交前替换路径占位符）
5. 命名MCP（例如，“sfcc”）
6. 选择用户或工作区配置

这将在您的用户settings.json或工作区.vscode/mcp.json中创建一个新的服务器定义：

{
    "servers": {
        "sfcc": {
            "type": "stdio",
            "command": "node",
            "args": [
                "<full-path-to-your>/build/index.js"
            ]
        }
    }
}

现在，您可以通过MCP: 列出服务器命令来监控、启动、重启或停止服务器。通过切换到GitHub Copilot Chat中的代理模式来使用工具。

使用

启动服务器：

node build/index.js

端点配置

端点在src/endpoints.json中配置。每个端点具有以下结构：

{
    "path": "/your/endpoint/{param}",
    "description": "此端点的功能描述",
    "method": "GET",  // 可选：HTTP方法（GET, POST, PUT, DELETE）。默认为GET
    "params": [
        {
            "name": "param",
            "description": "参数描述",
            "type": "string",
            "required": true
        }
    ]
}

• path：API端点路径，带大括号内的路径参数
• description：端点功能的描述
• method：使用的HTTP方法（GET, POST, PUT, DELETE）。未指定时默认为GET
• params：参数定义数组
  • name：参数名称
  • description：参数描述
  • type：参数类型（string, number, boolean）
  4. required：参数是否必需

出现在路径中的参数（如{param}）用于路径替换。其他参数将自动添加为查询参数。

POST请求和请求体

对于POST端点，您可以在调用工具时使用requestBody参数提供JSON请求体。例如：

{
  "site_id": "SiteGenesis",
  "requestBody": {
    "query": {
      "text_query": {
        "search_phrase": "shirt"
      }
    },
    "sort": "price-asc",
    "count": 10
  }
}

默认请求体

端点可以定义一个defaultBody属性，如果未提供请求体，则使用该属性。这使得无需知道确切的请求体结构即可更轻松地使用API。例如，如果未提供特定查询，产品搜索和活动搜索端点的默认请求体将匹配所有项目。

路径参数与查询参数

根据端点的不同，参数可以有不同的用途：

1. 路径参数：包含在端点路径中的大括号内参数，如/sites/{site_id}/campaign_search
2. 查询参数：附加到URL作为查询字符串的其他参数

路径参数示例（活动搜索）：

{
  "site_id": "SiteGenesis",
  "requestBody": {
    "query": {
      "term_query": {
        "fields": ["enabled"],
        "operator": "is",
        "values": ["true"]
      }
    },
    "count": 20
  }
}

工具名称

工具名称从端点路径自动生成：

• 路径分隔符被替换为下划线
• 路径参数被替换为"by_param"
• 如果需要，名称会被截断至64个字符
• 如果需要，通过数字后缀确保唯一性

示例：/catalogs/{id}/products变为catalogs_by_id_products

您也可以在端点配置中指定自定义工具名称：

{
  "path": "/product_search",
  "toolName": "product_search",
  "description": "搜索产品..."
}

自定义处理器

您可以通过以下方式为端点创建自定义处理器：

1. 在端点定义中指定自定义toolName
2. 创建一个名为handler_[toolName]的函数，该函数将代替默认处理器被调用

要创建自定义处理器，请创建一个名称模式为handler_[toolName]的函数。该函数将被自动检测并代替默认处理器使用：

/**
 * 产品搜索的自定义处理器
 * 当访问具有工具名称“product_search”的端点时，将调用此函数而不是默认处理器
 */
export async function handler_product_search(endpoint, params) {
  console.log(`调用了${endpoint.path}的自定义处理器，参数为：`, params);
  
  // 示例：在实际请求之前进行自定义处理
  if (params.requestBody && typeof params.requestBody === 'object') {
    // 如需修改请求
    params.requestBody.custom_field = '由自定义处理器添加';
  }
  
  // 使用修改后的参数调用默认处理器
  const defaultHandler = getDefaultHandler();
  return await defaultHandler(endpoint, params);
}

创建自定义处理器

您可以在index.ts文件中直接定义自定义处理器：

/**
 * 具有工具名称“example_endpoint”的端点的自定义处理器
 */
async function handler_example_endpoint(endpoint, params) {
  // 您的自定义实现
  // ...
}

// 将自定义处理器全局可用
(global as any).handler_example_endpoint = handler_example_endpoint;

您的自定义处理器函数将接收两个参数：

• endpoint：端点配置对象
• params：发送到端点的参数

该函数应返回将发送回客户端的数据。

辅助函数

使用此辅助函数访问默认处理器：

// 辅助函数以获取默认处理器
function getDefaultHandler() {
  if (typeof handleSFCCRequest === 'function') {
    return handleSFCCRequest;
  }
  if (typeof (global as any).handleSFCCRequest === 'function') {
    return (global as any).handleSFCCRequest;
  }
  throw new Error('默认处理器不可用');
}

自定义处理器模式

您可以在自定义处理器中实现不同的模式：

预处理：在调用默认处理器之前修改参数

export async function handler_example(endpoint, params) {
  // 修改参数
  params.customField = '值';
  
  // 使用修改后的参数调用默认处理器
  return await getDefaultHandler()(endpoint, params);
}

后处理：在调用默认处理器之后增强结果

export async function handler_example(endpoint, params) {
  // 从默认处理器获取结果
  const result = await getDefaultHandler()(endpoint, params);
  
  // 修改结果
  result.enhancedField = '值';
  
  return result;
}

完全覆盖：不调用默认处理器的情况下实现自定义行为

export async function handler_example(endpoint, params) {
  // 自定义实现
  return {
    custom: true,
    data: [...]
  };
}

测试

SFCC MCP服务器包括全面的测试以确保可靠性并促进自动化CI/CD过程。

运行测试

# 运行所有测试
npm test

# 开发模式下运行测试
npm run test:watch

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

测试覆盖率

测试套件涵盖：

• 工具实用程序 (tests/tool-utils.test.ts)：工具名称生成和模式构建
• 配置管理 (tests/config-simple.test.ts)：环境配置和会话处理
• 集成测试 (tests/integration.test.ts)：MCP服务器实例化和工具注册

测试框架

该项目使用Jest并支持TypeScript进行测试。测试位于tests/目录下，并遵循命名约定*.test.ts。

部署

SFCC MCP服务器支持自动部署到Google App Engine。

快速开始

1. 设置Google云：

   npm run setup:gcp
   

2. 带有版本的部署：

   npm run version:create
   

3. 手动部署：

   npm run version:deploy
   

文档

• DEPLOYMENT.md：完整的部署设置指南
• REMOTE.md：远程服务器配置和使用

可用命令

npm run setup:gcp          # 交互式Google云设置
npm run version:create     # 创建版本并自动部署
npm run version:deploy     # 带版本输入的手动部署
npm run deploy             # 直接部署到App Engine

许可证

MIT