npm package: @sf-explorer/omnistudio-mcp-server
Description: MCP server for analyzing Salesforce OmniStudio dependencies using LangChain and LangGraph
Author: Nicolas Despres
Latest version: 0.1.0

# OmniStudio Dependency Analyzer MCP Server

[![npm version](https://badge.fury.io/js/@sf-explorer%2Fomnistudio-mcp-server.svg)](https://www.npmjs.com/package/@sf-explorer/omnistudio-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **⚠️ Experimental Project**: This is an experimental MCP server implementation that leverages **LangGraph** for intelligent dependency traversal and analysis. We're exploring novel approaches to dependency management and welcome your feedback and contributions!

A powerful MCP (Model Context Protocol) server for analyzing Salesforce OmniStudio dependencies using TypeScript, LangChain, and LangGraph.

## 🚀 Quick Install

```bash
# Use with npx (no installation needed!)
npx @sf-explorer/omnistudio-mcp-server

# Or install globally
npm install -g @sf-explorer/omnistudio-mcp-server
```

Then add to your Claude Desktop or Cursor config - [see Configuration](#️-configuration).

## 🧪 Why This Experimental Approach?

This project explores the intersection of **Model Context Protocol (MCP)** and **LangGraph**'s state-based orchestration to solve complex dependency analysis challenges:

### Benefits of the LangGraph + MCP Approach

- **🎯 State-Based Orchestration**: LangGraph's state machine pattern naturally models dependency traversal, making the analysis flow explicit and maintainable
- **🔄 Recursive Graph Traversal**: Complex nested dependencies (OmniScripts calling IPs calling DataRaptors) are handled elegantly through graph nodes
- **🛡️ Circular Dependency Detection**: Built-in state tracking prevents infinite loops in circular references
- **🎨 Multiple Output Formats**: The graph structure enables easy transformation to Mermaid, GraphViz, D3.js, or JSON visualizations
- **🤖 AI-Ready Architecture**: MCP integration makes it seamless for AI assistants like Claude to analyze and reason about complex OmniStudio architectures
- **🔌 Extensible Pipeline**: Adding new dependency types or analysis steps is as simple as adding new graph nodes

### Why We Need Your Feedback

We're testing whether this architecture can:
- ✅ Scale to large orgs with thousands of components
- ✅ Handle edge cases in real-world OmniStudio deployments
- ✅ Provide actionable insights for migration and refactoring
- ✅ Integrate smoothly with developer workflows

**Your feedback, bug reports, and contributions help shape the future of this approach!**

## 📊 Quick Example: What This Tool Produces

Here's a real example of the dependency analysis output for a customer onboarding flow:

```mermaid
graph TD
    OS001["CustomerOnboarding\n[OmniScript]\nType: Service | SubType: New"]:::omniscript
    IP001["ValidateCustomer\n[IntegrationProcedure]"]:::integration
    IP002["CreateAccount\n[IntegrationProcedure]"]:::integration
    DR001["CustomerExtract\n[DataRaptor Extract]"]:::dataraptor
    DR002["AccountTransform\n[DataRaptor Transform]"]:::dataraptor
    DR003["AccountLoad\n[DataRaptor Load]"]:::dataraptor
    APEX001["CustomerValidationService\n[Apex Class]"]:::apex
    OBJ001["Contact\n[Standard Object]"]:::object
    OBJ002["Account\n[Standard Object]"]:::object
    HTTP001["CreditCheck API\n[External Service]"]:::http
    
    OS001 -->|calls| IP001
    OS001 -->|calls| IP002
    IP001 -->|uses| DR001
    IP001 -->|invokes| APEX001
    IP001 -->|calls| HTTP001
    OBJ001 -->|reads from| DR001
    IP002 -->|uses| DR002
    IP002 -->|uses| DR003
    DR002 -->|uses| DR001
    DR003 -->|writes to| OBJ002
    
    classDef omniscript fill:#4CAF50,stroke:#2E7D32,color:#fff,stroke-width:3px
    classDef integration fill:#2196F3,stroke:#1565C0,color:#fff,stroke-width:2px
    classDef dataraptor fill:#9C27B0,stroke:#6A1B9A,color:#fff,stroke-width:2px
    classDef apex fill:#FF9800,stroke:#E65100,color:#fff,stroke-width:2px
    classDef object fill:#607D8B,stroke:#37474F,color:#fff,stroke-width:2px
    classDef http fill:#F44336,stroke:#C62828,color:#fff,stroke-width:2px
```

**What you see above:**
- 🟢 **OmniScript** initiates the customer onboarding process
- 🔵 **Integration Procedures** handle validation and account creation logic
- 🟣 **DataRaptors** extract, transform, and load customer data
- 🟠 **Apex Class** performs custom business validation
- ⚫ **Salesforce Objects** (Contact, Account) show data flow
- 🔴 **External API** call for credit check verification

This is generated automatically from your Salesforce org metadata. See the [Real-World Example](#-examples--documentation) for more complex scenarios!

## 🌟 Features

- 🔍 **Comprehensive Dependency Analysis**: Analyze OmniScripts, Integration Procedures, FlexCards, LWC, and Apex dependencies
- 🔎 **Type/SubType Search**: Search and analyze OmniScripts and Integration Procedures by their Type and SubType fields (e.g., `Quote_Create`) instead of system-generated names
- 🏢 **Multi-Namespace Support**: Automatically works with Core OmniStudio, vlocity_cmt (Communications Cloud), and vlocity_ins (Financial Services Cloud)
- 📊 **Visual Dependency Graphs**: Generate interactive dependency visualizations in multiple formats
  - Mermaid diagrams (for documentation and Markdown)
  - GraphViz DOT format (for advanced visualizations)
  - D3.js JSON (for interactive web visualizations)
  - JSON (for programmatic access)
- 💬 **Pre-Built MCP Prompts**: 7 ready-to-use prompts for common analysis tasks (analyze, debug, document, explore, etc.) - [See PROMPTS.md](./PROMPTS.md)
- 🔧 **Resource Exposure**: Access and query OmniStudio components through MCP resources
- 🤖 **AI-Powered Analysis**: Leverage LangGraph for intelligent dependency resolution
- 🌐 **MCP Protocol**: Standard Model Context Protocol for seamless integration with AI assistants like Claude
- 🔄 **Namespace Abstraction**: Work with a unified Core API regardless of your OmniStudio deployment type

## 🏗️ Architecture

- **MCP Server**: Built with `@modelcontextprotocol/sdk`
- **Dependency Analysis**: LangGraph for state-based dependency graph construction and traversal
- **AI Integration**: LangChain for extensible AI capabilities
- **Salesforce Integration**: jsforce for robust Salesforce API interactions

## 📦 Installation

### Option 1: Using npx (Recommended) ⭐

The easiest way to use this MCP server is via `npx`:

```bash
# No installation needed! Just use npx in your MCP config
npx @sf-explorer/omnistudio-mcp-server
```

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "omnistudio": {
      "command": "npx",
      "args": ["-y", "@sf-explorer/omnistudio-mcp-server"],
      "env": {
        "SF_AUTH_MODE": "sfdx",
        "SF_SFDX_ORG_ALIAS": "your-org-alias",
        "SF_API_VERSION": "60.0"
      }
    }
  }
}
```

**Benefits:**
- ✅ No manual installation or updates needed
- ✅ Always uses the latest version
- ✅ No need to clone the repository
- ✅ Cleaner setup

### Option 2: Local Development

If you want to contribute or modify the code:

```bash
# Clone the repository
git clone https://github.com/sf-explorer/omnistudio-mcp-server.git
cd omnistudio-mcp-server

# Install dependencies
npm install

# Build the project
npm run build
```

## ⚙️ Configuration

The server supports **three authentication modes**: SFDX, Username/Password, and OAuth.

### Option 1: SFDX Authentication (Recommended) ⭐

If you have an org already authenticated with the Salesforce CLI, you can use it directly:

```bash
# Salesforce Credentials (SFDX Mode)
SF_AUTH_MODE=sfdx
SF_SFDX_ORG_ALIAS=myorg  # Your org alias or username
SF_API_VERSION=60.0

# Server Configuration
MCP_SERVER_NAME=omnistudio-analyzer
MCP_SERVER_VERSION=1.0.0
```

**Prerequisites:**
- Install Salesforce CLI: [https://developer.salesforce.com/tools/salesforcecli](https://developer.salesforce.com/tools/salesforcecli)
- Authenticate your org:
  ```bash
  # New CLI (sf)
  sf org login web --alias myorg
  
  # Or legacy CLI (sfdx)
  sfdx auth:web:login --setalias myorg
  ```

**Benefits of SFDX Mode:**
- ✅ No need to store passwords in `.env` file
- ✅ Uses OAuth tokens automatically
- ✅ Leverages existing CLI authentication
- ✅ Tokens refresh automatically
- ✅ Works with both production and sandbox orgs

### Option 2: Username/Password Authentication

Create a `.env` file with your Salesforce credentials:

```bash
# Salesforce Credentials (Username/Password Mode)
SF_AUTH_MODE=username_password  # Optional, this is the default
SF_USERNAME=your_salesforce_username@example.com
SF_PASSWORD=your_salesforce_password
SF_SECURITY_TOKEN=your_security_token  # Optional if using IP filter
SF_DOMAIN=login  # Use 'test' for sandbox
SF_API_VERSION=60.0

# Server Configuration
MCP_SERVER_NAME=omnistudio-analyzer
MCP_SERVER_VERSION=1.0.0
```

### Option 3: Direct OAuth Token

If you have an OAuth access token, you can use it directly:

```bash
# Salesforce Credentials (OAuth Mode)
SF_AUTH_MODE=oauth
SF_ACCESS_TOKEN=your_oauth_access_token
SF_INSTANCE_URL=https://yourinstance.salesforce.com
SF_API_VERSION=60.0

# Server Configuration
MCP_SERVER_NAME=omnistudio-analyzer
MCP_SERVER_VERSION=1.0.0
```

## 🚀 Usage

### Running the Server

```bash
# Development mode (with hot reload)
npm run dev

# Production mode
npm run build
npm start
```

### Using the Client

```bash
# Build first
npm run build

# Run the example client
npm run client
```

### Integration with Claude Desktop

#### Using npx (Recommended):

```json
{
  "mcpServers": {
    "omnistudio": {
      "command": "npx",
      "args": ["-y", "@sf-explorer/omnistudio-mcp-server"],
      "env": {
        "SF_AUTH_MODE": "sfdx",
        "SF_SFDX_ORG_ALIAS": "your-org-alias",
        "SF_API_VERSION": "60.0"
      }
    }
  }
}
```

#### Using local installation:

```json
{
  "mcpServers": {
    "omnistudio": {
      "command": "node",
      "args": ["/absolute/path/to/omnistudio/dist/index.js"]
    }
  }
}
```

### Integration with VSCode and Cursor

#### Cursor Setup (MCP Support Built-in) ⭐

Cursor has native MCP support built into the editor. Follow these steps:

**Step 1: Authenticate with Salesforce CLI**
```bash
# Install Salesforce CLI if not already installed
# Visit: https://developer.salesforce.com/tools/salesforcecli

# Authenticate your org
sf org login web --alias myorg

# Verify authentication
sf org display --target-org myorg
```

**Step 2: Configure MCP Server**

1. **Open Cursor Settings:**
   - macOS: `Cursor > Settings > Features > Model Context Protocol`
   - Windows/Linux: `File > Preferences > Settings > Features > Model Context Protocol`
   
   OR edit directly: `~/.cursor/mcp_settings.json` (macOS/Linux) or `%APPDATA%\Cursor\mcp_settings.json` (Windows)

2. **Add the configuration** (Using npx - Recommended):
```json
{
  "mcpServers": {
    "omnistudio": {
      "command": "npx",
      "args": ["-y", "@sf-explorer/omnistudio-mcp-server"],
      "env": {
        "SF_AUTH_MODE": "sfdx",
        "SF_SFDX_ORG_ALIAS": "myorg",
        "SF_API_VERSION": "60.0"
      }
    }
  }
}
```

3. **Alternative: Using local installation:**
```json
{
  "mcpServers": {
    "omnistudio": {
      "command": "node",
      "args": ["/absolute/path/to/omnistudio-mcp-server/dist/index.js"]
    }
  }
}
```

**Step 3: Restart Cursor**

Completely quit and restart Cursor to load the MCP server.

**Step 4: Test the Integration**

Open Cursor's AI chat and ask:
- "What OmniStudio namespaces are detected in my org?"
- "List all my OmniScripts"
- "Analyze dependencies for CustomerOnboarding OmniScript"

#### VSCode Setup (Requires Extension)

VSCode requires an MCP extension to support Model Context Protocol servers.

**Step 1: Install MCP Extension**

1. Open VSCode Extensions (`Cmd+Shift+X` / `Ctrl+Shift+X`)
2. Search for "Model Context Protocol" or "MCP"
3. Install a compatible MCP extension (check VSCode Marketplace for current options)

**Step 2: Authenticate with Salesforce CLI**
```bash
# Install Salesforce CLI if not already installed
# Visit: https://developer.salesforce.com/tools/salesforcecli

# Authenticate your org
sf org login web --alias myorg

# Verify authentication
sf org display --target-org myorg
```

**Step 3: Configure MCP Server**

The configuration location depends on your installed MCP extension. Common locations:

1. **Settings.json approach:**
   - Open VSCode Settings (`Cmd+,` / `Ctrl+,`)
   - Search for "MCP" or "Model Context Protocol"
   - Edit settings.json directly

```json
{
  "mcp.servers": {
    "omnistudio": {
      "command": "npx",
      "args": ["-y", "@sf-explorer/omnistudio-mcp-server"],
      "env": {
        "SF_AUTH_MODE": "sfdx",
        "SF_SFDX_ORG_ALIAS": "myorg",
        "SF_API_VERSION": "60.0"
      }
    }
  }
}
```

2. **Workspace settings (.vscode/settings.json):**
```json
{
  "mcp.servers": {
    "omnistudio": {
      "command": "npx",
      "args": ["-y", "@sf-explorer/omnistudio-mcp-server"],
      "env": {
        "SF_AUTH_MODE": "sfdx",
        "SF_SFDX_ORG_ALIAS": "myorg",
        "SF_API_VERSION": "60.0"
      }
    }
  }
}
```

3. **Alternative: Using local installation:**
```json
{
  "mcp.servers": {
    "omnistudio": {
      "command": "node",
      "args": ["/absolute/path/to/omnistudio-mcp-server/dist/index.js"]
    }
  }
}
```

**Step 4: Reload VSCode**

Run the command: "Reload Window" (`Cmd+Shift+P` / `Ctrl+Shift+P` → type "Reload Window")

**Step 5: Test the Integration**

Access the MCP server through your installed extension's interface (varies by extension).

#### Quick Setup Summary (Both Editors)

```bash
# 1. Authenticate with Salesforce CLI (one time)
sf org login web --alias myorg

# 2. Get your org alias
sf org list

# 3. Add MCP configuration (see above for your editor)
# 4. Update SF_SFDX_ORG_ALIAS with your actual org alias
# 5. Restart your IDE

# 6. Test it!
# Ask: "List all OmniScripts in my org"
```

#### Benefits of Using npx:
- ✅ No manual installation or updates needed
- ✅ Always uses the latest version
- ✅ No need to clone the repository
- ✅ Cleaner setup
- ✅ Works identically across different machines

#### Troubleshooting:

**Cursor:**
- Verify MCP is enabled in Cursor settings
- Check Cursor logs: `Help > Toggle Developer Tools > Console`
- Ensure the `omnistudio` server appears in the MCP servers list

**VSCode:**
- Verify MCP extension is installed and active
- Check extension logs in Output panel
- Ensure your MCP extension supports the standard MCP protocol
- Try reloading the window if changes don't take effect

**Both:**
- Verify Salesforce CLI is installed: `sf --version`
- Verify org is authenticated: `sf org display --target-org myorg`
- Check org alias is correct: `sf org list`
- Ensure npx is available: `npx --version`

## 🔧 Available Tools

### 1. **analyze_omniscript_dependencies**
Analyze all dependencies for an OmniScript including Integration Procedures, DataRaptors, and embedded components. **Now supports searching by Type/SubType!**

```typescript
// Search by name
{
  name: "MyOmniScript",
  maxDepth: 5,  // Optional: maximum depth for traversal
  format: "mermaid"  // Options: json, mermaid, graphviz, d3, detailed
}

// OR search by Type/SubType ⭐ NEW
{
  type: "Quote",
  subtype: "Create",
  language: "English",  // Optional, defaults to "English"
  maxDepth: 5,
  format: "mermaid"
}
```

### 2. **analyze_integration_procedure_dependencies**
Analyze Integration Procedure dependencies including DataRaptors, Apex classes, and HTTP actions. **Now supports searching by Type/SubType!**

```typescript
// Search by name
{
  name: "MyIntegrationProcedure",
  maxDepth: 5,
  format: "json"
}

// OR search by Type/SubType ⭐ NEW
{
  type: "Account",
  subtype: "Retrieve",
  maxDepth: 5,
  format: "detailed"
}
```

### 3. **analyze_flexcard_dependencies**
Analyze FlexCard dependencies including Integration Procedures and data sources.

```typescript
{
  name: "MyFlexCard",
  maxDepth: 3,
  format: "mermaid"
}
```

### 4. **list_omniscripts**
List all active OmniScripts in your org.

### 5. **list_integration_procedures**
List all active Integration Procedures.

### 6. **list_flexcards**
List all active FlexCards.

### 7. **get_omniscript_by_type_subtype** ⭐ NEW
Get an OmniScript by its Type and SubType (common way to reference OmniScripts).

```typescript
{
  type: "Quote",           // Type of the OmniScript
  subtype: "Create",       // SubType of the OmniScript
  language: "English"      // Optional, defaults to "English"
}
```

### 8. **get_integration_procedure_by_type_subtype** ⭐ NEW
Get an Integration Procedure by its Type and SubType.

```typescript
{
  type: "Account",         // Type of the Integration Procedure
  subtype: "Retrieve"      // SubType of the Integration Procedure
}
```

### 9. **get_component_details**
Get detailed information about a specific component.

```typescript
{
  name: "ComponentName",
  type: "omniscript"  // Options: omniscript, integration-procedure, flexcard, dataraptor, apex, lwc
}
```

### 10. **get_namespace_info** ⭐ NEW
Get information about detected OmniStudio namespaces in your org (Core, vlocity_cmt, vlocity_ins).

This tool shows:
- Which OmniStudio deployment type you have
- Whether you're using Core OmniStudio, Communications Cloud, or Financial Services Cloud
- How the abstraction layer is handling your specific deployment

## 💬 Pre-Built Prompts ⭐ NEW

The server includes **7 ready-to-use prompts** that help you interact with OmniStudio components more effectively. Prompts follow the [MCP specification](https://modelcontextprotocol.io/) and provide structured guidance for common tasks.

### Available Prompts

1. **`analyze-omniscript`** - Analyze dependencies for a specific OmniScript
2. **`analyze-integration-procedure`** - Analyze dependencies for an Integration Procedure
3. **`explore-omnistudio`** - Get an overview of all OmniStudio components in your org
4. **`debug-dependencies`** - Debug and troubleshoot dependency issues
5. **`document-component`** - Generate comprehensive documentation for a component
6. **`namespace-check`** - Check OmniStudio namespace configuration
7. **`impact-analysis`** - Analyze the impact of changing or removing a component

### Using Prompts in Claude Desktop

Once configured, you can use prompts by simply asking Claude:

```
Use the analyze-omniscript prompt with omniscript_name="CustomerOnboarding"
```

or

```
Use the explore-omnistudio prompt
```

Claude will automatically discover and execute the appropriate prompts, providing you with comprehensive analysis and insights.

### Why Use Prompts?

- ✅ **Consistent**: Ensures you're using tools correctly every time
- ✅ **Complete**: Remembers to check everything you need
- ✅ **Expert**: Encodes best practices for OmniStudio analysis
- ✅ **Time-Saving**: No need to remember tool names and parameters
- ✅ **Discoverable**: Easy to explore what the server can do

**[→ See Full Prompt Documentation](./PROMPTS.md)**

## 🏢 Multi-Namespace Support

The server includes an **abstraction layer** that automatically handles different OmniStudio deployment types:

### Supported Namespaces

1. **Core OmniStudio** (Spring '24+)
   - Objects: `OmniScript__c`, `OmniProcess__c`, `OmniUiCard__c`, `OmniDataTransform__c`
   - Fields: `Type__c`, `SubType__c`, `IsActive__c`, etc.

2. **vlocity_cmt** (Communications Cloud / Vlocity CMT)
   - Objects: `vlocity_cmt__OmniScript__c`, `vlocity_cmt__OmniProcess__c`, etc.
   - Fields: `vlocity_cmt__Type__c`, `vlocity_cmt__SubType__c`, etc.

3. **vlocity_ins** (Financial Services Cloud / Vlocity Insurance)
   - Objects: `vlocity_ins__OmniScript__c`, `vlocity_ins__OmniProcess__c`, etc.
   - Fields: `vlocity_ins__Type__c`, `vlocity_ins__SubType__c`, etc.

### How It Works

```
User Request → Detect Namespace → Build Query → Execute → Normalize Response → Return Core Structure
```

1. **On Connection**: The client automatically detects which namespace(s) exist in your org
2. **Query Translation**: All queries are automatically translated to use the correct namespace
3. **Response Normalization**: All records are normalized to Core structure for consistent processing
4. **Transparent Processing**: The analyzer and tools work with Core types regardless of actual deployment

**Example:**
- You request: "Get OmniScript 'CustomerOnboarding'"
- Server detects: `vlocity_cmt` namespace
- Query executed: `SELECT ... FROM vlocity_cmt__OmniScript__c WHERE vlocity_cmt__Name = 'CustomerOnboarding'`
- Response normalized: `{ Type__c: 'Service', SubType__c: 'New', ... }` (Core structure)
- Processing continues using Core types

**Check Your Namespace:**
```bash
# Use the get_namespace_info tool to see which deployment type you have
```

## 📚 Available Resources

Access OmniStudio components via MCP resources:

- `omnistudio://omniscripts` - All active OmniScripts
- `omnistudio://integration-procedures` - All active Integration Procedures
- `omnistudio://flexcards` - All active FlexCards
- `omnistudio://dataraptors` - All active DataRaptors
- `omnistudio://lwc` - All Lightning Web Components
- `omnistudio://apex` - All Apex Classes
- `omnistudio://omniscript/{name}` - Specific OmniScript
- `omnistudio://integration-procedure/{name}` - Specific Integration Procedure
- `omnistudio://flexcard/{name}` - Specific FlexCard

## 📊 Visualization Examples

### Mermaid Diagram
```mermaid
graph TD
    OS001["CustomerOnboarding\n[OmniScript]"]:::omniscript
    IP001["ValidateCustomer\n[IntegrationProcedure]"]:::integration
    DR001["CustomerDataRaptor\n[DataRaptor]"]:::dataraptor
    OS001 -->|calls| IP001
    IP001 -->|uses| DR001

    classDef omniscript fill:#4CAF50,stroke:#2E7D32,color:#fff
    classDef integration fill:#2196F3,stroke:#1565C0,color:#fff
    classDef dataraptor fill:#9C27B0,stroke:#6A1B9A,color:#fff
```

## 📚 Examples & Documentation

### Real-World Example: MultiSite Quote Order Flow

See a complete production example with step-by-step instructions:

**[→ View MultiSite Quote Order Flow Example](./examples/multisite-quote-order-flow.md)**

This example demonstrates:
- ✅ Multi-level dependency traversal (5 levels deep)
- ✅ DataRaptor object dependencies (reads from / writes to)
- ✅ Standard vs Custom Salesforce objects differentiation
- ✅ Integration Procedure calls with recursive analysis
- ✅ Apex class invocations
- ✅ HTTP Action tracking for external API calls
- ✅ Correct data flow visualization

### User Guide

New to OmniStudio dependency analysis? Start here:

**[→ User Guide with Common Use Cases](./examples/USER_GUIDE.md)**

### Additional Documentation

- [Pre-Built Prompts Guide](./PROMPTS.md) ⭐ NEW
- [Architecture Overview](./ARCHITECTURE.md)
- [Namespace Detection Guide](./NAMESPACE_GUIDE.md)
- [Quick Start Guide](./QUICKSTART.md)
- [Testing Documentation](./TESTING.md)
- [All Examples](./examples/)

## 🧩 Components Analyzed

The server analyzes these OmniStudio and Salesforce components:

- **OmniScripts**: Including embedded OmniScripts and Integration Procedure calls
- **Integration Procedures**: Including DataRaptor actions, Apex calls, and HTTP actions
- **FlexCards**: Including data source Integration Procedures
- **DataRaptors**: Extract, Transform, Load, and Turbo Extract types with object dependencies
- **Lightning Web Components (LWC)**: Custom components
- **Apex Classes**: Including OmniStudio service calls
- **Salesforce Objects**: Both Standard Objects (Account, Opportunity) and Custom Objects (e.g., `vlocity_cmt__PriceList__c`)
- **External APIs**: HTTP endpoints called by Integration Procedures and OmniScripts

## 🔄 Dependency Types

The analyzer tracks these dependency relationships:

- `calls` - Component invokes another (e.g., OmniScript → Integration Procedure, IP → External API)
- `embeds` - Component embeds another (e.g., OmniScript → Embedded OmniScript)
- `uses` - Component uses a resource (e.g., Integration Procedure → DataRaptor)
- `references` - Component references another
- `invokes` - Direct invocation (e.g., Integration Procedure → Apex Class)
- `reads from` - DataRaptor reads from a Salesforce object (arrow: Object → DataRaptor)
- `writes to` - DataRaptor writes to a Salesforce object (arrow: DataRaptor → Object)

## 🛠️ Development

```bash
# Watch mode for development
npm run watch

# Lint code
npm run lint

# Format code
npm run format

# Clean build artifacts
npm run clean
```

## 📝 Example Usage with Claude

Once integrated with Claude Desktop, you can ask:

> "Analyze the dependencies for the CustomerOnboarding OmniScript and show me a visual diagram"

> "List all Integration Procedures in my org"

> "Show me what DataRaptors are used by the OrderProcessing Integration Procedure"

> "Get details about the AccountFlexCard"

## 🔍 How It Works

The server uses **LangGraph** to build a state machine that:

1. **Fetches** component data from Salesforce
2. **Parses** component definitions to extract dependencies
3. **Traverses** the dependency tree recursively
4. **Builds** a complete dependency graph
5. **Generates** visualizations in multiple formats

The state-based approach ensures efficient traversal and prevents infinite loops in circular dependencies.

## 🤝 Contributing

**We actively welcome contributions!** This is an experimental project and your input is invaluable.

### Ways to Contribute

- 🐛 **Report Bugs**: Found an issue? Open a GitHub issue with reproduction steps
- 💡 **Suggest Features**: Have ideas for improving dependency analysis? We'd love to hear them
- 📝 **Improve Documentation**: Help us make this easier to understand and use
- 🧪 **Test with Your Org**: Try it with your Salesforce org and report what works (or doesn't)
- 🔧 **Submit PRs**: Code contributions are highly appreciated
- 💬 **Share Feedback**: Tell us about your experience, pain points, and use cases

### Areas Where We Need Help

- **Performance Testing**: How does it scale with large orgs (1000+ components)?
- **Edge Cases**: Unusual OmniStudio patterns or configurations
- **Visualization**: Better ways to present dependency graphs
- **Integration**: New use cases for MCP + LangGraph patterns
- **Documentation**: Real-world examples and tutorials

### Questions or Ideas?

Open a GitHub issue or discussion. We're here to collaborate and learn together!

## 📄 License

MIT

## 🙏 Acknowledgments

- Built with the [Model Context Protocol](https://modelcontextprotocol.io/)
- Powered by [LangChain](https://js.langchain.com/) and [LangGraph](https://langchain-ai.github.io/langgraphjs/)
- Salesforce integration via [jsforce](https://jsforce.github.io/)

## 🐛 Troubleshooting

### Connection Issues

**For Username/Password Mode:**
- Verify your `.env` file has correct Salesforce credentials
- Check if your security token is current
- For IP-filtered orgs, remove `SF_SECURITY_TOKEN` from `.env`
- For sandbox, set `SF_DOMAIN=test`
- Ensure network connectivity to Salesforce

**For SFDX Mode:**
- Verify org is authenticated: `sf org display --target-org myorg`
- Check org alias exists: `sf org list`
- Re-authenticate if needed: `sf org login web --alias myorg`
- Ensure Salesforce CLI is installed and in PATH
- Verify the org alias in `.env` matches your authenticated org

**For OAuth Mode:**
- Verify access token is valid and not expired
- Check instance URL format (e.g., `https://yourinstance.salesforce.com`)
- Ensure token has required API permissions

### No Data Returned
- Confirm components exist and are active in your org
- Check if you have proper permissions to access the components
- Verify the component names are correct (case-sensitive)

### Dependencies Missing
- Some dependencies may be implicit and not captured in metadata
- Custom implementations may require additional parsing logic
- Check the console for any warnings or errors

## 📮 Support

For issues, questions, or feature requests, please open an issue on GitHub.