@salesforce/mcp 0.10.2 → 0.11.1

package/README.md

@@ -223,10 +223,8 @@ To configure [Cursor](https://www.cursor.com/) to work with Salesforce DX MCP Se
 {
   "mcpServers": {
     "salesforce": {
-      "command": {
-        "path": "npx",
-        "args": ["-y", "@salesforce/mcp", "--orgs", "DEFAULT_TARGET_ORG", "--toolsets", "all"]
-      }
+      "command": "npx",
+      "args": ["-y", "@salesforce/mcp", "--orgs", "DEFAULT_TARGET_ORG", "--toolsets", "all"]
     }
   }
 }

package/lib/sf-mcp-server.d.ts

@@ -2,12 +2,22 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Implementation } from '@modelcontextprotocol/sdk/types.js';
 import { ServerOptions } from '@modelcontextprotocol/sdk/server/index.js';
 import { Telemetry } from './telemetry.js';
+import { RateLimitConfig } from './shared/rate-limiter.js';
 type ToolMethodSignatures = {
     tool: McpServer['tool'];
     connect: McpServer['connect'];
 };
 /**
- * A server implementation that extends the base MCP server with telemetry capabilities.
+ * Extended server options that include telemetry and rate limiting
+ */
+export type SfMcpServerOptions = ServerOptions & {
+    /** Optional telemetry instance for tracking server events */
+    telemetry?: Telemetry;
+    /** Optional rate limiting configuration */
+    rateLimit?: Partial<RateLimitConfig>;
+};
+/**
+ * A server implementation that extends the base MCP server with telemetry and rate limiting capabilities.
  *
  * The method overloads for `tool` are taken directly from the source code for the original McpServer. They're
  * copied here so that the types don't get lost.
@@ -18,15 +28,15 @@ export declare class SfMcpServer extends McpServer implements ToolMethodSignatur
     private logger;
     /** Optional telemetry instance for tracking server events */
     private telemetry?;
+    /** Rate limiter for controlling tool call frequency */
+    private rateLimiter?;
     /**
      * Creates a new SfMcpServer instance
      *
      * @param {Implementation} serverInfo - The server implementation details
-     * @param {ServerOptions & { telemetry?: Telemetry }} [options] - Optional server configuration including telemetry
+     * @param {SfMcpServerOptions} [options] - Optional server configuration including telemetry and rate limiting
      */
-    constructor(serverInfo: Implementation, options?: ServerOptions & {
-        telemetry?: Telemetry;
-    });
+    constructor(serverInfo: Implementation, options?: SfMcpServerOptions);
     connect: McpServer['connect'];
     tool: McpServer['tool'];
 }

package/lib/sf-mcp-server.js

@@ -15,8 +15,9 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Logger } from '@salesforce/core';
+import { createRateLimiter } from './shared/rate-limiter.js';
 /**
- * A server implementation that extends the base MCP server with telemetry capabilities.
+ * A server implementation that extends the base MCP server with telemetry and rate limiting capabilities.
  *
  * The method overloads for `tool` are taken directly from the source code for the original McpServer. They're
  * copied here so that the types don't get lost.
@@ -27,15 +28,22 @@ export class SfMcpServer extends McpServer {
     logger = Logger.childFromRoot('mcp-server');
     /** Optional telemetry instance for tracking server events */
     telemetry;
