SFCC MCP Server

SFCC MCP 服务

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

功能

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

安装

# Install dependencies
npm install

# Build the server
npm run build

配置

在项目根目录中创建 .env 文件，并添加以下变量：

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

# Admin API Credentials (Client credentials flow)
SFCC_ADMIN_CLIENT_ID=your_admin_client_id
SFCC_ADMIN_CLIENT_SECRET=your_admin_client_secret

OCAPI 配置

要使用 SFCC Data API，需要在 SFCC 中配置具有相应权限的 API 客户端：

API 客户端

1. 在 SFCC Account Manager 中，转到 API Client
2. 创建新的 API 客户端，或编辑现有客户端
3. 配置 OAuth 设置：
   • OAuth Client ID：（你的客户端 ID）
   • OAuth Client Secret：（你的客户端密钥）
   • Default scopes：包含端点所需的作用域
   • Token Endpoint Auth Method：client_secret_post
4. 配置 API 客户端角色：
   • 分配适当的角色以访问所需的数据

Business Manager

1. 在 SFCC Business Manager 中，转到 Administration > Site Development > Open Commerce API Settings
2. 配置示例请参见 ocapi-bm-config.json

VSCode 的 MCP 配置

1. 打开命令面板（Ctrl/Cmd + Shift + P）
2. 输入“MCP”，然后选择 MCP: Add Server...
3. 选择 Command (stdio) Manual Install
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: List Servers 命令监控、启动、重启或停止服务。在 GitHub Copilot Chat 中切换到 Agent 模式，即可使用工具。

使用方法

启动服务：

node build/index.js

端点配置

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

{
    "path": "/your/endpoint/{param}",
    "description": "Description of what this endpoint does",
    "method": "GET",  // Optional: HTTP method (GET, POST, PUT, DELETE). Defaults to GET
    "params": [
        {
            "name": "param",
            "description": "Description of the parameter",
            "type": "string",
            "required": true
        }
    ]
}

• path：API 端点路径，路径参数用花括号括起
• description：端点功能说明
• method：要使用的 HTTP 方法（GET、POST、PUT、DELETE）。如果未指定，则默认为 GET
• params：参数定义数组
  • name：参数名称
  • description：参数说明
  • type：参数类型（string、number、boolean）
  • required：参数是否必填

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

POST 请求和请求正文

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

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

默认请求正文

端点可以定义 defaultBody 属性，在未提供请求正文时使用。这样，即使不知道请求正文的确切结构，也能更轻松地使用 API。例如，如果未指定查询条件，product_search 和 campaign_search 端点的默认请求正文会匹配所有项目。

路径参数与查询参数

参数可根据端点以不同方式使用：

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

带有路径参数的端点示例（campaign_search）：

{
  "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": "Search for products..."
}

自定义处理程序

你可以通过以下方式为端点创建自定义处理程序：

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

要创建自定义处理程序，请创建一个符合 handler_[toolName] 命名模式的函数。系统会自动检测并使用此函数，而非默认处理程序：

/**
 * Custom handler for product search
 * This function will be called instead of the default handler when 
 * the endpoint with toolName "product_search" is accessed
 */
export async function handler_product_search(endpoint, params) {
  console.log(`Custom handler for ${endpoint.path} called with params:`, params);
  
  // Example of custom processing before making the actual request
  if (params.requestBody && typeof params.requestBody === 'object') {
    // Modify the request if needed
    params.requestBody.custom_field = 'Added by custom handler';
  }
  
  // Call the default handler with your modified params
  const defaultHandler = getDefaultHandler();
  return await defaultHandler(endpoint, params);
}

创建自定义处理程序

你可以直接在 index.ts 文件中定义自定义处理程序：

/**
 * Custom handler for an endpoint with toolName "example_endpoint"
 */
async function handler_example_endpoint(endpoint, params) {
  // Your custom implementation
  // ...
}

// Make the custom handler accessible globally
(global as any).handler_example_endpoint = handler_example_endpoint;

自定义处理程序函数会接收两个参数：

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

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

辅助函数

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

// Helper to get the default handler
function getDefaultHandler() {
  if (typeof handleSFCCRequest === 'function') {
    return handleSFCCRequest;
  }
  if (typeof (global as any).handleSFCCRequest === 'function') {
    return (global as any).handleSFCCRequest;
  }
  throw new Error('Default handler not available');
}

自定义处理程序模式

你可以在自定义处理程序中实现不同的模式：

预处理： 调用默认处理程序前修改参数

export async function handler_example(endpoint, params) {
  // Modify params
  params.customField = 'value';
  
  // Call default handler with modified params
  return await getDefaultHandler()(endpoint, params);
}

后处理： 调用默认处理程序后增强结果

export async function handler_example(endpoint, params) {
  // Get result from default handler
  const result = await getDefaultHandler()(endpoint, params);
  
  // Modify the result
  result.enhancedField = 'value';
  
  return result;
}

完全覆盖： 不调用默认处理程序，自行实现自定义行为

export async function handler_example(endpoint, params) {
  // Custom implementation
  return {
    custom: true,
    data: [...]
  };
}

测试

SFCC MCP Server 包含全面的测试，以确保可靠性并支持自动化 CI/CD 流程。

运行测试

# Run all tests
npm test

# Run tests in watch mode for development
npm run test:watch

# Run tests with coverage report
npm run test:coverage

测试覆盖范围

测试套件涵盖：

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

测试框架

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

部署

SFCC MCP Server 支持自动部署到 Google App Engine。

快速入门

1. 设置 Google Cloud：

   npm run setup:gcp
   

2. 使用版本控制进行部署：

   npm run version:create
   

3. 手动部署：

   npm run version:deploy
   

文档

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

可用命令

npm run setup:gcp          # Interactive Google Cloud setup
npm run version:create     # Create version and auto-deploy
npm run version:deploy     # Manual deployment with version input
npm run deploy             # Direct deployment to App Engine

许可证

MIT