@loopops/mcp-server 2.8.0 → 3.0.0

package/dist/api-client.js

@@ -256,6 +256,63 @@ function persistRotatedRefreshToken(newToken) {
         }
     }
 }
+/**
+ * Build a useful error message when Okta rejects our refresh token. The
+ * generic answer ("token may be revoked or idle-expired") is the last
+ * resort — first we check whether settings.json is pointing at the wrong
+ * tenant or client, which is a much more common cause and one the user
+ * cannot diagnose from the bare 400.
+ *
+ * The Loop API exposes the tenant it actually authenticates against at
+ * `GET /api/mcp/tenant-info` (added 2026-04-29 alongside the
+ * trial-2194356 → integrator-4680962 migration). If that endpoint
+ * disagrees with our env vars, we report exactly which key is wrong and
+ * the one-shot fix command. Older webapp deployments will 404 the
+ * endpoint — we silently fall through to the generic message.
+ */
+async function diagnoseRefreshFailure(status, body) {
+    const head = `Okta refresh failed (HTTP ${status}). Detail: ${body.slice(0, 300)}`;
+    const generic = "Your refresh token may be revoked or idle-expired. Re-run " +
+        "`npx @loopops/mcp-cli@latest login` (the `@latest` pin bypasses the " +
+        "npx cache, which can serve a stale cli with old tenant defaults for " +
+        "up to 24h after a publish).";
+    if (!apiUrl)
+        return `${head}\n\n${generic}`;
+    try {
+        const apiBase = new URL(apiUrl).origin;
+        const tenantInfoUrl = `${apiBase}/api/mcp/tenant-info`;
+        const probe = await doFetch(tenantInfoUrl, { method: "GET", headers: { accept: "application/json" } }, 5_000);
+        if (!probe.ok)
+            return `${head}\n\n${generic}`;
+        const live = (await probe.json());
+        const issuerMismatch = !!live.issuer && live.issuer !== oktaIssuer;
+        const clientMismatch = !!live.clientId && live.clientId !== oktaClientId;
+        if (!issuerMismatch && !clientMismatch)
+            return `${head}\n\n${generic}`;
+        const lines = [
+            head,
+            "",
+            "DIAGNOSIS: your MCP config points at a tenant the Loop API does not recognise.",
+        ];
+        if (issuerMismatch) {
+            lines.push(`  OKTA_ISSUER on disk:    ${oktaIssuer}`);
+            lines.push(`  OKTA_ISSUER expected:   ${live.issuer}`);
+        }
+        if (clientMismatch) {
+            lines.push(`  OKTA_CLIENT_ID on disk:  ${oktaClientId}`);
+            lines.push(`  OKTA_CLIENT_ID expected: ${live.clientId}`);
+        }
+        lines.push("");
+        lines.push("Fix: `npx @loopops/mcp-cli@latest login`. The `@latest` pin is " +
+            "important — without it, npx may serve a cached older cli that " +
+            "writes the same wrong defaults right back to disk.");
+        return lines.join("\n");
+    }
+    catch {
+        // Network blip, DNS failure, or older webapp without the endpoint.
+        return `${head}\n\n${generic}`;
+    }
+}
 /**
  * Mint a fresh access token via Okta's /token endpoint. Updates the
  * in-memory cache AND (if Okta rotated the refresh token) persists the
@@ -298,7 +355,8 @@ async function refreshAccessTokenOnce() {
         }, DEFAULT_TIMEOUT_MS);
         if (!response.ok) {
             const body = await response.text().catch(() => "<unreadable>");
-            throw new OktaRefreshError(`Okta refresh failed (HTTP ${response.status}). Your refresh token may be revoked or idle-expired. Re-run \`npx @loopops/mcp-cli login\`. Detail: ${body.slice(0, 300)}`);
+            const diagnosis = await diagnoseRefreshFailure(response.status, body);
+            throw new OktaRefreshError(diagnosis);
         }
         const tokens = (await response.json());
         cachedAccessToken = tokens.access_token;

package/dist/index.js

@@ -8,7 +8,7 @@ import { registerConfigTools } from "./tools/config.js";
 import { registerEngTools } from "./tools/eng.js";
 import { registerCrmTools } from "./tools/crm.js";
 import { registerEngageTools } from "./tools/engage.js";
-import { registerCompanyGraphTools } from "./tools/company-graph.js";
+import { registerAccountMasterTools } from "./tools/account-master.js";
 const skillsResponseSchema = z.object({
     role: z.string(),
     skills: z.array(z.string()),
@@ -41,6 +41,6 @@ registerConfigTools(server, allowedSkills);
 registerEngTools(server, allowedSkills);
 registerCrmTools(server, allowedSkills);
 registerEngageTools(server, allowedSkills);
-registerCompanyGraphTools(server, allowedSkills);
+registerAccountMasterTools(server, allowedSkills);
 const transport = new StdioServerTransport();
 await server.connect(transport);

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

@@ -0,0 +1,18 @@
+/**
+ * Account Master — MCP tool wrappers (ops+).
+ *
+ * Read-only tools (Phase 1.4):
+ *   account_lookup           — find accounts by domain / name / external IDs
+ *   account_show             — full detail for one account
+ *   list_pending_account_matches — review queue for inbound candidates
+ *
+ * Mutating tools:
+ *   import_accounts_csv      — parse a CSV upload, write inbound candidates,
+ *                              optionally drain via the orchestrator
+ *
+ * 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 registerAccountMasterTools(server: McpServer, allowed: Set<string>): void;

package/dist/tools/account-master.js

@@ -0,0 +1,166 @@
+/**
+ * Account Master — MCP tool wrappers (ops+).
+ *
+ * Read-only tools (Phase 1.4):
+ *   account_lookup           — find accounts by domain / name / external IDs
+ *   account_show             — full detail for one account
+ *   list_pending_account_matches — review queue for inbound candidates
+ *
+ * Mutating tools:
+ *   import_accounts_csv      — parse a CSV upload, write inbound candidates,
+ *                              optionally drain via the orchestrator
+ *
+ * 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 { safeTool } from "./_helpers.js";
+export function registerAccountMasterTools(server, allowed) {
+    if (allowed.has("account_lookup")) {
+        server.tool("account_lookup", "Find Account Master accounts by domain, name, account_id, SF Account ID, or legal-entity identifier (DUNS/LEI/EIN). Provide at least one. Multiple keys combine as OR — returns the union. Use this to investigate review-queue candidates or to cross-reference an SF Account back to its CG record.", {
+            domain: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Domain to look up (e.g. 'acme.com'). Email addresses also accepted; the matcher extracts the domain."),
+            accountName: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Company name to match. Looks up by exact-after-normalization (Inc/LLC/etc. stripped, punctuation collapsed)."),
+            accountId: z
+                .string()
+                .uuid()
+                .optional()
+                .describe("Account Master account_id (UUID)."),
+            sfAccountId: z
+                .string()
+                .min(3)
+                .optional()
+                .describe("Salesforce Account record ID (15- or 18-char SF id)."),
+            duns: z.string().min(1).optional().describe("D&B DUNS identifier."),
+            lei: z.string().min(1).optional().describe("Legal Entity Identifier (LEI)."),
+            ein: z.string().min(1).optional().describe("US EIN."),
+        }, 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.", {
+            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("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
+                .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. 'csv_import', 'backfill'). Omit to see all."),
+        }, safeTool(async (input) => trpcQuery("mcp.listPendingAccountMatches", input)));
+    }
+    if (allowed.has("import_accounts_csv")) {
+        server.tool("import_accounts_csv", [
+            "Import a CSV of accounts into the Account Master. Headers are case- and",
+            "punctuation-tolerant — `Company Name`, `name`, `Web Site`, `Billing Country`,",
+            "`DUNS`, etc. all map to canonical fields. Rows without a domain or",
+            "(account_name + country) are skipped. Each accepted row becomes an",
+            "`inbound_account_candidate` with the given source; with `process: true` they",
+            "drain through the matcher immediately, otherwise they wait for the next",
+            "`account_master_match_orchestrator` cron tick. Use `dry_run: true` to preview without",
+            "writing — recommended on the first import from any new source.",
+        ].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."),
+            source: z
+                .string()
+                .min(1)
+                .max(64)
+                .regex(/^[a-z0-9_]+$/)
+                .optional()
+                .describe("Slug stored in `inbound_account_candidate.source` (snake_case). Defaults to 'csv_import'. Use a more specific value for traceability (e.g. 'partner_acme', 'tradeshow_2026q2')."),
+            dryRun: z
+                .boolean()
+                .optional()
+                .describe("If true, parse + normalize + summarize but write nothing. Use to preview unfamiliar CSV shapes."),
+            process: z
+                .boolean()
+                .optional()
+                .describe("If true, drain the queue via the matcher immediately after insert."),
+        }, safeTool(async (input) => trpcMutation("mcp.importAccountsCsv", input)));
+    }
+    if (allowed.has("show_account_master_config")) {
+        server.tool("show_account_master_config", [
+            "Read the current contents of a Account Master YAML config from the repo.",
+            "Use this before update_account_master_config to see the current state. Today only",
+            "`resolution_rules` exists; future entries (e.g. sfdc_field_map) join the enum.",
+        ].join(" "), {
+            file: z
+                .enum(["resolution_rules"])
+                .describe("Which file under config/account_master/ to read. Today only resolution_rules."),
+        }, safeTool(async (input) => trpcQuery("mcp.showAccountMasterConfig", input)));
+    }
+    if (allowed.has("sync_account_master_resolution_rules")) {
+        server.tool("sync_account_master_resolution_rules", [
+            "Apply the committed config/account_master/resolution_rules.yaml to the DB.",
+            "Server-side equivalent of `node scripts/account-master-sync-resolution-rules.mjs --resolve`.",
+            "Idempotent — re-running with no YAML changes is a no-op. Pair with",
+            "update_account_master_config to complete an edit→commit→apply cycle from one Claude",
+            "session, no local clone needed. Resolver backfills golden records by default.",
+        ].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 accounts 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.syncAccountMasterResolutionRules", input)));
+    }
+    if (allowed.has("update_account_master_config")) {
+        server.tool("update_account_master_config", [
+            "Edit a Account Master YAML config by committing the new content to the repo",
+            "via the GitHub API (same pattern as update_config for per-loop configs).",
+            "Workflow: read the current file with show_account_master_config, edit, send back via this tool.",
+            "Commit goes to the target branch (default `main`); Vercel auto-deploys.",
+            "After commit, run `node scripts/account-master-sync-resolution-rules.mjs --resolve`",
+            "from a local clone to apply the change to the DB and backfill golden records.",
+            "There's no direct DB-write path — YAML is the single source of truth, drift is",
+            "structurally impossible.",
+        ].join(" "), {
+            file: z
+                .enum(["resolution_rules"])
+                .describe("Which file under config/account_master/ to update. Today only resolution_rules."),
+            content: z
+                .string()
+                .min(1)
+                .describe("Full new YAML content (the tool replaces the file wholesale). Run show_account_master_config first to read, then edit, then send back."),
+            message: z
+                .string()
+                .min(3)
+                .max(72)
+                .describe("Git commit message. Convention: `cg: <what changed and why>` (e.g. 'cg: drop annual_revenue min_confidence to 40 — pdl coverage sparse')."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Target branch. Default: main. Pass a feature branch if you want review-before-merge."),
+        }, safeTool(async (input) => trpcMutation("mcp.updateAccountMasterConfig", input)));
+    }
+}

package/dist/tools/config.js

@@ -391,7 +391,7 @@ export function registerConfigTools(server, allowed) {
                 .string()
                 .min(3)
                 .max(72)
-                .describe("Git commit message. Convention: `govern: <what changed and why>` (e.g. 'govern: disable cg_sync_clickhouse cron temporarily')."),
+                .describe("Git commit message. Convention: `govern: <what changed and why>` (e.g. 'govern: disable account_master_sync_clickhouse cron temporarily')."),
             branch: z
                 .string()
                 .optional()

package/package.json

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