+    /** Rate limiter for controlling tool call frequency */
+    rateLimiter;
     /**
      * Creates a new SfMcpServer instance
      *
      * @param {Implementation} serverInfo - The server implementation details
-     * @param {ServerOptions & { telemetry?: Telemetry }} [options] - Optional server configuration including telemetry
+     * @param {SfMcpServerOptions} [options] - Optional server configuration including telemetry and rate limiting
      */
     constructor(serverInfo, options) {
         super(serverInfo, options);
         this.telemetry = options?.telemetry;
+        // Initialize rate limiter if configuration is provided
+        if (options?.rateLimit !== undefined) {
+            this.rateLimiter = createRateLimiter(options.rateLimit);
+            this.logger.debug('Rate limiter initialized', options.rateLimit);
+        }
         this.server.oninitialized = () => {
             const clientInfo = this.server.getClientVersion();
             if (clientInfo) {
@@ -68,6 +76,28 @@ export class SfMcpServer extends McpServer {
         const cb = rest[rest.length - 1];
         const wrappedCb = async (args) => {
             this.logger.debug(`Tool ${name} called`);
+            // Check rate limit before executing tool
+            if (this.rateLimiter) {
+                const rateLimitResult = this.rateLimiter.checkLimit();
+                if (!rateLimitResult.allowed) {
+                    this.logger.warn(`Tool ${name} rate limited. Retry after: ${rateLimitResult.retryAfter ?? 0}ms`);
+                    this.telemetry?.sendEvent('TOOL_RATE_LIMITED', {
+                        name,
+                        retryAfter: rateLimitResult.retryAfter,
+                        remaining: rateLimitResult.remaining,
+                    });
+                    return {
+                        isError: true,
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Rate limit exceeded. Too many tool calls. Please wait ${Math.ceil((rateLimitResult.retryAfter ?? 0) / 1000)} seconds before trying again.`,
+                            },
+                        ],
+                    };
+                }
+                this.logger.debug(`Tool ${name} rate check passed. Remaining: ${rateLimitResult.remaining}`);
+            }
             const startTime = Date.now();
             const result = await cb(args);
             const runtimeMs = Date.now() - startTime;

package/lib/shared/auth.js

@@ -150,9 +150,7 @@ const defaultOrgMaps = {
 async function getDefaultConfig(property) {
     // If the directory changes, the singleton instance of ConfigAggregator is not updated.
     // It continues to use the old local or global config.
-    // Note: We could update ConfigAggregator to have a clearInstance method like StateAggregator
-    // @ts-expect-error Accessing private static instance to reset singleton between directory changes
-    ConfigAggregator.instance = undefined;
+    await ConfigAggregator.clearInstance();
     const aggregator = await ConfigAggregator.create();
     const config = aggregator.getInfo(property);
     const { value, path, key, location } = config;

package/lib/shared/rate-limiter.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Configuration options for rate limiting
+ */
+export type RateLimitConfig = {
+    /** Maximum number of calls allowed per window (default: 60) */
+    limit: number;
+    /** Time window in milliseconds (default: 60000 = 1 minute) */
+    windowMs: number;
+    /** Allow burst of calls above the average rate (default: 10) */
+    burstAllowance: number;
+};
+/**
+ * Result of a rate limit check
+ */
+export type RateLimitResult = {
+    /** Whether the request is allowed */
+    allowed: boolean;
+    /** Number of requests remaining in current window */
+    remaining: number;
+    /** Time in milliseconds until the window resets */
+    resetTime: number;
+    /** Time in milliseconds to wait before retrying (only set when allowed=false) */
+    retryAfter?: number;
+};
+/**
+ * Token bucket rate limiter with burst allowance support
+ *
+ * Uses a token bucket algorithm where:
+ * - Tokens are added at a steady rate (limit/windowMs)
+ * - Burst allowance determines the maximum tokens that can accumulate
+ * - Each request consumes one token
+ */
+export declare class RateLimiter {
+    private readonly config;
+    private tokens;
+    private lastRefill;
+    private readonly tokensPerMs;
+    /**
+     * Creates a new rate limiter
+     *
+     * @param config Rate limiting configuration
+     */
+    constructor(config: RateLimitConfig);
+    /**
+     * Check if a request should be allowed and consume a token if so
+     *
+     * @returns Rate limit result
+     */
+    checkLimit(): RateLimitResult;
+    /**
+     * Get current status without consuming a token
+     *
+     * @returns Rate limit result for status check
+     */
+    getStatus(): RateLimitResult;
+    /**
+     * Refill tokens based on elapsed time
+     *
+     * @param now Current timestamp
+     */
+    private refillTokens;
+    /**
+     * Calculate time until the rate limit window resets
+     *
+     * @returns Milliseconds until reset
+     */
+    private calculateResetTime;
+    /**
+     * Calculate how long to wait before retrying
+     *
+     * @returns Milliseconds to wait
+     */
+    private calculateRetryAfter;
+}
+/**
+ * Create a rate limiter with default configuration
+ *
+ * @param overrides Partial configuration to override defaults
+ * @returns Configured rate limiter
+ */
+export declare function createRateLimiter(overrides?: Partial<RateLimitConfig>): RateLimiter;

package/lib/shared/rate-limiter.js

@@ -0,0 +1,130 @@
+/*
+ * Copyright 2025, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Token bucket rate limiter with burst allowance support
+ *
+ * Uses a token bucket algorithm where:
+ * - Tokens are added at a steady rate (limit/windowMs)
+ * - Burst allowance determines the maximum tokens that can accumulate
+ * - Each request consumes one token
+ */
+export class RateLimiter {
+    config;
+    tokens;
+    lastRefill;
+    tokensPerMs;
+    /**
+     * Creates a new rate limiter
+     *
+     * @param config Rate limiting configuration
+     */
+    constructor(config) {
+        this.config = config;
+        this.tokens = config.burstAllowance; // Start with full burst capacity
+        this.lastRefill = Date.now();
+        this.tokensPerMs = config.limit / config.windowMs;
+    }
+    /**
+     * Check if a request should be allowed and consume a token if so
+     *
+     * @returns Rate limit result
+     */
+    checkLimit() {
+        const now = Date.now();
+        this.refillTokens(now);
+        if (this.tokens >= 1) {
+            // Allow the request and consume a token
+            this.tokens -= 1;
+            return {
+                allowed: true,
+                remaining: Math.floor(this.tokens),
+                resetTime: this.calculateResetTime(),
+            };
+        }
+        else {
+            // Rate limit exceeded
+            const retryAfter = this.calculateRetryAfter();
+            return {
+                allowed: false,
+                remaining: 0,
+                resetTime: this.calculateResetTime(),
+                retryAfter,
+            };
+        }
+    }
+    /**
+     * Get current status without consuming a token
+     *
+     * @returns Rate limit result for status check
+     */
+    getStatus() {
+        const now = Date.now();
+        this.refillTokens(now);
+        return {
+            allowed: this.tokens >= 1,
+            remaining: Math.floor(this.tokens),
+            resetTime: this.calculateResetTime(),
+        };
+    }
+    /**
+     * Refill tokens based on elapsed time
+     *
+     * @param now Current timestamp
+     */
+    refillTokens(now) {
+        const elapsed = now - this.lastRefill;
+        const tokensToAdd = elapsed * this.tokensPerMs;
+        if (tokensToAdd > 0) {
+            this.tokens = Math.min(this.config.burstAllowance, this.tokens + tokensToAdd);
+            this.lastRefill = now;
+        }
+    }
+    /**
+     * Calculate time until the rate limit window resets
+     *
+     * @returns Milliseconds until reset
+     */
+    calculateResetTime() {
+        // Time to refill one token
+        const timePerToken = 1 / this.tokensPerMs;
+        return Math.ceil(timePerToken);
+    }
+    /**
+     * Calculate how long to wait before retrying
+     *
+     * @returns Milliseconds to wait
+     */
+    calculateRetryAfter() {
+        // Time needed to accumulate one token
+        return Math.ceil(1 / this.tokensPerMs);
+    }
+}
+/**
+ * Create a rate limiter with default configuration
+ *
+ * @param overrides Partial configuration to override defaults
+ * @returns Configured rate limiter
+ */
+export function createRateLimiter(overrides = {}) {
+    const config = {
+        limit: 60, // 60 calls per minute
+        windowMs: 60 * 1000, // 1 minute
+        burstAllowance: 10, // Allow bursts of up to 10 calls
+        ...overrides,
+    };
+    return new RateLimiter(config);
+}
+//# sourceMappingURL=rate-limiter.js.map

package/lib/tools/users/sf-assign-permission-set.js

@@ -69,7 +69,7 @@ export const registerToolAssignPermissionSet = (server) => {
             const connection = await getConnection(usernameOrAlias);
             // We need to clear the instance so we know we have the most up to date aliases
             // If a user sets an alias after server start up, it was not getting picked up
-            StateAggregator.clearInstance();
+            await StateAggregator.clearInstanceAsync();
             // Must NOT be nullish coalescing (??) In case the LLM uses and empty string
             const assignTo = (await StateAggregator.getInstance()).aliases.resolveUsername(onBehalfOf || usernameOrAlias);
             if (!assignTo.includes('@')) {