sfcc开发mcp服务器

Name: sfcc开发mcp服务器
Author: taurgis

作者：taurgis14 星标更新：2025-11-14

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

项目介绍

SFCC 开发 MCP 服务器

一个由人工智能驱动的模型上下文协议（MCP）服务器，提供对 Salesforce B2C Commerce Cloud 开发工具、文档和最佳实践的全面访问。

✨ 主要特性

🔍 完整 SFCC 文档访问 - 搜索和探索所有 SFCC API 类和方法
📚 最佳实践指南 - 编制了关于插件、钩子、控制器、客户端 JavaScript 等的开发指南
🏗️ SFRA 文档 - 增强了对 Storefront 参考架构文档的访问
📊 日志分析工具 - 实时错误监控、调试和作业日志分析
⚙️ 系统对象定义 - 探索自定义属性和站点偏好设置
🚀 插件生成 - 自动创建插件结构

🚀 快速开始

选项 1：仅文档模式（无需 SFCC 凭据）

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp"]
    }
  }
}

选项 2：完整模式（带有 SFCC 凭据用于日志和作业分析）

{
  "mcpServers": {
    "sfcc-dev": {
      "command": "npx",
      "args": ["sfcc-dev-mcp", "--dw-json", "/path/to/your/dw.json"]
    }
  }
}

创建一个包含您的 SFCC 凭据的 dw.json 文件：

{
  "hostname": "your-instance.sandbox.us01.dx.commercecloud.salesforce.com",
  "username": "your-username",
  "password": "your-password",
  "client-id": "your-client-id",
  "client-secret": "your-client-secret"
}

🎯 运行模式

模式	可用工具	是否需要 SFCC 凭据
仅文档	15 个工具	❌ 不需要
完整模式	36 个工具	✅ 需要

仅文档模式

适合学习和开发 - 不需要 SFCC 实例：

完整的 SFCC API 文档（5 个工具）
最佳实践指南（4 个工具）– 插件、客户端 JavaScript、控制器、钩子、安全/性能
SFRA 文档（5 个工具）
插件生成（1 个工具）

完整模式

完整的开发体验，具有实时 SFCC 实例访问：

所有仅文档功能（15 个工具）
实时日志分析（13 个工具）
系统对象定义（6 个工具）
代码版本管理（2 个工具）

� 架构概述

该服务器围绕一个能力门控、模块化处理器架构构建，干净地分离工具路由与领域逻辑：

核心层

