@elitedcs/ghl-mcp 3.27.2 → 3.28.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 3.28.0 — Tool allowlist (issue #1): cut context cost on big installs
+
+Two new optional env vars let you gate which tools register at startup so
+unused schemas never load into context. Closes [issue #1](https://github.com/drjerryrelth/ghl-command-feedback/issues/1).
+
+**New env vars (both optional, both default-empty):**
+
+- `GHL_ENABLED_MODULES` — comma-separated module names to register
+  (e.g. `contacts,conversations,locations,custom-objects`).
+- `GHL_ENABLED_TOOLS` — comma-separated tool names to register
+  (e.g. `search_contacts,get_contact,update_custom_value`).
+
+**Filter precedence:**
+
+- Neither set → every tool registers (backward compatible).
+- Modules only → tools in those modules register.
+- Tools only → those exact tool names register.
+- Both set → UNION (a tool registers if its module is enabled OR its
+  name is explicitly listed).
+
+**Always-on tools** never get filtered out, so setup and recovery still
+work even with a heavily-restricted allowlist:
+`setup_ghl_mcp`, `request_license`, `get_mcp_version`,
+`auto_capture_firebase_script`, `enable_workflow_builder`, `health_check`.
+
+**Validation + logging:**
+
+- Whitespace and commas both work as separators. Matching is case-insensitive.
+- Unrecognized names log a one-line WARNING to stderr and are ignored
+  (startup never aborts).
+- When the allowlist is active, startup logs one summary:
+  `Tool allowlist active: registered N of M tools (modules=[...]; explicit-tools=[...])`.
+- When unset, zero extra noise — existing logs are unchanged.
+
+**Motivation (from the issue):** running 25+ registered locations with
+all 212 tools registered burned tokens on every message in chats that
+didn't need GHL. Now buyers can restrict the surface to the modules
+they actually use.
+
 ## 3.27.2 — Fix license metadata: MIT → Proprietary
 
 Metadata-only release. Corrects the npm package's stated license, which

package/README.md

@@ -709,9 +709,48 @@ Source repo is private. Contributors need an invitation from `drjerryrelth`. The
 | `GHL_USER_ID` | No* | Your GHL user ID. Required for workflow builder tools. |
 | `GHL_FIREBASE_API_KEY` | No* | Firebase API key from GHL's auth system. Required for workflow builder tools. |
 | `GHL_FIREBASE_REFRESH_TOKEN` | No* | Firebase refresh token. Required for workflow builder tools. May rotate periodically. |
+| `GHL_ENABLED_MODULES` | No | Comma-separated module names to limit which tool groups register at startup (e.g. `contacts,conversations,locations`). Unset = every module registers (default). See "Reducing context / token usage" below. |
+| `GHL_ENABLED_TOOLS` | No | Comma-separated individual tool names to register (e.g. `search_contacts,get_contact,update_custom_value`). Set alongside `GHL_ENABLED_MODULES` to add specific tools on top of whole-module enables. |
 
 *Required only for the workflow builder (internal API) tools. The standard API tools work without these.
 
+### Reducing context / token usage
+
+Every registered MCP tool's schema is shipped to the model on every message. With 212 tools that's a meaningful per-message context cost even in chats that never touch GHL. If you only use a slice of GHL Command, restrict the tool surface with `GHL_ENABLED_MODULES` and/or `GHL_ENABLED_TOOLS`:
+
+```jsonc
+// Claude Desktop config — enable whole modules
+"env": {
+  "GHL_API_KEY": "pit-...",
+  "GHL_LOCATION_ID": "...",
+  "GHL_ENABLED_MODULES": "contacts,conversations,locations,custom-objects"
+}
+```
+
+```jsonc
+// Or pin to individual tools
+"env": {
+  "GHL_API_KEY": "pit-...",
+  "GHL_LOCATION_ID": "...",
+  "GHL_ENABLED_TOOLS": "search_contacts,get_contact,update_custom_value"
+}
+```
+
+Rules of the road:
+
+- **Neither set → every tool registers** (default, backward compatible — your existing config keeps working unchanged).
+- **`GHL_ENABLED_MODULES` only** → register tools in those modules.
+- **`GHL_ENABLED_TOOLS` only** → register only those exact tool names.
+- **Both set** → register the **union**: a tool registers if its module is in `GHL_ENABLED_MODULES` OR its name is in `GHL_ENABLED_TOOLS`. (Whole modules plus a few extra tools.)
+- Whitespace and commas both work as separators. Matching is case-insensitive.
+- Always-on tools register regardless of the allowlist so setup and recovery still work: `setup_ghl_mcp`, `request_license`, `get_mcp_version`, `auto_capture_firebase_script`, `enable_workflow_builder`, `health_check`.
+- Unrecognized module/tool names log a one-line WARNING to stderr and are ignored. Startup never aborts.
+- On startup with the allowlist active, the server logs one summary line: `Tool allowlist active: registered N of M tools (...)`.
+
+**Valid module names** (use these in `GHL_ENABLED_MODULES`):
+
+`contacts`, `conversations`, `opportunities`, `calendars`, `locations`, `workflows`, `funnels`, `forms`, `surveys`, `payments`, `products`, `invoices`, `campaigns`, `users`, `media`, `social-planner`, `courses`, `businesses`, `blogs`, `emails`, `trigger-links`, `custom-objects`, `associations`, `estimates`, `coupons`, `webhooks`, `documents`, `bulk-operations`, `account-export`, `template-deployer`, `workflow-builder`, `funnel-builder`, `form-builder`, `pipeline-builder`, `workflow-cloner`, `smart-lists`, `reputation`, `email-campaigns`, `email-builder`, `memberships`, `validators`, `diagnostics`, `location-switcher`
+
 ---
 
 ## Troubleshooting

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@elitedcs/ghl-mcp",
-      version: "3.27.2",
+      version: "3.28.0",
       mcpName: "io.github.drjerryrelth/ghl-command",
       description: "GoHighLevel MCP Server for Claude. 212 tools \u2014 full CRM, automation, marketing control, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
       main: "dist/index.js",
@@ -1776,6 +1776,89 @@ ${errorBody}`
   }
 };
 
+// src/tools/tool-filter.ts
+var ALWAYS_ON_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "setup_ghl_mcp",
+  "request_license",
+  "get_mcp_version",
+  "auto_capture_firebase_script",
+  "enable_workflow_builder",
+  "health_check"
+]);
+function parseList(raw) {
+  if (raw === void 0) return null;
+  const items = raw.split(/[,\s]+/).map((x) => x.trim().toLowerCase()).filter((x) => x.length > 0);
+  return items.length > 0 ? items : null;
+}
+function parseAllowlist(env) {
+  const moduleList = parseList(env.GHL_ENABLED_MODULES);
+  const toolList = parseList(env.GHL_ENABLED_TOOLS);
+  return {
+    enabledModules: moduleList ? new Set(moduleList) : null,
+    enabledTools: toolList ? new Set(toolList) : null,
+    rawModuleInput: moduleList,
+    rawToolInput: toolList
+  };
+}
+function isAllowlistActive(config3) {
+  return config3.enabledModules !== null || config3.enabledTools !== null;
+}
+function shouldRegister(toolName, moduleName, config3) {
+  if (ALWAYS_ON_TOOL_NAMES.has(toolName)) return true;
+  if (!isAllowlistActive(config3)) return true;
+  const toolLower = toolName.toLowerCase();
+  const moduleLower = moduleName.toLowerCase();
+  const moduleEnabled = config3.enabledModules?.has(moduleLower) ?? false;
+  const toolEnabled = config3.enabledTools?.has(toolLower) ?? false;
+  return moduleEnabled || toolEnabled;
+}
+function wrapServerForModule(realServer, moduleName, config3, attemptedTools, registeredTools) {
+  return new Proxy(realServer, {
+    get(target, prop, receiver) {
+      if (prop === "tool") {
+        return (name, ...rest) => {
+          attemptedTools.add(name);
+          if (!shouldRegister(name, moduleName, config3)) {
+            return void 0;
+          }
+          registeredTools.add(name);
+          return target.tool(name, ...rest);
+        };
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+}
+function validateAndLog(config3, knownModules, attemptedTools, registeredTools, log = (m) => process.stderr.write(m)) {
+  if (!isAllowlistActive(config3)) return;
+  if (config3.rawModuleInput) {
+    const knownLower = new Set([...knownModules].map((m) => m.toLowerCase()));
+    const unknown = config3.rawModuleInput.filter((m) => !knownLower.has(m));
+    if (unknown.length > 0) {
+      log(
+        `[ghl-mcp] WARNING: GHL_ENABLED_MODULES has unrecognized name(s): ${unknown.join(", ")}. Known modules: ${[...knownModules].sort().join(", ")}.
+`
+      );
+    }
+  }
+  if (config3.rawToolInput) {
+    const attemptedLower = new Set([...attemptedTools].map((t) => t.toLowerCase()));
+    const unknown = config3.rawToolInput.filter((t) => !attemptedLower.has(t));
+    if (unknown.length > 0) {
+      log(
+        `[ghl-mcp] WARNING: GHL_ENABLED_TOOLS has unrecognized name(s): ${unknown.join(", ")}.
+`
+      );
+    }
+  }
+  const moduleSummary = config3.enabledModules && config3.enabledModules.size > 0 ? `modules=[${[...config3.enabledModules].sort().join(",")}]` : "modules=(none)";
+  const toolSummary = config3.enabledTools && config3.enabledTools.size > 0 ? `explicit-tools=[${[...config3.enabledTools].sort().join(",")}]` : "explicit-tools=(none)";
+  log(
+    `[ghl-mcp] Tool allowlist active: registered ${registeredTools.size} of ${attemptedTools.size} tools (${moduleSummary}; ${toolSummary}).
+`
+  );
+}
+
 // src/tools/contacts.ts
 var import_zod6 = require("zod");
 
@@ -8602,24 +8685,58 @@ var publicApiTools = [
   [registerAccountExportTools, "account-export"],
   [registerTemplateDeployerTools, "template-deployer"]
 ];
-function registerAllTools(server2, client, registry2, mcpVersion) {
-  for (const [register] of publicApiTools) {
-    register(server2, client);
+var internalApiTools = [
+  [registerWorkflowBuilderTools, "workflow-builder"],
+  [registerFunnelBuilderTools, "funnel-builder"],
+  [registerFormBuilderTools, "form-builder"],
+  [registerPipelineBuilderTools, "pipeline-builder"],
+  [registerWorkflowClonerTools, "workflow-cloner"],
+  [registerSmartListTools, "smart-lists"],
+  [registerReputationTools, "reputation"],
+  [registerEmailCampaignTools, "email-campaigns"],
+  [registerEmailBuilderInternalTools, "email-builder"],
+  [registerMembershipTools, "memberships"]
+];
+var VALIDATORS_MODULE = "validators";
+var DIAGNOSTICS_MODULE = "diagnostics";
+var LOCATION_SWITCHER_MODULE = "location-switcher";
+var KNOWN_MODULES = /* @__PURE__ */ new Set([
+  ...publicApiTools.map(([, label]) => label),
+  ...internalApiTools.map(([, label]) => label),
+  VALIDATORS_MODULE,
+  DIAGNOSTICS_MODULE,
+  LOCATION_SWITCHER_MODULE
+]);
+function registerAllTools(server2, client, registry2, mcpVersion, env = process.env) {
+  const config3 = parseAllowlist(env);
+  const attemptedTools = /* @__PURE__ */ new Set();
+  const registeredTools = /* @__PURE__ */ new Set();
+  const wrap = (moduleName) => wrapServerForModule(server2, moduleName, config3, attemptedTools, registeredTools);
+  for (const [register, moduleName] of publicApiTools) {
+    register(wrap(moduleName), client);
   }
   const builderClient = WorkflowBuilderClient.fromEnv(registry2) ?? WorkflowBuilderClient.fromFirstCompany(registry2);
-  registerWorkflowBuilderTools(server2, builderClient);
-  registerFunnelBuilderTools(server2, builderClient);
-  registerFormBuilderTools(server2, builderClient);
-  registerPipelineBuilderTools(server2, builderClient);
-  registerWorkflowClonerTools(server2, builderClient);
-  registerSmartListTools(server2, builderClient);
-  registerReputationTools(server2, builderClient);
-  registerEmailCampaignTools(server2, builderClient);
-  registerEmailBuilderInternalTools(server2, builderClient);
-  registerMembershipTools(server2, builderClient);
-  registerValidatorTools(server2, client, builderClient);
-  registerDiagnosticTools(server2, mcpVersion ?? "unknown", client, builderClient, registry2 ?? null);
-  registerLocationSwitcherTools(server2, client, builderClient, registry2, mcpVersion);
+  for (const [register, moduleName] of internalApiTools) {
+    register(wrap(moduleName), builderClient);
+  }
+  registerValidatorTools(wrap(VALIDATORS_MODULE), client, builderClient);
+  registerDiagnosticTools(
+    wrap(DIAGNOSTICS_MODULE),
+    mcpVersion ?? "unknown",
+    client,
+    builderClient,
+    registry2 ?? null
+  );
+  registerLocationSwitcherTools(
+    wrap(LOCATION_SWITCHER_MODULE),
+    client,
+    builderClient,
+    registry2,
+    mcpVersion
+  );
+  if (isAllowlistActive(config3)) {
+    validateAndLog(config3, KNOWN_MODULES, attemptedTools, registeredTools);
+  }
 }
 
 // src/attestation.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elitedcs/ghl-mcp",
-  "version": "3.27.2",
+  "version": "3.28.0",
   "mcpName": "io.github.drjerryrelth/ghl-command",
   "description": "GoHighLevel MCP Server for Claude. 212 tools — full CRM, automation, marketing control, and the only programmatic GHL workflow builder, now multi-tenant across client accounts.",
   "main": "dist/index.js",