delegate-sf-mcp 0.2.0

package/.eslintrc.json

@@ -0,0 +1,20 @@
+{
+  "env": {
+    "es2022": true,
+    "node": true
+  },
+  "extends": [
+    "eslint:recommended"
+  ],
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module"
+  },
+  "rules": {
+    "indent": ["error", 2],
+    "quotes": ["error", "single"],
+    "semi": ["error", "always"],
+    "no-console": "off",
+    "no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]
+  }
+}

package/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, Aionda GmbH
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,76 @@
+# Delegate SF MCP — v0.2
+
+Nightly Salesforce hygiene sync. Human approval required before anything commits.
+
+## Setup
+
+### 1. Install
+
+```bash
+npm install
+```
+
+### 2. Salesforce Connected App
+
+In Salesforce Setup → App Manager → New Connected App:
+- Enable OAuth Settings: ✅
+- Callback URL: `http://localhost:8482/callback`
+- OAuth Scopes: `api`, `refresh_token`
+- Save → wait 2-10 min to propagate
+
+Copy the **Consumer Key** and **Consumer Secret**.
+
+### 3. Authenticate
+
+```bash
+node auth.js
+```
+
+Browser opens → log in → approve → tokens saved to `tokens.json`. Done.
+
+### 4. Configure Claude Desktop
+
+In `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "delegate-sf": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/delegate-mcp/src/index.js"]
+    }
+  }
+}
+```
+
+Replace `/ABSOLUTE/PATH/TO/delegate-mcp` with the actual path.
+
+### 5. Restart Claude Desktop
+
+Quit fully (⌘Q) and reopen. The tools should appear.
+
+---
+
+## Tools
+
+| Tool | What it does |
+|------|-------------|
+| `sf_query` | Run any SOQL query |
+| `sf_get_record` | Get a record by ID |
+| `sf_search` | SOSL search by name/keyword |
+| `sf_describe` | Get field metadata for any object |
+| `sf_create` | Create a record (runs verify first) |
+| `sf_update` | Update a record |
+| `sf_verify_exists` | Duplicate check before create |
+| `sf_hygiene_score` | Account hygiene score 0–100 |
+
+---
+
+## Re-authenticate
+
+```bash
+node auth.js
+# Answer 'y' to re-authenticate
+```
+
+Tokens refresh automatically during normal use.

package/auth.js

