salesforce-metadata-mcp 2.0.0

package/SETUP.md

@@ -0,0 +1,208 @@
+# Setup Guide
+
+Complete prerequisites and configuration for `salesforce-metadata-mcp`.
+
+---
+
+## Prerequisites
+
+### 1. Node.js 18+
+
+```bash
+node --version  # must be 18.0.0 or higher
+```
+
+Download from [nodejs.org](https://nodejs.org) if needed.
+
+### 2. Salesforce Org
+
+You need a Salesforce org (Developer Edition, Sandbox, or Production). Free Developer Edition orgs: [developer.salesforce.com/signup](https://developer.salesforce.com/signup).
+
+---
+
+## Authentication Methods
+
+The server tries these in order:
+
+### Method 1: OAuth Refresh Token (Recommended for Production)
+
+**Step 1: Create a Connected App in Salesforce**
+
+1. Go to **Setup → App Manager → New Connected App**
+2. Fill in: Connected App Name, API Name, Contact Email
+3. Under **OAuth Settings**, check **Enable OAuth Settings**
+4. Set Callback URL: `https://login.salesforce.com/services/oauth2/success`
+5. Add scopes: `Full Access (full)`, `Perform requests at any time (refresh_token, offline_access)`
+6. Save. Wait 2-10 minutes for the app to activate.
+7. Click **Manage Consumer Details** to get your **Consumer Key** (client_id) and **Consumer Secret**
+
+**Step 2: Get your Refresh Token**
+
+Using the Salesforce CLI:
+```bash
+sf org login web --client-id YOUR_CONSUMER_KEY --instance-url https://login.salesforce.com
+sf org display --target-org YOUR_USERNAME --json
+# Copy the refreshToken value
+```
+
+**Step 3: Configure environment variables**
+```env
+SF_INSTANCE_URL=https://yourorg.my.salesforce.com
+SF_CLIENT_ID=3MVG9...your_consumer_key...
+SF_CLIENT_SECRET=your_consumer_secret
+SF_REFRESH_TOKEN=5Aep...your_refresh_token...
+```
+
+### Method 2: Salesforce CLI Alias
+
+**Step 1: Install Salesforce CLI**
+```bash
+npm install -g @salesforce/cli
+sf --version
+```
+
+**Step 2: Authenticate**
+```bash
+sf org login web --instance-url https://login.salesforce.com --alias myOrg
+```
+
+**Step 3: Configure**
+```env
+SF_INSTANCE_URL=https://yourorg.my.salesforce.com
+SF_ALIAS=myOrg
+```
+
+### Method 3: Static Access Token (Dev/Testing Only)
+
+Access tokens expire after ~1 hour. Only use for quick testing.
+
+**Get an access token:**
+```bash
+sf org display --target-org myOrg --json
+# Look for "accessToken" in the output
+```
+
+**Configure:**
+```env
+SF_INSTANCE_URL=https://yourorg.my.salesforce.com
+SF_ACCESS_TOKEN=00D...your_access_token...
+```
+
+---
+
+## Claude Desktop Configuration
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+### Using OAuth (recommended)
+```json
+{
+  "mcpServers": {
+    "salesforce": {
+      "command": "npx",
+      "args": ["-y", "salesforce-metadata-mcp"],
+      "env": {
+        "SF_INSTANCE_URL": "https://yourorg.my.salesforce.com",
+        "SF_CLIENT_ID": "your_consumer_key",
+        "SF_CLIENT_SECRET": "your_consumer_secret",
+        "SF_REFRESH_TOKEN": "your_refresh_token"
+      }
+    }
+  }
+}
+```
+
+### Using CLI alias
+```json
+{
+  "mcpServers": {
+    "salesforce": {
+      "command": "npx",
+      "args": ["-y", "salesforce-metadata-mcp"],
+      "env": {
+        "SF_INSTANCE_URL": "https://yourorg.my.salesforce.com",
+        "SF_ALIAS": "myOrg"
+      }
+    }
+  }
+}
+```
+
+### Using a local build
+```json
+{
+  "mcpServers": {
+    "salesforce": {
+      "command": "node",
+      "args": ["/path/to/salesforce-metadata-mcp-server/dist/index.js"],
+      "env": {
+        "SF_INSTANCE_URL": "https://yourorg.my.salesforce.com",
+        "SF_ACCESS_TOKEN": "your_token"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Claude Code Configuration
+
+Add to `.claude/settings.json` in your project, or `~/.claude/settings.json` for global:
+
+```json
+{
+  "mcpServers": {
+    "salesforce": {
+      "command": "npx",
+      "args": ["-y", "salesforce-metadata-mcp"],
+      "env": {
+        "SF_INSTANCE_URL": "https://yourorg.my.salesforce.com",
+        "SF_CLIENT_ID": "your_consumer_key",
+        "SF_CLIENT_SECRET": "your_consumer_secret",
+        "SF_REFRESH_TOKEN": "your_refresh_token"
+      }
+    }
+  }
+}
+```
+
+---
+
+## HTTP Transport Mode
+
+For server deployments or multi-user scenarios:
+
+```env
+TRANSPORT=http
+PORT=3000
+```
+
+Start the server:
+```bash
+node dist/index.js
+```
+
+The server will listen at `http://localhost:3000/mcp`.
+
+---
+
+## Troubleshooting
+
+**"Missing SF_INSTANCE_URL environment variable"**
+→ Make sure `SF_INSTANCE_URL` is set in your MCP configuration env block.
+
+**"No access token returned from SF CLI"**
+→ Run `sf org login web` and verify the alias is correct.
+
+**"INVALID_SESSION_ID"**
+→ Your access token has expired. Use OAuth refresh token method for automatic renewal.
+
+**"INSUFFICIENT_ACCESS"**
+→ The authenticated user needs sufficient permissions. Try a System Administrator profile.
+
+**Metadata API errors**
+→ The org must have Metadata API enabled (all Developer/Enterprise/Unlimited editions have it).
+
+**"Cannot deploy Apex to production without test coverage"**
+→ Run `sf_run_apex_tests` first to verify coverage, then deploy with `runTests` specified.

package/TOOLS.md

@@ -0,0 +1,193 @@
+# Tools Reference
+
+Complete documentation for all 60+ tools in `salesforce-metadata-mcp`.
+
+---
+
+## Objects & Fields
+
+### sf_create_custom_object
+Creates a new Salesforce Custom Object using the Metadata API.
+
+**Parameters:**
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `fullName` | string | required | API name ending in `__c`, e.g. `Invoice__c` |
+| `label` | string | required | Singular display label |
+| `pluralLabel` | string | required | Plural display label |
+| `description` | string | — | Optional description |
+| `nameFieldLabel` | string | `"Name"` | Label for the standard Name field |
+| `nameFieldType` | `Text\|AutoNumber` | `"Text"` | Name field type |
+| `autoNumberFormat` | string | — | Format for AutoNumber, e.g. `INV-{0000}` |
+| `deploymentStatus` | `Deployed\|InDevelopment` | `"Deployed"` | Deployment status |
+| `sharingModel` | `ReadWrite\|Read\|Private\|...` | `"ReadWrite"` | OWD sharing model |
+| `enableActivities` | boolean | `true` | Allow Tasks/Events |
+| `enableHistory` | boolean | `false` | Enable field history tracking |
+| `enableReports` | boolean | `true` | Available in Reports |
+| `enableSearch` | boolean | `true` | Searchable |
+
+**Example prompts:**
+- "Create a custom object called Project__c with plural label Projects"
+- "Create a Job Application object with AutoNumber name format JOB-{0000}"
+- "Create a custom object called Feedback__c with Private sharing and no activities"
+
+---
+
+### sf_create_custom_field
+Creates a new field on an existing object.
+
+**Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `objectName` | string | Parent object API name |
+| `fieldName` | string | Field API name ending in `__c` |
+| `label` | string | Display label |
+| `type` | FieldType | Text, Number, Picklist, Lookup, etc. |
+| `required` | boolean | Is field required |
+| `unique` | boolean | Must values be unique |
+| `length` | number | For Text fields (1-255) |
+| `precision` / `scale` | number | For Number/Currency fields |
+| `picklistValues` | object | Required for Picklist/MultiselectPicklist |
+| `referenceTo` | string | For Lookup/MasterDetail |
+| `deleteConstraint` | string | For Lookup: Cascade/Restrict/SetNull |
+
+**Example prompts:**
+- "Add a Status__c picklist field to Invoice__c with values: Draft, Pending, Approved, Rejected"
+- "Add an Amount__c currency field to Opportunity with 2 decimal places"
+- "Add a lookup from Project__c to Account"
+
+---
+
+### sf_create_custom_metadata_type
+Creates a Custom Metadata Type (__mdt) for storing configuration.
+
+**Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fullName` | string | API name ending in `__mdt` |
+| `label` | string | Singular label |
+| `pluralLabel` | string | Plural label |
+| `description` | string | Optional description |
+| `fields` | array | Custom fields to add |
+
+**Example prompts:**
+- "Create a Feature_Flag__mdt Custom Metadata Type with a Boolean field IsEnabled__c"
+- "Create an Integration_Config__mdt type with fields for endpoint URL and API key"
+
+---
+
+### sf_create_apex_class
+Deploys an Apex class to the org via Metadata API zip deploy.
+
+**Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `className` | string | Class name (no __c) |
+| `classBody` | string | Full Apex source code |
+| `apiVersion` | string | API version, default `62.0` |
+
+**Example prompts:**
+- "Create an Apex class called AccountService with a method to get all active accounts"
+- "Create a Batch Apex class called DataCleanupBatch that deletes records older than 2 years"
+- "Create a Schedulable class called NightlyReport that generates a report email"
+
+**Expected output:** Deploy job ID and success/failure message with any compile errors.
+
+---
+
+### sf_execute_anonymous_apex
+Executes Apex code immediately via Tooling API.
+
+**Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `apexCode` | string | Apex code to execute |
+
+**Example prompts:**
+- "Run this Apex to update all Contact email addresses to lowercase"
+- "Execute: System.debug(UserInfo.getUserName());"
+- "Run anonymous Apex to backfill the missing CreatedDate__c field on all Account records"
+
+**Expected output:** Success/failure, compile errors if any, and debug log if present.
+
+---
+
+### sf_create_lwc
+Deploys a Lightning Web Component via Metadata API.
+
+**Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `componentName` | string | camelCase name, e.g. `accountCard` |
+| `html` | string | Full HTML template content |
+| `javascript` | string | Full JS controller content |
+| `css` | string | Optional CSS |
+| `targets` | array | Where to place the component |
+| `isExposed` | boolean | Available in App Builder |
+| `apiVersion` | string | Default `62.0` |
+
+**Example prompts:**
+- "Create an LWC called opportunityList that shows a table of open opportunities"
+- "Create a contact card LWC with name, email, phone and make it available on Record Pages"
+- "Create an LWC Flow Screen component for collecting address information"
+
+---
+
+### sf_create_agent (Agentforce)
+Creates an Agentforce Einstein Copilot agent.
+
+**Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `agentName` | string | Agent API name |
+| `label` | string | Display name |
+| `description` | string | Agent description |
+| `type` | string | `EinsteinCopilot` |
+| `company` | string | Company context |
+| `persona` | string | Agent persona description |
+| `tone` | `Formal\|Neutral\|Casual` | Communication tone |
+| `instructions` | string | System-level instructions |
+
+**Example prompts:**
+- "Create an Agentforce agent called SalesBot for helping sales reps close deals"
+- "Create a customer service agent with a formal tone for handling support cases"
+
+---
+
+### sf_deploy_metadata
+Deploys metadata components via SOAP deploy.
+
+**Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `components` | array | `[{type, name}]` to deploy |
+| `checkOnly` | boolean | Validate without deploying |
+| `runTests` | array | Test classes to run |
+| `rollbackOnError` | boolean | Rollback on any failure |
+| `waitMinutes` | number | Timeout (default 10 min) |
+
+**Example prompts:**
+- "Deploy the AccountService Apex class and AccountTrigger to the org"
+- "Validate the deployment of these components without making changes"
+- "Deploy MyFlow and MyClass, running MyClassTest during deployment"
+
+---
+
+### sf_create_mcp_server
+Generates a complete MCP server project on disk.
+
+**Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `serverName` | string | Server package name |
+| `outputDirectory` | string | Absolute path to output directory |
+| `description` | string | Server description |
+| `salesforceInstanceUrl` | string | Pre-configure org URL |
+
+**Example prompts:**
+- "Create a new MCP server called my-sf-integration in C:/projects/my-server"
+- "Generate a Salesforce MCP server project targeting https://myorg.salesforce.com"
+
+---
+
+*For the complete list of all 60+ tools, see [README.md](README.md).*

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,53 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import express from "express";
+import { registerTools } from "./tools/index.js";
+// ─── Server init ──────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "salesforce-metadata-mcp",
+    version: "2.0.0",
+});
+registerTools(server);
+// ─── Transport: stdio ─────────────────────────────────────────────────────────
+async function runStdio() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Salesforce Metadata MCP server v2.0.0 running on stdio");
+}
+// ─── Transport: HTTP ──────────────────────────────────────────────────────────
+async function runHTTP() {
+    const app = express();
+    app.use(express.json());
+    app.post("/mcp", async (req, res) => {
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
+        });
+        res.on("close", () => transport.close());
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    });
+    app.get("/health", (_req, res) => {
+        res.json({ status: "ok", server: "salesforce-metadata-mcp", version: "2.0.0" });
+    });
+    const port = parseInt(process.env.PORT ?? "3000", 10);
+    app.listen(port, () => {
+        console.error(`Salesforce Metadata MCP server v2.0.0 running on http://localhost:${port}/mcp`);
+    });
+}
+// ─── Entry point ──────────────────────────────────────────────────────────────
+const transport = process.env.TRANSPORT ?? "stdio";
+if (transport === "http") {
+    runHTTP().catch((err) => {
+        console.error("Server error:", err);
+        process.exit(1);
+    });
+}
+else {
+    runStdio().catch((err) => {
+        console.error("Server error:", err);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AACnG,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,iFAAiF;AAEjF,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,yBAAyB;IAC/B,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,aAAa,CAAC,MAAM,CAAC,CAAC;AAEtB,iFAAiF;AAEjF,KAAK,UAAU,QAAQ;IACrB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,wDAAwD,CAAC,CAAC;AAC1E,CAAC;AAED,iFAAiF;AAEjF,KAAK,UAAU,OAAO;IACpB,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAExB,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAClC,MAAM,SAAS,GAAG,IAAI,6BAA6B,CAAC;YAClD,kBAAkB,EAAE,SAAS;YAC7B,kBAAkB,EAAE,IAAI;SACzB,CAAC,CAAC;QACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC;QACzC,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChC,MAAM,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;QAC/B,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,yBAAyB,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAClF,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,MAAM,EAAE,EAAE,CAAC,CAAC;IACtD,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE;QACpB,OAAO,CAAC,KAAK,CAAC,qEAAqE,IAAI,MAAM,CAAC,CAAC;IACjG,CAAC,CAAC,CAAC;AACL,CAAC;AAED,iFAAiF;AAEjF,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,OAAO,CAAC;AACnD,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QAC/B,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;QACpC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;KAAM,CAAC;IACN,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QAChC,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;QACpC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}