@loopops/mcp-server 3.2.0 → 3.4.0

package/dist/api-client.js

@@ -272,10 +272,11 @@ function persistRotatedRefreshToken(newToken) {
  */
 async function diagnoseRefreshFailure(status, body) {
     const head = `Okta refresh failed (HTTP ${status}). Detail: ${body.slice(0, 300)}`;
-    const generic = "Your refresh token may be revoked or idle-expired. Re-run " +
-        "`npx @loopops/mcp-cli@latest login` (the `@latest` pin bypasses the " +
-        "npx cache, which can serve a stale cli with old tenant defaults for " +
-        "up to 24h after a publish).";
+    const generic = "Your refresh token may be revoked or idle-expired.\n" +
+        "  Diagnose: `npx @loopops/mcp-cli@latest doctor` — checks tenant config + token.\n" +
+        "  Fix:      `npx @loopops/mcp-cli@latest login` — re-authenticates from scratch.\n" +
+        "(The `@latest` pin matters: bare `npx @loopops/mcp-cli` may serve a " +
+        "cached older cli with stale tenant defaults for up to 24h after a publish.)";
     if (!apiUrl)
         return `${head}\n\n${generic}`;
     try {

package/dist/index.js

@@ -1,14 +1,27 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { trpcQuery } from "./api-client.js";
+import { registerIdentityTools } from "./tools/identity.js";
 import { registerReportingTools } from "./tools/reporting.js";
 import { registerConfigTools } from "./tools/config.js";
 import { registerEngTools } from "./tools/eng.js";
 import { registerCrmTools } from "./tools/crm.js";
 import { registerEngageTools } from "./tools/engage.js";
 import { registerAccountMasterTools } from "./tools/account-master.js";
+import { registerTalTools } from "./tools/tal.js";
+// Read our own package.json at runtime so the version baked into MCP
+// initialize-handshake `serverInfo.version` matches the published npm
+// version. Was hardcoded "1.0.0" — confusing in Claude Desktop logs and
+// any other MCP client that displays server version. `package.json` is
+// always included in npm tarballs, so the relative path `../package.json`
+// (from dist/index.js) resolves cleanly post-publish.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 const skillsResponseSchema = z.object({
     role: z.string(),
     skills: z.array(z.string()),
@@ -34,13 +47,15 @@ const allowedSkills = new Set(skills);
 console.error(`[MCP] Connected — role: ${role}, ${skills.length} skills`);
 const server = new McpServer({
     name: "loop-operations",
-    version: "1.0.0",
+    version: pkg.version,
 });
+registerIdentityTools(server, allowedSkills);
 registerReportingTools(server, allowedSkills);
 registerConfigTools(server, allowedSkills);
 registerEngTools(server, allowedSkills);
 registerCrmTools(server, allowedSkills);
 registerEngageTools(server, allowedSkills);
 registerAccountMasterTools(server, allowedSkills);
+registerTalTools(server, allowedSkills);
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/tools/identity.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Identity / connection-check tools.
+ *
+ * Currently just `mcp_whoami` — a data-independent first-call sanity check.
+ * Returns the caller's email, MCP role, SF user link state, and tool count.
+ * Designed for the onboarding flow: after install + restart, asking Claude
+ * "are you connected?" should resolve to this and confirm everything wired
+ * correctly without depending on having any actual Loop data yet.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerIdentityTools(server: McpServer, allowed: Set<string>): void;

package/dist/tools/identity.js

@@ -0,0 +1,21 @@
+/**
+ * Identity / connection-check tools.
+ *
+ * Currently just `mcp_whoami` — a data-independent first-call sanity check.
+ * Returns the caller's email, MCP role, SF user link state, and tool count.
+ * Designed for the onboarding flow: after install + restart, asking Claude
+ * "are you connected?" should resolve to this and confirm everything wired
+ * correctly without depending on having any actual Loop data yet.
+ */
+import { trpcQuery } from "../api-client.js";
+import { safeTool } from "./_helpers.js";
+export function registerIdentityTools(server, allowed) {
+    if (allowed.has("mcp_whoami")) {
+        server.tool("mcp_whoami", [
+            "Connection sanity check. Returns your email, MCP role, Salesforce user link state,",
+            "and the number of tools available to you. Use as a first-call verification after",
+            "install — works regardless of whether you have any Loop data yet, so it's a clean",
+            "way to confirm the auth chain (Okta → Loop → role resolution) is wired correctly.",
+        ].join(" "), {}, safeTool(async () => trpcQuery("mcp.whoami")));
+    }
+}

package/dist/tools/tal.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Target Account List (TAL) MCP tool wrappers.
+ *
+ * Phase 3.5.5 of docs/ACCOUNT-MASTER-PLAN.md.
+ *
+ * Tools (ops + eng):
+ *   list_tals             — catalog of every TAL with member counts
+ *   show_tal_membership   — paginated members of one TAL with key attributes
+ *   evaluate_tal_now      — manual trigger for the evaluator (one TAL)
+ *   create_tal            — define a new TAL with criteria + cadence
+ *
+ * tRPC procedures live in packages/api/src/routers/mcp.ts; input schemas
+ * in packages/api/src/routers/mcp-schemas.ts.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTalTools(server: McpServer, allowed: Set<string>): void;

package/dist/tools/tal.js

@@ -0,0 +1,143 @@
+/**
+ * Target Account List (TAL) MCP tool wrappers.
+ *
+ * Phase 3.5.5 of docs/ACCOUNT-MASTER-PLAN.md.
+ *
+ * Tools (ops + eng):
+ *   list_tals             — catalog of every TAL with member counts
+ *   show_tal_membership   — paginated members of one TAL with key attributes
+ *   evaluate_tal_now      — manual trigger for the evaluator (one TAL)
+ *   create_tal            — define a new TAL with criteria + cadence
+ *
+ * tRPC procedures live in packages/api/src/routers/mcp.ts; input schemas
+ * in packages/api/src/routers/mcp-schemas.ts.
+ */
+import { z } from "zod";
+import { trpcMutation, trpcQuery } from "../api-client.js";
+import { safeTool } from "./_helpers.js";
+// Local replicas of the criteria DSL types — kept narrow so the MCP
+// tool description doesn't have to ship the full zod schema. The
+// authoritative validator lives in mcp-schemas.ts; this is just for
+// tool-input typing on the client side.
+const conditionSchema = z.lazy(() => z.union([
+    z.object({
+        operator: z.enum(["AND", "OR", "NOT"]),
+        conditions: z.array(conditionSchema),
+    }),
+    z.object({
+        type: z.enum([
+            "attribute",
+            "score",
+            "lifecycle_state",
+            "member_of",
+            "exclusion",
+        ]),
+    }).passthrough(),
+]));
+const talIdentifierShape = {
+    talName: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Human-readable TAL name (e.g. 'signal_scanner_targets'). Easier to type than the UUID."),
+    talId: z
+        .string()
+        .uuid()
+        .optional()
+        .describe("TAL UUID. Use list_tals to discover it."),
+};
+export function registerTalTools(server, allowed) {
+    if (allowed.has("list_tals")) {
+        server.tool("list_tals", "Catalog every Target Account List (TAL): name, purpose, member count, cadence, active state, when last evaluated. TALs are named, criteria-based sets of accounts used by downstream consumers (signal scanner, ABM, outbound sequences, exclusion lists). Use this to discover what TALs exist before invoking show_tal_membership or evaluate_tal_now.", {
+            purpose: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Filter to a single purpose ('signal_scanner', 'outbound_sequence', 'abm_advertising', 'exclusion', etc.). Omit to see all."),
+            includeInactive: z
+                .boolean()
+                .optional()
+                .describe("Include TALs where is_active=false. Default: false."),
+        }, safeTool(async (input) => trpcQuery("mcp.listTals", input)));
+    }
+    if (allowed.has("show_tal_membership")) {
+        server.tool("show_tal_membership", "Show members of one Target Account List with their domain, segment, status, and when each was added. Includes the TAL's full membership criteria (DSL JSON) for context. Identify the TAL by tal_name (preferred) or tal_id. Capped at 100 members by default; pass `limit` for more.", {
+            ...talIdentifierShape,
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(500)
+                .optional()
+                .describe("Max members to return (1–500). Default: 100."),
+        }, safeTool(async (input) => trpcQuery("mcp.showTalMembership", input)));
+    }
+    if (allowed.has("evaluate_tal_now")) {
+        server.tool("evaluate_tal_now", "Manually trigger the TAL evaluator for one TAL right now. Re-computes membership against the current resolved record and applies adds/removes (with audit-log events). Use after editing a TAL's criteria, after a bulk enrichment run that may have changed which accounts qualify, or to skip waiting for the next scheduled evaluator pass. Pass `dryRun: true` to preview the changes without writing.", {
+            ...talIdentifierShape,
+            dryRun: z
+                .boolean()
+                .optional()
+                .describe("If true, classify changes but skip writes. Useful for previewing the impact of a criteria edit. Default: false."),
+        }, safeTool(async (input) => trpcMutation("mcp.evaluateTalNow", input)));
+    }
+    if (allowed.has("create_tal")) {
+        server.tool("create_tal", [
+            "Create a new Target Account List with a name, purpose, criteria DSL, and refresh cadence.",
+            "The TAL starts active but empty — call evaluate_tal_now to populate it.",
+            "",
+            "Criteria is a tree of conditions evaluated against an account's resolved attributes,",
+            "score, lifecycle states, and existing TAL memberships. Operators: AND, OR, NOT. Condition",
+            "types: attribute (with operators =, !=, >, >=, <, <=, in, not_in, exists, matches), score",
+            "(model + band), lifecycle_state (lifecycle_type + state), member_of (tal_name), exclusion",
+            "(tal_name — sugar for NOT member_of).",
+            "",
+            "Example criteria for 'enterprise US accounts that are enriched and not in the do-not-contact list':",
+            "{",
+            '  "operator": "AND",',
+            '  "conditions": [',
+            '    {"type": "attribute", "attribute": "employee_count", "operator": ">=", "value": 500},',
+            '    {"type": "attribute", "attribute": "hq_country", "operator": "=", "value": "US"},',
+            '    {"type": "lifecycle_state", "lifecycle_type": "enrichment", "state": "enriched"},',
+            '    {"type": "exclusion", "tal_name": "do_not_contact"}',
+            "  ]",
+            "}",
+        ].join("\n"), {
+            talName: z
+                .string()
+                .min(1)
+                .max(200)
+                .regex(/^[a-z0-9_]+$/, "tal_name must be snake_case")
+                .describe("Snake-case identifier (e.g. 'enterprise_expansion_targets'). Must be unique."),
+            description: z
+                .string()
+                .min(1)
+                .describe("One-sentence description of what this list is for and who consumes it."),
+            purpose: z
+                .enum([
+                "signal_scanner",
+                "abm_advertising",
+                "outbound_sequence",
+                "csm_book",
+                "event_invite",
+                "exclusion",
+            ])
+                .describe("What the TAL is for. Drives which consumers read it."),
+            consumerSystem: z
+                .string()
+                .optional()
+                .describe("Free-text identifier for the system that reads this TAL (e.g. 'signal_scanner', 'gong_engage'). Defaults to the purpose string."),
+            criteria: conditionSchema.describe("DSL tree of membership conditions. See tool description for grammar + example."),
+            refreshCadence: z
+                .enum(["frozen", "weekly", "daily", "hourly"])
+                .optional()
+                .describe("How often the evaluator should re-compute membership. 'frozen' = never recomputed. Default: weekly."),
+            maxSize: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Hard cap on TAL size. Matches above the cap are deterministically truncated. Omit for no cap."),
+        }, safeTool(async (input) => trpcMutation("mcp.createTal", input)));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopops/mcp-server",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Loop Operations MCP Server — AI skills for RevOps",
   "license": "UNLICENSED",
   "type": "module",