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

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

Cross-Object Search

Test Interface

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

⚙️ Configuration

Organization Profiles (data/configs/default.json)

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.