Sfcc MCP Server

SFCC MCP服务器

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

特性

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

安装

# 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数据API，您需要在SFCC中配置具有适当权限的API客户端：

API客户端

1. 在SFCC客户经理中，转到API客户端
2. 新建API客户端或编辑现有客户端
3. 配置OAuth设置：

- OAuth客户端ID:（您的客户端ID） - OAuth客户端密码：（您的客户端密码） - 默认作用域：包括端点所需的作用域 - 令牌端点身份验证方法： client_secret_post

1. 配置API客户端角色：

- 分配适当的角色以访问所需的数据

业务经理

1. 在SFCC Business Manager中，转至“管理”>“网站开发”>“开放商务API设置”
2. 看 ocapi-bm-config.json 对于配置示例

VSCode的MCP配置

1. 打开命令选项板(Ctrl/Cmd + Shift + P)
2. 键入“MCP”并选择 MCP: Add Server...
3. 选择 Command (stdio) Manual Install
4. 类型 node /build/index.js 对于该命令（在提交之前替换路径占位符）
5. 命名MCP（例如“sfcc”）
6. 选择为用户或工作区配置

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

{
    "servers": {
        "sfcc": {
            "type": "stdio",
            "command": "node",
            "args": [
                "/build/index.js"
            ]
        }
    }
}

现在，您可以通过以下方式监视/启动/重新启动/停止服务器 MCP: List Servers 命令。通过切换到使用工具 Agent GitHub Copilot聊天模式

用法

启动服务器：

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：参数类型（字符串、数字、布尔值） - required：参数是否为必填项

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

POST请求和请求机构

对于POST端点，您可以使用 requestBody 调用工具时的参数。例如：

{
  "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函数

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

// 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服务器包括全面的测试，以确保可靠性并促进自动化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进行测试。测试位于 tests/ 目录并遵循命名约定 *.test.ts.

部署

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

快速开始

1. 设置谷歌云：

   npm run setup:gcp

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

   npm run version:create

1. 手动部署：

   npm run version:deploy

文档

• 部署.md：完整的部署设置指南
• 远程.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

许可证

麻省理工学院