SFCC Development MCP Server

SFCC开发MCP服务器

](https://badge.fury.io/js/sfcc-dev-mcp) 

一个基于人工智能的模型上下文协议（MCP）服务器，提供对Salesforce B2C Commerce Cloud开发工具、文档和运行时诊断的全面访问。

✨ 主要特点

• 🔍 完成SFCC文件访问 -搜索和探索所有SFCC API类和方法
• 🏗️ SFRA文件 -增强对店面参考架构文档的访问
• 🧱 ISML模板参考 -完整的ISML元素文档，包括示例和使用指南
• 📊 日志分析工具 -SFCC实例的实时错误监控、调试和作业日志分析
• ⚙️ 系统对象定义 -探索自定义属性和网站首选项
• 🧪 脚本调试器 -在认证模式下执行和检查脚本调试器端点，包括非默认店面路由的自定义触发器URL/路径
• 🚀 墨盒生成 -自动创建具有工作区绑定路径安全性的盒式磁带结构（写入保留在工作区根目录内，或在根目录不可用时回退当前工作目录；阻止主目录回退）
• 🧩 代理技能引导 -将AGENTS.md和捆绑技能安装或合并到当前项目或AI助手的临时目录中
• ✅ 工具参数验证 -运行时模式验证在处理程序执行之前强制执行对象模式（顶级和嵌套）的必填字段、类型检查、枚举约束、整数/数字边界和严格的未知键检查
• ⏱️ MCP进度+取消 -工具调用荣誉请求取消信号并发出带外信号 notifications/progress 当客户端提供 progressToken

🚀 快速开始

选项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"]
    }
  }
}

创建一个 dw.json 将您的SFCC凭据归档。您可以使用任一身份验证模式（或两者都使用）：

• 基本身份验证： username + password
• OAuth： client-id + client-secret
• 可选店面身份验证（用于基本身份验证店面上的脚本调试器触发器）： storefrontUsername + storefrontPassword

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

在以下情况下，至少需要一个完整的凭证对 hostname 已设置。 如果提供了凭证， hostname 也是必需的。

选项3：自动发现（建议VS Code用户使用）

只需打开一个包含以下内容的VS Code工作区 dw.json file-服务器将自动发现并使用它：

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

🔧 配置发现优先级

服务器按以下顺序发现SFCC凭据（最高优先级优先）：

备注：默认情况下，服务器不再搜索当前工作目录，因为MCP服务器通常以 cwd 设置为用户的主目录。MCP工作空间根机制提供了可靠的项目上下文。

🎯 操作模式

仅文档模式

非常适合学习和发展，不需要SFCC实例：

• 完成SFCC API文档（5个工具）
• SFRA文件（5个工具）
• ISML模板文档（5个工具）
• 墨盒生成（1个工具，写入受限于工作区根/cwd）
• 代理指令引导（2个工具），用于复制/合并AGENTS.md和技能，或禁用未来的提示

全模式

具有完整的SFCC实例访问开发经验：

• 所有文档专用功能（18个工具）
• 实时日志分析和作业日志（13个工具）
• 系统对象定义（6个工具）
• 代码版本管理（2个工具）
• 脚本调试器操作（1个工具）

🏗️ 架构概述

此服务器围绕 能力门控模块化处理器架构 它将工具路由与域逻辑清晰地分开：

核心层

