@loopops/mcp-server 3.4.0 → 3.6.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 { registerScoringTools } from "./tools/scoring.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
@@ -57,5 +58,6 @@ registerCrmTools(server, allowedSkills);
 registerEngageTools(server, allowedSkills);
 registerAccountMasterTools(server, allowedSkills);
 registerTalTools(server, allowedSkills);
+registerScoringTools(server, allowedSkills);
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/tools/scoring.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ICP scoring MCP tool wrappers (Phase 3.4 + 3.5).
+ *
+ * Tools (ops + eng):
+ *   sync_account_master_icp_models   — apply config/account_master/icp_models.yaml → DB
+ *   score_account                    — score one account immediately
+ *   score_distribution               — band counts per active model
+ *   score_explain                    — per-feature breakdown for one account's score
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerScoringTools(server: McpServer, allowed: Set<string>): void;

package/dist/tools/scoring.js

@@ -0,0 +1,102 @@
+/**
+ * ICP scoring MCP tool wrappers (Phase 3.4 + 3.5).
+ *
+ * Tools (ops + eng):
+ *   sync_account_master_icp_models   — apply config/account_master/icp_models.yaml → DB
+ *   score_account                    — score one account immediately
+ *   score_distribution               — band counts per active model
+ *   score_explain                    — per-feature breakdown for one account's score
+ */
+import { z } from "zod";
+import { trpcMutation, trpcQuery } from "../api-client.js";
+import { safeTool } from "./_helpers.js";
+const accountIdentifierShape = {
+    accountId: z
+        .string()
+        .uuid()
+        .optional()
+        .describe("Account Master account_id (UUID). Use account_lookup if you don't have it."),
+    domain: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Account's primary domain (e.g. 'acme.com')."),
+    sfAccountId: z
+        .string()
+        .min(3)
+        .optional()
+        .describe("Salesforce Account ID."),
+    accountName: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Company name (matched after normalization)."),
+};
+export function registerScoringTools(server, allowed) {
+    if (allowed.has("sync_account_master_icp_models")) {
+        server.tool("sync_account_master_icp_models", [
+            "Apply config/account_master/icp_models.yaml to the DB. Reads YAML from GitHub, validates,",
+            "upserts icp_model rows by (model_name, model_version), and (by default) marks every",
+            "enriched account as pending_scoring so the score worker picks up the new model on its",
+            "next run.",
+            "",
+            "WRITE path for ICP model definitions. To create or edit a model:",
+            "  1. update_account_master_config file=icp_models  (commits new YAML to main)",
+            "  2. sync_account_master_icp_models                (apply YAML → DB; this tool)",
+            "  3. score_account (optional)                      (rescore a specific account immediately)",
+            "",
+            "Models in DB but absent from YAML are LEFT UNTOUCHED — to retire a model, set",
+            "is_active: false in YAML. Permanent deletion requires explicit DB action so a typo",
+            "doesn't orphan account_score rows.",
+            "",
+            "Idempotent. Safe to call after every update_account_master_config. Pass dryRun: true to",
+            "preview before applying.",
+        ].join("\n"), {
+            branch: z.string().optional().describe("Branch to read YAML from. Default: main."),
+            rescoreEnriched: z
+                .boolean()
+                .optional()
+                .describe("After applying model changes, mark every enriched account as pending_scoring. Default: true."),
+            dryRun: z
+                .boolean()
+                .optional()
+                .describe("Read + validate + diff against DB without writing. Default: false."),
+        }, safeTool(async (input) => trpcMutation("mcp.syncAccountMasterIcpModels", input)));
+    }
+    if (allowed.has("score_account")) {
+        server.tool("score_account", [
+            "Score one account immediately against every active ICP model. Resolves the account by",
+            "any of accountId / domain / sfAccountId / accountName.",
+            "",
+            "Use after a manual override or attribute backfill when you want the golden-record-driven",
+            "score to update without waiting for the next scheduled run. Inserts a fresh account_score",
+            "row (scoring is append-only) and applies the lifecycle transition (scored or",
+            "scoring_ineligible). Use score_explain afterward to see the per-feature breakdown.",
+        ].join("\n"), {
+            ...accountIdentifierShape,
+            forceRescore: z
+                .boolean()
+                .optional()
+                .describe("If true, marks the account pending_scoring even when it's currently in another scoring state. Default: true (the operator's intuition when calling this tool is 'rescore now')."),
+        }, safeTool(async (input) => trpcMutation("mcp.scoreAccount", input)));
+    }
+    if (allowed.has("score_distribution")) {
+        server.tool("score_distribution", "Band distribution per active ICP model. For each account, counts the most-recent score against each model. Useful for spotting model-tuning opportunities (e.g. 'all accounts are band C → bump weights') or comparing two model versions side-by-side during a migration.", {
+            modelName: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Filter to one model. Default: every active model."),
+        }, safeTool(async (input) => trpcQuery("mcp.scoreDistribution", input)));
+    }
+    if (allowed.has("score_explain")) {
+        server.tool("score_explain", "Per-feature points breakdown for one account's most-recent score against a model. Shows feature → category → weight → input value → points → source status, so you can answer 'why did Snowflake get 87?' or 'why is Acme scoring_ineligible?'", {
+            ...accountIdentifierShape,
+            modelName: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Model to explain. Default: the active model with the most-recent score."),
+        }, safeTool(async (input) => trpcQuery("mcp.scoreExplain", input)));
+    }
+}

package/dist/tools/tal.js

@@ -15,25 +15,6 @@
 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()
@@ -81,63 +62,36 @@ export function registerTalTools(server, allowed) {
                 .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.",
+    if (allowed.has("sync_account_master_tals")) {
+        server.tool("sync_account_master_tals", [
+            "Apply config/account_master/tals.yaml to the DB. Reads the YAML from GitHub, validates,",
+            "upserts target_account_list rows by tal_name, and (by default) re-evaluates each affected",
+            "TAL so membership reflects criteria changes immediately.",
             "",
-            "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).",
+            "This is the WRITE path for TAL definitions. To create or edit a TAL:",
+            "  1. update_account_master_config file=tals  (commits new YAML to main)",
+            "  2. sync_account_master_tals                (apply YAML → DB; this tool)",
+            "  3. evaluate_tal_now (optional)             (run sooner than the cron's next fire)",
             "",
-            "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"}',
-            "  ]",
-            "}",
+            "TALs in DB but absent from YAML are LEFT UNTOUCHED — to remove a TAL, set is_active: false",
+            "in YAML. Permanent deletion requires explicit DB action so an accidental YAML edit",
+            "doesn't orphan target_account_list_membership rows.",
+            "",
+            "Idempotent. Safe to call after every update_account_master_config. Pass dryRun: true to",
+            "preview before applying.",
         ].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
+            branch: 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"])
+                .describe("Branch to read YAML from. Default: main. Use a feature branch if you committed via update_account_master_config to a feature branch and want to test before merging."),
+            evaluate: z
+                .boolean()
                 .optional()
-                .describe("How often the evaluator should re-compute membership. 'frozen' = never recomputed. Default: weekly."),
-            maxSize: z
-                .number()
-                .int()
-                .positive()
+                .describe("After applying TAL changes, re-evaluate every affected TAL (criteria/is_active/max_size diffs) so membership picks up the new definition immediately. Default: true."),
+            dryRun: z
+                .boolean()
                 .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)));
+                .describe("Read + validate + diff against DB without writing. Useful for previewing a TAL edit before applying."),
+        }, safeTool(async (input) => trpcMutation("mcp.syncAccountMasterTals", input)));
     }
 }

package/package.json

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