Salesforce Object Server

A Model Context Protocol (MCP) server that helps AI agents understand Salesforce metadata by parsing .object-meta.xml and .field-meta.xml files. This server provides tools for discovering objects, fields, relationships, formulas, and validation rules to reduce AI hallucination when working with Salesforce repositories.

Features

• Universal Repository Support: Works with any Salesforce repository structure - no configuration needed
• Automatic Discovery: Recursively finds all .object-meta.xml and .field-meta.xml files
• Comprehensive Object Information: Access object metadata, fields, relationships, and validation rules
• Smart Caching: In-memory caching with file modification time checks for fast responses
• Relationship Mapping: Bidirectional relationship discovery (both incoming and outgoing)
• Formula & Validation Support: Parse and understand formula fields and validation rules
• Search Capabilities: Full-text search across all metadata

Available Tools

1. list_objects

List all Salesforce objects in the repository.

Parameters:

• includeStandard (optional): Include standard objects (default: true)
• pattern (optional): Filter by name pattern (case-insensitive)

Example:

{
  "includeStandard": false,
  "pattern": "Account"
}

2. get_object_details

Get comprehensive details about a specific object.

Parameters:

• objectName (required): API name of the object

Example:

{
  "objectName": "Account"
}

3. list_fields

List all fields for a specific object.

Parameters:

• objectName (required): API name of the object
• fieldType (optional): Filter by field type (Text, Lookup, Formula, etc.)

Example:

{
  "objectName": "Account",
  "fieldType": "Formula"
}

4. get_field_details

Get detailed information about a specific field.

Parameters:

• objectName (required): API name of the object
• fieldName (required): API name of the field

Example:

{
  "objectName": "Account",
  "fieldName": "AnnualRevenue"
}

5. find_relationships

Find all relationships for an object.

Parameters:

• objectName (required): API name of the object
• direction (optional): "outgoing", "incoming", or "both" (default: both)

Example:

{
  "objectName": "Contact",
  "direction": "both"
}

6. search_metadata

Search across all metadata by keyword.

Parameters:

• query (required): Search term (case-insensitive)
• scope (optional): "objects", "fields", or "all" (default: all)

Example:

{
  "query": "revenue",
  "scope": "fields"
}

7. get_validation_rules

Get validation rules for an object.

Parameters:

• objectName (required): API name of the object

Example:

{
  "objectName": "Opportunity"
}

Installation

Local Development

1. Clone the repository:

git clone <repository-url>
cd SFObjectMCP

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Run the server:

SF_REPO_PATH=/path/to/your/salesforce/repo npm start

Docker

1. Build the Docker image:

docker build -t sf-object-mcp .

2. Run the container:

docker run -it \
  -e SF_REPO_PATH=/workspace \
  -v /path/to/your/salesforce/repo:/workspace:ro \
  sf-object-mcp

Docker Compose

1. Edit docker-compose.yml and update the volume mount:

volumes:
  - /path/to/your/salesforce/repo:/workspace:ro

2. Start the server:

docker-compose up

MCP Configuration

To use this server with an MCP client (like Claude Desktop), add the following to your MCP configuration file:

Using Local Installation

{
  "mcpServers": {
    "salesforce-metadata": {
      "command": "node",
      "args": ["/path/to/SFObjectMCP/dist/index.js"],
      "env": {
        "SF_REPO_PATH": "/path/to/your/salesforce/repo"
      }
    }
  }
}

Using Docker

{
  "mcpServers": {
    "salesforce-metadata": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SF_REPO_PATH=/workspace",
        "-v",
        "/path/to/your/salesforce/repo:/workspace:ro",
        "sf-object-mcp"
      ]
    }
  }
}

Supported Formats

This server works with any Salesforce repository structure. It scans for .object-meta.xml and .field-meta.xml files anywhere in your repository, regardless of directory structure.

Examples of Supported Structures

Standard SFDX:

force-app/main/default/objects/Account/Account.object-meta.xml

Custom SFDX:

src-package/main/default/core/objects/Account/Account.object-meta.xml

Metadata API:

src/objects/Account.object

Any custom structure:

any-directory/objects/Account/Account.object-meta.xml

The scanner automatically finds all Salesforce metadata files regardless of where they're located in your repository structure.

How It Works

1. First Tool Call: When the first tool is called, the server scans the repository for all .object-meta.xml and .field-meta.xml files
2. Parsing: XML files are parsed and converted into structured TypeScript objects
3. Caching: Parsed metadata is cached in memory with file modification time tracking
4. Relationship Mapping: The server builds a bidirectional relationship map
5. Subsequent Calls: Future tool calls use the cache for fast responses

Development

Build

npm run build

Watch Mode

npm run watch

Development Mode

npm run dev

Troubleshooting

Error: SF_REPO_PATH environment variable is required

Make sure you've set the SF_REPO_PATH environment variable to point to your Salesforce repository.

No objects found

Ensure your repository contains .object-meta.xml files. The scanner searches the entire repository recursively, so metadata files can be in any directory structure. Common locations include:

• force-app/main/default/objects/
• src-package/main/default/core/objects/
• src/objects/
• Any custom directory containing an objects/ folder

Object/Field not found

The server only discovers objects and fields that have metadata files in the repository. Standard objects may not be present unless they've been customized.

Use Cases

• AI-Assisted Development: Help AI agents understand your Salesforce schema to provide accurate code suggestions
• Documentation: Generate documentation from metadata
• Schema Analysis: Understand relationships and dependencies
• Code Review: Validate field references and formula syntax
• Migration Planning: Map object and field usage

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.