• 工具架构 (src/core/tool-schemas/)：模块化、基于类别的工具定义（文档、SFRA、ISML、日志、作业日志、系统对象、盒式磁带、代码版本、代理指令、脚本调试器）。通过以下方式重新出口 tool-definitions.ts.
• 服务器编排模块 (src/core/server-tool-catalog.ts, src/core/server-tool-call-lifecycle.ts, src/core/server-workspace-discovery.ts)：保留 server.ts 通过提取能力感知工具目录逻辑， tools/call 生命周期（进度/取消/飞行前）和工作空间根重新配置流程。
• 工具参数验证器 (src/core/tool-argument-validator.ts)：在工具分派之前，在MCP边界对所有工具（必填字段、基元/对象/数组类型、枚举检查、整数/数字范围、字符串模式/长度以及顶级和嵌套级别的对象模式的严格未知键检查）强制执行运行时参数形状。
• OCAPI查询覆盖率 (src/core/tool-schemas/shared-schemas.ts)：共享搜索架构包括 text_query, term_query, bool_query, filtered_query，以及 match_all_query 因此MCP边界验证与支持的OCAPI查询模式保持一致。
• 处理器 (src/core/handlers/)：每个类别都有一个处理程序，它扩展了定时、结构化日志记录和错误规范化的公共基础，并通过配置驱动的连接 ConfiguredClientHandler 减少重复的样板（例如。 log-handler, docs-handler, isml-handler, system-object-handler).
• 客户 (src/clients/)：封装域操作（OCAPI、SFRA文档、ISML文档、模块化日志分析、脚本调试器、盒式磁带生成、代理指令同步）。处理程序委托给这些，因此编排和计算仍然是分开的。
• 服务 (src/services/)：文件系统和路径操作的依赖注入抽象——提高了可测试性并隔离了副作用。
• 模块化日志系统 (src/clients/logs/)：读取器（范围/尾部优化）、发现、处理器（行→ 结构化条目）、分析器（模式和健康）、格式化器（人类输出），用于可维护的进化。
• 配置工厂 (src/config/configuration-factory.ts)：确定能力(canAccessLogs, canAccessOCAPI)基于提供的凭证，并相应地过滤暴露的工具（最小特权原则）。
• 共享凭据验证 (src/config/credential-validation.ts)：集中验证两者的身份验证对完整性和主机名格式验证 dw.json 加载和运行时配置创建。
• 通话时间能力保护 (src/core/server.ts)：拒绝执行在当前模式下不可用的工具，因此隐藏的工具无法通过直接调用 tools/call 请求：
• 呼叫生命周期信号 (src/core/server.ts): tools/call 处理支持通过请求中止信号取消，并在呼叫者提供时发出尽力而为的进度通知 _meta.progressToken.
• 工具错误清理 (src/core/tool-error-response.ts)：在返回MCP工具响应之前，对上游执行错误进行消毒，减少后端有效负载详细信息的意外泄漏。
• 运行时WebDAV验证 (src/core/server.ts)：仅适用于OAuth配置(client-id/client-secret 没有 username/password)，日志/作业日志/脚本调试器工具的暴露由一次性WebDAV功能探测来控制，以避免工具的假阳性可用性。
• CLI选项帮助程序 (src/config/cli-options.ts)：集中命令行解析和环境凭据检测，以实现可预测的启动行为。
• 共享路径安全策略 (src/config/path-security-policy.ts)：跨工作区根发现和安全重用允许/阻止路径规则 dw.json 加载。
• 共享中止实用程序 (src/utils/abort-utils.ts)：HTTP和调试器客户端使用集中式超时和中止信号组合，以实现一致的取消语义和计时器清理。

为何这很重要

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

添加新工具（高级）

1. 将架构添加到中的相应文件 src/core/tool-schemas/ （或为新类别创建新文件）。
2. 从导出新架构 src/core/tool-schemas/index.ts 如果添加新文件。
3. 在客户端/服务中实现域逻辑（避免处理程序膨胀）。
4. 扩展现有的处理程序，或者如果它是一个新类别，则创建一个新的处理程序。
5. （仅适用于新类别）在内部注册新处理程序 registerHandlers() 在 server.ts.
6. 通过以下方式发现实际响应形状 npx aegis query 在编写测试之前。
7. 添加Jest单元测试+YAML MCP测试（如果需要凭据，则添加docs与full模式）。
8. 更新文档（如果更改，则AGENTS.md+README计数）。

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

🤖 AI接口设置

选择您喜欢的AI助手：

📦 安装

