Salesforce Metadata-Aware RAG MCP

A Model Context Protocol (MCP) server that provides advanced RAG capabilities for Salesforce metadata and code, enabling AI copilots to understand your Salesforce org configuration through intelligent chunking and vector search.

Features

Core Salesforce Integration

• Metadata API Integration: Access layouts, flows, custom objects, profiles, and permission sets
• Tooling API Integration: Retrieve Apex classes, triggers, and validation rules
• REST API Integration: Object schema descriptions and SOQL execution
• Rate Limiting: Built-in API quota management and retry logic
• Incremental Sync: Efficient updates for large orgs

Advanced RAG Capabilities

• Intelligent Chunking: Metadata-aware chunking system that splits Apex classes by methods, objects by fields, etc.
• Vector Indexing: PostgreSQL + pgvector for semantic similarity search
• Keyword Search: Full-text search with BM25 ranking
• Symbol Search: Exact matching for Salesforce objects, fields, and code symbols
• Hybrid Search: Combined vector + keyword search with intelligent reranking

MCP Integration

• Direct Claude Code Integration: Real-time Salesforce org exploration
• Structured Metadata Access: Type-aware retrieval and processing
• Symbol Extraction: Automatic discovery of relationships and dependencies

Available MCP Tools

• sf_metadata_list - List metadata components of specified types
• sf_tooling_getApexClasses - Retrieve all Apex classes from the org
• sf_describe_object - Describe a Salesforce object schema
• rag_status - Get system status and API usage stats

Development Setup

Prerequisites

• Node.js 18+ and npm
• Docker and Docker Compose (for PostgreSQL + pgvector)
• Salesforce org access (sandbox recommended for testing)
• Connected App or Username/Password authentication
• Python 3.8+ with sentence-transformers (optional, for production embeddings)

Installation

1. Clone and install dependencies:

npm install

2. Configure Salesforce credentials in .env:

# Copy the example file
cp .env.example .env

# Edit .env with your Salesforce credentials
SF_USERNAME="your_username@company.com"
SF_PASSWORD="your_password"
SF_SECURITY_TOKEN="your_security_token"
SF_LOGIN_URL="https://test.salesforce.com"  # Use for sandbox

3. Start PostgreSQL with pgvector:

docker compose up -d postgres

4. Build the project:

npm run build

Running the Server

MCP Server (for Claude Code):

npm run dev

Vector Integration Testing:

# Test chunking system
node dist/test-chunking.js

# Test full vector integration
node dist/test-vector-integration.js

# Test with live Salesforce data
node dist/test-mcp-chunking.js

Type checking:

npm run typecheck

MCP Integration

To integrate with VS Code or Claude Desktop, add this configuration to your MCP settings:

For Claude Desktop (add to claude_desktop_config.json):

{
  "mcpServers": {
    "salesforce-rag": {
      "command": "node",
      "args": ["/path/to/sfdxrag/dist/index.js"],
      "cwd": "/path/to/sfdxrag",
      "env": {
        "NODE_ENV": "production",
        "SF_LOGIN_URL": "https://your-org.my.salesforce.com/",
        "SF_USERNAME": "your_username@company.com",
        "SF_PASSWORD": "your_password",
        "SF_SECURITY_TOKEN": "your_security_token",
        "DOTENV_SILENT": "true",
        "LOG_LEVEL": "error"
      }
    }
  }
}

For Claude Code (add to .mcp.json in your workspace):

{
  "mcpServers": {
    "salesforce-rag": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/path/to/sfdxrag",
      "env": {
        "SF_LOGIN_URL": "https://your-org.my.salesforce.com/",
        "SF_USERNAME": "your_username@company.com",
        "SF_PASSWORD": "your_password",
        "SF_SECURITY_TOKEN": "your_security_token",
        "DOTENV_SILENT": "true",
        "LOG_LEVEL": "error"
      }
    }
  }
}

Adding to Claude Code MCP:

1. Create or update .mcp.json in your workspace root:

# Navigate to your project directory
cd /path/to/your-project

# Create .mcp.json with the salesforce-rag server configuration above
# Update the "cwd" path to point to your sfdxrag installation directory

2. Alternative: Use Claude Code MCP command:

claude mcp add salesforce-rag --env SF_LOGIN_URL=https://test.salesforce.com --env SF_USERNAME=your_salesforce_username --env SF_PASSWORD=your_salesforce_password --env SF_SECURITY_TOKEN=your_security_token --env NODE_ENV=development --env LOG_LEVEL=info -- npm run dev --cwd="/path to sfdxrag/"

After setting up:

1. Restart Claude Code/Desktop to reload MCP configuration
2. Test MCP tools:
   • sf_describe_object with {"objectName": "Account"}
   • sf_metadata_list with {"types": ["ApexClass", "Layout"]}
   • rag_status to check system health

Project Structure

src/
├── salesforce/          # Salesforce API clients
│   ├── connection.ts    # Authentication layer
│   ├── metadataClient.ts # Metadata API wrapper
│   ├── toolingClient.ts # Tooling API wrapper
│   └── restClient.ts    # REST API wrapper
├── chunking/           # Metadata chunking system
│   ├── types.ts        # Core interfaces and types
│   ├── base.ts         # Base chunker implementation
│   ├── apexChunker.ts  # Apex class method-level chunking
│   ├── customObjectChunker.ts # Object field-level chunking
│   ├── factory.ts      # Chunker selection factory
│   └── processor.ts    # Main processing pipeline
├── vector/             # Vector storage and search
│   ├── embedding.ts    # Embedding model interface and implementations
│   └── store.ts        # PostgreSQL + pgvector client
├── utils/              # Utilities
│   ├── logger.ts       # Winston logging setup
│   ├── errorHandler.ts # Global error handling
│   ├── rateLimiter.ts  # API rate limiting
│   └── packageGenerator.ts # package.xml generation
├── config/            # Configuration management
│   └── index.ts       # Environment config loader
├── mcp/              # MCP server implementation
│   └── server.ts     # MCP tool handlers
└── index.ts          # Main entry point

Environment Variables

Required for Salesforce connectivity:

• SF_USERNAME - Salesforce username
• SF_PASSWORD - Salesforce password
• SF_SECURITY_TOKEN - Salesforce security token
• SF_LOGIN_URL - Login URL (https://login.salesforce.com or https://test.salesforce.com)

Optional configuration:

• NODE_ENV - Environment (development/production)
• LOG_LEVEL - Logging level (debug/info/warn/error)
• PORT - Server port (default: 3000)
• DB_HOST - PostgreSQL host (default: localhost)
• DB_PORT - PostgreSQL port (default: 5433)
• DB_NAME - Database name (default: sfdxrag)
• DB_USER - Database user (default: postgres)
• DB_PASSWORD - Database password (default: postgres)

Architecture

Data Flow

1. Metadata Extraction: Retrieve Salesforce metadata via API clients
2. Intelligent Chunking: Process metadata using type-specific chunkers
3. Vector Indexing: Generate embeddings and store in PostgreSQL + pgvector
4. Search & Retrieval: Multi-modal search (vector + keyword + symbol)

Chunking System

The system includes specialized chunkers for different metadata types:

• ApexChunker: Splits classes by methods, preserving signatures and docblocks
• CustomObjectChunker: Splits objects by fields, validation rules, and metadata
• GenericChunker: Fallback for unsupported types

Vector Search

• Vector Search: Semantic similarity using sentence transformers
• Keyword Search: Full-text search with BM25 ranking
• Symbol Search: Exact matching for Salesforce symbols (objects, fields, classes)
• Hybrid Search: Combined search with intelligent reranking (70% vector, 30% keyword)

Testing

Current Test Coverage

✅ Chunking System: Apex classes split into method-level chunks with symbol extraction
✅ Vector Storage: PostgreSQL + pgvector integration with batch operations
✅ Search Functions: Vector, keyword, symbol, and hybrid search working
✅ MCP Integration: Live Salesforce data retrieval and processing
✅ Symbol Detection: Automatic discovery of custom objects and dependencies

Example Results

From Apex class analysis:

• Method-level chunking with separate chunks for class declaration and each method
• Symbol extraction working for custom objects, standard objects, and system calls
• Search functionality verified across all modes: semantic, keyword, symbol, hybrid

Production Deployment

For production use:

• Configure real embedding models using SentenceTransformerEmbedding
• Set up persistent PostgreSQL instance with appropriate resource allocation
• Configure proper authentication and security for multi-tenant access
• Implement monitoring and performance optimization for large metadata volumes