@loopops/mcp-server 3.9.0 → 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/_csv-input.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Helper for tools that accept "either CSV content as text, or a path to
+ * a CSV file." The MCP server runs locally as a subprocess on the user's
+ * machine, so file IO is available; this lets operators say "process the
+ * file at ~/Downloads/foo.csv" without a separate Read step in chat.
+ *
+ * Both `import_accounts_csv` and `process_approvals_csv` use this. The
+ * tRPC procedures behind them still take CSV content — this is purely
+ * a wrapper convenience.
+ */
+export type CsvInput = {
+    /** CSV content as a string (when operator pastes it inline). */
+    csv?: string;
+    /** Filesystem path (absolute, ~-prefixed, or relative to cwd). */
+    csvPath?: string;
+};
+/**
+ * Resolve to CSV content. Throws with operator-friendly messages on
+ * misuse (both unset, both set, file missing, file empty).
+ */
+export declare function resolveCsvInput(input: CsvInput): Promise<string>;
+/**
+ * Common Zod-friendly description for the csvPath field. Tool authors
+ * pass this as the `.describe()` argument so the wording stays
+ * consistent across tools.
+ */
+export declare const CSV_PATH_DESCRIPTION = "Path to a CSV file on the operator's machine. Absolute, ~-prefixed (e.g. `~/Downloads/foo.csv`), or relative to the MCP subprocess's working directory. Either `csv` or `csvPath` is required (not both).";

package/dist/tools/_csv-input.js

@@ -0,0 +1,56 @@
+/**
+ * Helper for tools that accept "either CSV content as text, or a path to
+ * a CSV file." The MCP server runs locally as a subprocess on the user's
+ * machine, so file IO is available; this lets operators say "process the
+ * file at ~/Downloads/foo.csv" without a separate Read step in chat.
+ *
+ * Both `import_accounts_csv` and `process_approvals_csv` use this. The
+ * tRPC procedures behind them still take CSV content — this is purely
+ * a wrapper convenience.
+ */
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+/**
+ * Resolve to CSV content. Throws with operator-friendly messages on
+ * misuse (both unset, both set, file missing, file empty).
+ */
+export async function resolveCsvInput(input) {
+    const hasContent = input.csv !== undefined && input.csv.length > 0;
+    const hasPath = input.csvPath !== undefined && input.csvPath.length > 0;
+    if (!hasContent && !hasPath) {
+        throw new Error("Provide either `csv` (the CSV content as text) or `csvPath` (a path to a CSV file).");
+    }
+    if (hasContent && hasPath) {
+        throw new Error("Provide either `csv` or `csvPath`, not both. Pick one — content for paste-in, path for an on-disk file.");
+    }
+    if (hasContent)
+        return input.csv;
+    // Path branch. Expand `~` to $HOME, resolve relative paths from
+    // the current working directory of the MCP subprocess.
+    let path = input.csvPath;
+    if (path.startsWith("~/")) {
+        path = resolve(homedir(), path.slice(2));
+    }
+    else if (!isAbsolute(path)) {
+        path = resolve(process.cwd(), path);
+    }
+    let content;
+    try {
+        content = await readFile(path, "utf-8");
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`Could not read CSV file at \`${path}\`: ${reason}`);
+    }
+    if (content.length === 0) {
+        throw new Error(`File at \`${path}\` is empty.`);
+    }
+    return content;
+}
+/**
+ * Common Zod-friendly description for the csvPath field. Tool authors
+ * pass this as the `.describe()` argument so the wording stays
+ * consistent across tools.
+ */
+export const CSV_PATH_DESCRIPTION = "Path to a CSV file on the operator's machine. Absolute, ~-prefixed (e.g. `~/Downloads/foo.csv`), or relative to the MCP subprocess's working directory. Either `csv` or `csvPath` is required (not both).";

package/dist/tools/account-master.js

@@ -16,6 +16,7 @@
  */
 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 registerAccountMasterTools(server, allowed) {
     if (allowed.has("account_lookup")) {
@@ -82,8 +83,9 @@ export function registerAccountMasterTools(server, allowed) {
         ].join(" "), {
             csv: z
                 .string()
-                .min(1)
-                .describe("CSV content as text. First row must be the header. Accepts the same header aliases as the account-master-csv-import.mjs script."),
+                .optional()
+                .describe("CSV content as text. First row must be the header. Accepts the same header aliases as the account-master-csv-import.mjs script. Provide this OR csvPath, not both."),
+            csvPath: z.string().optional().describe(CSV_PATH_DESCRIPTION),
             source: z
                 .string()
                 .min(1)
@@ -99,7 +101,12 @@ export function registerAccountMasterTools(server, allowed) {
                 .boolean()
                 .optional()
                 .describe("If true, drain the queue via the matcher immediately after insert."),
-        }, safeTool(async (input) => trpcMutation("mcp.importAccountsCsv", input)));
+        }, 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.importAccountsCsv", { csv, ...rest });
+        }));
     }
     if (allowed.has("override_account_attribute")) {
         server.tool("override_account_attribute", [

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/sfdc-sync.js

@@ -11,6 +11,7 @@
  */
 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";
 const accountIdentifierShape = {
     accountId: z
@@ -88,6 +89,10 @@ export function registerSfdcSyncTools(server, allowed) {
             "writes the same lifecycle event (with reason + snapshot payload) as a single-account",
             "approval would.",
             "",
+            "Provide EITHER `csv` (paste content inline) OR `csvPath` (path to a file on the",
+            "operator's machine; absolute or `~/`-prefixed). The MCP subprocess reads files locally,",
+            "so `csvPath` works for both Claude Code and Claude Desktop.",
+            "",
             "Validation:",
             "  - account_id must currently be in pending_initial_deployment_review (else row fails)",
             "  - reason must be ≥3 chars on approve=yes rows (else row fails)",
@@ -101,9 +106,13 @@ export function registerSfdcSyncTools(server, allowed) {
         ].join("\n"), {
             csv: z
                 .string()
-                .min(1)
-                .describe("CSV content (header row + data rows). Required headers: account_id, approve, reason. Other columns from export_pending_approvals are tolerated."),
-        }, safeTool(async (input) => trpcMutation("mcp.processApprovalsCsv", input)));
+                .optional()
+                .describe("CSV content (header row + data rows). Required headers: account_id, approve, reason. Other columns from export_pending_approvals are tolerated. Provide this OR csvPath, not both."),
+            csvPath: z.string().optional().describe(CSV_PATH_DESCRIPTION),
+        }, safeTool(async (input) => {
+            const csv = await resolveCsvInput(input);
+            return trpcMutation("mcp.processApprovalsCsv", { csv });
+        }));
     }
     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.", {

package/package.json

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