Content
# Salesforce Architecture Diagram MCP Server
## Purpose
The **sfdc-arch-mcp** server is a Model Context Protocol (MCP) server that enables AI assistants to generate professional, presentation-quality Salesforce architecture diagrams. It provides:
- **Curated SVG Logo Library** — 1700+ real company logos (not AI-generated approximations)
- **Salesforce Brand Standards** — Colors, typography, and spacing from architect.salesforce.com
- **Presentation-Quality SVG Slides** — Full-bleed landscape slides with free-form node placement, curved connectors, and Salesforce branding
- **Well-Architected Validation** — Anti-pattern detection and architectural best practices
- **Mermaid Diagrams** — For documentation and wikis
### What It Does
| Capability | Description |
|------------|-------------|
| Generate SVG Slide Diagrams | Presentation-quality architecture slides (default approach) |
| Generate Mermaid Diagrams | Markdown-based diagrams for documentation and wikis |
| Validate Architecture | Check designs against Salesforce Well-Architected pillars |
| Provide Design Specs | Retrieve Salesforce brand colors, spacing, and patterns |
| Export to Image | Convert HTML slides to PNG/PDF/SVG |
### Diagram Types Supported
- **System Landscape** — Source/target orgs, integration architecture, external systems
- **Module Architecture** — Layered module dependencies with cross-layer connectors
- **Data Pipeline / Flow** — SDK pipelines, instrumentation flows, processing stages
- **Sequence Diagrams** — Bootstrap flows, integration message sequences
- **Data Model (ERD)** — Entities, fields, and relationships (Mermaid)
### Diagram Output: SVG Slides (Default)
All architecture diagrams should be generated as **raw HTML with inline SVG** — full-bleed landscape slides matching Salesforce engineering workshop quality. See `docs/PRESENTATION_DIAGRAMS.md` for the complete guide and `context/slide-template.html` for a ready-to-copy template.
Do NOT use `generate_html_diagram` or `generate_html_diagram_v2` MCP tools — those produce CSS card/grid layouts which are not presentation quality.
---
## Setup Instructions
### Prerequisites
- Node.js 18+ installed
- Claude Code (or another MCP-compatible client)
- npm package manager
### Installation
```bash
# Clone or navigate to the project
cd /path/to/sfdc-arch-mcp
# Install dependencies
npm install
# Build TypeScript
npm run build
# Verify build succeeded
ls dist/index.js
```
### Configure MCP Client
Add the server to your Claude Code MCP configuration file.
**Location:** `~/.claude.json` or project-level `.claude.json`
```json
{
"mcpServers": {
"sfdc-designer": {
"command": "node",
"args": ["/absolute/path/to/sfdc-arch-mcp/dist/index.js"]
}
}
}
```
**Example with actual path:**
```json
{
"mcpServers": {
"sfdc-designer": {
"command": "node",
"args": ["/Users/michael.falkner/sfdc-arch-mcp/dist/index.js"]
}
}
}
```
### Verify Setup
After configuring, restart your AI client. The MCP tools should be available:
- `mcp__sfdc-designer__get_sfdc_specs` — brand colors and design specs
- `mcp__sfdc-designer__criticize_architecture` — Well-Architected validation
- `mcp__sfdc-designer__generate_mermaid_diagram` — Mermaid diagrams for docs
- `mcp__sfdc-designer__export_to_image` — HTML to PNG/PDF export
- `mcp__sfdc-designer__list_logos` — discover available SVG logos
For architecture diagrams, the AI writes raw SVG HTML directly (no MCP tool needed). See `docs/PRESENTATION_DIAGRAMS.md` and `context/slide-template.html`.
---
## How to Use
### Method 1: Natural Language Prompts (Recommended)
Describe the architecture diagram you want. The AI assistant will write raw HTML with inline SVG, using `context/slide-template.html` as a starting point.
#### Architecture Diagrams (SVG Slides)
```
Create a system landscape diagram showing our Salesforce org integrating with
SAP, MuleSoft, and Snowflake. Save as a presentation-quality SVG slide.
```
```
Generate a module dependency diagram showing our SDK layers: API at the bottom,
instrumentation and implementation in the middle, agent and extension at top,
with curved connector lines between layers.
```
```
Build a data pipeline diagram showing Application → Instrumentation → SDK →
Processing → Backend with free-form node placement and bezier curve connectors.
```
```
Create a migration architecture slide showing our ACW source org connected to
UA target org via Gearset, with data flow arrows and labeled connections.
```
#### Mermaid Diagrams (for Documentation)
```
Generate a Mermaid flowchart showing our integration architecture. I need this
for our Confluence documentation.
```
```
Create a Mermaid sequence diagram showing the API call flow between Salesforce,
MuleSoft, and SAP for order processing.
```
```
Build a Mermaid ERD for our Salesforce data model that I can embed in GitHub README.
```
#### Architecture Validation
```
Review this architecture for anti-patterns: We have 6 external systems all
directly connected to Salesforce without a middleware layer, and we're using
basic authentication for the SAP integration.
```
### Method 2: CLI Tool for Batch Processing
For generating multiple diagrams or specific export formats:
```bash
node scripts/generate-diagram.js config.json output --png --pdf
node scripts/generate-diagram.js --batch configs/ --all --output-dir=./output
```
---
## CLI Commands Reference
### Generate Single Diagram
```bash
# Basic HTML output
node scripts/generate-diagram.js config.json
# HTML + PNG
node scripts/generate-diagram.js config.json output.html --png
# All formats (HTML, PNG, PDF, SVG)
node scripts/generate-diagram.js config.json output --all
# High resolution PNG
node scripts/generate-diagram.js config.json output --png --scale=3 --width=1920
```
### Batch Processing
```bash
# Process all JSON configs in a directory
node scripts/generate-diagram.js --batch configs/ --png --output-dir=./diagrams
# All formats for batch
node scripts/generate-diagram.js --batch configs/ --all --output-dir=./output
```
### CLI Options
| Option | Description | Default |
|--------|-------------|---------|
| `--png` | Generate PNG image | - |
| `--pdf` | Generate PDF document | - |
| `--svg` | Generate SVG vector | - |
| `--all` | Generate all formats | - |
| `--png-only` | Only PNG, no HTML | - |
| `--pdf-only` | Only PDF, no HTML | - |
| `--width=N` | Viewport width in pixels | 1400 |
| `--scale=N` | Resolution scale factor | 2 |
| `--batch <dir>` | Process all .json files in directory | - |
| `--output-dir <dir>` | Output directory for batch mode | ./output |
| `--open` | Open result after generation | - |
---
## Example Prompts by Use Case
### System Landscape
```
Create a presentation-quality architecture slide showing our Salesforce org
at the center, with MuleSoft as the integration layer connecting to SAP (ERP),
Workday (HR), and Snowflake (Analytics). Use curved connector lines with
flow labels showing data direction.
```
### Migration Architecture
```
Build an architecture slide showing data migration from our legacy ACW org
to a new UA org via Gearset. Show Accounts, Contacts, and Opportunities
flowing through the migration tool with labeled connections.
```
### Module Dependencies
```
Create a multi-layer module architecture diagram with API at the bottom,
SDK in the middle, Instrumentation and Extension layers above, and Agent
at the top. Show cross-layer dependency lines with "depends" and "implements"
labels. Use different colors per layer.
```
### Data Pipeline / Processing Flow
```
Build a data pipeline diagram showing: Application → Instrumentation →
SDK Processing → Exporters → Backend Services. Place components in
free-form layout with bezier curve connectors and flow label badges.
```
### Architecture Review
```
Review this proposed architecture for issues:
- Direct SOAP connections from Salesforce to 5 different legacy systems
- API credentials stored in Salesforce custom metadata
- No retry logic or error handling
- All integrations run synchronously on record save
```
### Mermaid for Documentation
```
I need Mermaid diagrams for our technical documentation:
1. A flowchart showing our order-to-cash process
2. A sequence diagram showing the quote approval workflow
3. An ERD showing our custom objects for inventory management
```
---
## Available Tools Reference
### SVG Slide Diagrams (Primary Approach)
Architecture diagrams are generated by writing raw HTML with inline SVG. No MCP tool call needed — the AI writes the HTML directly using the template and patterns from `docs/PRESENTATION_DIAGRAMS.md`.
- **Template**: `context/slide-template.html`
- **Guide**: `docs/PRESENTATION_DIAGRAMS.md`
- **Visual references**: `context/image (17).png`, `context/image (18).png`, `context/image (19).png`
### generate_mermaid_diagram
Generates Mermaid markdown diagrams.
**Best for:** Documentation, wikis, GitHub READMEs, Confluence
**Parameters:**
- `type` (required): `flowchart` | `sequence` | `erd` | `mindmap`
- `direction`: `TB` | `BT` | `LR` | `RL` (for flowcharts)
- `title`: Diagram title
- `nodes`: Flowchart nodes
- `connections`: Node connections
- `entities`: ERD entities
- `relationships`: ERD relationships
- `participants`: Sequence diagram participants
- `messages`: Sequence diagram messages
### get_sfdc_specs
Retrieves Salesforce design specifications.
**Best for:** Getting brand colors, spacing values, design patterns
**Parameters:**
- `category`: `colors` | `spacing` | `cards` | `headers` | `connectors` | `patterns` | `levels` | `all`
- `cloudType`: `salesCloud` | `serviceCloud` | `platform` | `industries` | `nonprofit`
### criticize_architecture
Validates architecture against Well-Architected pillars.
**Best for:** Architecture reviews, anti-pattern detection, design validation
**Parameters:**
- `description`: Natural language description of the architecture
- `diagramSchema`: Structured schema with components and connections
**Detects Anti-Patterns:**
- God Flow (massive single Flow)
- Hard-coded IDs/Secrets
- Point-to-Point Integration
- Data Silos
- Admin User for Integration
### export_to_image
Exports HTML to PNG/JPEG/PDF/SVG via Puppeteer.
**Best for:** Converting SVG slide HTML files to image formats
### Legacy Tools (Not Recommended)
The following tools produce CSS card/grid layouts and should NOT be used for architecture diagrams:
- `generate_html_diagram` — produces CSS card-based layouts
- `generate_html_diagram_v2` — produces CSS card-based layouts with containers
- `generate_diagram_config` — produces JSON configs for the legacy card tools
---
## Logo Library Reference
Use these keys in the `logo` field of nodes:
### Salesforce Products
| Key | Product |
|-----|---------|
| `salesforce.core` | Salesforce Cloud (generic) |
| `salesforce.sales-cloud` | Sales Cloud |
| `salesforce.service-cloud` | Service Cloud |
| `salesforce.marketing-cloud` | Marketing Cloud |
| `salesforce.commerce-cloud` | Commerce Cloud |
| `salesforce.experience-cloud` | Experience Cloud |
| `salesforce.data-cloud` | Data Cloud |
| `salesforce.tableau` | Tableau |
| `salesforce.mulesoft` | MuleSoft |
| `salesforce.slack` | Slack |
| `salesforce.heroku` | Heroku |
### Integration Platforms
| Key | Platform |
|-----|----------|
| `integration.mulesoft` | MuleSoft Anypoint |
| `integration.informatica` | Informatica |
| `integration.boomi` | Dell Boomi |
| `integration.jitterbit` | Jitterbit |
| `integration.workato` | Workato |
### Cloud Providers
| Key | Provider |
|-----|----------|
| `cloud.aws` | Amazon Web Services |
| `cloud.azure` | Microsoft Azure |
| `cloud.gcp` | Google Cloud Platform |
| `cloud.snowflake` | Snowflake |
### Enterprise Systems
| Key | System |
|-----|--------|
| `enterprise.sap` | SAP |
| `enterprise.oracle` | Oracle |
| `enterprise.workday` | Workday |
| `enterprise.servicenow` | ServiceNow |
| `enterprise.microsoft` | Microsoft |
### DevOps Tools
| Key | Tool |
|-----|------|
| `tools.gearset` | Gearset |
| `tools.copado` | Copado |
| `tools.dataloader` | Data Loader |
| `tools.github` | GitHub |
| `tools.gitlab` | GitLab |
| `tools.jira` | Jira |
| `tools.confluence` | Confluence |
### Generic Icons
| Key | Icon |
|-----|------|
| `generic.database` | Database cylinder |
| `generic.cloud` | Cloud shape |
| `generic.settings` | Gear/settings |
| `generic.api` | API connector |
| `generic.external-system` | Generic external system |
---
## Brand Colors Reference
| Color Name | Hex | Usage |
|------------|-----|-------|
| Sales Cloud | `#0176D3` | Sales-related diagrams |
| Service Cloud | `#FF5D2D` | Service-related diagrams |
| Platform Navy | `#032D60` | Headers, primary text |
| Success Green | `#2E844A` | Target orgs, success states |
| Industries Teal | `#0B827C` | Source orgs, industries |
| Warning Yellow | `#FFB75D` | Callouts, warnings |
| Error Red | `#EA001B` | Errors, anti-patterns |
| Neutral Gray | `#706E6B` | Secondary elements |
---
## Troubleshooting
### MCP Server Not Found
1. Verify the path in `.claude.json` is absolute
2. Ensure `npm run build` completed successfully
3. Restart Claude Code after configuration changes
### Logos Not Rendering
1. Check the logo key matches the library (e.g., `salesforce.core` not `salesforce`)
2. Verify `scraper/logo_library.json` exists
3. Use `generic.external-system` as fallback
### PNG/PDF Export Fails
1. Ensure Puppeteer is installed: `npm install puppeteer`
2. Check write permissions on output directory
3. Try with `--width=1200` for smaller viewports
### Build Errors
```bash
# Clean and rebuild
rm -rf dist/
npm run build
```
---
## Version History
| Version | Changes |
|---------|---------|
| 3.0.0 | Default to presentation-quality SVG slides; CSS card tools marked legacy |
| 2.0.0 | Replaced Nano Banana with HTML/Mermaid/JSON output |
| 1.0.0 | Initial release with Nano Banana integration |
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available