@loopops/mcp-server 3.3.0 → 3.4.0

package/dist/index.js

@@ -13,6 +13,7 @@ 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
@@ -55,5 +56,6 @@ 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/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.3.0",
+  "version": "3.4.0",
   "description": "Loop Operations MCP Server — AI skills for RevOps",
   "license": "UNLICENSED",
   "type": "module",