@mindstone/mcp-server-salesforce 0.1.2

package/LICENSE

@@ -0,0 +1,97 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Mindstone Learning Limited
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+**Licensor**: Mindstone Learning Limited
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+**Software**: Salesforce MCP Server
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A "Competing
+Use" means making the Software available to third parties as a commercial
+hosted service that directly competes with any product or service provided by
+the Licensor.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, OF
+ANY CHARACTER INCLUDING DAMAGES FOR LOSS OF GOODWILL, LOST PROFITS, LOST SALES
+OR BUSINESS, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, LOST CONTENT,
+DATA OR DATA USE, BREACH OF DUTY OF GOOD FAITH, OR ANY AND ALL OTHER DAMAGES
+OR LOSSES OF ANY KIND OR NATURE WHATSOEVER (WHETHER DIRECT, INDIRECT, SPECIAL,
+COLLATERAL, INCIDENTAL, CONSEQUENTIAL OR OTHERWISE) ARISING OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THIS LICENSE, EVEN IF SUCH PARTY SHALL HAVE
+BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+### Trademark
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Change Date
+
+Four years from the date the Software is made available under these Terms and
+Conditions: **2030-04-08**
+
+## Change License
+
+MIT License
+
+## License Details
+
+| Parameter | Value |
+|---|---|
+| Licensor | Mindstone Learning Limited |
+| Software | Salesforce MCP Server |
+| Use Limitation | Competing Use |
+| Change Date | 2030-04-08 |
+| Change License | MIT |

package/README.md

@@ -0,0 +1,80 @@
+# @mindstone/mcp-server-salesforce
+
+Salesforce CRM MCP server — accounts, contacts, opportunities, leads, tasks, users, and custom objects via the Salesforce API.
+
+## Installation
+
+```bash
+npx -y @mindstone/mcp-server-salesforce
+```
+
+## Configuration
+
+### OAuth (Recommended)
+
+Set these environment variables:
+
+- `SALESFORCE_CLIENT_ID` — Your Salesforce Connected App client ID
+- `SALESFORCE_CLIENT_SECRET` — Your Salesforce Connected App client secret
+- `SALESFORCE_SANDBOX` — Set to `"true"` for sandbox environments (optional)
+
+Then call `salesforce_connect_account` to start the OAuth flow.
+
+### Manual Token
+
+- `SALESFORCE_ACCESS_TOKEN` — A valid Salesforce access token
+- `SALESFORCE_INSTANCE_URL` — Your Salesforce instance URL (e.g., `https://mycompany.my.salesforce.com`)
+
+### Additional Options
+
+- `SALESFORCE_CONFIG_DIR` — Custom config directory (default: `~/.mcp/salesforce`)
+
+## Available Tools (26)
+
+### Account Management
+- `salesforce_connect_account` — Connect a Salesforce account via OAuth
+- `salesforce_list_connected_accounts` — List connected accounts
+- `salesforce_disconnect_account` — Disconnect an account
+
+### CRM Accounts
+- `salesforce_get_accounts` — Get CRM accounts with filters
+- `salesforce_create_account` — Create a CRM account
+- `salesforce_update_account` — Update a CRM account
+
+### Contacts
+- `salesforce_get_contacts` — Get contacts with filters
+- `salesforce_create_contact` — Create a contact
+- `salesforce_update_contact` — Update a contact
+
+### Opportunities
+- `salesforce_get_opportunities` — Get opportunities with filters
+- `salesforce_create_opportunity` — Create an opportunity
+- `salesforce_update_opportunity` — Update an opportunity
+
+### Leads
+- `salesforce_get_leads` — Get leads with filters
+- `salesforce_create_lead` — Create a lead
+- `salesforce_convert_lead` — Convert a lead to Account + Contact
+- `salesforce_update_lead` — Update a lead
+
+### Tasks
+- `salesforce_get_tasks` — Get tasks with filters
+- `salesforce_create_task` — Create a task
+- `salesforce_update_task` — Update a task
+
+### Users
+- `salesforce_get_users` — Get Salesforce users
+
+### Query & Schema
+- `salesforce_query` — Execute raw SOQL queries
+- `salesforce_describe_object` — Get object metadata and fields
+- `salesforce_list_objects` — List available Salesforce objects
+
+### Generic CRUD
+- `salesforce_create_record` — Create any Salesforce record
+- `salesforce_update_record` — Update any Salesforce record
+- `salesforce_get_records` — Query any Salesforce object
+
+## License
+
+FSL-1.1-MIT