工具定义 (src/core/tool-definitions.ts)：按类别分组的声明性模式（文档、最佳实践、SFRA、日志、作业日志、系统对象、插件生成、代码版本）。
处理器 (src/core/handlers/*.ts)：每个类别都有一个扩展通用基础的处理器，用于计时、结构化日志记录和错误规范化（例如 log-handler、docs-handler、system-object-handler）。
客户端 (src/clients/)：封装领域操作（OCAPI、SFRA 文档、最佳实践、模块化日志分析）。处理器委托给这些客户端，以便编排和计算保持分离。
服务 (src/services/)：依赖注入抽象，用于文件系统和路径操作——提高可测试性并隔离副作用。
模块化日志系统 (src/clients/logs/)：读取器（范围/尾部优化）、发现、处理器（行 → 结构化条目）、分析器（模式及健康状况）、格式化器（人类输出），以实现可持续演进。
配置工厂 (src/config/configuration-factory.ts)：根据提供的凭据确定功能（canAccessLogs、canAccessOCAPI），并相应地过滤暴露的工具（最小权限原则）。

为什么这很重要

可扩展性：添加新工具通常意味着添加一个模式 + 最小处理器逻辑（或如果是一个新领域，则添加一个新的处理器）。
安全性：需要凭据的工具在能力标志为假时永远不会暴露。
可测试性：单元测试针对客户端和模块；集成/MCP 测试验证处理器路由和响应结构。
性能：尾部日志读取 + 轻量级缓存（cache.ts、log-cache.ts）减少不必要的 I/O。

添加新工具（高层次）

将模式对象添加到 tool-definitions.ts 中正确导出的数组中。
在客户端/服务中实现领域逻辑（避免使处理器膨胀）。
扩展现有处理器或创建新的处理器（如果是新类别）。
（仅对于新类别）在 server.ts 的 registerHandlers() 中注册新处理器。
使用 npx mcp-aegis query 发现实际响应形状，然后编写测试。
添加 Jest 单元测试 + YAML MCP 测试（文档 vs 完整模式，如果需要凭据）。
更新文档（开发指南 + 如果更改则更新 README）。

有关更深入的内部视图，请参阅文档网站上的开发指南。

�🤖 AI 接口设置

选择您喜欢的 AI 助手：

接口	最适合	设置指南
Claude Desktop	多轮对话、调试	📖 设置指南
GitHub Copilot	VS Code 集成、内联建议	📖 设置指南
Cursor	现代 AI 驱动编辑器	📖 设置指南

📦 安装

使用 npx（推荐）

提示：添加 -y（或 --yes）以抑制 npx 在下载包之前显示的交互提示。这可以防止 AI 客户端（Claude Desktop、Copilot、Cursor）等待确认而挂起。

# 测试服务器
npx -y sfcc-dev-mcp

# 使用您的配置
npx -y sfcc-dev-mcp --dw-json /path/to/your/dw.json

全局安装

npm install -g sfcc-dev-mcp
sfcc-dev-mcp --dw-json /path/to/your/dw.json

🐛 调试模式及日志

启用调试日志

# 启用调试模式以获取详细日志
npx -y sfcc-dev-mcp --debug

# 或使用配置文件
npx -y sfcc-dev-mcp --dw-json /path/to/your/dw.json --debug

日志文件位置

服务器将日志写入系统的临时目录：

macOS：/var/folders/{user-id}/T/sfcc-mcp-logs/
Linux：/tmp/sfcc-mcp-logs/
Windows：%TEMP%\sfcc-mcp-logs\

创建的日志文件：

sfcc-mcp-info.log - 一般应用程序日志和启动消息
sfcc-mcp-debug.log - 详细的调试信息（仅当启用 --debug 时）
sfcc-mcp-error.log - 错误消息和堆栈跟踪
sfcc-mcp-warn.log - 警告消息

查找您的日志目录

// 精确路径因系统而异 - 要找到您的：
node -e "console.log(require('os').tmpdir() + '/sfcc-mcp-logs')"

📖 文档

📚 完整文档 - 综合指南和参考

快速链接：

安装指南 - 详细的安装选项
AI 接口设置 - 配置 Claude Desktop、GitHub Copilot 或 Cursor
配置指南 - SFCC 凭据和数据 API 设置
可用工具 - 完整工具参考
示例 - 现实世界的使用模式
故障排除 - 常见问题及其解决方案

🛠️ 示例 AI 交互

🧑‍💻 "创建一个新的 SFCC 控制器用于产品搜索"
🤖 生成完整的控制器，包括正确的导入、路由处理和 SFRA 模式

🧑‍💻 "我的结账流程有什么问题？检查日志"
🤖 分析最近的错误日志，识别问题并提出修复建议

🧑‍💻 "展示如何实现 OCAPI 钩子进行订单验证"
🤖 提供最佳实践指南，附带完整的钩子实现示例

🔒 安全注意事项

本地开发重点：设计用于个人开发者在本地机器上的使用
凭据保护：dw.json 文件不应提交到版本控制
网络安全：所有 API 调用均使用 HTTPS 和适当的身份验证
无数据存储：服务器不会在本地持久保存任何 SFCC 数据

🔮 未来计划

我们正在不断改进 SFCC 开发 MCP 服务器，并计划了一些令人兴奋的新功能：

🎯 即将增强的功能

🧠 更智能的日志抓取 - 增强日志分析，具备智能过滤、模式识别和上下文错误关联
🚀 部署工具 - 与 SFCC 部署过程和代码版本管理集成

🤝 我们欢迎您的贡献！

有任何新功能或改进的想法吗？我们很乐意听到您的意见！

💡 功能请求：打开一个问题来讨论您的想法
🐛 错误报告：通过报告遇到的问题帮助我们改进
🔧 拉取请求：贡献代码、文档或示例
📚 文档：帮助扩展我们的指南和最佳实践

查看我们的贡献指南开始，或浏览我们的开放问题来了解您可以如何帮助。

您的专业知识和反馈让这个工具对整个 SFCC 社区更好！

🤝 贡献

我们欢迎贡献！请参阅我们的贡献指南获取详细信息。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🚀 准备使用 AI 加速您的 SFCC 开发吗？

📖 从完整文档开始