@loopops/mcp-server 3.9.1 → 3.12.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 { registerPeopleMasterTools } from "./tools/people-master.js";
 import { registerScoringTools } from "./tools/scoring.js";
 import { registerSfdcSyncTools } from "./tools/sfdc-sync.js";
 import { registerTalTools } from "./tools/tal.js";
@@ -58,6 +59,7 @@ registerEngTools(server, allowedSkills);
 registerCrmTools(server, allowedSkills);
 registerEngageTools(server, allowedSkills);
 registerAccountMasterTools(server, allowedSkills);
+registerPeopleMasterTools(server, allowedSkills);
 registerTalTools(server, allowedSkills);
 registerScoringTools(server, allowedSkills);
 registerSfdcSyncTools(server, allowedSkills);

package/dist/tools/crm.js

@@ -1,49 +1,25 @@
 import { z } from "zod";
-import { trpcQuery, trpcMutation } from "../api-client.js";
+import { trpcMutation } from "../api-client.js";
 import { safeTool } from "./_helpers.js";
-import { leadStatusSchema, opportunityStageSchema, pipelineSortSchema, quarterSchema, rangeSchema, salesforceLeadIdSchema, salesforceOpportunityIdSchema, targetAccountTierSchema, } from "./_schemas.js";
+import { leadStatusSchema, salesforceLeadIdSchema, salesforceOpportunityIdSchema, targetAccountTierSchema, } from "./_schemas.js";
 export function registerCrmTools(server, allowed) {
-    if (allowed.has("my_pipeline")) {
-        server.tool("my_pipeline", "List open Salesforce opportunities (deals with forecasts). Reps see their own, managers see their team's, leadership sees all. For new leads that haven't converted yet, use 'my_leads' instead.", {
-            stage: opportunityStageSchema
-                .optional()
-                .describe("Filter by Salesforce stage. Omit to see all open opportunities."),
-            sort: pipelineSortSchema
-                .optional()
-                .describe("Sort order. Default: close_date ascending."),
-        }, safeTool(async ({ stage, sort }) => trpcQuery("mcp.myPipeline", { stage, sort })));
-    }
-    if (allowed.has("my_leads")) {
-        server.tool("my_leads", "List Salesforce leads assigned to you (or your team if you're a manager) that were created in the given time window. For open opportunities with forecasts, use 'my_pipeline' instead.", {
-            status: leadStatusSchema
-                .optional()
-                .describe("Filter by Salesforce Lead status. E.g., 'Open - Not Contacted'. Omit for any status."),
-            range: rangeSchema
-                .optional()
-                .describe("Time window for lead creation date. E.g., '7d' = last 7 days, '30d' = default, '90d' = last quarter."),
-        }, safeTool(async ({ status, range }) => trpcQuery("mcp.myLeads", { status, range })));
-    }
-    if (allowed.has("pipeline_health")) {
-        server.tool("pipeline_health", "Pipeline health summary: deals by stage, win rate, average deal size, pipeline velocity.", {
-            range: rangeSchema
-                .optional()
-                .describe("Time window for closed-deal analysis. Longer ranges (30d, 90d, 180d, 1y) give more stable metrics. Default: 90d."),
-        }, safeTool(async ({ range }) => trpcQuery("mcp.pipelineHealth", { range })));
-    }
-    if (allowed.has("rep_performance")) {
-        server.tool("rep_performance", "Compare rep performance: open pipeline, activities, lead count, win rate.", {
-            range: rangeSchema
-                .optional()
-                .describe("Time window for closed deals and activity. Default: 30d."),
-        }, safeTool(async ({ range }) => trpcQuery("mcp.repPerformance", { range })));
-    }
-    if (allowed.has("forecast")) {
-        server.tool("forecast", "Pipeline forecast: weighted pipeline by close date, comparison to target.", {
-            quarter: quarterSchema
-                .optional()
-                .describe("Quarter to forecast. Default: current quarter."),
-        }, safeTool(async ({ quarter }) => trpcQuery("mcp.forecast", { quarter })));
-    }
+    // my_pipeline retired 2026-05-06 — replaced by ClickHouse parameterized
+    // view analytics.my_pipeline. Row policies on salesforce.opportunity
+    // enforce per-user scoping (rep: own; manager: team; leadership/ops/eng:
+    // all). Query via the Cloud Remote MCP server (mcp.clickhouse.cloud/mcp).
+    // See docs/CH-ANALYTICS-VIEWS.md.
+    // my_leads retired 2026-05-06 — replaced by ClickHouse view
+    // analytics.my_leads. Row policies on salesforce.lead enforce per-user
+    // scoping. Filter by created_date in the caller. See docs/CH-ANALYTICS-VIEWS.md.
+    // pipeline_health retired 2026-05-06 — replaced by ClickHouse views
+    // analytics.pipeline_by_stage + analytics.win_rate(range_days). Query via
+    // the Cloud Remote MCP server (mcp.clickhouse.cloud/mcp). Row policies on
+    // salesforce.opportunity enforce per-user scoping. See docs/CH-ANALYTICS-VIEWS.md.
+    // rep_performance retired 2026-05-06 — replaced by ClickHouse view
+    // analytics.rep_performance(range_days). See docs/CH-ANALYTICS-VIEWS.md.
+    // forecast retired 2026-05-06 — replaced by ClickHouse view
+    // analytics.forecast(quarter_start, quarter_end). Caller computes the
+    // quarter window. See docs/CH-ANALYTICS-VIEWS.md.
     if (allowed.has("update_opportunity")) {
         server.tool("update_opportunity", "Update an opportunity's close date, next step, or description. You can identify the deal by Salesforce Opportunity ID or exact opportunity name. Reps can only update their own deals. Requires a reason for the change.", {
             opportunityId: salesforceOpportunityIdSchema

package/dist/tools/people-master.d.ts

@@ -0,0 +1,22 @@
+/**
+ * People Master — MCP tool wrappers (ops+).
+ *
+ * Read-only tools (Phase 1.3):
+ *   person_lookup                — find people by email / employee_id /
+ *                                  person_id / fullName (+ managerEmail to
+ *                                  scope a name lookup)
+ *   person_show                  — full detail for one person
+ *   list_pending_people_matches  — review queue for inbound candidates
+ *   walk_hierarchy               — preview a hierarchy walk's membership
+ *
+ * Mutating tools:
+ *   import_people_csv                       — parse a Workday-shaped CSV upload,
+ *                                             write inbound candidates
+ *   sync_people_master_resolution_rules     — apply YAML → DB and re-resolve
+ *
+ * See packages/api/src/routers/mcp.ts for the tRPC procedure
+ * implementations and packages/api/src/routers/mcp-schemas.ts for the
+ * input schemas.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPeopleMasterTools(server: McpServer, allowed: Set<string>): void;

package/dist/tools/people-master.js

@@ -0,0 +1,166 @@
+/**
+ * People Master — MCP tool wrappers (ops+).
+ *
+ * Read-only tools (Phase 1.3):
+ *   person_lookup                — find people by email / employee_id /
+ *                                  person_id / fullName (+ managerEmail to
+ *                                  scope a name lookup)
+ *   person_show                  — full detail for one person
+ *   list_pending_people_matches  — review queue for inbound candidates
+ *   walk_hierarchy               — preview a hierarchy walk's membership
+ *
+ * Mutating tools:
+ *   import_people_csv                       — parse a Workday-shaped CSV upload,
+ *                                             write inbound candidates
+ *   sync_people_master_resolution_rules     — apply YAML → DB and re-resolve
+ *
+ * See packages/api/src/routers/mcp.ts for the tRPC procedure
+ * implementations and packages/api/src/routers/mcp-schemas.ts for the
+ * input schemas.
+ */
+import { z } from "zod";
+import { trpcMutation, trpcQuery } from "../api-client.js";
+import { CSV_PATH_DESCRIPTION, resolveCsvInput } from "./_csv-input.js";
+import { safeTool } from "./_helpers.js";
+export function registerPeopleMasterTools(server, allowed) {
+    if (allowed.has("person_lookup")) {
+        server.tool("person_lookup", "Find People Master persons by email, employee_id, person_id, or fullName. Provide at least one. Multiple keys combine as OR — returns the union. Pair fullName with managerEmail when possible to avoid ambiguous name matches.", {
+            email: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Work email. Matches both `person.primary_email` and email aliases in `person_identifier`."),
+            employeeId: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Workday employee_id (e.g. 'W00123'). Case-sensitive."),
+            personId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("People Master person_id (UUID)."),
+            fullName: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Full name. Matched after normalization (case-insensitive, punctuation collapsed; apostrophes/hyphens/accents preserved). Returns multiple matches if name is ambiguous — pair with managerEmail."),
+            managerEmail: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Manager's work email. Scopes a fullName lookup to that manager's direct reports — recommended whenever you only have a name."),
+        }, safeTool(async (input) => trpcQuery("mcp.personLookup", input)));
+    }
+    if (allowed.has("person_show")) {
+        server.tool("person_show", "Show full detail for one person: identifiers, manager + direct reports, lifecycle states (ingestion / activity_capture), resolved attributes (the golden record with provenance), and recent lifecycle events. Use person_lookup first if you only have an email or name.", {
+            personId: z
+                .string()
+                .uuid()
+                .describe("person_id (UUID). Use person_lookup if you don't have it yet."),
+        }, safeTool(async ({ personId }) => trpcQuery("mcp.personShow", { personId })));
+    }
+    if (allowed.has("list_pending_people_matches")) {
+        server.tool("list_pending_people_matches", "Show inbound person candidates currently in `match_status='needs_review'` — rows the matcher couldn't confidently resolve. Each entry includes the source, ingestion time, and the candidate's email/employee_id so you can investigate via `person_lookup`.", {
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(200)
+                .optional()
+                .describe("Max candidates to return (1–200). Default: 50."),
+            source: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Filter to a single inbound source (e.g. 'workday_csv'). Omit to see all."),
+        }, safeTool(async (input) => trpcQuery("mcp.listPendingPeopleMatches", input)));
+    }
+    if (allowed.has("walk_hierarchy")) {
+        server.tool("walk_hierarchy", [
+            "Preview a hierarchy walk's membership. Reads `config/people_master/hierarchy_walks.yaml`",
+            "from the repo branch (default `main`), runs the evaluator against the live DB, and",
+            "returns the member list plus filter diagnostics (how many people were filtered by each",
+            "rule). Pass `walkId` to evaluate a specific walk; omit it to list all defined walks.",
+            "Use this to sanity-check a walk before wiring it into Activity Capture, or to see who",
+            "would be in scope after editing the YAML on a feature branch (pass `branch:` to point",
+            "at it).",
+        ].join(" "), {
+            walkId: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("walk_id from hierarchy_walks.yaml (e.g. 'cro_org'). Omit to list all defined walks."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Branch to read YAML from. Default: 'main'."),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(500)
+                .optional()
+                .describe("Max members to render in the response. Default: 100. Stats reflect the full walk regardless."),
+        }, safeTool(async (input) => trpcQuery("mcp.walkHierarchy", input)));
+    }
+    if (allowed.has("import_people_csv")) {
+        server.tool("import_people_csv", [
+            "Import a Workday-shaped CSV of people into the People Master. Headers are case- and",
+            "punctuation-tolerant — `Worker ID`, `Employee ID`, `Work Email`, `Job Title`, `Manager",
+            "Email`, etc. all map to canonical fields. Rows without `work_email` AND without",
+            "(`employee_id` + `full_name`) are skipped. Each accepted row becomes an",
+            "`inbound_person_candidate` with the given source; with `process: true` they drain",
+            "through the matcher immediately, otherwise they wait for the next",
+            "`people_master_match_orchestrator` cron tick. Use `dryRun: true` to preview without",
+            "writing — recommended on the first import from any new source.",
+        ].join(" "), {
+            csv: z
+                .string()
+                .optional()
+                .describe("CSV content as text. First row must be the header. Provide this OR csvPath, not both."),
+            csvPath: z.string().optional().describe(CSV_PATH_DESCRIPTION),
+            source: z
+                .string()
+                .min(1)
+                .max(64)
+                .regex(/^[a-z0-9_]+$/)
+                .optional()
+                .describe("Slug stored in `inbound_person_candidate.source` (snake_case). Defaults to 'workday_csv'."),
+            dryRun: z
+                .boolean()
+                .optional()
+                .describe("If true, parse + normalize + summarize but write nothing."),
+            process: z
+                .boolean()
+                .optional()
+                .describe("If true, drain the matcher orchestrator immediately after insert."),
+        }, safeTool(async (input) => {
+            const csv = await resolveCsvInput(input);
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { csv: _csv, csvPath: _csvPath, ...rest } = input;
+            return trpcMutation("mcp.importPeopleCsv", { csv, ...rest });
+        }));
+    }
+    if (allowed.has("sync_people_master_resolution_rules")) {
+        server.tool("sync_people_master_resolution_rules", [
+            "Apply the committed config/people_master/resolution_rules.yaml to the DB.",
+            "Server-side equivalent of `node scripts/people-master-sync-resolution-rules.mjs --resolve`.",
+            "Idempotent — re-running with no YAML changes is a no-op. Resolver backfills golden",
+            "records by default (pass `resolve: false` to skip).",
+        ].join(" "), {
+            branch: z
+                .string()
+                .optional()
+                .describe("Branch to read YAML from. Default: main. Useful for testing a feature branch's YAML before merging."),
+            resolve: z
+                .boolean()
+                .optional()
+                .describe("Re-run the resolver across affected persons after applying rule changes so golden records update. Default: true."),
+            dryRun: z
+                .boolean()
+                .optional()
+                .describe("Read + validate + diff against DB without writing. Useful for previewing."),
+        }, safeTool(async (input) => trpcMutation("mcp.syncPeopleMasterResolutionRules", input)));
+    }
+}

package/dist/tools/reporting.js

@@ -1,31 +1,14 @@
 import { trpcQuery } from "../api-client.js";
 import { safeTool } from "./_helpers.js";
-import { loopNameSchema, rangeSchema, salesforceLeadIdSchema, } from "./_schemas.js";
+import { rangeSchema, salesforceLeadIdSchema, } from "./_schemas.js";
 export function registerReportingTools(server, allowed) {
-    if (allowed.has("loop_health")) {
-        server.tool("loop_health", "Query loop execution health: counts, success rate, latency, errors. Filter by loop name and time range.", {
-            loop: loopNameSchema
-                .optional()
-                .describe("Filter to a specific loop. Omit for all loops."),
-            range: rangeSchema
-                .optional()
-                .describe("Time window. Short ranges (1h, 6h, 24h) are most useful. Default: 24h."),
-        }, safeTool(async ({ loop, range }) => trpcQuery("mcp.loopHealth", { loop, range })));
-    }
-    if (allowed.has("scoring_distribution")) {
-        server.tool("scoring_distribution", "Analyze lead scoring distribution: score histogram, grade breakdown, average score by factor.", {
-            range: rangeSchema
-                .optional()
-                .describe("Time window. Default: 7d."),
-        }, safeTool(async ({ range }) => trpcQuery("mcp.scoringDistribution", { range })));
-    }
-    if (allowed.has("routing_report")) {
-        server.tool("routing_report", "Analyze routing decisions: rule match rates, queue distribution, agent fallback percentage.", {
-            range: rangeSchema
-                .optional()
-                .describe("Time window. Default: 7d."),
-        }, safeTool(async ({ range }) => trpcQuery("mcp.routingReport", { range })));
-    }
+    // loop_health retired 2026-05-06 — replaced by ClickHouse parameterized
+    // view analytics.loop_health(range_days). Query via the Cloud Remote MCP
+    // server (mcp.clickhouse.cloud/mcp). See docs/CH-ANALYTICS-VIEWS.md.
+    // scoring_distribution retired 2026-05-06 — replaced by ClickHouse view
+    // analytics.scoring_distribution(range_days). See docs/CH-ANALYTICS-VIEWS.md.
+    // routing_report retired 2026-05-06 — replaced by ClickHouse view
+    // analytics.routing_report(range_days). See docs/CH-ANALYTICS-VIEWS.md.
     if (allowed.has("enrichment_coverage")) {
         server.tool("enrichment_coverage", "Analyze lead enrichment coverage: enrichment rate, top industries, headcount distribution.", {
             range: rangeSchema

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopops/mcp-server",
-  "version": "3.9.1",
+  "version": "3.12.0",
   "description": "Loop Operations MCP Server — AI skills for RevOps",
   "license": "UNLICENSED",
   "type": "module",
@@ -20,12 +20,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsx src/index.ts",
-    "start": "node dist/index.js",
-    "prepublishOnly": "pnpm build"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "zod": "^3.24.4"
@@ -34,5 +28,10 @@
     "@types/node": "^22.15.21",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
   }
-}
+}