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

Related MCP server: MCP Salesforce Connector

🚀 Quick Start

Prerequisites

• Node.js 18+

• Salesforce org with API access

• Valid Salesforce access tokens

Installation

1. Clone and Install

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

2. 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"
     }
   }

3. 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"]
     }
   }

4. 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:

1. Set features.dmlOperations.enabled: true

2. Enable specific operations (insert, update, etc.)

3. Configure safety guardrails

4. 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

1. Intent Detection: Analyze user question for search type and entities

2. Object Resolution: Map business terms to Salesforce objects using synonyms

3. Field Discovery: Use Describe API to find relevant fields

4. Query Generation: Build optimized SOQL/SOSL queries

5. Data Retrieval: Execute queries with error handling and retries

6. 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

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit changes (git commit -m 'Add amazing feature')

4. Push to branch (git push origin feature/amazing-feature)

5. 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.