feat: add @vlocode/mcp — MCP server for Salesforce/Vlocity agent operations

packages/mcp/README.md

@@ -0,0 +1,98 @@
+# @vlocode/mcp
+
+Vlocode **Model Context Protocol (MCP)** server that enables AI agents (GitHub Copilot, Claude, etc.) to interact with Salesforce and Vlocity datapacks directly from your IDE.
+
+## Features
+
+The server exposes the following tools:
+
+| Tool | Description |
+|------|-------------|
+| `deploy_datapacks` | Deploy Vlocity datapacks from local folders to Salesforce |
+| `retrieve_datapacks` | Export/retrieve Salesforce objects as Vlocity datapacks |
+| `deploy_metadata` | Deploy Salesforce metadata (Apex, LWC, etc.) |
+| `list_sobjects` | List all Salesforce objects in the connected org |
+| `describe_sobject` | Describe a Salesforce object with its fields and metadata |
+| `describe_sobject_field` | Describe a specific field on a Salesforce object |
+| `list_profiles` | List all Salesforce profiles |
+| `add_fls_to_profile` | Add Field Level Security permissions to a profile |
+
+## Installation
+
+```bash
+npm install -g @vlocode/mcp
+```
+
+## Usage
+
+### Command-line options
+
+```
+vlocode-mcp [options]
+
+Options:
+  -u, --user <username>   SFDX username or alias to connect to Salesforce
+  -i, --instance <url>    Salesforce instance URL (default: login.salesforce.com)
+  --log-level <level>     Log level: debug | verbose | info | warn | error
+  --debug                 Enable debug logging
+  --verbose               Enable verbose logging
+  -h, --help              Show help
+```
+
+### VS Code MCP configuration
+
+Add the following to your `.vscode/mcp.json` (or VS Code User Settings) to make the Vlocode MCP server available to GitHub Copilot and other agents:
+
+```json
+{
+  "servers": {
+    "vlocode": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@vlocode/mcp", "--user", "myorg@example.com"]
+    }
+  }
+}
+```
+
+Replace `myorg@example.com` with your SFDX org username or alias.
+
+### Authentication
+
+The server uses SFDX authentication. Ensure you have authenticated with the target org before starting the server:
+
+```bash
+sf org login web --alias myorg
+```
+
+## Examples
+
+### Deploy datapacks
+
+An agent can deploy datapacks using the `deploy_datapacks` tool:
+
+```
+Deploy the datapacks in ./datapacks/OmniScript to my Salesforce org
+```
+
+### Retrieve datapacks
+
+```
+Export the OmniScript record with ID a1B000000000000 as a datapack to ./output
+```
+
+### Describe a Salesforce object
+
+```
+What fields does the Account object have?
+```
+
+### Add FLS to a profile
+
+```
+Grant read access to Account.Phone and Account.Fax for the Standard profile
+```
+
+## License
+
+MIT

packages/mcp/bin/run

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Recreate __dirname for ESM
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+if (existsSync(join(__dirname, '../dist/mcp.mjs'))) {
+    await import('../dist/mcp.mjs');
+} else {
+    // Development mode: run via ts-node / tsx
+    const { register } = await import('node:module');
+    const { pathToFileURL } = await import('node:url');
+    register('ts-node/esm', pathToFileURL('./'));
+    await import('../src/index.ts');
+}

packages/mcp/package.json

@@ -0,0 +1,61 @@
+{
+    "name": "@vlocode/mcp",
+    "version": "1.41.2",
+    "description": "Vlocode MCP (Model Context Protocol) server for Salesforce and Vlocity datapack operations",
+    "keywords": [
+        "Vlocity",
+        "Salesforce",
+        "Datapacks",
+        "MCP",
+        "ModelContextProtocol"
+    ],
+    "bin": {
+        "vlocode-mcp": "bin/run"
+    },
+    "main": "src/index.ts",
+    "type": "module",
+    "publishConfig": {
+        "main": "dist/mcp.mjs",
+        "access": "public"
+    },
+    "readme": "./README.md",
+    "engines": {
+        "node": ">=20.0.0"
+    },
+    "scripts": {
+        "watch": "tsdown -c tsdown.config.mts --watch",
+        "build": "tsdown -c tsdown.config.mts",
+        "prepublish": "pnpm run clean && pnpm run build",
+        "pack-only": "pnpm pack",
+        "clean": "shx rm -rf ./dist './*.tgz' './src/**/*.{d.ts,ts.map,js.map,js}'"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Codeneos/vlocode.git"
+    },
+    "author": {
+        "name": "Peter van Gulik",
+        "email": "peter@curlybracket.nl"
+    },
+    "files": [
+        "/dist",
+        "/bin"
+    ],
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/Codeneos/vlocode/issues"
+    },
+    "homepage": "https://github.com/Codeneos/vlocode#readme",
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.27.1"
+    },
+    "devDependencies": {
+        "@vlocode/core": "workspace:*",
+        "@vlocode/salesforce": "workspace:*",
+        "@vlocode/util": "workspace:*",
+        "@vlocode/vlocity": "workspace:*",
+        "@vlocode/vlocity-deploy": "workspace:*",
+        "shx": "^0.3.4"
+    },
+    "publisher": "curlybracket"
+}

