jasonjuela/salesforce-mcp-server

Salesforce MCP Server

A Node.js (Express-based) server that implements a Salesforce-aware MCP (Model Context Protocol) microservice, designed to interface with any LLM (starting with OpenAI's API). This server can receive natural language input, retrieve Salesforce schema metadata via OAuth2 from a live org, and return structured LLM responses in text, markdown, charts, or tabular JSON format.

🚀 Features

• Natural Language Interface: Ask questions about your Salesforce org in plain English
• OAuth2 Authentication: Secure Salesforce authentication using OAuth2 Authorization Code flow
• Schema Awareness: Understands custom objects, fields, and relationships
• Multiple Response Formats: Returns data as text, markdown, tables, or charts
• Streaming Support: Real-time streaming responses from OpenAI
• Privacy-Aware Logging: Automatic PII redaction in logs
• Namespace Support: Special handling for custom namespaces (like owsc__)

🏗️ Architecture

src/
├── app.js                 # Main Express application
├── routes/
│   ├── auth.js           # OAuth2 authentication routes
│   └── generate.js       # Main API endpoints
├── services/
│   ├── salesforceService.js  # Salesforce API integration
│   └── mcpService.js     # MCP prompt construction logic
├── llmAdapters/
│   └── openaiAdapter.js  # OpenAI API integration
├── middleware/
│   ├── auth.js           # JWT authentication middleware
│   └── errorHandlers.js  # Error handling middleware
└── utils/
    ├── logger.js         # Privacy-aware logging
    └── validation.js     # Input validation utilities

📦 Installation

1. Clone the repository

   git clone <repository-url>
   cd salesforce-mcp-server
   

2. Install dependencies

   npm install
   

3. Configure environment variables

   cp env.example .env
   

   Edit .env with your configuration:

   # Server Configuration
   PORT=3000
   NODE_ENV=development
   
   # OpenAI Configuration
   OPENAI_API_KEY=sk-your-openai-api-key-here
   OPENAI_MODEL=gpt-4o
   
   # Salesforce OAuth2 Configuration
   SALESFORCE_CLIENT_ID=your-salesforce-client-id
   SALESFORCE_CLIENT_SECRET=your-salesforce-client-secret
   SALESFORCE_REDIRECT_URI=http://localhost:3000/auth/callback
   
   # JWT Configuration
   JWT_SECRET=your-jwt-secret-key-here
   
   # Custom Namespace
   CUSTOM_NAMESPACE=owsc__
   

4. Start the server

   # Development mode with auto-reload
   npm run dev
   
   # Production mode
   npm start
   

🔧 Configuration

Salesforce Connected App Setup

1. In Salesforce Setup, create a new Connected App:

   • App Name: Salesforce MCP Server
   • API Name: salesforce_mcp_server
   • Contact Email: your-email@domain.com

2. Enable OAuth Settings:

   • Callback URL: http://localhost:3000/auth/callback
   • Selected OAuth Scopes:
     • Access and manage your data (api)
     • Perform requests on your behalf at any time (refresh_token, offline_access)
     • Access your basic information (id, profile, email, address, phone)

3. Note the Consumer Key and Consumer Secret for your .env file

OpenAI Setup

1. Get your API key from OpenAI Platform
2. Add it to your .env file as OPENAI_API_KEY

🔐 Authentication Flow

1. Initiate Login

   curl -X GET http://localhost:3000/auth/login
   

2. Follow the returned URL to authenticate with Salesforce

3. Use the returned JWT token in subsequent API calls:

   Authorization: Bearer <jwt-token>
   

📡 API Endpoints

Authentication

• GET /auth/login - Initiate Salesforce OAuth2 login
• GET /auth/callback - OAuth2 callback handler
• POST /auth/refresh - Refresh access token
• GET /auth/status - Check authentication status
• POST /auth/logout - Logout

Main API

• POST /api/generate - Main endpoint for natural language queries
• GET /api/objects - Get all custom objects
• GET /api/objects/:objectName - Get object metadata
• GET /api/search?q=<term> - Search metadata

Generate Request Format

{
  "user_question": "What is owsc__Order__c?",
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 4000
}

Response Format

{
  "type": "markdown",
  "content": "# owsc__Order__c Object\n\nThe **owsc__Order__c** object represents...",
  "metadata": {
    "objects": ["owsc__Order__c"],
    "intent": "explain_object",
    "confidence": 0.9,
    "timestamp": "2024-01-15T10:30:00.000Z",
    "processingTime": 1234
  }
}

🧪 Test Scenarios

The server handles these types of questions:

Object & Field Understanding

"What is owsc__Action__c?"
"Explain the fields on owsc__Action_Item__c."
"What fields are on owsc__Shipment__c?"

Relationships & Schema Exploration

"How is owsc__Order__c related to Account?"
"List all custom objects in the owsc__ namespace."
"Show me the relationships for owsc__Product__c."

Data Queries

"What are my sales for July 2025?"
"Show me recent orders."
"List all accounts in the wine industry."

Visual Output

"Show a chart of sales by wine type."
"List barrels by age in a table."
"Create a visualization of order trends."

🔍 Response Types

The server returns responses in different formats based on the question:

• text: Simple text responses
• markdown: Formatted documentation with headers, lists, etc.
• table: Structured tabular data
• chart: Chart.js configuration for data visualization
• json: Raw JSON data for complex structures

🛡️ Security Features

• JWT Authentication: Secure token-based authentication
• PII Redaction: Automatic removal of sensitive data from logs
• Rate Limiting: Protection against API abuse
• Input Validation: Comprehensive input sanitization
• CORS Protection: Configurable cross-origin resource sharing

📝 Logging

The server includes privacy-aware logging that automatically redacts:

• Email addresses
• Salesforce record IDs
• Credit card numbers
• SSNs
• Other PII patterns

Logs are stored in ./logs/ directory with rotation.

🚀 Development

Running Tests

npm test

Development Mode

npm run dev

Debugging

Set LOG_LEVEL=debug in your .env file for detailed logging.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

For issues and questions:

1. Check the logs in ./logs/ directory
2. Verify your .env configuration
3. Ensure Salesforce Connected App is properly configured
4. Check that your OpenAI API key is valid

🔗 Related Documentation

• Salesforce REST API
• OpenAI API
• Express.js
• OAuth 2.0