@@ -0,0 +1,148 @@
+/**
+ * auth.js — Delegate SF MCP Auth
+ *
+ * Run once: node auth.js
+ * Browser opens → approve in Salesforce → tokens saved to tokens.json
+ * Then start the MCP: node src/index.js
+ */
+
+import jsforce from 'jsforce';
+import http from 'http';
+import { exec } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import readline from 'readline';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TOKEN_FILE = path.join(__dirname, 'tokens.json');
+const PORT = 8482;
+const REDIRECT_URI = `http://localhost:${PORT}/callback`;
+
+// ── Prompt helpers ────────────────────────────────────────────────────────────
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+const ask = (q) => new Promise(resolve => rl.question(q, resolve));
+
+function openBrowser(url) {
+  const cmd =
+    process.platform === 'darwin' ? `open "${url}"` :
+    process.platform === 'win32'  ? `start "" "${url}"` :
+    `xdg-open "${url}"`;
+  exec(cmd, err => { if (err) console.log(`\nCould not auto-open browser. Visit manually:\n${url}\n`); });
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+console.log('\n━━━ Delegate SF MCP — Auth Setup ━━━\n');
+
+// Check for existing tokens
+if (fs.existsSync(TOKEN_FILE)) {
+  const existing = JSON.parse(fs.readFileSync(TOKEN_FILE, 'utf8'));
+  console.log(`Found existing tokens for: ${existing.instanceUrl}`);
+  const reauth = await ask('Re-authenticate? (y/N): ');
+  if (reauth.toLowerCase() !== 'y') {
+    console.log('Using existing tokens. Run: node src/index.js');
+    process.exit(0);
+  }
+}
+
+// Get credentials
+console.log('\nYou need a Salesforce Connected App with:');
+console.log(`  Callback URL: ${REDIRECT_URI}`);
+console.log('  OAuth Scopes: api, refresh_token\n');
+
+const loginUrl    = await ask('Login URL (press Enter for https://login.salesforce.com): ');
+const clientId    = await ask('Consumer Key: ');
+const clientSecret = await ask('Consumer Secret: ');
+rl.close();
+
+const oauth2 = new jsforce.OAuth2({
+  loginUrl: loginUrl.trim() || 'https://login.salesforce.com',
+  clientId: clientId.trim(),
+  clientSecret: clientSecret.trim(),
+  redirectUri: REDIRECT_URI,
+});
+
+const authUrl = oauth2.getAuthorizationUrl({ scope: 'api refresh_token sfap_api mcp_api' });
+
+// ── Local callback server ─────────────────────────────────────────────────────
+
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url, `http://localhost:${PORT}`);
+
+  if (url.pathname !== '/callback') {
+    res.writeHead(404);
+    res.end('Not found');
+    return;
+  }
+
+  const code = url.searchParams.get('code');
+  const error = url.searchParams.get('error');
+
+  if (error || !code) {
+    const msg = error || 'No code returned';
+    res.writeHead(400);
+    res.end(`<h2 style="font-family:sans-serif;color:red">❌ Auth failed: ${msg}</h2>`);
+    server.close();
+    console.error(`\n❌ Auth failed: ${msg}`);
+    process.exit(1);
+  }
+
+  try {
+    const conn = new jsforce.Connection({ oauth2 });
+    await conn.authorize(code);
+
+    const tokens = {
+      instanceUrl:  conn.instanceUrl,
+      accessToken:  conn.accessToken,
+      refreshToken: conn.refreshToken,
+      clientId:     clientId.trim(),
+      clientSecret: clientSecret.trim(),
+      loginUrl:     loginUrl.trim() || 'https://login.salesforce.com',
+    };
+
+    fs.writeFileSync(TOKEN_FILE, JSON.stringify(tokens, null, 2));
+
+    // Quick test — get user info
+    const identity = await conn.identity();
+
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end(`
+      <html><body style="font-family:sans-serif;padding:40px;max-width:500px">
+        <h2>✅ Authorized!</h2>
+        <p>Logged in as <strong>${identity.display_name}</strong> (${identity.email})</p>
+        <p>Instance: <code>${conn.instanceUrl}</code></p>
+        <p>Tokens saved to <code>tokens.json</code>.</p>
+        <p>You can close this tab.<br>Start the MCP server: <code>node src/index.js</code></p>
+      </body></html>
+    `);
+
+    server.close();
+    console.log(`\n✅ Authorized as: ${identity.display_name} (${identity.email})`);
+    console.log(`   Instance: ${conn.instanceUrl}`);
+    console.log('   Tokens saved to tokens.json\n');
+    console.log('Next step: node src/index.js\n');
+    process.exit(0);
+
+  } catch (err) {
+    res.writeHead(500, { 'Content-Type': 'text/html' });
+    res.end(`<html><body style="font-family:sans-serif;padding:40px"><h2 style="color:red">❌ Error</h2><pre>${err.message}</pre></body></html>`);
+    server.close();
+    console.error('\n❌ Token exchange failed:', err.message);
+    process.exit(1);
+  }
+});
+
+server.listen(PORT, () => {
+  console.log(`\nOpening Salesforce login in your browser...`);
+  console.log(`(If browser doesn't open, visit: ${authUrl})\n`);
+  openBrowser(authUrl);
+});
+
+// Timeout after 2 minutes
+setTimeout(() => {
+  console.error('\n⏱  Timed out waiting for auth. Run auth.js again.');
+  server.close();
+  process.exit(1);
+}, 120_000);

package/bin/config-helper.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+import { config } from 'dotenv';
+import { FileStorageManager } from '../src/auth/file-storage.js';
+
+// Load environment variables
+config();
+
+async function showConfigHelper() {
+  console.log('🔧 MCP Salesforce Connected App Configuration Helper');
+  console.log('===================================================\n');
+
+  console.log('Your Salesforce Connected App needs to be configured with the following callback URLs:\n');
+
+  // Show multiple callback URLs to cover different scenarios
+  const ports = [8080, 8000, 8001, 8002, 8003, 8004, 8005];
+  console.log('Callback URLs to add to your Salesforce Connected App:');
+  ports.forEach(port => {
+    console.log(`• http://localhost:${port}/callback`);
+  });
+
+  console.log('\nInstructions:');
+  console.log('1. Go to Salesforce Setup → App Manager');
+  console.log('2. Find your Connected App and click "View"');
+  console.log('3. Click "Manage" → "Edit Policies"');
+  console.log('4. In "Callback URL" section, add ALL the URLs listed above');
+  console.log('5. Save the changes');
+  console.log('6. Wait 2-10 minutes for changes to propagate\n');
+
+  console.log('Current Configuration:');
+  try {
+    const fileStorage = new FileStorageManager();
+    const credentials = await fileStorage.getCredentials();
+    const apiConfig = await fileStorage.getApiConfig();
+    
+    if (credentials) {
+      console.log(`• Instance URL: ${credentials.instanceUrl}`);
+      console.log(`• Client ID: ${credentials.clientId?.substring(0, 20)}...`);
+      console.log(`• Preferred Port: ${apiConfig.callbackPort}`);
+    } else {
+      console.log('• No configuration found in ~/.mcp-salesforce.json');
+      console.log('• Please run the salesforce_setup tool first');
+    }
+  } catch (error) {
+    console.log(`• Error reading configuration: ${error.message}`);
+  }
+
+  console.log('\nAfter updating your Connected App, run: npm run setup');
+}
+
+showConfigHelper().catch(console.error);