package/dist/auth.d.ts

@@ -0,0 +1,19 @@
+import { type AuthMode, type SalesforceTokenData, type SalesforceAccountsConfig } from './types.js';
+export declare function resolveAuthMode(): AuthMode;
+export declare function getAuthMode(): AuthMode;
+export declare function _resetAuthMode(): void;
+export declare function loadAccounts(): SalesforceAccountsConfig;
+export declare function saveAccounts(config: SalesforceAccountsConfig): void;
+export declare function loadToken(accountId: string): SalesforceTokenData | null;
+export declare function saveToken(accountId: string, token: SalesforceTokenData): void;
+export declare function deleteToken(accountId: string): void;
+export declare function getActiveToken(): {
+    accountId: string;
+    token: SalesforceTokenData;
+};
+export declare function startStandaloneOAuth(): Promise<{
+    success: boolean;
+    username?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,331 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as crypto from 'node:crypto';
+import * as http from 'node:http';
+import { ConnectorError, } from './types.js';
+import { BRIDGE_STATE_PATH } from './bridge.js';
+// ---------------------------------------------------------------------------
+// Auth Mode Detection (resolved ONCE at startup)
+// ---------------------------------------------------------------------------
+let resolvedMode = null;
+export function resolveAuthMode() {
+    if (resolvedMode !== null)
+        return resolvedMode;
+    const hasBridge = !!BRIDGE_STATE_PATH;
+    const hasClientId = !!process.env.SALESFORCE_CLIENT_ID;
+    const hasClientSecret = !!process.env.SALESFORCE_CLIENT_SECRET;
+    const hasManualToken = !!process.env.SALESFORCE_ACCESS_TOKEN;
+    if (hasBridge) {
+        resolvedMode = 'bridge';
+        if (hasClientId || hasManualToken) {
+            console.error('[Salesforce MCP] WARNING: Bridge state detected alongside other auth env vars. Using bridge mode (highest precedence).');
+        }
+    }
+    else if (hasClientId && hasClientSecret) {
+        resolvedMode = 'standalone_oauth';
+    }
+    else if (hasManualToken) {
+        resolvedMode = 'manual_token';
+    }
+    else {
+        resolvedMode = 'unconfigured';
+    }
+    console.error(`[Salesforce MCP] Auth mode: ${resolvedMode}`);
+    return resolvedMode;
+}
+export function getAuthMode() {
+    if (resolvedMode === null)
+        return resolveAuthMode();
+    return resolvedMode;
+}
+export function _resetAuthMode() {
+    resolvedMode = null;
+}
+// ---------------------------------------------------------------------------
+// Config Directory & Token Persistence
+// ---------------------------------------------------------------------------
+function getConfigDir() {
+    return process.env.SALESFORCE_CONFIG_DIR || path.join(os.homedir(), '.mcp', 'salesforce');
+}
+function getCredentialsDir() {
+    return path.join(getConfigDir(), 'credentials');
+}
+function sanitizeFilename(name) {
+    return name.replace(/[^a-zA-Z0-9._-]/g, '-');
+}
+function ensureDirectories() {
+    const configDir = getConfigDir();
+    const credDir = getCredentialsDir();
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+    }
+    if (!fs.existsSync(credDir)) {
+        fs.mkdirSync(credDir, { recursive: true, mode: 0o700 });
+    }
+}
+function getAccountsPath() {
+    return path.join(getConfigDir(), 'accounts.json');
+}
+function getTokenPath(accountId) {
+    return path.join(getCredentialsDir(), `${sanitizeFilename(accountId)}.token.json`);
+}
+function atomicWriteFile(filePath, data) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    const tmpPath = `${filePath}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+    const fd = fs.openSync(tmpPath, 'w', 0o600);
+    try {
+        fs.writeSync(fd, data);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(tmpPath, filePath);
+}
+// ---------------------------------------------------------------------------
+// Account Management
+// ---------------------------------------------------------------------------
+export function loadAccounts() {
+    ensureDirectories();
+    try {
+        const data = fs.readFileSync(getAccountsPath(), 'utf-8');
+        return JSON.parse(data);
+    }
+    catch {
+        return { accounts: [] };
+    }
+}
+export function saveAccounts(config) {
+    ensureDirectories();
+    atomicWriteFile(getAccountsPath(), JSON.stringify(config, null, 2));
+}
+export function loadToken(accountId) {
+    try {
+        const data = fs.readFileSync(getTokenPath(accountId), 'utf-8');
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+export function saveToken(accountId, token) {
+    ensureDirectories();
+    atomicWriteFile(getTokenPath(accountId), JSON.stringify(token, null, 2));
+}
+export function deleteToken(accountId) {
+    try {
+        fs.unlinkSync(getTokenPath(accountId));
+    }
+    catch {
+        // Token file may not exist
+    }
+}
+// ---------------------------------------------------------------------------
+// Active Token Resolution
+// ---------------------------------------------------------------------------
+export function getActiveToken() {
+    const mode = getAuthMode();
+    if (mode === 'manual_token') {
+        const accessToken = process.env.SALESFORCE_ACCESS_TOKEN || '';
+        const instanceUrl = process.env.SALESFORCE_INSTANCE_URL || 'https://login.salesforce.com';
+        return {
+            accountId: 'manual',
+            token: {
+                access_token: accessToken,
+                instance_url: instanceUrl,
+                expires_at: Number.MAX_SAFE_INTEGER,
+                username: 'manual-token',
+            },
+        };
+    }
+    if (mode === 'unconfigured') {
+        throw new ConnectorError('No Salesforce authentication configured', 'UNCONFIGURED', 'Set up authentication: (1) Set SALESFORCE_CLIENT_ID and SALESFORCE_CLIENT_SECRET for OAuth, or (2) Set SALESFORCE_ACCESS_TOKEN and SALESFORCE_INSTANCE_URL for manual token mode. See README for details.');
+    }
+    const config = loadAccounts();
+    if (config.accounts.length === 0) {
+        throw new ConnectorError('No Salesforce accounts connected', 'NO_ACCOUNT', 'Call salesforce_connect_account to connect your Salesforce account.');
+    }
+    const accountId = config.accounts[0].id;
+    const token = loadToken(accountId);
+    if (!token) {
+        throw new ConnectorError('Salesforce credentials not found', 'NO_CREDENTIALS', 'Call salesforce_connect_account to reconnect.');
+    }
+    return { accountId, token };
+}
+// ---------------------------------------------------------------------------
+// Standalone OAuth Flow
+// ---------------------------------------------------------------------------
+let authInProgress = false;
+export async function startStandaloneOAuth() {
+    if (authInProgress) {
+        return { success: false, error: 'Authentication already in progress. Please complete the current flow first.' };
+    }
+    const clientId = process.env.SALESFORCE_CLIENT_ID;
+    const clientSecret = process.env.SALESFORCE_CLIENT_SECRET;
+    if (!clientId || !clientSecret) {
+        return {
+            success: false,
+            error: 'SALESFORCE_CLIENT_ID and SALESFORCE_CLIENT_SECRET must be set for standalone OAuth.',
+        };
+    }
+    authInProgress = true;
+    try {
+        const result = await runOAuthCallbackServer(clientId, clientSecret);
+        return result;
+    }
+    finally {
+        authInProgress = false;
+    }
+}
+async function runOAuthCallbackServer(clientId, clientSecret) {
+    const state = crypto.randomBytes(32).toString('hex');
+    const codeVerifier = crypto.randomBytes(32).toString('base64url');
+    const codeChallenge = crypto.createHash('sha256').update(codeVerifier).digest('base64url');
+    const port = parseInt(process.env.SALESFORCE_OAUTH_PORT || '0', 10);
+    // Hard-coded loopback bind. We deliberately do NOT honour an env override
+    // (previously `MCP_OAUTH_BIND_HOST`): an OAuth callback server with a
+    // short-lived auth code is a privilege-bearing local service and must
+    // never be exposed beyond loopback. (M3.2 — VAL-SALESFORCE-017..019.)
+    const bindHost = '127.0.0.1';
+    const isSandbox = process.env.SALESFORCE_SANDBOX === 'true';
+    const loginBase = isSandbox ? 'https://test.salesforce.com' : 'https://login.salesforce.com';
+    const timeoutMs = 5 * 60 * 1000;
+    return new Promise((resolve) => {
+        const server = http.createServer(async (req, res) => {
+            if (!req.url?.startsWith('/callback')) {
+                res.writeHead(404);
+                res.end('Not found');
+                return;
+            }
+            const url = new URL(req.url, `http://${bindHost}:${actualPort}`);
+            const code = url.searchParams.get('code');
+            const returnedState = url.searchParams.get('state');
+            const error = url.searchParams.get('error');
+            if (error) {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end('<html><body><h2>Authentication failed</h2><p>You can close this window.</p></body></html>');
+                cleanup();
+                resolve({ success: false, error: `OAuth error: ${error}` });
+                return;
+            }
+            if (returnedState !== state) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end('<html><body><h2>Invalid state parameter</h2><p>Please try again.</p></body></html>');
+                cleanup();
+                resolve({ success: false, error: 'OAuth state mismatch — possible CSRF attack.' });
+                return;
+            }
+            if (!code) {
+                res.writeHead(400, { 'Content-Type': 'text/html' });
+                res.end('<html><body><h2>Missing authorization code</h2><p>Please try again.</p></body></html>');
+                cleanup();
+                resolve({ success: false, error: 'No authorization code received.' });
+                return;
+            }
+            try {
+                const redirectUri = `http://localhost:${actualPort}/callback`;
+                const tokenResponse = await fetch(`${loginBase}/services/oauth2/token`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                    body: new URLSearchParams({
+                        grant_type: 'authorization_code',
+                        client_id: clientId,
+                        client_secret: clientSecret,
+                        redirect_uri: redirectUri,
+                        code,
+                        code_verifier: codeVerifier,
+                    }).toString(),
+                });
+                if (!tokenResponse.ok) {
+                    const errText = await tokenResponse.text();
+                    res.writeHead(200, { 'Content-Type': 'text/html' });
+                    res.end('<html><body><h2>Token exchange failed</h2><p>You can close this window.</p></body></html>');
+                    cleanup();
+                    resolve({ success: false, error: `Token exchange failed: ${errText}` });
+                    return;
+                }
+                const tokenData = (await tokenResponse.json());
+                const username = tokenData.id?.split('/').pop() || `user-${Date.now()}`;
+                const accountId = sanitizeFilename(username);
+                const instanceUrl = tokenData.instance_url;
+                const token = {
+                    access_token: tokenData.access_token,
+                    refresh_token: tokenData.refresh_token,
+                    instance_url: instanceUrl,
+                    issued_at: tokenData.issued_at,
+                    username,
+                    expires_at: Date.now() + 2 * 60 * 60 * 1000,
+                    login_url: loginBase,
+                };
+                saveToken(accountId, token);
+                const config = loadAccounts();
+                const existingIdx = config.accounts.findIndex((a) => a.id === accountId);
+                const account = {
+                    id: accountId,
+                    username,
+                    instance_url: instanceUrl,
+                    is_sandbox: isSandbox,
+                    connected_at: new Date().toISOString(),
+                };
+                if (existingIdx >= 0) {
+                    config.accounts[existingIdx] = account;
+                }
+                else {
+                    config.accounts.push(account);
+                }
+                saveAccounts(config);
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end('<html><body><h2>Authentication successful!</h2><p>You can close this window.</p></body></html>');
+                cleanup();
+                resolve({ success: true, username });
+            }
+            catch (err) {
+                res.writeHead(500, { 'Content-Type': 'text/html' });
+                res.end('<html><body><h2>Authentication error</h2><p>You can close this window.</p></body></html>');
+                cleanup();
+                resolve({
+                    success: false,
+                    error: `Token exchange error: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        });
+        let actualPort = port;
+        let timeoutHandle;
+        const cleanup = () => {
+            clearTimeout(timeoutHandle);
+            server.close();
+        };
+        server.listen(port, bindHost, () => {
+            const addr = server.address();
+            if (addr && typeof addr !== 'string') {
+                actualPort = addr.port;
+            }
+            const redirectUri = `http://localhost:${actualPort}/callback`;
+            const scopes = process.env.SALESFORCE_OAUTH_SCOPES || 'api refresh_token';
+            const authorizeUrl = `${loginBase}/services/oauth2/authorize?` +
+                new URLSearchParams({
+                    client_id: clientId,
+                    redirect_uri: redirectUri,
+                    response_type: 'code',
+                    scope: scopes,
+                    state,
+                    code_challenge: codeChallenge,
+                    code_challenge_method: 'S256',
+                }).toString();
+            console.error(`[Salesforce MCP] Open this URL to authenticate:\n${authorizeUrl}`);
+        });
+        timeoutHandle = setTimeout(() => {
+            cleanup();
+            resolve({ success: false, error: 'OAuth flow timed out after 5 minutes.' });
+        }, timeoutMs);
+        server.on('error', (err) => {
+            cleanup();
+            resolve({ success: false, error: `OAuth server error: ${err.message}` });
+        });
+    });
+}
+//# sourceMappingURL=auth.js.map

