salesforce-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build and Development Commands

# Build the TypeScript project
npm run build

# Run development mode with MCP inspector for debugging
npm run dev

# Build MCP Bundle (.mcpb) for distribution
npm run build:mcpb

# Install dependencies
npm install

Architecture Overview

This is a Model Context Protocol (MCP) server that enables AI assistants to interact with Salesforce orgs through the Salesforce CLI. The codebase follows a modular architecture with clear separation of concerns.

Core Components

1. Tool Registration Pattern: Each tool category has its own file in src/tools/ that exports a registration function. Tools are registered in src/index.ts using functions like registerApexTools(server).

2. Permission System: All tools check permissions via src/config/permissions.ts which enforces:

   • READ_ONLY mode: Prevents Apex execution when enabled
   • ALLOWED_ORGS: Restricts access to specific org aliases

3. Salesforce Integration: Two approaches are used:

   • Native API calls via @salesforce/apex-node for Apex operations
   • CLI commands via src/utils/sfCommand.ts for most other operations

4. Connection Management: src/shared/connection.ts handles Salesforce authentication by reusing existing Salesforce CLI auth tokens.

Tool Implementation Pattern

When implementing new tools, follow this pattern:

// 1. Define Zod schema for input validation (targetOrg is optional — falls back to SF CLI default)
const MyToolSchema = z.object({
    targetOrg: z.string().optional(),
    // other parameters
});

// 2. Resolve target org (uses default if not provided)
let targetOrg: string;
try {
    targetOrg = await resolveTargetOrg(input.targetOrg);
} catch (error: any) {
    return {
        content: [
            {
                type: "text",
                text: JSON.stringify({
                    success: false,
                    message: error.message,
                }),
            },
        ],
    };
}

// 3. Check permissions
if (!permissions.canAccessOrg(targetOrg)) {
    return { error: "Access denied" };
}

// 4. Execute operation (via CLI or native API)
const result = await executeSfCommand(["command", "args"], targetOrg);

// 5. Return structured response
return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };