@loopops/mcp-server 3.5.0 → 3.7.0

package/dist/index.js

@@ -13,6 +13,8 @@ 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 { registerSfdcSyncTools } from "./tools/sfdc-sync.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 +59,7 @@ registerCrmTools(server, allowedSkills);
 registerEngageTools(server, allowedSkills);
 registerAccountMasterTools(server, allowedSkills);
 registerTalTools(server, allowedSkills);
+registerScoringTools(server, allowedSkills);
+registerSfdcSyncTools(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/sfdc-sync.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SFDC sync MCP tool wrappers (Phase 4).
+ *
+ * Tools (ops + eng):
+ *   deploy_account               — push one account immediately
+ *   approve_initial_deployment   — promote pending_initial_deployment_review
+ *                                  to pending_update_deployment
+ *   deployment_status            — top-line counts + initial-review queue
+ *   drift_report                 — drifted accounts
+ *   resolve_drift                — operator picks accept_am or accept_sf
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSfdcSyncTools(server: McpServer, allowed: Set<string>): void;

package/dist/tools/sfdc-sync.js

@@ -0,0 +1,91 @@
+/**
+ * SFDC sync MCP tool wrappers (Phase 4).
+ *
+ * Tools (ops + eng):
+ *   deploy_account               — push one account immediately
+ *   approve_initial_deployment   — promote pending_initial_deployment_review
+ *                                  to pending_update_deployment
+ *   deployment_status            — top-line counts + initial-review queue
+ *   drift_report                 — drifted accounts
+ *   resolve_drift                — operator picks accept_am or accept_sf
+ */
+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."),
+};
+export function registerSfdcSyncTools(server, allowed) {
+    if (allowed.has("deploy_account")) {
+        server.tool("deploy_account", [
+            "Push one account's golden record + score to Salesforce immediately. Builds the SF payload",
+            "from config/account_master/sfdc_field_map.yaml, PATCHes the SF Account record, and",
+            "updates salesforce_mapping with the canonical hash for drift detection.",
+            "",
+            "Use after a manual override or attribute backfill when you want SF updated immediately",
+            "instead of waiting for the next account_master_deploy_orchestrator cron fire (every 15m).",
+            "",
+            "Initial-deployment review accounts (no SF mapping yet, mode=review in YAML) are NOT",
+            "pushed by this tool. Approve them via approve_initial_deployment first.",
+        ].join("\n"), accountIdentifierShape, safeTool(async (input) => trpcMutation("mcp.deployAccount", input)));
+    }
+    if (allowed.has("approve_initial_deployment")) {
+        server.tool("approve_initial_deployment", [
+            "Approve an account currently in `pending_initial_deployment_review` (the queue gate when",
+            "config/account_master/sfdc_deploy.yaml has initial_deployment.mode=review). Promotes the",
+            "account to pending_update_deployment so the next deploy run pushes it to SF.",
+            "",
+            "Use this for the first push of every new account until you flip mode=auto in the YAML",
+            "(once you trust the eligibility filter + field map).",
+        ].join("\n"), accountIdentifierShape, safeTool(async (input) => trpcMutation("mcp.approveInitialDeployment", input)));
+    }
+    if (allowed.has("deployment_status")) {
+        server.tool("deployment_status", "Top-line counts of accounts in each deployment lifecycle state (pending review, pending update, deployed, deployment_failed, sync_drift). Includes a sample of the initial-review queue so ops can spot-check what's waiting for approval.", {
+            sampleSize: z
+                .number()
+                .int()
+                .positive()
+                .max(100)
+                .optional()
+                .describe("How many initial-review samples to surface (1-100). Default: 10."),
+        }, safeTool(async (input) => trpcQuery("mcp.deploymentStatus", input)));
+    }
+    if (allowed.has("drift_report")) {
+        server.tool("drift_report", "List accounts in `sync_drift` — where SF state diverged from the AM golden record. Each row shows the SF Account ID, when drift was detected, and the last-pushed hash. Resolve with `resolve_drift accountId=X choice=accept_am|accept_sf`.", {
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(500)
+                .optional()
+                .describe("Max drifted accounts to return. Default 50."),
+        }, safeTool(async (input) => trpcQuery("mcp.driftReport", input)));
+    }
+    if (allowed.has("resolve_drift")) {
+        server.tool("resolve_drift", [
+            "Resolve a drifted account by picking the canonical winner.",
+            "",
+            "  accept_am  → re-queue for deployment; AM values overwrite SF",
+            "  accept_sf  → treat SF as authoritative for the diverged fields; write them back into AM",
+            "               via manual overrides (v1 path requires a follow-up step — tool emits the",
+            "               recipe)",
+            "",
+            "Always include a `reason` — it lands on the lifecycle event for audit.",
+        ].join("\n"), {
+            ...accountIdentifierShape,
+            choice: z.enum(["accept_am", "accept_sf"]).describe("Which side wins."),
+            reason: z
+                .string()
+                .min(3)
+                .max(500)
+                .describe("Operator note for the lifecycle event audit log."),
+        }, safeTool(async (input) => trpcMutation("mcp.resolveDrift", input)));
+    }
+}

package/package.json

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