package/dist/bridge.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export declare const BRIDGE_STATE_PATH: string;
+/**
+ * Send a request to the host app bridge.
+ */
+export declare const bridgeRequest: (urlPath: string, body?: Record<string, unknown>) => Promise<{
+    success: boolean;
+    username?: string;
+    warning?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.js

@@ -0,0 +1,37 @@
+import * as fs from 'node:fs';
+import { REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export const BRIDGE_STATE_PATH = process.env.MCP_HOST_BRIDGE_STATE || process.env.MINDSTONE_REBEL_BRIDGE_STATE || '';
+const loadBridgeState = () => {
+    if (!BRIDGE_STATE_PATH)
+        return null;
+    try {
+        const raw = fs.readFileSync(BRIDGE_STATE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Send a request to the host app bridge.
+ */
+export const bridgeRequest = async (urlPath, body = {}) => {
+    const bridge = loadBridgeState();
+    if (!bridge) {
+        return { success: false, error: 'Bridge not available' };
+    }
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${urlPath}`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${bridge.token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    return response.json();
+};
+//# sourceMappingURL=bridge.js.map

package/dist/client.d.ts

@@ -0,0 +1,23 @@
+import jsforce from 'jsforce';
+import { type SalesforceAccount } from './types.js';
+/**
+ * Ensure the connector is in a mode that can make API calls.
+ */
+export declare function requireAuth(): void;
+/**
+ * Get a jsforce connection for the current account.
+ */
+export declare function getConnection(accountId?: string): Promise<jsforce.Connection>;
+/**
+ * Execute an operation with a jsforce connection, handling session expiry.
+ */
+export declare function withConnection<T>(accountId: string | undefined, operation: (conn: jsforce.Connection) => Promise<T>): Promise<T>;
+/**
+ * List all connected accounts with their status.
+ */
+export declare function listConnectedAccounts(): SalesforceAccount[];
+/**
+ * Remove a connected account.
+ */
+export declare function removeAccount(usernameOrId: string): void;
+//# sourceMappingURL=client.d.ts.map