@loopops/mcp-server 3.13.0 → 3.19.0

package/dist/index.js

@@ -9,6 +9,7 @@ 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 { registerDeployTools } from "./tools/deploy.js";
 import { registerEngTools } from "./tools/eng.js";
 import { registerCrmTools } from "./tools/crm.js";
 import { registerEngageTools } from "./tools/engage.js";
@@ -60,6 +61,7 @@ registerCrmTools(server, allowedSkills);
 registerEngageTools(server, allowedSkills);
 registerAccountMasterTools(server, allowedSkills);
 registerPeopleMasterTools(server, allowedSkills);
+registerDeployTools(server, allowedSkills);
 registerTalTools(server, allowedSkills);
 registerScoringTools(server, allowedSkills);
 registerSfdcSyncTools(server, allowedSkills);

package/dist/tools/account-master.js

@@ -47,13 +47,21 @@ export function registerAccountMasterTools(server, allowed) {
         }, safeTool(async (input) => trpcQuery("mcp.accountLookup", input)));
     }
     if (allowed.has("account_show")) {
-        server.tool("account_show", "Show full detail for one Account Master account: identifiers, lifecycle states (enrichment / scoring / deployment), linked legal entities, resolved attributes (the golden record with provenance), latest ICP score, TAL memberships, Salesforce mapping, and recent lifecycle events. Use account_lookup first if you only have a domain or name.", {
+        server.tool("account_show", "Show full detail for one Account Master account: identifiers, lifecycle states (enrichment / scoring / deployment), linked legal entities, resolved attributes (the golden record with provenance), latest ICP score, TAL memberships, Salesforce mapping, parent + immediate children, and recent lifecycle events. Use account_lookup first if you only have a domain or name. Use walk_account_hierarchy for the full descendants subtree.", {
             accountId: z
                 .string()
                 .uuid()
                 .describe("Account Master account_id (UUID). Use account_lookup if you don't have it yet."),
         }, safeTool(async ({ accountId }) => trpcQuery("mcp.accountShow", { accountId })));
     }
+    if (allowed.has("walk_account_hierarchy")) {
+        server.tool("walk_account_hierarchy", "Show one account's place in the parent_account_id graph — ancestors (chain up to the ultimate parent) and the full descendants subtree (BFS, depth-tagged). When you have any one of Disney's selling units, this gives you all of them. Read-only. Cycle-safe (capped at depth 32). Use account_show for the full per-account detail; use account_lookup if you don't have an account_id yet.", {
+            accountId: z
+                .string()
+                .uuid()
+                .describe("Account Master account_id (UUID) to walk from. The walk shows ancestors above and descendants below this point."),
+        }, safeTool(async ({ accountId }) => trpcQuery("mcp.walkAccountHierarchy", { accountId })));
+    }
     if (allowed.has("list_pending_account_matches")) {
         server.tool("list_pending_account_matches", "Show inbound candidates currently in `match_status='needs_review'` — the queue of inbound rows the matcher couldn't confidently resolve. Each entry includes the source, ingestion time, and the normalized attributes the matcher saw, so you can run `account_lookup` against them to investigate.", {
             limit: z

package/dist/tools/deploy.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Deploy — placement-pipeline MCP tools (ops+).
+ *
+ * Phase 1.2 (this file) ships the first user-placement tool:
+ *   propose_user_assignments — run the Python placement model on Modal,
+ *                              persist proposals against an open
+ *                              planning_cycle. See docs/DEPLOY-PLAN.md.
+ *
+ * The review/edit/approve/commit triplet (Phase 1.3–1.5) lands here too
+ * as it ships. Quota + account placement (Phases 2–3) get separate
+ * groups on top.
+ *
+ * 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 registerDeployTools(server: McpServer, allowed: Set<string>): void;

package/dist/tools/deploy.js

@@ -0,0 +1,470 @@
+/**
+ * Deploy — placement-pipeline MCP tools (ops+).
+ *
+ * Phase 1.2 (this file) ships the first user-placement tool:
+ *   propose_user_assignments — run the Python placement model on Modal,
+ *                              persist proposals against an open
+ *                              planning_cycle. See docs/DEPLOY-PLAN.md.
+ *
+ * The review/edit/approve/commit triplet (Phase 1.3–1.5) lands here too
+ * as it ships. Quota + account placement (Phases 2–3) get separate
+ * groups on top.
+ *
+ * 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";
+export function registerDeployTools(server, allowed) {
+    if (allowed.has("propose_user_assignments")) {
+        server.tool("propose_user_assignments", [
+            "Run the user-placement model for an open planning cycle. The",
+            "model walks the active scenario's roster + the current",
+            "config/deploy/assignments.yaml and emits one proposal row per AE",
+            "across three kinds: 'assign' (planned hire onto a new territory),",
+            "'ratify' (existing AE staying put), 'depart' (AE in",
+            "assignments.yaml but not in the roster — will be removed at",
+            "commit). Patches in hierarchy.yaml not covered by any",
+            "assign/ratify proposal surface as 'uncovered territories'",
+            "warnings. Re-running on the same cycle supersedes the prior set",
+            "of proposals — the partial unique index keeps only one active",
+            "proposal per (cycle, user). Pass dryRun:true to preview the",
+            "model output without writing to the proposal table.",
+        ].join(" "), {
+            planningCycleId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Planning cycle to write proposals against. Defaults to the org's currently-open cycle if exactly one exists; if multiple open or none, the call returns an error listing the cycles found."),
+            scenarioId: z
+                .string()
+                .optional()
+                .describe("Override which scenario to load (e.g. 'stretch'). Default: 'base'. Must exist in config/design/scenarios/."),
+            dryRun: z
+                .boolean()
+                .optional()
+                .describe("Run the model and return proposals without persisting. Useful for previewing what the model would emit before committing to a cycle. Default: false."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Git branch to read configs from. Default: main."),
+        }, safeTool(async (input) => trpcMutation("mcp.proposeUserAssignments", input)));
+    }
+    if (allowed.has("propose_quotas")) {
+        server.tool("propose_quotas", [
+            "Run the quota model for an open planning cycle. Produces one",
+            "annual quota proposal per (territory, primary measure) by",
+            "aggregating the same per-AE per-month productivity vector that",
+            "drives /capacity at the AE's actual territory_slug (no ancestor",
+            "walk). Two refusals before the model runs:",
+            "(1) any user_assignment_proposal in the cycle is non-terminal —",
+            "Phase 1 must be fully committed/superseded first;",
+            "(2) capacity_config.active_scenario isn't set — quotas need a",
+            "promoted capacity plan as their source.",
+            "Defaults: scenario = capacity_config.active_scenario; measures =",
+            "scenario primary_measures with target_settable=true (secondary",
+            "measures don't get quotas). Re-running on the same cycle",
+            "supersedes the prior set. Pass dryRun:true to preview without",
+            "persisting.",
+        ].join(" "), {
+            planningCycleId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Planning cycle to write proposals against. Defaults to the org's currently-open cycle if exactly one exists."),
+            scenarioId: z
+                .string()
+                .optional()
+                .describe("Override which scenario to load. Default: capacity_config.active_scenario."),
+            measureIds: z
+                .array(z.string())
+                .optional()
+                .describe("Override measure filter. Default: scenario primary_measures with target_settable=true."),
+            dryRun: z
+                .boolean()
+                .optional()
+                .describe("Run the model and return proposals without persisting. Default: false."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Git branch to read configs from. Default: main."),
+        }, safeTool(async (input) => trpcMutation("mcp.proposeQuotas", input)));
+    }
+    if (allowed.has("review_quotas")) {
+        server.tool("review_quotas", [
+            "List territory_quota_proposal rows for a planning cycle, scoped",
+            "to your hierarchy subtree. Reps + managers see proposals for the",
+            "patches under territories they cover (per",
+            "config/deploy/assignments.yaml); leadership / ops / eng see all.",
+            "Default state filter is the active queue ([proposed, in_review,",
+            "edited, approved]). Output groups proposals by territory + shows",
+            "modeled vs final amount per measure, and rolls up totals at the",
+            "target_depth (per capacity_config) with gap-vs-target indicators",
+            "when targets.yaml has a matching row. Patches in your scope with",
+            "no quota proposal surface in their own warning section. Use the",
+            "row id shown for `edit_quota` later.",
+        ].join(" "), {
+            planningCycleId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Planning cycle to read from. Defaults to the org's currently-open cycle."),
+            state: z
+                .array(z.enum([
+                "proposed",
+                "in_review",
+                "edited",
+                "approved",
+                "committed",
+                "superseded",
+            ]))
+                .optional()
+                .describe("States to include. Default: [proposed, in_review, edited, approved]."),
+            territorySlug: z
+                .string()
+                .optional()
+                .describe("Filter to a single territory slug. Combines with the caller's hierarchy-subtree scope."),
+            measureId: z
+                .string()
+                .optional()
+                .describe("Filter to a single measure id (e.g. 'new_acv'). Default: all measures with rows in this cycle."),
+            cursor: z
+                .string()
+                .optional()
+                .describe("Pagination cursor. Pass the cursor value from a prior response."),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(500)
+                .optional()
+                .describe("Max proposals per page (1–500). Default: 100."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Git branch to read configs from. Default: main."),
+        }, safeTool(async (input) => trpcQuery("mcp.reviewQuotas", input)));
+    }
+    if (allowed.has("edit_rep_inputs")) {
+        server.tool("edit_rep_inputs", [
+            "Record a per-cycle override of a position's effective",
+            "characteristics (start_date / segment / profile). Upserts a",
+            "rep_input_override row keyed by (cycle, position_id). Manager+",
+            "scoped — the position must cover a patch in your hierarchy",
+            "subtree. The override is recorded but doesn't immediately",
+            "rewrite quotas; run propose_quotas after to refresh modeled",
+            "amounts (the loader picks up the override automatically).",
+            "Pass null to clear an existing override field. Refuses if the",
+            "cycle is closed or if a segment/profile id doesn't exist in",
+            "config.",
+        ].join(" "), {
+            positionId: z
+                .string()
+                .min(1)
+                .describe("Phase 1.7 position id (`<plan_year>-<8 hex>`). The position whose effective characteristics you want to override."),
+            planningCycleId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Planning cycle to scope the override to. Defaults to the org's currently-open cycle."),
+            overrideStartDate: z
+                .string()
+                .nullable()
+                .optional()
+                .describe("Override the position's effective ramp date (YYYY-MM-DD). Pass null to clear."),
+            overrideSegment: z
+                .string()
+                .nullable()
+                .optional()
+                .describe("Override the position's effective segment id. Pass null to clear."),
+            overrideProfile: z
+                .string()
+                .nullable()
+                .optional()
+                .describe("Override the position's effective ae_profile id. Pass null to clear."),
+            notes: z
+                .string()
+                .min(5)
+                .describe("Why you're setting this override — required, min 5 chars. Captured in audit log."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Git branch to read configs from. Default: main."),
+        }, safeTool(async (input) => trpcMutation("mcp.editRepInputs", input)));
+    }
+    if (allowed.has("edit_quota")) {
+        server.tool("edit_quota", [
+            "Override the modeled annual quota for a (territory, measure)",
+            "row. Sets final_amount to the new value, transitions state to",
+            "'edited', captures notes + reviewer_id. Manager+ scoped — the",
+            "territory must be in your hierarchy subtree. Refuses if the",
+            "new amount violates any rule in config/deploy/",
+            "quota_guardrails.yaml — adjust the amount or ask ops to relax",
+            "the guardrail. Refuses if the cycle is closed or if the",
+            "proposal is already committed/superseded.",
+        ].join(" "), {
+            proposalId: z
+                .string()
+                .uuid()
+                .describe("territory_quota_proposal id to edit. Get from review_quotas."),
+            newAmount: z
+                .number()
+                .nonnegative()
+                .describe("New annual quota in the measure's native unit. Must be >= 0."),
+            notes: z
+                .string()
+                .min(5)
+                .describe("Why you're editing — required, min 5 chars. Captured in audit log."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Git branch to read configs from. Default: main."),
+        }, safeTool(async (input) => trpcMutation("mcp.editQuota", input)));
+    }
+    if (allowed.has("approve_quotas")) {
+        server.tool("approve_quotas", [
+            "Bulk-approve quota proposals for an open planning cycle. State",
+            "transitions: proposed | in_review | edited → approved.",
+            "Manager+ scoped — defaults to all proposals in the cycle in",
+            "approvable states within your hierarchy subtree. Pass",
+            "proposalIds to approve a subset. final_amount stays as set",
+            "(manager-edited) or defaults to modeled_amount on approve.",
+            "Per-proposal audit row.",
+        ].join(" "), {
+            planningCycleId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Planning cycle to approve in. Defaults to the org's currently-open cycle."),
+            proposalIds: z
+                .array(z.string().uuid())
+                .optional()
+                .describe("Specific proposal ids. Default: all approvable in your subtree."),
+            notes: z
+                .string()
+                .optional()
+                .describe("Free-form approval note. Captured on every approved proposal's audit row."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Git branch to read configs from. Default: main."),
+        }, safeTool(async (input) => trpcMutation("mcp.approveQuotas", input)));
+    }
+    if (allowed.has("revise_quota_proposal")) {
+        server.tool("revise_quota_proposal", [
+            "Demote an approved quota proposal back to edited so the manager",
+            "can revise their final_amount. Ops-only. State `approved →",
+            "edited`. final_amount is preserved (manager sees what they",
+            "previously approved). Audit row records who sent it back and",
+            "why. Refuses on non-approved or closed-cycle proposals.",
+        ].join(" "), {
+            proposalId: z
+                .string()
+                .uuid()
+                .describe("Quota proposal id (UUID). Must be in `approved` state."),
+            notes: z
+                .string()
+                .min(5)
+                .describe("Why you're sending this back — required, min 5 chars. Captured in audit log."),
+        }, safeTool(async (input) => trpcMutation("mcp.reviseQuotaProposal", input)));
+    }
+    if (allowed.has("commit_quotas")) {
+        server.tool("commit_quotas", [
+            "Take the manager-approved set and write the cycle's resolved",
+            "quotas to config/deploy/quotas.yaml on GitHub, then transition",
+            "every approved row to committed. Ops-only. Default is dryRun:",
+            "true (returns the YAML diff without writing); pass dryRun:false",
+            "to actually commit. The YAML carries a metadata header pinning",
+            "it to source_planning_cycle_id + source_scenario_id +",
+            "source_capacity_commit_sha + plan-year window. Pursue/Coach",
+            "loops will read this file at runtime for per-rep quota tracking.",
+        ].join(" "), {
+            planningCycleId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Planning cycle to commit. Defaults to the org's currently-open cycle."),
+            dryRun: z
+                .boolean()
+                .optional()
+                .describe("When true (default), return the YAML diff without writing. Pass false to commit + advance state."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Branch to commit quotas.yaml to. Default: main."),
+        }, safeTool(async (input) => trpcMutation("mcp.commitQuotas", input)));
+    }
+    if (allowed.has("review_user_assignments")) {
+        server.tool("review_user_assignments", [
+            "List user-placement proposals for a planning cycle, scoped to",
+            "your hierarchy subtree. Reps + managers see proposals for the",
+            "patches under territories they cover (per",
+            "config/deploy/assignments.yaml); leadership / ops / eng see all.",
+            "Default state filter is the active review queue",
+            "([proposed, in_review, edited]). Ratify proposals (existing AEs",
+            "with no change) appear by default — pass `proposalKind:[assign]`",
+            "to skip them. Depart proposals (AEs being removed) surface in",
+            "their own warning section. Use the `id` shown for each proposal",
+            "as `proposalId` for `edit_user_assignment`.",
+        ].join(" "), {
+            planningCycleId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Planning cycle to read from. Defaults to the org's currently-open cycle."),
+            state: z
+                .array(z.enum([
+                "proposed",
+                "in_review",
+                "edited",
+                "approved",
+                "committed",
+                "superseded",
+            ]))
+                .optional()
+                .describe("Filter to these proposal states. Default: ['proposed','in_review','edited']."),
+            proposalKind: z
+                .array(z.enum(["assign", "ratify", "depart"]))
+                .optional()
+                .describe("Filter by proposal kind. Default: all (assign + ratify + depart). Use ['depart'] to focus on departures, ['assign'] to skip ratifies."),
+            territorySlug: z
+                .string()
+                .optional()
+                .describe("Narrow to one territory slug (e.g. 'ams/east/northeast/ny-metro')."),
+            cursor: z
+                .string()
+                .optional()
+                .describe("Pagination cursor from a prior response's `next_cursor`. Omit on first page."),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(500)
+                .optional()
+                .describe("Max proposals per page (1–500). Default: 100."),
+        }, safeTool(async (input) => trpcQuery("mcp.reviewUserAssignments", input)));
+    }
+    if (allowed.has("approve_user_assignments")) {
+        server.tool("approve_user_assignments", [
+            "Bulk-approve user-placement proposals you have authority over.",
+            "State `proposed | edited → approved`. Sets `final_*` to",
+            "`proposed_*` if you didn't override via `edit_user_assignment`.",
+            "Per-proposal audit row written. Approval locks the proposal out",
+            "of the active review queue; ops will sweep them up via",
+            "`commit_user_assignments` to write back to assignments.yaml.",
+            "Pass `proposalIds` to approve a subset; default is all",
+            "in-scope proposals in proposed/edited state for the cycle.",
+        ].join(" "), {
+            planningCycleId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Planning cycle. Defaults to the org's currently-open cycle."),
+            proposalIds: z
+                .array(z.string().uuid())
+                .optional()
+                .describe("Specific proposal ids to approve. Default: all proposals in your scope in proposed/edited state."),
+            notes: z
+                .string()
+                .optional()
+                .describe("Optional approval note (captured in the audit row for every approved proposal)."),
+        }, safeTool(async (input) => trpcMutation("mcp.approveUserAssignments", input)));
+    }
+    if (allowed.has("revise_user_assignment")) {
+        server.tool("revise_user_assignment", [
+            "Ops only. Send an approved proposal back to the manager for",
+            "revisions. State `approved → edited`. Preserves `final_*`",
+            "values so the manager can see exactly what they previously",
+            "approved before deciding what to revise. Required `notes`",
+            "explaining why. Per-proposal audit row written. Cannot be",
+            "used on `committed` proposals (those are already in YAML —",
+            "run a fresh propose_user_assignments cycle to change them).",
+        ].join(" "), {
+            proposalId: z
+                .string()
+                .uuid()
+                .describe("Proposal id (UUID) to revise. Get from review_user_assignments with `state:[approved]`."),
+            notes: z
+                .string()
+                .min(5)
+                .describe("Why you're sending this back — required, captured in the audit log so the manager sees the intent."),
+        }, safeTool(async (input) => trpcMutation("mcp.reviseUserAssignment", input)));
+    }
+    if (allowed.has("close_cycle")) {
+        server.tool("close_cycle", [
+            "Ops only. Mark a planning cycle done. State `open → closed`.",
+            "Every non-`committed` proposal in the cycle (proposed /",
+            "in_review / edited / approved) moves to `superseded` —",
+            "abandoned at close. Already-`committed` proposals are",
+            "untouched (they're already in YAML). After close, the cycle",
+            "is read-only history; new propose / edit / approve / revise /",
+            "commit calls against this cycle id will be refused. Required",
+            "`notes` captured in the cycle-level audit row.",
+        ].join(" "), {
+            planningCycleId: z
+                .string()
+                .uuid()
+                .describe("Planning cycle to close. Must currently be `open`. Closing is irreversible."),
+            notes: z
+                .string()
+                .min(5)
+                .describe("Why you're closing the cycle — required, captured in the cycle-level audit row."),
+        }, safeTool(async (input) => trpcMutation("mcp.closeCycle", input)));
+    }
+    if (allowed.has("commit_user_assignments")) {
+        server.tool("commit_user_assignments", [
+            "Ops only. Write the cycle's approved placements back to",
+            "`config/deploy/assignments.yaml` and transition every approved",
+            "proposal to `committed`. Default is dry-run — returns the YAML",
+            "diff + per-proposal disposition without writing or transitioning.",
+            "Pass `dryRun:false` to commit. Mutation rules: `assign` adds (or",
+            "mutates) a user entry, `ratify` is a no-op, `depart` removes the",
+            "user. After commit succeeds, run `sync_territories` to push the",
+            "new YAML state to Salesforce.",
+        ].join(" "), {
+            planningCycleId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Planning cycle to commit. Defaults to the org's currently-open cycle."),
+            dryRun: z
+                .boolean()
+                .optional()
+                .describe("Default true — return diff without writing. Pass `false` to commit."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Branch to write assignments.yaml to. Default: main."),
+        }, safeTool(async (input) => trpcMutation("mcp.commitUserAssignments", input)));
+    }
+    if (allowed.has("edit_user_assignment")) {
+        server.tool("edit_user_assignment", [
+            "Override the agent's pick on a specific user-placement proposal.",
+            "Sets `final_*` fields, transitions state to 'edited', captures",
+            "your `notes` (required, min 5 chars), and writes an audit_log",
+            "row. Validates that the new territory slug is a real patch in",
+            "hierarchy.yaml and that you have visibility into both the source",
+            "and destination patches. Depart proposals can't be edited via",
+            "this tool — to cancel a departure, add the rep back to the active",
+            "scenario's roster and re-run propose_user_assignments.",
+        ].join(" "), {
+            proposalId: z
+                .string()
+                .uuid()
+                .describe("Proposal id (UUID) to edit. Get from review_user_assignments."),
+            newTerritorySlug: z
+                .string()
+                .optional()
+                .describe("New patch slug. Must be in hierarchy.yaml at the patch level. Omit to keep the proposed slug."),
+            newRole: z
+                .string()
+                .optional()
+                .describe("New role id (e.g. 'ae'). Must be in roles.yaml. Omit to keep the proposed role."),
+            notes: z
+                .string()
+                .min(5)
+                .describe("Why you're editing — required, captured in the audit log."),
+        }, safeTool(async (input) => trpcMutation("mcp.editUserAssignment", input)));
+    }
+}

package/package.json

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