@loopops/mcp-server 3.9.1 → 3.10.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/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/package.json

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