# Salesforce Object MCP 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:**
```json
{
  "includeStandard": false,
  "pattern": "Account"
}
```

### 2. `get_object_details`
Get comprehensive details about a specific object.

**Parameters:**
- `objectName` (required): API name of the object

**Example:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "query": "revenue",
  "scope": "fields"
}
```

### 7. `get_validation_rules`
Get validation rules for an object.

**Parameters:**
- `objectName` (required): API name of the object

**Example:**
```json
{
  "objectName": "Opportunity"
}
```

## Installation

### Local Development

1. Clone the repository:
```bash
git clone <repository-url>
cd SFObjectMCP
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

4. Run the server:
```bash
SF_REPO_PATH=/path/to/your/salesforce/repo npm start
```

### Docker

1. Build the Docker image:
```bash
docker build -t sf-object-mcp .
```

2. Run the container:
```bash
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:
```yaml
volumes:
  - /path/to/your/salesforce/repo:/workspace:ro
```

2. Start the server:
```bash
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

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

### Using Docker

```json
{
  "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
```bash
npm run build
```

### Watch Mode
```bash
npm run watch
```

### Development Mode
```bash
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.