内容
# 销售力架构图 MCP 服务器
## 目的
**sfdc-arch-mcp** 服务器是一个模型上下文协议（MCP）服务器，使 AI 助手能够生成专业的、演示质量的销售力架构图。它提供：
- **精选的 SVG 标志库** — 1700+ 个真实公司标志（非 AI 生成的近似值）
- **销售力品牌标准** — 颜色、字体和间距来自 architect.salesforce.com
- **演示质量的 SVG 幻灯片** — 全景式幻灯片，带有自由形式的节点放置、曲线连接器和销售力品牌
- **良好的架构验证** — 反模式检测和架构最佳实践
- **Mermaid 图表** — 用于文档和 wiki
### 它做什么
| 功能 | 描述 |
| --- | --- |
| 生成 SVG 幻灯片图表 | 演示质量的架构幻灯片（默认方法） |
| 生成 Mermaid 图表 | 用于文档和 wiki 的基于 Markdown 的图表 |
| 验证架构 | 检查设计是否符合销售力的良好架构支柱 |
| 提供设计规范 | 检索销售力品牌颜色、间距和模式 |
| 导出为图像 | 将 HTML 幻灯片转换为 PNG/PDF/SVG |
### 支持的图表类型
- **系统景观** — 源/目标组织、集成架构、外部系统
- **模块架构** — 分层模块依赖关系，带有跨层连接器
- **数据管道/流程** — SDK 管道、仪器流程、处理阶段
- **序列图** — 引导流程、集成消息序列
- **数据模型（ERD）** — 实体、字段和关系（Mermaid）
### 图表输出：SVG 幻灯片（默认）
所有架构图应生成为 **原始 HTML，带有内联 SVG** — 完整出血的景观幻灯片，匹配销售力工程研讨会的质量。有关完整指南，请参见 `docs/PRESENTATION_DIAGRAMS.md`，并使用 `context/slide-template.html` 作为可复制的模板。
不要使用 `generate_html_diagram` 或 `generate_html_diagram_v2` MCP 工具 — 这些工具会生成 CSS 卡片/网格布局，不符合演示质量。
---
## 设置说明
### 先决条件
- 已安装 Node.js 18+
- Claude Code（或另一个 MCP 兼容客户端）
- npm 包管理器
### 安装
```bash
# 克隆或导航到项目
cd /path/to/sfdc-arch-mcp
# 安装依赖项
npm install
# 构建 TypeScript
npm run build
# 验证构建成功
ls dist/index.js
```
### 配置 MCP 客户端
将服务器添加到您的 Claude Code MCP 配置文件中。
**位置：** `~/.claude.json` 或项目级 `.claude.json`
```json
{
"mcpServers": {
"sfdc-designer": {
"command": "node",
"args": ["/绝对路径/to/sfdc-arch-mcp/dist/index.js"]
}
}
}
```
**示例路径：**
```json
{
"mcpServers": {
"sfdc-designer": {
"command": "node",
"args": ["/Users/michael.falkner/sfdc-arch-mcp/dist/index.js"]
}
}
}
```
### 验证设置
配置完成后，重启您的 AI 客户端。MCP 工具应该可用：
- `mcp__sfdc-designer__get_sfdc_specs` — 品牌颜色和设计规范
- `mcp__sfdc-designer__criticize_architecture` — 良好架构验证
- `mcp__sfdc-designer__generate_mermaid_diagram` — 用于文档的 Mermaid 图表
- `mcp__sfdc-designer__export_to_image` — HTML 到 PNG/PDF 导出
- `mcp__sfdc-designer__list_logos` — 发现可用的 SVG 标志
有关架构图，请直接编写原始 SVG HTML（无需 MCP 工具）。请参见 `docs/PRESENTATION_DIAGRAMS.md` 和 `context/slide-template.html`。
---
## 使用方法
### 方法 1：自然语言提示（推荐）
描述您想要的架构图。AI 助手将直接编写原始 HTML，带有内联 SVG，使用 `context/slide-template.html` 作为起点。
#### 架构图（SVG 幻灯片）
```
创建系统景观图，显示我们的销售力组织与 SAP、MuleSoft 和 Snowflake 集成。保存为演示质量的 SVG 幻灯片。
```
```
生成模块依赖关系图，显示我们的 SDK 层：API 在底部，仪器和实现在中间，代理和扩展在顶部，层之间带有曲线连接线。
```
```
构建数据管道图，显示应用程序 → 仪器 → SDK → 处理 → 后端服务，带有自由形式的节点放置和贝塞尔曲线连接器。
```
```
创建迁移架构幻灯片，显示我们的 ACW 源组织通过 Gearset 连接到 UA 目标组织，带有数据流箭头和标签连接。
```
#### Mermaid 图表（用于文档）
```
生成 Mermaid 流程图，显示我们的集成架构。我需要它用于我们的 Confluence 文档。
```
```
创建 Mermaid 序列图，显示 Salesforce、MuleSoft 和 SAP 之间的 API 调用流程，用于订单处理。
```
```
为我们的销售力数据模型构建 Mermaid ERD，我可以将其嵌入到 GitHub README 中。
```
#### 架构验证
```
使用以下架构审查反模式：我们有 6 个外部系统直接连接到销售力，没有中间件层，并且我们对 SAP 集成使用基本身份验证。
```
### 方法 2：用于批量处理的 CLI 工具
用于生成多个图表或特定导出格式：
```bash
node scripts/generate-diagram.js config.json output --png --pdf
node scripts/generate-diagram.js --batch configs/ --all --output-dir=./output
```
---
## CLI 命令参考
### 生成单个图表
```bash
# 基本 HTML 输出
node scripts/generate-diagram.js config.json
# HTML + PNG
node scripts/generate-diagram.js config.json output.html --png
# 所有格式（HTML、PNG、PDF、SVG）
node scripts/generate-diagram.js config.json output --all
# 高分辨率 PNG
node scripts/generate-diagram.js config.json output --png --scale=3 --width=1920
```
### 批量处理
```bash
# 处理目录中的所有 JSON 配置
node scripts/generate-diagram.js --batch configs/ --png --output-dir=./diagrams
# 批量处理所有格式
node scripts/generate-diagram.js --batch configs/ --all --output-dir=./output
```
### CLI 选项
| 选项 | 描述 | 默认值 |
| --- | --- | --- |
| `--png` | 生成 PNG 图像 | - |
| `--pdf` | 生成 PDF 文档 | - |
| `--svg` | 生成 SVG 矢量 | - |
| `--all` | 生成所有格式 | - |
| `--png-only` | 仅 PNG，无 HTML | - |
| `--pdf-only` | 仅 PDF，无 HTML | - |
| `--width=N` | 像素宽度 | 1400 |
| `--scale=N` | 分辨率缩放因子 | 2 |
| `--batch <dir>` | 处理目录中的所有 .json 文件 | - |
| `--output-dir <dir>` | 批量模式输出目录 | ./output |
| `--open` | 生成后打开结果 | - |
---
## 示例提示按用例
### 系统景观
```
创建演示质量的架构幻灯片，显示我们的销售力组织位于中心，MuleSoft 作为集成层，连接 SAP（ERP）、Workday（HR）和 Snowflake（分析）。使用曲线连接线和显示数据方向的流标签。
```
### 迁移架构
```
构建架构幻灯片，显示从我们的旧 ACW 组织到新 UA 组织的 Gearset 数据迁移。显示通过迁移工具流动的 Accounts、Contacts 和 Opportunities，带有标签连接。
```
### 模块依赖关系
```
创建多层模块架构图，API 在底部，SDK 在中间，Instrumentation 和 Extension 层在上方，Agent 在顶部。显示跨层依赖关系线，带有“依赖”和“实现”标签。使用每层的不同颜色。
```
### 数据管道/处理流程
```
构建数据管道图，显示：应用程序 → 仪器 → SDK 处理 → 导出器 → 后端服务。放置组件时使用自由表单布局和贝塞尔曲线连接器和流标签徽章。
```
### 架构审查
```
审查此提议的架构是否存在问题：
- 直接从销售力到 5 个不同遗留系统的 SOAP 连接
- API 凭证存储在销售力自定义元数据中
- 无重试逻辑或错误处理
- 所有集成在记录保存时同步运行
```
### 用于文档的 Mermaid
```
我需要用于技术文档的 Mermaid 图表：
1. 显示我们的订单到现金流程的流程图
2. 显示报价审批工作流的序列图
3. 显示我们的库存管理自定义对象的 ERD
```
---
## 可用工具参考
### SVG 幻灯片图表（主要方法）
架构图通过编写原始 HTML 和内联 SVG 生成。无需调用 MCP 工具 — AI 直接使用 `docs/PRESENTATION_DIAGRAMS.md` 中的模板和模式编写 HTML。
- **模板：** `context/slide-template.html`
- **指南：** `docs/PRESENTATION_DIAGRAMS.md`
- **视觉参考：** `context/image (17).png`、`context/image (18).png`、`context/image (19).png`
### generate_mermaid_diagram
生成 Mermaid Markdown 图表。
**最适合：** 文档、wiki、GitHub README、Confluence
**参数：**
- `type`（必填）：`flowchart` | `sequence` | `erd` | `mindmap`
- `direction`：`TB` | `BT` | `LR` | `RL`（用于流程图）
- `title`：图表标题
- `nodes`：流程图节点
- `connections`：节点连接
- `entities`：ERD 实体
- `relationships`：ERD 关系
- `participants`：序列图参与者
- `messages`：序列图消息
### get_sfdc_specs
检索销售力设计规范。
**最适合：** 获取品牌颜色、间距值、设计模式
**参数：**
- `category`：`colors` | `spacing` | `cards` | `headers` | `connectors` | `patterns` | `levels` | `all`
- `cloudType`：`salesCloud` | `serviceCloud` | `platform` | `industries` | `nonprofit`
### criticize_architecture
根据 Well-Architected 支柱验证架构。
**最适合：** 架构审查、反模式检测、设计验证
**参数：**
- `description`：架构的自然语言描述
- `diagramSchema`：具有组件和连接的结构化模式
**检测反模式：**
- God Flow（巨大的单个 Flow）
- 硬编码 ID/密钥
- 点对点集成
- 数据孤岛
- 集成管理员用户
### export_to_image
通过 Puppeteer 将 HTML 导出为 PNG/JPEG/PDF/SVG。
**最适合：** 将 SVG 幻灯片 HTML 文件转换为图像格式
### 旧工具（不推荐）
以下工具生成 CSS 卡片/网格布局，不应用于架构图：
- `generate_html_diagram` — 生成基于 CSS 卡片的布局
- `generate_html_diagram_v2` — 生成带有容器的基于 CSS 卡片的布局
- `generate_diagram_config` — 为旧卡片工具生成 JSON 配置
---
## 标志库参考
在节点的 `logo` 字段中使用这些键：
### 销售力产品
| 键 | 产品 |
| --- | --- |
| `salesforce.core` | 销售力云（通用） |
| `salesforce.sales-cloud` | 销售云 |
| `salesforce.service-cloud` | 服务云 |
| `salesforce.marketing-cloud` | 营销云 |
| `salesforce.commerce-cloud` | 商务云 |
| `salesforce.experience-cloud` | 体验云 |
| `salesforce.data-cloud` | 数据云 |
| `salesforce.tableau` | Tableau |
| `salesforce.mulesoft` | MuleSoft |
| `salesforce.slack` | Slack |
| `salesforce.heroku` | Heroku |
### 集成平台
| 键 | 平台 |
| --- | --- |
| `integration.mulesoft` | MuleSoft Anypoint |
| `integration.informatica` | Informatica |
| `integration.boomi` | Dell Boomi |
| `integration.jitterbit` | Jitterbit |
| `integration.workato` | Workato |
### 云提供商
| 键 | 提供商 |
| --- | --- |
| `cloud.aws` | Amazon Web Services |
| `cloud.azure` | Microsoft Azure |
| `cloud.gcp` | Google Cloud Platform |
| `cloud.snowflake` | Snowflake |
### 企业系统
| 键 | 系统 |
| --- | --- |
| `enterprise.sap` | SAP |
| `enterprise.oracle` | Oracle |
| `enterprise.workday` | Workday |
| `enterprise.servicenow` | ServiceNow |
| `enterprise.microsoft` | Microsoft |
### DevOps 工具
| 键 | 工具 |
| --- | --- |
| `tools.gearset` | Gearset |
| `tools.copado` | Copado |
| `tools.dataloader` | Data Loader |
| `tools.github` | GitHub |
| `tools.gitlab` | GitLab |
| `tools.jira` | Jira |
| `tools.confluence` | Confluence |
### 通用图标
| 键 | 图标 |
| --- | --- |
| `generic.database` | 数据库圆柱体 |
| `generic.cloud` | 云形状 |
| `generic.settings` | 齿轮/设置 |
| `generic.api` | API 连接器 |
| `generic.external-system` | 通用外部系统 |
---
## 品牌颜色参考
| 颜色名称 | 十六进制 | 用途 |
| --- | --- | --- |
| 销售云 | `#0176D3` | 销售相关图表 |
| 服务云 | `#FF5D2D` | 服务相关图表 |
| 平台海军蓝 | `#032D60` | 标题、主要文本 |
| 成功绿色 | `#2E844A` | 目标组织、成功状态 |
| 行业青绿色 | `#0B827C` | 源组织、行业 |
| 警告黄色 | `#FFB75D` | 标注、警告 |
| 错误红色 | `#EA001B` | 错误、反模式 |
| 中性灰色 | `#706E6B` | 次要元素 |
---
## 故障排除
### MCP 服务器未找到
1. 验证 `.claude.json` 中的路径是否为绝对路径
2. 确保 `npm run build` 成功完成
3. 配置更改后重启 Claude Code
### 标志未渲染
1. 检查标志键是否与库匹配（例如，`salesforce.core` 而不是 `salesforce`）
2. 验证 `scraper/logo_library.json` 是否存在
3. 使用 `generic.external-system` 作为备用
### PNG/PDF 导出失败
1. 确保 Puppeteer 已安装：`npm install puppeteer`
2. 检查输出目录的写入权限
3. 尝试使用 `--width=1200` 进行较小的视口
### 构建错误
```bash
# 清洁并重建
rm -rf dist/
npm run build
```
---
## 版本历史
| 版本 | 更改 |
| --- | --- |
| 3.0.0 | 默认使用演示质量的 SVG 幻灯片；CSS 卡片工具标记为旧版 |
| 2.0.0 | 用 HTML/Mermaid/JSON 输出替换 Nano Banana |
| 1.0.0 | 初始版本，带有 Nano Banana 集成 |
