Orion Salesforce MCP Server

A powerful and intelligent Salesforce data interaction server designed specifically for wholesale distribution systems. This MCP (Model Control Plane) server provides natural language querying capabilities with advanced SOQL/SOSL generation, intelligent field resolution, and comprehensive data manipulation features.

🌟 Key Features

Intelligent Data Querying

Natural Language to SOQL: Convert plain English questions into optimized Salesforce queries
Smart Object & Field Resolution: Automatically map business terms to Salesforce API names using configurable synonyms
Cross-Object Search (SOSL): Search across multiple objects simultaneously with intelligent result aggregation
Relationship Traversal: Automatically handle lookups and master-detail relationships
Time-Sensitive Filtering: Intelligent date range detection and application

Data Manipulation (DML)

Controlled DML Operations: Configurable Insert, Update, Upsert, Delete, Undelete, and Merge capabilities
Feature Flags: Granular control over DML operations with org-specific configuration
Safety Guardrails: Built-in limits, confirmation requirements, and bulk operation controls
Permission Respect: Honor Salesforce field-level security and object permissions

Hybrid AI Responses

Data-Driven Answers: Combine actual Salesforce data with LLM knowledge for contextual responses
Intelligent Fallbacks: Graceful handling when data is unavailable or insufficient
Business Context: Understand wholesale distribution terminology and processes

Enterprise-Ready Architecture

Multi-Org Support: Configure different Salesforce orgs with unique settings and permissions
Robust Error Handling: Comprehensive Salesforce API error handling with clear user feedback
Security First: Token management, PII redaction, and configurable access controls
Performance Optimized: Intelligent caching, query optimization, and efficient API usage

🚀 Quick Start

Prerequisites

Node.js 18+
Salesforce org with API access
Valid Salesforce access tokens

Installation

Clone and Install

git clone https://github.com/jasonjuela/orion-salesforce-mcp-server.git
cd orion-salesforce-mcp-server
npm install

Configure Salesforce Tokens

cp data/secrets/tokens.example.json data/secrets/tokens.json

Edit data/secrets/tokens.json with your Salesforce credentials:

{
  "default": {
    "access_token": "your_access_token_here",
    "instance_url": "https://your-instance.salesforce.com",
    "token_type": "Bearer"
  }
}

Customize Organization Profile

Edit data/configs/default.json to match your Salesforce org structure:

{
  "orgId": "your-org-name",
  "namespaces": ["your_namespace__"],
  "objectSynonyms": {
    "owsc__Item__c": ["wine", "product", "inventory"],
    "owsc__Order__c": ["order", "purchase order", "po"]
  }
}

Start the Server
```
npm start
```
Server runs on http://localhost:3018

📖 Usage Examples

Basic Querying

# Natural language queries
curl -X POST http://localhost:3018/generate/stream \
  -H "Content-Type: application/json" \
  -d '{
    "user_question": "What is the alcohol percentage of Cockburn'\''s wines?",
    "orgId": "default",
    "sessionId": "demo"
  }'

Cross-Object Search

# Search across multiple objects
curl -X POST http://localhost:3018/generate/stream \
  -H "Content-Type: application/json" \
  -d '{
    "user_question": "search for Smith across all objects",
    "orgId": "default", 
    "sessionId": "demo"
  }'

Test Interface

Open http://localhost:3018 in your browser for a simple web interface to test queries.

⚙️ Configuration

Organization Profiles (`data/configs/default.json`)

{
  "orgId": "wholesale-system",
  "description": "Wholesale distribution system configuration",
  "namespaces": ["owsc__"],
  
  "guardrails": {
    "piiRedaction": true,
    "maxRows": 1000,
    "defaultDateRange": "LAST_N_MONTHS:6",
    "allowedObjects": [],
    "blockedObjects": ["UserRecordAccess", "ObjectPermissions"]
  },
  
  "features": {
    "dmlOperations": {
      "enabled": false,
      "allowedOperations": {
        "insert": false,
        "update": false,
        "upsert": false,
        "delete": false,
        "undelete": false,
        "merge": false
      },
      "safeguards": {
        "maxRecordsPerOperation": 50,
        "requireConfirmation": true,
        "allowBulkOperations": false
      }
    }
  },
  
  "objectSynonyms": {
    "owsc__Item__c": ["wine", "product", "inventory", "item"],
    "owsc__Order__c": ["order", "purchase order", "po"],
    "Account": ["account", "customer", "client"]
  }
}

DML Operations

To enable data manipulation:

Set features.dmlOperations.enabled: true
Enable specific operations (insert, update, etc.)
Configure safety guardrails
Specify allowed/blocked objects in dmlRestrictions

🏗️ Architecture

Core Components

Planner Service (src/services/planner.js): Intent detection and query generation
Salesforce Service (src/services/salesforce.js): API client with retry logic
Intelligent Resolver (src/services/intelligentResolver.js): Object and field mapping
Stream Generator (src/routes/generateStream.js): Main orchestration and LLM integration

Data Flow

Intent Detection: Analyze user question for search type and entities
Object Resolution: Map business terms to Salesforce objects using synonyms
Field Discovery: Use Describe API to find relevant fields
Query Generation: Build optimized SOQL/SOSL queries
Data Retrieval: Execute queries with error handling and retries
Response Generation: Combine data with LLM for intelligent answers

🔧 API Endpoints

Primary Endpoints

POST /generate/stream - Main query interface with streaming responses
GET /auth/login - Salesforce OAuth initiation (placeholder)
GET /auth/callback - OAuth callback handler (placeholder)
GET /search/capabilities - Check available search capabilities
POST /search/cross-object - Direct SOSL search endpoint

Response Format

Streaming responses include:

Query plan (SOQL/SOSL)
Data retrieval status
Record count
Formatted results
LLM-generated insights

🛡️ Security Features

Token Management: Secure credential storage and rotation
PII Redaction: Configurable personally identifiable information filtering
Object Whitelisting: Control access to specific Salesforce objects
Field-Level Security: Respect Salesforce permissions
Query Limits: Prevent expensive or dangerous operations
Feature Flags: Granular control over dangerous operations like DML

🎯 Wholesale Distribution Focus

Optimized for wholesale/distribution use cases:

Inventory Management: Track items, lots, containers, and locations
Order Processing: Handle purchase orders, sales orders, and fulfillment
Supply Chain: Manage vendors, warehouses, and shipping
Financial Operations: Support invoicing, payments, and accounting
Business Intelligence: Aggregate data for reporting and analytics

🚦 Production Considerations

Performance

Implement response caching for frequent queries
Use connection pooling for Salesforce API calls
Add request rate limiting
Monitor API usage limits

Security

Implement proper OAuth flows
Add request authentication/authorization
Enable HTTPS in production
Regular token rotation
Audit logging

Monitoring

Add comprehensive logging
Implement health checks
Monitor Salesforce API limits
Track query performance metrics

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For questions, issues, or feature requests:

Open an issue on GitHub
Check existing documentation
Review configuration examples

Built for intelligent Salesforce data interaction with wholesale distribution in mind.