package/bin/mcp-salesforce.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+// Simple wrapper to run the main index.js file
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Import and run the main module
+const mainModule = path.join(__dirname, '..', 'src', 'index.js');
+import(mainModule);

package/bin/setup.js

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+
+import { config } from 'dotenv';
+import { TokenManager } from '../src/auth/token-manager.js';
+import { FileStorageManager } from '../src/auth/file-storage.js';
+import { readFile } from 'fs/promises';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+// Load environment variables
+config();
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+class SetupTool {
+  constructor() {
+    this.fileStorage = new FileStorageManager();
+  }
+
+  /**
+   * Display welcome message and instructions
+   */
+  displayWelcome() {
+    console.log('🚀 MCP Salesforce Server Setup Tool');
+    console.log('=====================================\n');
+    
+    console.log('This tool will help you authenticate with Salesforce using OAuth.');
+    console.log('You will need:\n');
+    
+    console.log('1. A Salesforce Connected App with OAuth enabled');
+    console.log('2. The Consumer Key (Client ID) and Consumer Secret');
+    console.log('3. Your Salesforce instance URL (e.g., https://yourorg.salesforce.com)\n');
+    
+    console.log('📖 For setup instructions, see: docs/oauth-guide.md\n');
+  }
+
+  /**
+   * Validate required configuration
+   */
+  async validateConfiguration() {
+    console.log('🔍 Checking configuration...');
+    
+    try {
+      const credentials = await this.fileStorage.getCredentials();
+      
+      if (!credentials) {
+        console.error('\n❌ No Salesforce credentials found in ~/.mcp-salesforce.json');
+        console.error('📝 Please run the salesforce_setup tool first to configure your credentials.');
+        process.exit(1);
+      }
+
+      const { clientId, clientSecret, instanceUrl } = credentials;
+      
+      if (!clientId || !clientSecret || !instanceUrl) {
+        console.error('\n❌ Incomplete credentials in ~/.mcp-salesforce.json');
+        console.error('📝 Please run the salesforce_setup tool to reconfigure your credentials.');
+        process.exit(1);
+      }
+
+      console.log(`✅ Client ID: ${this.maskSensitive('CLIENT_ID', clientId)}`);
+      console.log(`✅ Client Secret: ${this.maskSensitive('CLIENT_SECRET', clientSecret)}`);
+      console.log(`✅ Instance URL: ${instanceUrl}`);
+      
+      console.log('✅ Configuration valid\n');
+      return credentials;
+    } catch (error) {
+      console.error(`\n❌ Error reading configuration: ${error.message}`);
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Mask sensitive values for display
+   */
+  maskSensitive(key, value) {
+    if (key.includes('SECRET')) {
+      return value.substring(0, 8) + '***';
+    }
+    if (key.includes('CLIENT_ID')) {
+      return value.substring(0, 12) + '***';
+    }
+    return value;
+  }
+
+  /**
+   * Test Salesforce instance connectivity
+   */
+  async testConnectivity(instanceUrl) {
+    console.log('🔗 Testing Salesforce instance connectivity...');
+    
+    try {
+      const response = await fetch(`${instanceUrl}/services/data/`, {
+        method: 'GET',
+        timeout: 10000
+      });
+
+      if (response.ok) {
+        const data = await response.json();
+        console.log(`✅ Successfully connected to ${instanceUrl}`);
+        console.log(`📊 Available API versions: ${data.length}`);
+        return true;
+      } else {
+        console.error(`❌ HTTP ${response.status}: ${response.statusText}`);
+        return false;
+      }
+    } catch (error) {
+      console.error(`❌ Connection failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Perform OAuth authentication flow
+   */
+  async performOAuth(clientId, clientSecret, instanceUrl) {
+    console.log('🔐 Starting OAuth authentication flow...\n');
+    
+    try {
+      const tokenManager = new TokenManager(clientId, clientSecret, instanceUrl);
+      
+      console.log('📝 Instructions:');
+      console.log('1. Your browser will open to Salesforce login');
+      console.log('2. Log in with your Salesforce credentials');
+      console.log('3. If prompted, approve the OAuth request');
+      console.log('4. The browser will redirect back automatically\n');
+      
+      // Wait for user to be ready
+      console.log('Press Enter when ready to continue...');
+      await this.waitForInput();
+      
+      // Perform authentication
+      const tokens = await tokenManager.authenticateWithOAuth();
+      
+      console.log('\n✅ OAuth authentication successful!');
+      console.log(`🏢 Instance: ${tokens.instance_url}`);
+      console.log(`⏰ Token expires: ${new Date(tokens.expires_at).toLocaleString()}`);
+      
+      return tokens;
+    } catch (error) {
+      console.error(`\n❌ OAuth authentication failed: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Test the stored tokens by making an API call
+   */
+  async testAuthentication(credentials) {
+    console.log('\n🧪 Testing authentication...');
+    
+    try {
+      const tokenManager = new TokenManager(credentials.clientId, credentials.clientSecret, credentials.instanceUrl);
+      await tokenManager.initialize();
+      
+      const result = await tokenManager.testTokens();
+      
+      if (result.valid) {
+        console.log('✅ Authentication test successful!');
+        console.log(`📡 API versions available: ${result.apiVersions}`);
+        return true;
+      } else {
+        console.error(`❌ Authentication test failed: ${result.error}`);
+        return false;
+      }
+    } catch (error) {
+      console.error(`❌ Authentication test error: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Display final setup summary
+   */
+  async displaySummary() {
+    console.log('\n🎉 Setup Complete!');
+    console.log('==================\n');
+    
+    console.log('Your MCP Salesforce server is now configured and ready to use.\n');
+    
+    console.log('Next steps:');
+    console.log('1. Add the server to your Claude Desktop configuration');
+    console.log('2. Restart Claude Desktop');
+    console.log('3. Start using Salesforce tools in your conversations\n');
+    
+    console.log('Configuration for Claude Desktop:');
+    console.log('```json');
+    console.log('{');
+    console.log('  "mcpServers": {');
+    console.log('    "salesforce": {');
+    console.log('      "command": "node",');
+    console.log(`      "args": ["${join(process.cwd(), 'src/index.js')}"]`);
+    console.log('    }');
+    console.log('  }');
+    console.log('}```\n');
+    
+    console.log('📚 For more information, see the documentation in the docs/ folder.');
+    console.log('🔧 Your credentials are stored securely in ~/.mcp-salesforce.json');
+  }
+
+  /**
+   * Wait for user input
+   */
+  async waitForInput() {
+    return new Promise((resolve) => {
+      process.stdin.once('data', () => {
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Main setup process
+   */
+  async run() {
+    try {
+      this.displayWelcome();
+      
+      // Validate configuration
+      const credentials = await this.validateConfiguration();
+      
+      // Test connectivity
+      const connected = await this.testConnectivity(credentials.instanceUrl);
+      if (!connected) {
+        console.error('\n❌ Cannot connect to Salesforce instance. Please check your instance URL.');
+        process.exit(1);
+      }
+      
+      // Perform OAuth flow
+      await this.performOAuth(
+        credentials.clientId,
+        credentials.clientSecret,
+        credentials.instanceUrl
+      );
+      
+      // Test authentication
+      const authValid = await this.testAuthentication(credentials);
+      
+      if (!authValid) {
+        console.error('\n❌ Authentication test failed. Please try running setup again.');
+        process.exit(1);
+      }
+      
+      // Show summary
+      await this.displaySummary();
+      
+      console.log('✅ Setup completed successfully!');
+      process.exit(0);
+      
+    } catch (error) {
+      console.error(`\n💥 Setup failed: ${error.message}`);
+      console.error('\n🔧 Troubleshooting:');
+      console.error('1. Check your ~/.mcp-salesforce.json configuration');
+      console.error('2. Verify your Salesforce Connected App settings');
+      console.error('3. Ensure you have the correct permissions');
+      console.error('4. Check your network connection\n');
+      process.exit(1);
+    }
+  }
+}
+
+// Run setup if called directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const setup = new SetupTool();
+  setup.run();
+}