使用npx（推荐）

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

# Test the server
npx -y sfcc-dev-mcp

# Use with your configuration
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

🐛 调试模式和日志记录

启用调试日志记录

# Enable debug mode for detailed logging
npx -y sfcc-dev-mcp --debug

# Or with configuration file
npx -y sfcc-dev-mcp --dw-json /path/to/your/dw.json --debug

--debug 接受 true/false, 1/0，或 yes/no无效值会快速失败，并显示明确的错误消息。

日志文件位置

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

• macOS: /var/folders/{user-id}/T/sfcc-mcp-logs/
• Linux: /tmp/sfcc-mcp-logs/
• 视窗: %TEMP%\sfcc-mcp-logs\

已创建日志文件：

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

查找日志目录

// The exact path varies by system - to find yours:
node -e "console.log(require('os').tmpdir() + '/sfcc-mcp-logs')"

🧪 释放流程（维护人员）

此存储库现在将Changeset用于npm版本。

当一个变化应该在一个新的 sfcc-dev-mcp version，从存储库根添加变更集：

npm run changeset

对照检查待定发布状态 main 合并前：

npm run release:status

发布工作流程 main 从挂起的变更集中创建或更新发布拉取请求。合并该发布拉取请求通过npm可信发布（GitHub Actions OIDC）发布npm包，等待npm传播，对已发布的NPX工件重新运行MCP测试，然后将相同版本发布到MCP注册表。

npm run version-packages 也同步 server.json 与软件包版本一样 validate:server-json 继续传递发布PR。

包发布现在使用GitHub Actions OIDC可信发布，因此不需要单独的npm发布密钥。

您可以在本地运行相同的验证：

# Ensure docs-site tool catalog stays in sync with runtime tool definitions
npm run validate:tools-sync

# Ensure docs-site skills catalog stays in sync with bundled skills
npm run validate:skills-sync

# Ensure MCP registry metadata stays in sync with package.json
npm run validate:server-json

# In a separate terminal, start the mock server first for full-mode MCP tests
npm run test:mock-server:start

# Uses latest published version by default
npm run test:mcp:published-npx

# Or pin a specific published version
bash ./scripts/test-published-npx.sh 1.0.21

在GitHub Actions中，发布工作流自动管理模拟服务器生命周期。

📖 文档

📚 完整文档 -全面的指南和参考

文档来源位于 docs-site-v2/ （VitePress）。遗留的React网站仍保留在 docs-site/.

快速链接：

• 入门指南 -安装和首次运行设置
• AI接口设置 -配置Claude Desktop、GitHub Copilot或游标
• 配置指南 -SFCC凭据和数据API设置
• 可用工具 -完整的工具参考
• 例子 -真实世界的使用模式
• 故障排除 -常见问题和解决方案

🛠️ AI交互示例

🧑‍💻 "Create a new SFCC controller for product search"
🤖 Generates complete controller with proper imports, route handling, and SFRA patterns

🧑‍💻 "What's wrong with my checkout flow? Check the logs"  
🤖 Analyzes recent error logs, identifies issues, and suggests fixes

🧑‍💻 "Show me how to implement OCAPI hooks for order validation"
🤖 Retrieves related SFCC classes and methods, then proposes a concrete hook implementation pattern

🔒 安全说明

• 地方发展重点：专为个人开发人员在本地计算机上使用而设计
• 凭证保护：dw.json文件永远不应该提交到版本控制中
• 网络安全：所有API调用都使用具有正确身份验证的HTTPS
• 无数据存储：服务器不在本地保存任何SFCC数据

🔮 未来计划

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

🎯 即将推出的增强功能

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

🤝 我们欢迎您的贡献！

对新功能或改进有想法吗？我们很乐意收到您的来信！

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

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

🤝 贡献

我们欢迎捐款！请查看我们的 贡献指南 了解详情。

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

🚀 准备好用人工智能加速SFCC开发了吗？

📖 开始使用完整文档