packages/mcp/src/index.ts

@@ -0,0 +1,82 @@
+import { LogLevel } from '@vlocode/core';
+import { startMcpServer, type VlocodeMcpOptions } from './server.js';
+
+/**
+ * Parse a minimal set of command-line options for the MCP server.
+ * We deliberately keep this lightweight (no Commander dependency)
+ * because the MCP server is meant to be embedded in agent configurations.
+ */
+function parseArgs(argv: string[]): VlocodeMcpOptions {
+    const opts: VlocodeMcpOptions = {};
+
+    for (let i = 2; i < argv.length; i++) {
+        const arg = argv[i];
+
+        if ((arg === '-u' || arg === '--user') && argv[i + 1]) {
+            opts.user = argv[++i];
+        } else if ((arg === '-i' || arg === '--instance') && argv[i + 1]) {
+            opts.instance = argv[++i];
+        } else if (arg === '--debug') {
+            opts.logLevel = LogLevel.debug;
+        } else if (arg === '--verbose') {
+            opts.logLevel = LogLevel.verbose;
+        } else if ((arg === '--log-level') && argv[i + 1]) {
+            const level = argv[++i].toLowerCase();
+            const levelMap: Record<string, LogLevel> = {
+                debug: LogLevel.debug,
+                verbose: LogLevel.verbose,
+                info: LogLevel.info,
+                warn: LogLevel.warn,
+                error: LogLevel.error,
+            };
+            opts.logLevel = levelMap[level] ?? LogLevel.warn;
+        } else if (arg === '--help' || arg === '-h') {
+            printHelp();
+            process.exit(0);
+        }
+    }
+
+    return opts;
+}
+
+function printHelp() {
+    process.stderr.write(
+        [
+            'Usage: vlocode-mcp [options]',
+            '',
+            'Start the Vlocode MCP (Model Context Protocol) server over stdio.',
+            '',
+            'Options:',
+            '  -u, --user <username>       SFDX username or alias to connect to Salesforce',
+            '  -i, --instance <url>        Salesforce instance URL (default: login.salesforce.com)',
+            '  --log-level <level>         Log level: debug | verbose | info | warn | error (default: warn)',
+            '  --debug                     Enable debug logging',
+            '  --verbose                   Enable verbose logging',
+            '  -h, --help                  Show this help message',
+            '',
+            'MCP tools exposed:',
+            '  deploy_datapacks            Deploy Vlocity datapacks from local folders',
+            '  retrieve_datapacks          Export Salesforce objects as datapacks',
+            '  deploy_metadata             Deploy Salesforce metadata',
+            '  list_sobjects               List all Salesforce objects',
+            '  describe_sobject            Describe a Salesforce object and its fields',
+            '  describe_sobject_field      Describe a specific field on a Salesforce object',
+            '  list_profiles               List all Salesforce profiles',
+            '  add_fls_to_profile          Add Field Level Security to a profile',
+            '',
+            'Example VS Code MCP configuration (.vscode/mcp.json):',
+            '  {',
+            '    "servers": {',
+            '      "vlocode": {',
+            '        "type": "stdio",',
+            '        "command": "npx",',
+            '        "args": ["-y", "@vlocode/mcp", "--user", "myorg@example.com"]',
+            '      }',
+            '    }',
+            '  }',
+        ].join('\n') + '\n'
+    );
+}
+
+const options = parseArgs(process.argv);
+await startMcpServer(options);