delegate-sf-mcp 0.2.0

package/src/index.js

@@ -0,0 +1,168 @@
+/**
+ * index.js — Delegate SF MCP Server
+ *
+ * Start: node src/index.js
+ * Requires tokens.json (run node auth.js first)
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+import {
+  handleQuery,
+  handleGetRecord,
+  handleSearch,
+  handleDescribe,
+  handleCreate,
+  handleUpdate,
+  handleVerifyRecordExists,
+  handleGetHygieneScore,
+} from './tools.js';
+
+// ── Tool definitions ──────────────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'sf_query',
+    description: 'Run a SOQL query against Salesforce. Use for reading records with filters. Example: SELECT Id, Name, StageName FROM Opportunity WHERE StageName = \'Prospecting\'',
+    inputSchema: {
+      type: 'object',
+      properties: { soql: { type: 'string', description: 'The SOQL query to execute' } },
+      required: ['soql'],
+    },
+  },
+  {
+    name: 'sf_get_record',
+    description: 'Get a single Salesforce record by ID with specific fields.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        object_type: { type: 'string', description: 'Salesforce object API name (e.g. Opportunity, Contact, Account)' },
+        record_id:   { type: 'string', description: '18-character Salesforce record ID' },
+        fields:      { type: 'array', items: { type: 'string' }, description: 'Fields to return. Defaults to Id, Name.' },
+      },
+      required: ['object_type', 'record_id'],
+    },
+  },
+  {
+    name: 'sf_search',
+    description: 'Search across Salesforce objects using SOSL. Use when you have a name or keyword but not a specific ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        search_term:  { type: 'string', description: 'Text to search for' },
+        object_types: { type: 'array', items: { type: 'string' }, description: 'Objects to search. Defaults to Contact, Account, Lead, Opportunity.' },
+        fields:       { type: 'array', items: { type: 'string' }, description: 'Fields to return per object. Defaults to Id, Name.' },
+      },
+      required: ['search_term'],
+    },
+  },
+  {
+    name: 'sf_describe',
+    description: 'Get field metadata for a Salesforce object — field names, types, required fields, picklist values. Use before creating or updating records to know what fields exist.',
+    inputSchema: {
+      type: 'object',
+      properties: { object_type: { type: 'string', description: 'Salesforce object API name' } },
+      required: ['object_type'],
+    },
+  },
+  {
+    name: 'sf_create',
+    description: 'Create a new record in Salesforce. Always run sf_verify_exists first for Contact/Lead/Account to prevent duplicates.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        object_type: { type: 'string', description: 'Salesforce object API name' },
+        fields:      { type: 'object', description: 'Key-value pairs of field API names and values' },
+      },
+      required: ['object_type', 'fields'],
+    },
+  },
+  {
+    name: 'sf_update',
+    description: 'Update an existing Salesforce record. Requires the record ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        object_type: { type: 'string', description: 'Salesforce object API name' },
+        record_id:   { type: 'string', description: '18-character Salesforce record ID' },
+        fields:      { type: 'object', description: 'Key-value pairs of fields to update' },
+      },
+      required: ['object_type', 'record_id', 'fields'],
+    },
+  },
+  {
+    name: 'sf_verify_exists',
+    description: 'Check if a Contact or Lead already exists before creating one. Prevents duplicates. Matches by email first, then phone, then name+company. Always use before sf_create for people records.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        object_type: { type: 'string', description: 'Contact, Lead, or Account' },
+        name:        { type: 'string', description: 'Full name to check' },
+        email:       { type: 'string', description: 'Email address (most reliable match)' },
+        phone:       { type: 'string', description: 'Phone number' },
+        company:     { type: 'string', description: 'Company name (used with name match)' },
+      },
+      required: ['object_type'],
+    },
+  },
+  {
+    name: 'sf_hygiene_score',
+    description: 'Get a hygiene score (0-100) for a Salesforce Account. Checks field completeness, activity recency, stage accuracy, contact coverage, and next step presence. Returns score, grade, strengths, and issues.',
+    inputSchema: {
+      type: 'object',
+      properties: { account_id: { type: 'string', description: '18-character Salesforce Account ID' } },
+      required: ['account_id'],
+    },
+  },
+];
+
+// ── Handler map ───────────────────────────────────────────────────────────────
+
+const HANDLERS = {
+  sf_query:         handleQuery,
+  sf_get_record:    handleGetRecord,
+  sf_search:        handleSearch,
+  sf_describe:      handleDescribe,
+  sf_create:        handleCreate,
+  sf_update:        handleUpdate,
+  sf_verify_exists: handleVerifyRecordExists,
+  sf_hygiene_score: handleGetHygieneScore,
+};
+
+// ── Server ────────────────────────────────────────────────────────────────────
+
+const server = new Server(
+  { name: 'delegate-sf-mcp', version: '0.2.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params;
+
+  const handler = HANDLERS[name];
+  if (!handler) {
+    return {
+      content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+      isError: true,
+    };
+  }
+
+  try {
+    const text = await handler(args ?? {});
+    return { content: [{ type: 'text', text }] };
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `❌ ${err.message}` }],
+      isError: true,
+    };
+  }
+});
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/salesforce/client.js

@@ -0,0 +1,388 @@
+import jsforce from 'jsforce';
+import { TokenManager } from '../auth/token-manager.js';
+import { FileStorageManager } from '../auth/file-storage.js';
+
+export class SalesforceClient {
+  constructor(clientId, clientSecret, instanceUrl) {
+    this.clientId = clientId;
+    this.clientSecret = clientSecret;
+    this.instanceUrl = instanceUrl;
+    this.tokenManager = new TokenManager(clientId, clientSecret, instanceUrl);
+    this.connection = null;
+    this.initialized = false;
+  }
+
+  /**
+   * Initialize the Salesforce client
+   */
+  async initialize() {
+    if (this.initialized) {
+      return true;
+    }
+
+    try {
+      // Initialize token manager
+      const hasTokens = await this.tokenManager.initialize();
+      if (!hasTokens) {
+        throw new Error('Authentication required - no valid tokens found. Use the salesforce_auth tool to authenticate with Salesforce.');
+      }
+
+      // Create jsforce connection
+      await this.createConnection();
+      
+      this.initialized = true;
+      return true;
+    } catch (error) {
+      throw error;
+    }
+  }
+
+  /**
+   * Create and configure jsforce connection
+   */
+  async createConnection() {
+    try {
+      const accessToken = await this.tokenManager.getValidAccessToken();
+      const tokenInfo = this.tokenManager.getTokenInfo();
+
+      // Get API version from config file
+      const fileStorage = new FileStorageManager();
+      const apiConfig = await fileStorage.getApiConfig();
+
+      this.connection = new jsforce.Connection({
+        instanceUrl: tokenInfo.instance_url,
+        accessToken: accessToken,
+        version: apiConfig.apiVersion
+      });
+
+      // Test connection
+      await this.connection.identity();
+    } catch (error) {
+      throw new Error(`Failed to create Salesforce connection: ${error.message}`);
+    }
+  }
+
+  /**
+   * Ensure connection is valid, refresh if needed
+   */
+  async ensureValidConnection() {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+
+    try {
+      // Check if token needs refresh
+      if (await this.tokenManager.needsRefresh()) {
+        await this.tokenManager.refreshTokens();
+        await this.createConnection();
+      }
+    } catch (error) {
+      throw error;
+    }
+  }
+
+  /**
+   * Execute SOQL query
+   */
+  async query(soql, options = {}) {
+    await this.ensureValidConnection();
+
+    try {
+      const result = await this.connection.query(soql, options);
+      
+      return {
+        totalSize: result.totalSize,
+        done: result.done,
+        records: result.records,
+        nextRecordsUrl: result.nextRecordsUrl
+      };
+    } catch (error) {
+      // Handle authentication errors first
+      if (this.isAuthenticationError(error)) {
+        throw new Error('Authentication required - your Salesforce session has expired. Use the salesforce_auth tool to re-authenticate.');
+      }
+
+      // Handle specific Salesforce errors
+      if (error.name === 'INVALID_QUERY' || error.errorCode === 'INVALID_QUERY') {
+        throw new Error(`Invalid SOQL query: ${error.message}`);
+      }
+      
+      if (error.name === 'INVALID_FIELD' || error.errorCode === 'INVALID_FIELD') {
+        throw new Error(`Invalid field in query: ${error.message}`);
+      }
+
+      if (error.name === 'INVALID_TYPE' || error.errorCode === 'INVALID_TYPE') {
+        throw new Error(`Invalid object type: ${error.message}`);
+      }
+
+      // Handle authentication errors
+      if (error.message.includes('Session expired') || error.message.includes('INVALID_SESSION_ID')) {
+        await this.tokenManager.refreshTokens();
+        await this.createConnection();
+        // Retry once after token refresh
+        try {
+          const retryResult = await this.connection.query(soql, options);
+          return {
+            totalSize: retryResult.totalSize,
+            done: retryResult.done,
+            records: retryResult.records,
+            nextRecordsUrl: retryResult.nextRecordsUrl
+          };
+        } catch (retryError) {
+          throw new Error(`Query failed after token refresh: ${retryError.message}`);
+        }
+      }
+
+      // Generic error handling with better message
+      const errorMessage = error.message || 'Unknown Salesforce error';
+      throw new Error(`Salesforce query error: ${this.formatSalesforceError(error)}`);
+    }
+  }
+
+  /**
+   * Create a new record
+   */
+  async create(sobject, data) {
+    await this.ensureValidConnection();
+
+    try {
+      const result = await this.connection.sobject(sobject).create(data);
+      
+      if (result.success) {
+        return {
+          id: result.id,
+          success: true,
+          sobject: sobject,
+          data: data
+        };
+      } else {
+        throw new Error(`Create failed: ${JSON.stringify(result.errors)}`);
+      }
+    } catch (error) {
+      if (this.isAuthenticationError(error)) {
+        throw new Error('Authentication required - your Salesforce session has expired. Use the salesforce_auth tool to re-authenticate.');
+      }
+      throw new Error(`Create ${sobject} failed: ${this.formatSalesforceError(error)}`);
+    }
+  }
+
+  /**
+   * Update an existing record
+   */
+  async update(sobject, id, data) {
+    await this.ensureValidConnection();
+
+    try {
+      const result = await this.connection.sobject(sobject).update({
+        Id: id,
+        ...data
+      });
+      
+      if (result.success) {
+        return {
+          id: result.id,
+          success: true,
+          sobject: sobject,
+          data: data
+        };
+      } else {
+        throw new Error(`Update failed: ${JSON.stringify(result.errors)}`);
+      }
+    } catch (error) {
+      if (this.isAuthenticationError(error)) {
+        throw new Error('Authentication required - your Salesforce session has expired. Use the salesforce_auth tool to re-authenticate.');
+      }
+      throw new Error(`Update ${sobject} failed: ${this.formatSalesforceError(error)}`);
+    }
+  }
+
+  /**
+   * Delete a record
+   */
+  async delete(sobject, id) {
+    await this.ensureValidConnection();
+
+    try {
+      const result = await this.connection.sobject(sobject).destroy(id);
+      
+      if (result.success) {
+        return {
+          id: result.id,
+          success: true,
+          sobject: sobject
+        };
+      } else {
+        throw new Error(`Delete failed: ${JSON.stringify(result.errors)}`);
+      }
+    } catch (error) {
+      if (this.isAuthenticationError(error)) {
+        throw new Error('Authentication required - your Salesforce session has expired. Use the salesforce_auth tool to re-authenticate.');
+      }
+      throw new Error(`Delete ${sobject} failed: ${this.formatSalesforceError(error)}`);
+    }
+  }
+
+  /**
+   * Describe an SObject (get schema information)
+   */
+  async describe(sobject) {
+    await this.ensureValidConnection();
+
+    try {
+      const result = await this.connection.sobject(sobject).describe();
+      
+      return {
+        name: result.name,
+        label: result.label,
+        labelPlural: result.labelPlural,
+        keyPrefix: result.keyPrefix,
+        createable: result.createable,
+        updateable: result.updateable,
+        deletable: result.deletable,
+        queryable: result.queryable,
+        fields: result.fields.map(field => ({
+          name: field.name,
+          label: field.label,
+          type: field.type,
+          length: field.length,
+          required: !field.nillable && !field.defaultedOnCreate,
+          createable: field.createable,
+          updateable: field.updateable,
+          picklistValues: field.picklistValues || [],
+          referenceTo: field.referenceTo || [],
+          relationshipName: field.relationshipName
+        })),
+        recordTypeInfos: result.recordTypeInfos || []
+      };
+    } catch (error) {
+      if (this.isAuthenticationError(error)) {
+        throw new Error('Authentication required - your Salesforce session has expired. Use the salesforce_auth tool to re-authenticate.');
+      }
+      throw new Error(`Describe ${sobject} failed: ${this.formatSalesforceError(error)}`);
+    }
+  }
+
+  /**
+   * Get all available SObjects
+   */
+  async describeGlobal() {
+    await this.ensureValidConnection();
+
+    try {
+      const result = await this.connection.describeGlobal();
+      
+      const sobjects = result.sobjects
+        .filter(sobject => sobject.queryable) // Only queryable objects
+        .map(sobject => ({
+          name: sobject.name,
+          label: sobject.label,
+          labelPlural: sobject.labelPlural,
+          keyPrefix: sobject.keyPrefix,
+          custom: sobject.custom,
+          createable: sobject.createable,
+          updateable: sobject.updateable,
+          deletable: sobject.deletable,
+          queryable: sobject.queryable
+        }))
+        .sort((a, b) => a.label.localeCompare(b.label));
+
+      return sobjects;
+    } catch (error) {
+      if (this.isAuthenticationError(error)) {
+        throw new Error('Authentication required - your Salesforce session has expired. Use the salesforce_auth tool to re-authenticate.');
+      }
+      throw new Error(`Global describe failed: ${this.formatSalesforceError(error)}`);
+    }
+  }
+
+  /**
+   * Get user information
+   */
+  async getUserInfo() {
+    await this.ensureValidConnection();
+
+    try {
+      const identity = await this.connection.identity();
+      return {
+        id: identity.user_id,
+        username: identity.username,
+        display_name: identity.display_name,
+        email: identity.email,
+        organization_id: identity.organization_id,
+        urls: identity.urls
+      };
+    } catch (error) {
+      throw new Error(`Failed to get user info: ${this.formatSalesforceError(error)}`);
+    }
+  }
+
+  /**
+   * Format Salesforce error messages for better readability
+   */
+  formatSalesforceError(error) {
+    if (error.name === 'INVALID_FIELD') {
+      return `Invalid field: ${error.message}`;
+    }
+    if (error.name === 'REQUIRED_FIELD_MISSING') {
+      return `Required field missing: ${error.message}`;
+    }
+    if (error.name === 'FIELD_CUSTOM_VALIDATION_EXCEPTION') {
+      return `Validation rule failed: ${error.message}`;
+    }
+    if (error.name === 'INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY') {
+      return `Insufficient permissions: ${error.message}`;
+    }
+    if (error.name === 'INVALID_SESSION_ID') {
+      return 'Session expired - please re-authenticate';
+    }
+    
+    return error.message || 'Unknown Salesforce error';
+  }
+
+  /**
+   * Check if an error is authentication-related
+   */
+  isAuthenticationError(error) {
+    const authErrorIndicators = [
+      'INVALID_SESSION_ID',
+      'Session expired',
+      'invalid_grant',
+      'Authentication failure',
+      'Unauthorized',
+      'Invalid token',
+      'Token expired',
+      'Not authenticated',
+      'Authentication required',
+      'No access token available',
+      'refresh token is invalid',
+      'Session has expired'
+    ];
+
+    const errorMessage = error.message || '';
+    const errorString = error.toString() || '';
+    
+    return authErrorIndicators.some(indicator => 
+      errorMessage.includes(indicator) || errorString.includes(indicator)
+    );
+  }
+
+  /**
+   * Test connection health
+   */
+  async testConnection() {
+    try {
+      await this.ensureValidConnection();
+      const identity = await this.connection.identity();
+      return {
+        connected: true,
+        user: identity.username,
+        organization: identity.organization_id
+      };
+    } catch (error) {
+      return {
+        connected: false,
+        error: error.message
+      };
+    }
+  }
+}

