@mindstone/mcp-server-salesforce 0.1.2

package/dist/tools/tasks.js

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+import { withErrorHandling, escapeSOQL, escapeSOQLLike, validateFields, validateAndMergeCustomFields, formatSOQLDate, checkSaveResult } from '../utils.js';
+import { withConnection } from '../client.js';
+import { ConnectorError } from '../types.js';
+export function registerTaskTools(server) {
+    server.registerTool('salesforce_get_tasks', {
+        description: `Get tasks. Filters: subject_contains, status, priority, who_id, what_id, activity_date_from, activity_date_to. Max 200 (default: 50).`,
+        inputSchema: z.object({
+            limit: z.number().int().min(1).max(200).optional().describe('Max results 1-200 (default: 50)'),
+            subject_contains: z.string().optional().describe('Filter by subject'),
+            status: z.string().optional().describe('Filter by status'),
+            priority: z.string().optional().describe('Filter by priority'),
+            who_id: z.string().optional().describe('Filter by WhoId (Contact or Lead ID)'),
+            what_id: z.string().optional().describe('Filter by WhatId (Account or Opportunity ID)'),
+            activity_date_from: z.string().optional().describe('Filter tasks on/after date (YYYY-MM-DD)'),
+            activity_date_to: z.string().optional().describe('Filter tasks on/before date (YYYY-MM-DD)'),
+            fields: z.array(z.string()).optional().describe('Custom fields'),
+        }),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, withErrorHandling(async (args) => {
+        return withConnection(undefined, async (conn) => {
+            const defaultFields = ['Id', 'Subject', 'Status', 'Priority', 'WhoId', 'WhatId', 'ActivityDate', 'Description', 'OwnerId', 'IsClosed'];
+            const fields = validateFields(args.fields || [], defaultFields);
+            let query = `SELECT ${fields.join(', ')} FROM Task`;
+            const conditions = [];
+            if (args.subject_contains)
+                conditions.push(`Subject LIKE '%${escapeSOQLLike(args.subject_contains)}%'`);
+            if (args.status)
+                conditions.push(`Status = '${escapeSOQL(args.status)}'`);
+            if (args.priority)
+                conditions.push(`Priority = '${escapeSOQL(args.priority)}'`);
+            if (args.who_id)
+                conditions.push(`WhoId = '${escapeSOQL(args.who_id)}'`);
+            if (args.what_id)
+                conditions.push(`WhatId = '${escapeSOQL(args.what_id)}'`);
+            if (args.activity_date_from)
+                conditions.push(`ActivityDate >= ${formatSOQLDate(args.activity_date_from, 'activity_date_from')}`);
+            if (args.activity_date_to)
+                conditions.push(`ActivityDate <= ${formatSOQLDate(args.activity_date_to, 'activity_date_to')}`);
+            if (conditions.length > 0)
+                query += ` WHERE ${conditions.join(' AND ')}`;
+            const limit = Math.min(Math.max(1, args.limit ?? 50), 200);
+            query += ` LIMIT ${limit}`;
+            const result = await conn.query(query);
+            return JSON.stringify({ ok: true, records: result.records, totalSize: result.totalSize });
+        });
+    }));
+    server.registerTool('salesforce_create_task', {
+        description: `Create a task. Required: subject. Optional: status, priority, who_id, what_id, activity_date, description, owner_id, fields.`,
+        inputSchema: z.object({
+            subject: z.string().min(1).describe('Task subject (required)'),
+            status: z.string().optional().describe('Task status (default: Not Started)'),
+            priority: z.string().optional().describe('Priority (High, Normal, Low)'),
+            who_id: z.string().optional().describe('Contact or Lead ID'),
+            what_id: z.string().optional().describe('Account or Opportunity ID'),
+            activity_date: z.string().optional().describe('Due date (YYYY-MM-DD)'),
+            description: z.string().optional().describe('Task description'),
+            owner_id: z.string().optional().describe('Owner User ID'),
+            fields: z.record(z.unknown()).optional().describe('Additional/custom fields'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, withErrorHandling(async (args) => {
+        if (args.activity_date)
+            formatSOQLDate(args.activity_date, 'activity_date');
+        return withConnection(undefined, async (conn) => {
+            const data = { Subject: args.subject };
+            if (args.status)
+                data.Status = args.status;
+            if (args.priority)
+                data.Priority = args.priority;
+            if (args.who_id)
+                data.WhoId = args.who_id;
+            if (args.what_id)
+                data.WhatId = args.what_id;
+            if (args.activity_date)
+                data.ActivityDate = args.activity_date;
+            if (args.description)
+                data.Description = args.description;
+            if (args.owner_id)
+                data.OwnerId = args.owner_id;
+            if (args.fields)
+                validateAndMergeCustomFields(data, args.fields);
+            const result = await conn.sobject('Task').create(data);
+            if (!result.success)
+                throw new ConnectorError('Failed to create task', 'CREATE_ERROR', JSON.stringify(result.errors));
+            return JSON.stringify({ ok: true, status: 'success', object: 'Task', id: result.id, subject: args.subject });
+        });
+    }));
+    server.registerTool('salesforce_update_task', {
+        description: `Update a task. Required: id. Updatable: subject, status, priority, who_id, what_id, activity_date, description, owner_id, fields.`,
+        inputSchema: z.object({
+            id: z.string().min(1).describe('Salesforce Task ID (required)'),
+            subject: z.string().optional().describe('Task subject'),
+            status: z.string().optional().describe('Task status'),
+            priority: z.string().optional().describe('Priority'),
+            who_id: z.string().optional().describe('Contact or Lead ID'),
+            what_id: z.string().optional().describe('Account or Opportunity ID'),
+            activity_date: z.string().optional().describe('Due date (YYYY-MM-DD)'),
+            description: z.string().optional().describe('Description'),
+            owner_id: z.string().optional().describe('Owner User ID'),
+            fields: z.record(z.unknown()).optional().describe('Additional/custom fields'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, withErrorHandling(async (args) => {
+        if (args.activity_date)
+            formatSOQLDate(args.activity_date, 'activity_date');
+        return withConnection(undefined, async (conn) => {
+            const updateData = { Id: args.id };
+            if (args.subject)
+                updateData.Subject = args.subject;
+            if (args.status)
+                updateData.Status = args.status;
+            if (args.priority)
+                updateData.Priority = args.priority;
+            if (args.who_id)
+                updateData.WhoId = args.who_id;
+            if (args.what_id)
+                updateData.WhatId = args.what_id;
+            if (args.activity_date)
+                updateData.ActivityDate = args.activity_date;
+            if (args.description)
+                updateData.Description = args.description;
+            if (args.owner_id)
+                updateData.OwnerId = args.owner_id;
+            if (args.fields)
+                validateAndMergeCustomFields(updateData, args.fields);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const result = await conn.sobject('Task').update(updateData);
+            checkSaveResult(result, 'Failed to update task');
+            return JSON.stringify({ ok: true, status: 'success', object: 'Task', id: args.id });
+        });
+    }));
+}
+//# sourceMappingURL=tasks.js.map

package/dist/tools/users.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerUserTools(server: McpServer): void;
+//# sourceMappingURL=users.d.ts.map

package/dist/tools/users.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { withErrorHandling, escapeSOQLLike, validateFields, isValidQueryFieldName } from '../utils.js';
+import { withConnection } from '../client.js';
+export function registerUserTools(server) {
+    server.registerTool('salesforce_get_users', {
+        description: `Get Salesforce users. Filters: name_contains, email_contains, role_contains, is_active. Max 200 (default: 50).`,
+        inputSchema: z.object({
+            limit: z.number().int().min(1).max(200).optional().describe('Max results 1-200 (default: 50)'),
+            name_contains: z.string().optional().describe('Filter by name'),
+            email_contains: z.string().optional().describe('Filter by email'),
+            role_contains: z.string().optional().describe('Filter by UserRole.Name'),
+            is_active: z.boolean().optional().describe('Filter by active status'),
+            fields: z.array(z.string()).optional().describe('Custom fields'),
+        }),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, withErrorHandling(async (args) => {
+        return withConnection(undefined, async (conn) => {
+            const defaultFields = ['Id', 'Name', 'Email', 'Username', 'IsActive', 'UserRoleId', 'Profile.Name'];
+            const fields = validateFields(args.fields || [], defaultFields, isValidQueryFieldName);
+            let query = `SELECT ${fields.join(', ')} FROM User`;
+            const conditions = [];
+            if (args.name_contains)
+                conditions.push(`Name LIKE '%${escapeSOQLLike(args.name_contains)}%'`);
+            if (args.email_contains)
+                conditions.push(`Email LIKE '%${escapeSOQLLike(args.email_contains)}%'`);
+            if (args.role_contains)
+                conditions.push(`UserRole.Name LIKE '%${escapeSOQLLike(args.role_contains)}%'`);
+            if (args.is_active !== undefined)
+                conditions.push(`IsActive = ${args.is_active}`);
+            if (conditions.length > 0)
+                query += ` WHERE ${conditions.join(' AND ')}`;
+            const limit = Math.min(Math.max(1, args.limit ?? 50), 200);
+            query += ` LIMIT ${limit}`;
+            const result = await conn.query(query);
+            return JSON.stringify({ ok: true, records: result.records, totalSize: result.totalSize });
+        });
+    }));
+}
+//# sourceMappingURL=users.js.map

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+export declare const REQUEST_TIMEOUT_MS = 30000;
+export declare const SERVER_NAME = "salesforce-mcp-server";
+/** Server version reported on MCP `initialize`. Read from package.json so
+ *  it cannot drift from the published npm version. */
+export declare const SERVER_VERSION: string;
+export interface BridgeState {
+    port: number;
+    token: string;
+}
+export declare class ConnectorError extends Error {
+    readonly code: string;
+    readonly resolution: string;
+    constructor(message: string, code: string, resolution: string);
+}
+export type AuthMode = 'bridge' | 'standalone_oauth' | 'manual_token' | 'unconfigured';
+export interface SalesforceTokenData {
+    access_token: string;
+    refresh_token?: string;
+    instance_url: string;
+    token_type?: string;
+    issued_at?: string;
+    id?: string;
+    username?: string;
+    organization_id?: string;
+    expires_at?: number;
+    signature?: string;
+    login_url?: string;
+}
+export interface SalesforceAccount {
+    id: string;
+    username: string;
+    instance_url: string;
+    is_sandbox: boolean;
+    connected_at: string;
+}
+export interface SalesforceAccountsConfig {
+    accounts: SalesforceAccount[];
+}
+export interface SaveResult {
+    success: boolean;
+    id?: string;
+    errors?: unknown[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,19 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+export const REQUEST_TIMEOUT_MS = 30_000;
+export const SERVER_NAME = 'salesforce-mcp-server';
+/** Server version reported on MCP `initialize`. Read from package.json so
+ *  it cannot drift from the published npm version. */
+export const SERVER_VERSION = pkg.version;
+export class ConnectorError extends Error {
+    code;
+    resolution;
+    constructor(message, code, resolution) {
+        super(message);
+        this.code = code;
+        this.resolution = resolution;
+        this.name = 'ConnectorError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,62 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Wraps a tool handler with standard error handling.
+ */
+export declare function withErrorHandling<T>(fn: (args: T, extra: unknown) => Promise<string>): ToolHandler<T>;
+/**
+ * Escape a string value for safe use in SOQL queries.
+ *
+ * Escapes the four characters that SOQL gives special meaning to:
+ *   - `\\`  (backslash — the SOQL escape character)
+ *   - `'`   (single quote — string delimiter; SOQL doubles the quote)
+ *   - `%`   (LIKE wildcard — matches zero-or-more characters)
+ *   - `_`   (LIKE wildcard — matches exactly one character)
+ *
+ * The wildcard characters MUST be escaped at every interpolation site so
+ * that user-supplied substrings cannot expand the pattern beyond the
+ * literal value the caller intended. For LIKE sites, prefer the
+ * dedicated `escapeSOQLLike` helper for an explicit signal of intent.
+ */
+export declare function escapeSOQL(value: string): string;
+/**
+ * Escape a user-supplied substring for interpolation inside a SOQL
+ * `LIKE '%...%'` clause. Identical to `escapeSOQL` semantically (both
+ * escape `\\`, `'`, `%`, `_`) but exists as a separate helper so every
+ * `LIKE` site is unambiguously marked as wildcard-aware.
+ */
+export declare function escapeSOQLLike(value: string): string;
+/**
+ * Validate that a field name is safe (alphanumeric + underscore only).
+ */
+export declare function isValidFieldName(field: string): boolean;
+/**
+ * Validate query field names (supports dot-notation for relationship fields).
+ */
+export declare function isValidQueryFieldName(field: string): boolean;
+/**
+ * Validate that an sObject API name is safe.
+ */
+export declare function validateObjectName(name: string): void;
+/**
+ * Format a date string for SOQL (YYYY-MM-DD format required).
+ */
+export declare function formatSOQLDate(dateStr: string, paramName: string): string;
+/**
+ * Validate field names and return validated or default fields.
+ */
+export declare function validateFields(fields: string[], defaultFields: string[], validator?: (field: string) => boolean): string[];
+/**
+ * Validate and merge custom fields into update data.
+ */
+export declare function validateAndMergeCustomFields(updateData: Record<string, unknown>, fields: Record<string, unknown>): void;
+export declare const ALLOWED_FILTER_OPERATORS: Set<string>;
+export declare function checkSaveResult(result: {
+    success: boolean;
+    errors?: unknown[];
+} | Array<{
+    success: boolean;
+    errors?: unknown[];
+}>, errorMessage: string): void;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,134 @@
+import { ConnectorError } from './types.js';
+/**
+ * Wraps a tool handler with standard error handling.
+ */
+export function withErrorHandling(fn) {
+    return async (args, extra) => {
+        try {
+            const result = await fn(args, extra);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (error) {
+            if (error instanceof ConnectorError) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: false,
+                                error: error.message,
+                                code: error.code,
+                                resolution: error.resolution,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: errorMessage }) }],
+                isError: true,
+            };
+        }
+    };
+}
+/**
+ * Escape a string value for safe use in SOQL queries.
+ *
+ * Escapes the four characters that SOQL gives special meaning to:
+ *   - `\\`  (backslash — the SOQL escape character)
+ *   - `'`   (single quote — string delimiter; SOQL doubles the quote)
+ *   - `%`   (LIKE wildcard — matches zero-or-more characters)
+ *   - `_`   (LIKE wildcard — matches exactly one character)
+ *
+ * The wildcard characters MUST be escaped at every interpolation site so
+ * that user-supplied substrings cannot expand the pattern beyond the
+ * literal value the caller intended. For LIKE sites, prefer the
+ * dedicated `escapeSOQLLike` helper for an explicit signal of intent.
+ */
+export function escapeSOQL(value) {
+    if (!value)
+        return '';
+    return value
+        // Backslash MUST be escaped first to avoid double-escaping.
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "''")
+        .replace(/%/g, '\\%')
+        .replace(/_/g, '\\_');
+}
+/**
+ * Escape a user-supplied substring for interpolation inside a SOQL
+ * `LIKE '%...%'` clause. Identical to `escapeSOQL` semantically (both
+ * escape `\\`, `'`, `%`, `_`) but exists as a separate helper so every
+ * `LIKE` site is unambiguously marked as wildcard-aware.
+ */
+export function escapeSOQLLike(value) {
+    return escapeSOQL(value);
+}
+/**
+ * Validate that a field name is safe (alphanumeric + underscore only).
+ */
+export function isValidFieldName(field) {
+    return /^[a-zA-Z][a-zA-Z0-9_]*$/.test(field);
+}
+/**
+ * Validate query field names (supports dot-notation for relationship fields).
+ */
+export function isValidQueryFieldName(field) {
+    return /^[a-zA-Z][a-zA-Z0-9_.]*$/.test(field);
+}
+/**
+ * Validate that an sObject API name is safe.
+ */
+export function validateObjectName(name) {
+    if (!name || !/^[A-Za-z][A-Za-z0-9_]*$/.test(name)) {
+        throw new ConnectorError(`Invalid object name: "${name}"`, 'INVALID_OBJECT_NAME', 'Object names must start with a letter and contain only letters, numbers, and underscores (e.g., Account, Invoice__c)');
+    }
+}
+/**
+ * Format a date string for SOQL (YYYY-MM-DD format required).
+ */
+export function formatSOQLDate(dateStr, paramName) {
+    const match = dateStr.match(/^(\d{4}-\d{2}-\d{2})/);
+    if (!match) {
+        throw new ConnectorError(`Invalid ${paramName}: "${dateStr}"`, 'INVALID_DATE_FORMAT', 'Use YYYY-MM-DD format (e.g., "2026-01-09")');
+    }
+    return match[1];
+}
+/**
+ * Validate field names and return validated or default fields.
+ */
+export function validateFields(fields, defaultFields, validator = isValidFieldName) {
+    if (!fields || fields.length === 0)
+        return defaultFields;
+    const invalidFields = fields.filter((f) => !validator(f));
+    if (invalidFields.length > 0) {
+        throw new ConnectorError(`Invalid field names: ${invalidFields.join(', ')}`, 'INVALID_FIELD_NAMES', 'Field names must start with a letter and contain only letters, numbers, and underscores (e.g., Id, Name, Custom_Field__c)');
+    }
+    return fields;
+}
+/**
+ * Validate and merge custom fields into update data.
+ */
+export function validateAndMergeCustomFields(updateData, fields) {
+    const reservedFields = Object.keys(fields).filter((f) => f === 'Id' || f === 'id');
+    if (reservedFields.length > 0) {
+        throw new ConnectorError('Cannot override record ID via fields parameter', 'RESERVED_FIELD_OVERRIDE', 'Remove "Id" from the fields object — Salesforce manages record IDs automatically');
+    }
+    const invalidFields = Object.keys(fields).filter((f) => !isValidFieldName(f));
+    if (invalidFields.length > 0) {
+        throw new ConnectorError(`Invalid custom field names: ${invalidFields.join(', ')}`, 'INVALID_FIELD_NAMES', 'Field names must start with a letter and contain only letters, numbers, and underscores (e.g., Situation__c, Pain__c)');
+    }
+    for (const [key, value] of Object.entries(fields)) {
+        updateData[key] = value;
+    }
+}
+export const ALLOWED_FILTER_OPERATORS = new Set(['=', '!=', '<', '>', '<=', '>=', 'LIKE']);
+export function checkSaveResult(result, errorMessage) {
+    const res = Array.isArray(result) ? result[0] : result;
+    if (!res.success) {
+        throw new ConnectorError(errorMessage, 'UPDATE_ERROR', JSON.stringify(res.errors));
+    }
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@mindstone/mcp-server-salesforce",
+  "version": "0.1.2",
+  "mcpName": "io.github.mindstone/mcp-server-salesforce",
+  "description": "Salesforce CRM MCP server \u2014 accounts, contacts, opportunities, leads, tasks, and custom objects via Salesforce API",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "mcp-server-salesforce": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mindstone/mcp-servers.git",
+    "directory": "connectors/salesforce"
+  },
+  "homepage": "https://github.com/mindstone/mcp-servers/tree/main/connectors/salesforce",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "jsforce": "^3.6.2",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@mindstone/mcp-test-harness": "file:../../test-harness",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.1.3",
+    "msw": "^2.13.2",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "overrides": {
+    "fast-uri": "^3.1.2",
+    "hono": "^4.12.18",
+    "ip-address": "^10.2.0"
+  }
+}