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_secretOCAPI配置
要使用SFCC数据API，您需要在SFCC中配置具有适当权限的API客户端：
API客户端
- 在SFCC客户经理中，转到API客户端
- 新建API客户端或编辑现有客户端
- 配置OAuth设置：
- OAuth客户端ID:（您的客户端ID） - OAuth客户端密码：（您的客户端密码） - 默认作用域：包括端点所需的作用域 - 令牌端点身份验证方法： client_secret_post
- 配置API客户端角色：
- 分配适当的角色以访问所需的数据
业务经理
- 在SFCC Business Manager中，转至“管理”>“网站开发”>“开放商务API设置”
- 看
ocapi-bm-config.json对于配置示例
VSCode的MCP配置
- 打开命令选项板(
Ctrl/Cmd + Shift + P) - 键入“MCP”并选择
MCP: Add Server... - 选择
Command (stdio) Manual Install - 类型
node /build/index.js对于该命令（在提交之前替换路径占位符） - 命名MCP（例如“sfcc”）
- 选择为用户或工作区配置
这将在您的用户中创建新的服务器定义 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）。如果未指定，则默认为GETparams：参数定义数组
- 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端点具有与所有项目匹配的默认主体。
路径参数与查询参数
根据端点的不同，参数可以以不同的方式使用：
- 路径参数：端点路径中包含的带花括号的参数，如
/sites/{site_id}/campaign_search - 查询参数：作为查询字符串附加到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..."
}自定义处理程序
您可以通过以下方式为端点创建自定义处理程序：
- 指定自定义
toolName在端点定义中 - 创建一个名为的函数
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。
快速开始
- 设置谷歌云：
npm run setup:gcp- 使用版本控制进行部署：
npm run version:create- 手动部署：
npm run version:deploy文档
可用命令
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许可证
麻省理工学院