package/src/sf-client.js

@@ -0,0 +1,79 @@
+/**
+ * sf-client.js — Salesforce connection
+ * Reads tokens.json, handles refresh automatically via jsforce v1
+ */
+
+import jsforce from 'jsforce';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TOKEN_FILE = path.join(__dirname, '..', 'tokens.json');
+
+let _conn = null;
+
+export function getConnection() {
+  if (_conn) return _conn;
+
+  if (!fs.existsSync(TOKEN_FILE)) {
+    throw new Error('No tokens.json found. Run: node auth.js');
+  }
+
+  const tokens = JSON.parse(fs.readFileSync(TOKEN_FILE, 'utf8'));
+
+  const oauth2 = new jsforce.OAuth2({
+    loginUrl:     tokens.loginUrl,
+    clientId:     tokens.clientId,
+    clientSecret: tokens.clientSecret,
+    redirectUri:  'http://localhost:8482/callback',
+  });
+
+  _conn = new jsforce.Connection({
+    oauth2,
+    instanceUrl:  tokens.instanceUrl,
+    accessToken:  tokens.accessToken,
+    refreshToken: tokens.refreshToken,
+    version:      '59.0',
+  });
+
+  // Persist refreshed tokens automatically
+  _conn.on('refresh', (newAccessToken) => {
+    const updated = { ...tokens, accessToken: newAccessToken };
+    fs.writeFileSync(TOKEN_FILE, JSON.stringify(updated, null, 2));
+  });
+
+  return _conn;
+}
+
+/** Run a SOQL query, return array of records */
+export async function query(soql) {
+  const conn = getConnection();
+  const result = await conn.query(soql);
+  return result.records;
+}
+
+/** Run SOSL search, return flat array of records across all types */
+export async function search(sosl) {
+  const conn = getConnection();
+  const result = await conn.search(sosl);
+  return result.searchRecords ?? [];
+}
+
+/** Describe a Salesforce object — returns field metadata */
+export async function describe(objectName) {
+  const conn = getConnection();
+  return await conn.describe(objectName);
+}
+
+/** Create a record */
+export async function createRecord(objectName, fields) {
+  const conn = getConnection();
+  return await conn.sobject(objectName).create(fields);
+}
+
+/** Update a record */
+export async function updateRecord(objectName, id, fields) {
+  const conn = getConnection();
+  return await conn.sobject(objectName).update({ Id: id, ...fields });
+}