@loopops/mcp-server 1.0.0

package/dist/api-client.d.ts

@@ -0,0 +1,38 @@
+/**
+ * tRPC client for connecting to the hosted Loop Operations API.
+ * Used when the MCP server runs in API mode (API_URL + API_KEY set).
+ */
+export declare function isApiMode(): boolean;
+export declare function getApiUrl(): string;
+export declare function getApiKey(): string;
+/** Base class so callers can distinguish API errors from unexpected errors. */
+export declare class ApiError extends Error {
+    constructor(message: string);
+}
+/** The request took longer than the configured timeout. */
+export declare class ApiTimeoutError extends ApiError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/** fetch() itself failed (DNS, TCP reset, etc.) — no HTTP response received. */
+export declare class ApiNetworkError extends ApiError {
+    constructor(cause: unknown);
+}
+/** API returned a non-2xx HTTP status. */
+export declare class ApiHttpError extends ApiError {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+/** API returned 401/403 — API key missing, expired, or lacks permission. */
+export declare class ApiAuthError extends ApiError {
+    readonly status: number;
+    readonly body: string;
+    /** The tRPC error's `message` field if parseable, else null. */
+    readonly serverMessage: string | null;
+    constructor(status: number, body: string);
+}
+/** Make a tRPC query call to the hosted API. Retries once on timeout/network/5xx. */
+export declare function trpcQuery<T = unknown>(path: string, input?: Record<string, unknown>): Promise<T>;
+/** Make a tRPC mutation call to the hosted API. Does NOT retry (non-idempotent). */
+export declare function trpcMutation<T = unknown>(path: string, input: Record<string, unknown>): Promise<T>;

package/dist/api-client.js

@@ -0,0 +1,188 @@
+/**
+ * tRPC client for connecting to the hosted Loop Operations API.
+ * Used when the MCP server runs in API mode (API_URL + API_KEY set).
+ */
+const apiUrl = process.env.API_URL;
+const apiKey = process.env.API_KEY;
+const DEFAULT_TIMEOUT_MS = Number(process.env.API_TIMEOUT_MS || 30_000);
+export function isApiMode() {
+    return !!apiUrl;
+}
+export function getApiUrl() {
+    if (!apiUrl)
+        throw new Error("API_URL not set");
+    return apiUrl;
+}
+export function getApiKey() {
+    if (!apiKey)
+        throw new Error("API_KEY not set");
+    return apiKey;
+}
+/** Base class so callers can distinguish API errors from unexpected errors. */
+export class ApiError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ApiError";
+    }
+}
+/** The request took longer than the configured timeout. */
+export class ApiTimeoutError extends ApiError {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`Loop API request timed out after ${timeoutMs}ms`);
+        this.timeoutMs = timeoutMs;
+        this.name = "ApiTimeoutError";
+    }
+}
+/** fetch() itself failed (DNS, TCP reset, etc.) — no HTTP response received. */
+export class ApiNetworkError extends ApiError {
+    constructor(cause) {
+        super(`Loop API network error: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = "ApiNetworkError";
+        this.cause = cause;
+    }
+}
+/** API returned a non-2xx HTTP status. */
+export class ApiHttpError extends ApiError {
+    status;
+    body;
+    constructor(status, body) {
+        super(`Loop API returned ${status}: ${body.slice(0, 300)}`);
+        this.status = status;
+        this.body = body;
+        this.name = "ApiHttpError";
+    }
+}
+/** API returned 401/403 — API key missing, expired, or lacks permission. */
+export class ApiAuthError extends ApiError {
+    status;
+    body;
+    /** The tRPC error's `message` field if parseable, else null. */
+    serverMessage;
+    constructor(status, body) {
+        super(`Loop API auth error (${status}): ${body.slice(0, 300)}`);
+        this.status = status;
+        this.body = body;
+        this.name = "ApiAuthError";
+        this.serverMessage = extractTrpcMessage(body);
+    }
+}
+/**
+ * tRPC returns errors wrapped in an envelope. Extract the `message`
+ * field so MCP tools can surface the server's actionable text verbatim
+ * instead of our generic fallback.
+ *
+ * Shape (tRPC fetch adapter, HTTP error): [{ error: { json: { message } } }]
+ *   or { error: { json: { message } } }
+ */
+function extractTrpcMessage(body) {
+    try {
+        const parsed = JSON.parse(body);
+        const candidates = Array.isArray(parsed) ? parsed : [parsed];
+        for (const c of candidates) {
+            if (!c || typeof c !== "object")
+                continue;
+            const errorNode = c.error;
+            if (errorNode && typeof errorNode === "object") {
+                const json = errorNode.json;
+                if (json && typeof json === "object") {
+                    const msg = json.message;
+                    if (typeof msg === "string" && msg.trim().length > 0)
+                        return msg;
+                }
+                // Older/simpler shape: error.message at the top level
+                const flat = errorNode.message;
+                if (typeof flat === "string" && flat.trim().length > 0)
+                    return flat;
+            }
+        }
+    }
+    catch {
+        // Body wasn't JSON; fall through.
+    }
+    return null;
+}
+async function doFetch(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new ApiTimeoutError(timeoutMs);
+        }
+        throw new ApiNetworkError(err);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function readAndThrow(response) {
+    const body = await response.text().catch(() => "<unreadable>");
+    if (response.status === 401 || response.status === 403) {
+        throw new ApiAuthError(response.status, body);
+    }
+    throw new ApiHttpError(response.status, body);
+}
+function isRetryable(err) {
+    if (err instanceof ApiTimeoutError)
+        return true;
+    if (err instanceof ApiNetworkError)
+        return true;
+    if (err instanceof ApiHttpError && err.status >= 500)
+        return true;
+    return false;
+}
+/** Make a tRPC query call to the hosted API. Retries once on timeout/network/5xx. */
+export async function trpcQuery(path, input) {
+    const url = new URL(getApiUrl());
+    url.pathname = url.pathname.replace(/\/$/, "") + "/" + path;
+    if (input !== undefined) {
+        url.searchParams.set("input", JSON.stringify({ json: input }));
+    }
+    const init = {
+        method: "GET",
+        redirect: "follow",
+        headers: {
+            Authorization: `Bearer ${getApiKey()}`,
+            "Content-Type": "application/json",
+        },
+    };
+    let lastErr;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const response = await doFetch(url.toString(), init, DEFAULT_TIMEOUT_MS);
+            if (!response.ok)
+                await readAndThrow(response);
+            const data = (await response.json());
+            return data.result?.data?.json;
+        }
+        catch (err) {
+            lastErr = err;
+            if (!isRetryable(err))
+                throw err;
+            if (attempt === 0)
+                continue;
+        }
+    }
+    throw lastErr;
+}
+/** Make a tRPC mutation call to the hosted API. Does NOT retry (non-idempotent). */
+export async function trpcMutation(path, input) {
+    const url = new URL(getApiUrl());
+    url.pathname = url.pathname.replace(/\/$/, "") + "/" + path;
+    const response = await doFetch(url.toString(), {
+        method: "POST",
+        redirect: "follow",
+        headers: {
+            Authorization: `Bearer ${getApiKey()}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ json: input }),
+    }, DEFAULT_TIMEOUT_MS);
+    if (!response.ok)
+        await readAndThrow(response);
+    const data = (await response.json());
+    return data.result?.data?.json;
+}

package/dist/db.d.ts

@@ -0,0 +1,3 @@
+import pg from "pg";
+export type Db = pg.Pool;
+export declare function createDb(connectionString: string): Db;

package/dist/db.js

@@ -0,0 +1,8 @@
+import pg from "pg";
+export function createDb(connectionString) {
+    return new pg.Pool({
+        connectionString,
+        max: 3,
+        idleTimeoutMillis: 30000,
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { trpcQuery } from "./api-client.js";
+import { registerReportingTools } from "./tools/reporting.js";
+import { registerConfigTools } from "./tools/config.js";
+import { registerEngTools } from "./tools/eng.js";
+import { registerCrmTools } from "./tools/crm.js";
+import { registerEngageTools } from "./tools/engage.js";
+const skillsResponseSchema = z.object({
+    role: z.string(),
+    skills: z.array(z.string()),
+});
+async function loadSkills() {
+    try {
+        const raw = await trpcQuery("mcp.getMySkills");
+        const parsed = skillsResponseSchema.safeParse(raw);
+        if (!parsed.success) {
+            console.error("[MCP] Unexpected response shape from mcp.getMySkills:", parsed.error.message);
+            console.error("[MCP] Raw response:", JSON.stringify(raw).slice(0, 500));
+            return { role: "unknown", skills: [] };
+        }
+        return parsed.data;
+    }
+    catch (err) {
+        console.error("[MCP] Failed to load skills from Loop API — starting with zero tools:", err instanceof Error ? err.message : String(err));
+        return { role: "unknown", skills: [] };
+    }
+}
+const { role, skills } = await loadSkills();
+const allowedSkills = new Set(skills);
+console.error(`[MCP] Connected — role: ${role}, ${skills.length} skills`);
+const server = new McpServer({
+    name: "loop-operations",
+    version: "1.0.0",
+});
+registerReportingTools(server, allowedSkills);
+registerConfigTools(server, allowedSkills);
+registerEngTools(server, allowedSkills);
+registerCrmTools(server, allowedSkills);
+registerEngageTools(server, allowedSkills);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/roles.d.ts

@@ -0,0 +1 @@
+export declare function loadSkillsForRole(roleName: string): Promise<Set<string>>;

package/dist/roles.js

@@ -0,0 +1,33 @@
+import { readFile } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "yaml";
+function resolveSkills(roles, roleName, visited = new Set()) {
+    if (visited.has(roleName))
+        return [];
+    visited.add(roleName);
+    const role = roles[roleName];
+    if (!role)
+        return [];
+    const inherited = role.inherits
+        ? resolveSkills(roles, role.inherits, visited)
+        : [];
+    return [...new Set([...inherited, ...role.skills])];
+}
+export async function loadSkillsForRole(roleName) {
+    // Look for skills.yaml relative to the project root
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const configPath = resolve(__dirname, "../../../config/mcp/skills.yaml");
+    // Try project-relative path first, then fall back to cwd-based path
+    let raw;
+    try {
+        raw = await readFile(configPath, "utf-8");
+    }
+    catch {
+        const cwdPath = resolve(process.cwd(), "config/mcp/skills.yaml");
+        raw = await readFile(cwdPath, "utf-8");
+    }
+    const config = parse(raw);
+    const skills = resolveSkills(config.roles, roleName);
+    return new Set(skills);
+}

package/dist/tools/_helpers.d.ts

@@ -0,0 +1,14 @@
+type McpToolResult = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+};
+/**
+ * Wrap a tool handler so backend errors never crash the MCP subprocess.
+ * Converts thrown errors into structured MCP `isError: true` responses
+ * with a human-readable hint specific to the error class.
+ */
+export declare function safeTool<Args>(fn: (args: Args) => Promise<string>): (args: Args) => Promise<McpToolResult>;
+export {};

package/dist/tools/_helpers.js

@@ -0,0 +1,49 @@
+import { ApiAuthError, ApiHttpError, ApiNetworkError, ApiTimeoutError } from "../api-client.js";
+/**
+ * Wrap a tool handler so backend errors never crash the MCP subprocess.
+ * Converts thrown errors into structured MCP `isError: true` responses
+ * with a human-readable hint specific to the error class.
+ */
+export function safeTool(fn) {
+    return async (args) => {
+        try {
+            const text = await fn(args);
+            return { content: [{ type: "text", text }] };
+        }
+        catch (err) {
+            const text = formatErrorForUser(err);
+            // stderr goes to the MCP client's logs (e.g. Claude Code logs) for diagnosis.
+            console.error("[MCP] Tool error:", err);
+            return { content: [{ type: "text", text }], isError: true };
+        }
+    };
+}
+function formatErrorForUser(err) {
+    if (err instanceof ApiAuthError) {
+        // The server sends actionable messages for the four specific auth
+        // failure modes (expired, revoked, idle-revoked, suspended). Use them
+        // verbatim so the user sees dates + the re-mint URL + the right
+        // escalation path. Only fall back to a generic hint when the server
+        // didn't include a parseable message.
+        if (err.serverMessage)
+            return err.serverMessage;
+        return ("Your Loop access couldn't be verified. " +
+            "Re-mint your MCP key at https://www.loopops.io/mcp/connect (Okta sign-in required), " +
+            "then restart Claude Desktop. If the problem persists, contact Revenue Operations.");
+    }
+    if (err instanceof ApiTimeoutError) {
+        return (`The Loop API took longer than ${err.timeoutMs}ms to respond. ` +
+            "Try again, or contact ops if this persists.");
+    }
+    if (err instanceof ApiNetworkError) {
+        return ("Could not reach the Loop API. Check your network connection. " +
+            `Underlying error: ${err.message}`);
+    }
+    if (err instanceof ApiHttpError) {
+        return `Loop API returned HTTP ${err.status}. Details: ${err.body.slice(0, 500)}`;
+    }
+    if (err instanceof Error) {
+        return `Unexpected error calling Loop API: ${err.message}`;
+    }
+    return "Unexpected error calling Loop API.";
+}

package/dist/tools/_schemas.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Zod schemas for MCP tool inputs.
+ *
+ * IMPORTANT: These must stay in sync with
+ * packages/api/src/routers/mcp-schemas.ts. Both sides validate the same
+ * fields, so any enum value / regex / refinement added here must also
+ * be present in the backend (or the backend will reject a valid-looking
+ * MCP input).
+ *
+ * Why duplicated: `@loopops/mcp-server` compiles to standalone .js via tsc
+ * and is distributed outside the pnpm workspace graph consumed by the
+ * Next.js web app. Importing `@loop/api/mcp-schemas` as a workspace dep
+ * broke the web app's type inference (TS2742). For the demo env the
+ * duplication is the pragmatic trade-off; see the PR 3 postmortem in
+ * MEMORY.md or the commit message.
+ */
+import { z } from "zod";
+export declare const rangeSchema: z.ZodEnum<["1h", "6h", "24h", "7d", "30d", "90d", "180d", "1y"]>;
+export declare const loopNameSchema: z.ZodEnum<["generate", "route", "engage", "pursue", "govern", "plan", "deploy"]>;
+export declare const leadStatusSchema: z.ZodEnum<["Open - Not Contacted", "Working - Contacted", "Qualified", "Closed - Converted", "Closed - Not Converted"]>;
+export declare const opportunityStageSchema: z.ZodEnum<["Prospecting", "Qualification", "Needs Analysis", "Value Proposition", "Id. Decision Makers", "Perception Analysis", "Proposal/Price Quote", "Negotiation/Review", "Closed Won", "Closed Lost"]>;
+export declare const pipelineSortSchema: z.ZodEnum<["close_date", "amount", "stage"]>;
+export declare const sequenceStatusSchema: z.ZodEnum<["draft", "approved", "sending", "completed", "rejected"]>;
+export declare const sequenceApproveMethodSchema: z.ZodEnum<["resend", "sf_task"]>;
+export declare const quarterSchema: z.ZodEnum<["Q1", "Q2", "Q3", "Q4"]>;
+export declare const targetAccountTierSchema: z.ZodEnum<["tier_1", "tier_2", "tier_3"]>;
+export declare const salesforceLeadIdSchema: z.ZodString;
+export declare const salesforceOpportunityIdSchema: z.ZodString;

package/dist/tools/_schemas.js

@@ -0,0 +1,69 @@
+/**
+ * Zod schemas for MCP tool inputs.
+ *
+ * IMPORTANT: These must stay in sync with
+ * packages/api/src/routers/mcp-schemas.ts. Both sides validate the same
+ * fields, so any enum value / regex / refinement added here must also
+ * be present in the backend (or the backend will reject a valid-looking
+ * MCP input).
+ *
+ * Why duplicated: `@loopops/mcp-server` compiles to standalone .js via tsc
+ * and is distributed outside the pnpm workspace graph consumed by the
+ * Next.js web app. Importing `@loop/api/mcp-schemas` as a workspace dep
+ * broke the web app's type inference (TS2742). For the demo env the
+ * duplication is the pragmatic trade-off; see the PR 3 postmortem in
+ * MEMORY.md or the commit message.
+ */
+import { z } from "zod";
+// ─── Shared enums ──────────────────────────────────────────────────────────
+export const rangeSchema = z.enum([
+    "1h",
+    "6h",
+    "24h",
+    "7d",
+    "30d",
+    "90d",
+    "180d",
+    "1y",
+]);
+export const loopNameSchema = z.enum(["generate", "route", "engage", "pursue", "govern", "plan", "deploy"]);
+export const leadStatusSchema = z.enum([
+    "Open - Not Contacted",
+    "Working - Contacted",
+    "Qualified",
+    "Closed - Converted",
+    "Closed - Not Converted",
+]);
+export const opportunityStageSchema = z.enum([
+    "Prospecting",
+    "Qualification",
+    "Needs Analysis",
+    "Value Proposition",
+    "Id. Decision Makers",
+    "Perception Analysis",
+    "Proposal/Price Quote",
+    "Negotiation/Review",
+    "Closed Won",
+    "Closed Lost",
+]);
+export const pipelineSortSchema = z.enum(["close_date", "amount", "stage"]);
+export const sequenceStatusSchema = z.enum([
+    "draft",
+    "approved",
+    "sending",
+    "completed",
+    "rejected",
+]);
+export const sequenceApproveMethodSchema = z.enum(["resend", "sf_task"]);
+export const quarterSchema = z.enum(["Q1", "Q2", "Q3", "Q4"]);
+export const targetAccountTierSchema = z.enum(["tier_1", "tier_2", "tier_3"]);
+export const salesforceLeadIdSchema = z
+    .string()
+    .regex(/^00Q[a-zA-Z0-9]{12}([a-zA-Z0-9]{3})?$/, {
+    message: "Must be a Salesforce Lead ID starting with 00Q.",
+});
+export const salesforceOpportunityIdSchema = z
+    .string()
+    .regex(/^006[a-zA-Z0-9]{12}([a-zA-Z0-9]{3})?$/, {
+    message: "Must be a Salesforce Opportunity ID starting with 006.",
+});

package/dist/tools/config.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerConfigTools(server: McpServer, allowed: Set<string>): void;

package/dist/tools/config.js

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import { trpcQuery, trpcMutation } from "../api-client.js";
+import { safeTool } from "./_helpers.js";
+import { loopNameSchema } from "./_schemas.js";
+export function registerConfigTools(server, allowed) {
+    if (allowed.has("show_config")) {
+        server.tool("show_config", "Show current YAML config for a loop. Returns the raw YAML content from the Git repo.", {
+            loop: loopNameSchema.describe("Loop whose config you want to view."),
+            file: z
+                .string()
+                .optional()
+                .describe("Config file name without extension (e.g., 'lead_scoring', 'rules', 'plays'). Defaults to the loop's main config."),
+        }, safeTool(async ({ loop, file }) => trpcQuery("mcp.showConfig", { loop, file })));
+    }
+    if (allowed.has("diff_config")) {
+        server.tool("diff_config", "Show recent changes to a loop's config files via Git commit history.", {
+            loop: loopNameSchema.describe("Loop whose config history you want."),
+            commits: z
+                .number()
+                .int()
+                .positive()
+                .max(50)
+                .optional()
+                .describe("Number of recent commits to show (1–50). Default: 5."),
+        }, safeTool(async ({ loop, commits }) => trpcQuery("mcp.diffConfig", { loop, commits })));
+    }
+    if (allowed.has("update_config")) {
+        server.tool("update_config", "Update a YAML config file. Shows the diff before committing. Validates the YAML structure.", {
+            loop: loopNameSchema.describe("Loop whose config you want to update."),
+            file: z
+                .string()
+                .optional()
+                .describe("Config file name. Defaults to the loop's main config."),
+            content: z.string().min(1).describe("The full updated YAML content."),
+            message: z.string().min(1).describe("Commit message describing the change."),
+            branch: z.string().optional().describe("Branch to commit to. Default: main."),
+        }, safeTool(async ({ loop, file, content, message, branch }) => trpcMutation("mcp.updateConfig", { loop, file, content, message, branch })));
+    }
+    if (allowed.has("deploy_config")) {
+        server.tool("deploy_config", "Deploy config by committing to main branch. Triggers Vercel deploy automatically.", {
+            loop: loopNameSchema.describe("Loop to deploy config for."),
+            message: z.string().min(1).describe("Deploy commit message."),
+        }, safeTool(async ({ loop, message }) => trpcQuery("mcp.deployConfig", { loop, message })));
+    }
+    if (allowed.has("deactivate_loop")) {
+        server.tool("deactivate_loop", "Stop a loop from running on the next webhook. Sets loops.active=false; the /api/loops/{slug}/config endpoint then returns 503 and any n8n workflow trying to fetch config halts. Trigger payloads are NOT lost — they remain in n8n's execution log and can be re-run after activate_loop. Use when a loop is misbehaving and needs immediate containment.", {
+            slug: loopNameSchema.describe("Slug of the loop to deactivate (e.g., 'pursue')."),
+            reason: z
+                .string()
+                .min(8)
+                .describe("Why you're deactivating. Required — recorded in audit_log so the next on-call has context."),
+        }, safeTool(async ({ slug, reason }) => trpcMutation("mcp.deactivateLoop", { slug, reason })));
+    }
+    if (allowed.has("activate_loop")) {
+        server.tool("activate_loop", "Resume a previously-deactivated loop. Sets loops.active=true; n8n workflows resume on the next webhook. Audit_log row written.", {
+            slug: loopNameSchema.describe("Slug of the loop to reactivate (e.g., 'pursue')."),
+        }, safeTool(async ({ slug }) => trpcMutation("mcp.activateLoop", { slug })));
+    }
+    if (allowed.has("sync_territories")) {
+        server.tool("sync_territories", "Reconcile config/plan/hierarchy.yaml (tree) + config/deploy/assignments.yaml (user coverage) with Salesforce ETM (Territory2 + UserTerritory2Association records). Dry-run by default — returns a diff summary. Pass dryRun:false to actually write to Salesforce. Safe to re-run; idempotent.", {
+            dryRun: z
+                .boolean()
+                .default(true)
+                .describe("When true (default), reports what would change but makes no writes to Salesforce. Pass false to apply."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Branch to read YAML from. Default: main."),
+        }, safeTool(async ({ dryRun, branch }) => trpcMutation("mcp.syncTerritories", { dryRun, branch })));
+    }
+    if (allowed.has("list_scenarios")) {
+        server.tool("list_scenarios", "List every planning scenario declared in config/plan/scenarios/. Each scenario is a complete, self-describing plan (declares its own roster, targets, target_productivity). Shows which scenario is currently active (per capacity_config.yaml) and flags any scenarios that are missing required components. Discovery tool — use this before running capacity_report with a specific scenarioId.", {
+            branch: z
+                .string()
+                .optional()
+                .describe("Git branch to read scenarios from. Default: main."),
+        }, safeTool(async ({ branch }) => trpcMutation("mcp.listScenarios", { branch })));
+    }
+    if (allowed.has("capacity_report")) {
+        server.tool("capacity_report", "Run the Plan capacity model: rolls each AE's ramp-aware contribution into territory totals at the configured target_depth and compares against targets.yaml. Returns one table per measure (capacity, target, gap, % attainment). Pure config-driven math; updating roster.yaml or target_productivity.yaml and re-running shows the new plan immediately. No writes.", {
+            scenarioId: z
+                .string()
+                .optional()
+                .describe("Override the active scenario. Defaults to capacity_config.active_scenario (typically 'base')."),
+            planYear: z
+                .number()
+                .int()
+                .optional()
+                .describe("Override the configured plan year. Defaults to capacity_config.planning.plan_year."),
+            measureIds: z
+                .array(z.string())
+                .optional()
+                .describe("Filter the report to a subset of measures. Default: all target_settable measures (new_logo_volume, new_logo_acv, new_acv, new_arr)."),
+            showContributions: z
+                .boolean()
+                .default(false)
+                .describe("When true, include the per-AE contribution table beneath each cell. Useful for auditing the math; verbose."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Git branch to read configs from. Default: main."),
+        }, safeTool(async ({ scenarioId, planYear, measureIds, showContributions, branch }) => trpcMutation("mcp.capacityReport", {
+            scenarioId,
+            planYear,
+            measureIds,
+            showContributions,
+            branch,
+        })));
+    }
+    if (allowed.has("preview_routing")) {
+        server.tool("preview_routing", "Simulate Route loop resolution for a hypothetical lead. Walks config/route/rules.yaml, dispatches to territory/pool/queue/user/target_account handler, and returns the resolved owner + audit trail. Useful for testing rule changes before merging. Requires at least billing geography or email.", {
+            email: z.string().optional().describe("Lead email — also extracts the domain for target_account lookup."),
+            billing_country: z.string().optional().describe("ISO country code (US, GB, JP, etc.)."),
+            billing_state: z.string().optional().describe("ISO state code (CA, NY, etc.)."),
+            billing_city: z.string().optional().describe("City name."),
+            employee_count: z.number().int().nonnegative().optional().describe("Company headcount."),
+            industry: z.string().optional().describe("SF Industry picklist value."),
+            source: z.string().optional().describe("Lead source (Web, Partner Referral, etc.)."),
+        }, safeTool(async (input) => trpcMutation("mcp.previewRouting", input)));
+    }
+    if (allowed.has("list_pending_territories")) {
+        server.tool("list_pending_territories", "List Accounts currently in a pending territory assignment state (Territory_Slug__c starts with 'pending:'). Returns the status breakdown + per-account table with agent reasoning when available. Pending accounts are re-evaluated on each assign_territories run.", {
+            includeReasoning: z
+                .boolean()
+                .default(true)
+                .describe("Include the agent's reasoning column (joins agent_decisions)."),
+        }, safeTool(async ({ includeReasoning }) => trpcQuery("mcp.listPendingTerritories", { includeReasoning })));
+    }
+    if (allowed.has("assign_territories")) {
+        server.tool("assign_territories", "Match each target Account to a territory Patch using config/plan/hierarchy.yaml (tree) + config/deploy/territories.yaml (billing match rules). Writes Account.Territory_Slug__c + ObjectTerritory2Association in SF. Dry-run by default. Uses Claude Haiku + web_search as a fallback when deterministic matching fails. Auto-applies agent matches at confidence ≥ 0.9; flags 0.75-0.9 for review.", {
+            mode: z
+                .enum(["new", "all"])
+                .default("new")
+                .describe("'new' (default): only accounts without a current territory. 'all': re-evaluate everything (use after territories.yaml changes)."),
+            dryRun: z
+                .boolean()
+                .default(true)
+                .describe("When true (default), shows the diff without writing to Salesforce."),
+            useAgent: z
+                .boolean()
+                .default(true)
+                .describe("Run Claude fallback for accounts the deterministic matcher cannot resolve. Set false to skip the agent."),
+            branch: z.string().optional().describe("Branch to read YAML from. Default: main."),
+        }, safeTool(async ({ mode, dryRun, useAgent, branch }) => trpcMutation("mcp.assignTerritories", { mode, dryRun, useAgent, branch })));
+    }
+}

package/dist/tools/crm.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCrmTools(server: McpServer, allowed: Set<string>): void;

package/dist/tools/crm.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { trpcQuery, trpcMutation } from "../api-client.js";
+import { safeTool } from "./_helpers.js";
+import { leadStatusSchema, opportunityStageSchema, pipelineSortSchema, quarterSchema, rangeSchema, 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 })));
+    }
+    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
+                .optional()
+                .describe("Salesforce Opportunity ID (006…). Preferred if known."),
+            opportunityName: z
+                .string()
+                .optional()
+                .describe("Exact opportunity name, used when you don't have the Salesforce ID."),
+            close_date: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/, { message: "Use YYYY-MM-DD." })
+                .optional()
+                .describe("New close date in YYYY-MM-DD format."),
+            next_step: z.string().optional().describe("Next step text."),
+            description: z.string().optional().describe("Opportunity description."),
+            reason: z
+                .string()
+                .min(1)
+                .describe("Why this change is being made (required, logged)."),
+        }, safeTool(async ({ opportunityId, opportunityName, close_date, next_step, description, reason }) => trpcMutation("mcp.updateOpportunity", {
+            opportunityId,
+            opportunityName,
+            fields: { close_date, next_step, description },
+            reason,
+        })));
+    }
+    if (allowed.has("update_lead")) {
+        server.tool("update_lead", "Update a lead's status or description. Reps can only update their own leads. Requires a reason for the change.", {
+            leadId: salesforceLeadIdSchema.describe("Salesforce Lead ID (00Q…)."),
+            status: leadStatusSchema
+                .optional()
+                .describe("New Salesforce Lead status."),
+            description: z.string().optional().describe("Lead description."),
+            reason: z
+                .string()
+                .min(1)
+                .describe("Why this change is being made (required, logged)."),
+        }, safeTool(async ({ leadId, status, description, reason }) => trpcMutation("mcp.updateLead", {
+            leadId,
+            fields: { status, description },
+            reason,
+        })));
+    }
+    if (allowed.has("push_target_account_to_sf")) {
+        server.tool("push_target_account_to_sf", "Create Salesforce Account records from the target account list. Pushes accounts that don't yet have an SF Account ID. Ops+ only.", {
+            domain: z
+                .string()
+                .optional()
+                .describe("Push a single account by domain (e.g., 'databricks.com')."),
+            tier: targetAccountTierSchema
+                .optional()
+                .describe("Push all accounts in a tier."),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(500)
+                .optional()
+                .describe("Max accounts to push in one batch (1–500). Default: 100."),
+        }, safeTool(async ({ domain, tier, limit }) => trpcMutation("mcp.pushTargetAccountToSf", {
+            domain,
+            tier,
+            limit: limit || 100,
+        })));
+    }
+}

package/dist/tools/eng.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerEngTools(server: McpServer, allowed: Set<string>): void;

package/dist/tools/eng.js

@@ -0,0 +1,54 @@
+import { execSync } from "node:child_process";
+import { z } from "zod";
+import { trpcMutation, trpcQuery } from "../api-client.js";
+import { safeTool } from "./_helpers.js";
+import { rangeSchema } from "./_schemas.js";
+export function registerEngTools(server, allowed) {
+    if (allowed.has("system_diagnostics")) {
+        server.tool("system_diagnostics", "System health diagnostics: failed executions, error patterns, latency outliers.", {
+            range: rangeSchema
+                .optional()
+                .describe("Time window. Short ranges (1h, 6h, 24h, 7d) are most useful. Default: 24h."),
+        }, safeTool(async ({ range }) => trpcQuery("mcp.systemDiagnostics", { range })));
+    }
+    if (allowed.has("revoke_api_key")) {
+        server.tool("revoke_api_key", "Immediately revoke every active MCP API key for a user. The user's loop_sk_* tokens in Claude Desktop stop working on the next tRPC call (401). Use for urgent access cutoff (suspected compromise, termination not yet processed in Okta). Routine offboarding should just deactivate the user in Okta — the 5-min reconciler picks that up.", {
+            email: z
+                .string()
+                .email()
+                .describe("Email of the Loop user to revoke."),
+            reason: z
+                .string()
+                .min(8)
+                .describe("Why you're revoking. Required — recorded in audit_log."),
+        }, safeTool(async ({ email, reason }) => trpcMutation("mcp.revokeApiKey", { email, reason })));
+    }
+    if (allowed.has("access_review")) {
+        server.tool("access_review", "Produce a user-access snapshot for SOC/security review. Lists every Loop user with role, status, SF linkage, active/revoked key counts, and last-active date. The review itself is audited — auditors can see who produced it and when. Intended for quarterly access reviews.", {
+            includeRevoked: z
+                .boolean()
+                .optional()
+                .describe("If true, also include users whose API keys have been revoked (for full historical picture). Default: false (active access only)."),
+        }, safeTool(async ({ includeRevoked }) => trpcQuery("mcp.accessReview", { includeRevoked })));
+    }
+    if (allowed.has("sync_local")) {
+        server.tool("sync_local", "Pull the latest changes from the remote repo into your local working tree. Runs `git pull --ff-only` in the repo at $LOOP_REPO_PATH. Use this after update_config / deploy_config writes commits directly to the remote branch so your local clone catches up.", {}, safeTool(async () => {
+            const repoPath = process.env.LOOP_REPO_PATH;
+            if (!repoPath) {
+                return "LOOP_REPO_PATH is not set. Add it to your MCP server env (pointing at your local repo root) and restart Claude.";
+            }
+            try {
+                const output = execSync("git pull --ff-only", {
+                    cwd: repoPath,
+                    encoding: "utf-8",
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+                return `Synced \`${repoPath}\`:\n\n\`\`\`\n${output.trim() || "Already up to date."}\n\`\`\``;
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return `Failed to sync \`${repoPath}\`:\n\n\`\`\`\n${message}\n\`\`\`\n\nCommon causes: uncommitted changes, wrong branch, or diverged history. Resolve manually with \`git status\` / \`git log\`.`;
+            }
+        }));
+    }
+}

package/dist/tools/engage.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerEngageTools(server: McpServer, allowed: Set<string>): void;

package/dist/tools/engage.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { trpcQuery, trpcMutation } from "../api-client.js";
+import { safeTool } from "./_helpers.js";
+import { salesforceLeadIdSchema, sequenceApproveMethodSchema, sequenceStatusSchema, } from "./_schemas.js";
+export function registerEngageTools(server, allowed) {
+    if (allowed.has("my_sequences")) {
+        server.tool("my_sequences", "Show email sequences generated by the Engage loop. Reps see their own, managers see their team's.", {
+            status: sequenceStatusSchema
+                .optional()
+                .describe("Filter by sequence lifecycle status."),
+            leadId: salesforceLeadIdSchema
+                .optional()
+                .describe("Filter by Salesforce Lead ID."),
+            leadEmail: z
+                .string()
+                .email()
+                .optional()
+                .describe("Filter by lead email address."),
+            leadCompany: z.string().optional().describe("Filter by company name."),
+        }, safeTool(async ({ status, leadId, leadEmail, leadCompany }) => trpcQuery("mcp.mySequences", {
+            status,
+            leadId,
+            leadEmail,
+            leadCompany,
+        })));
+    }
+    if (allowed.has("review_sequence")) {
+        server.tool("review_sequence", "Show full detail of a generated sequence: all emails, quality scores, and research brief. You can look it up by sequence ID, lead ID, lead email, or company.", {
+            sequenceId: z.string().uuid().optional().describe("Sequence ID (UUID)."),
+            leadId: salesforceLeadIdSchema
+                .optional()
+                .describe("Salesforce Lead ID."),
+            leadEmail: z
+                .string()
+                .email()
+                .optional()
+                .describe("Lead email address."),
+            leadCompany: z.string().optional().describe("Company name."),
+        }, safeTool(async ({ sequenceId, leadId, leadEmail, leadCompany }) => trpcQuery("mcp.reviewSequence", {
+            sequenceId,
+            leadId,
+            leadEmail,
+            leadCompany,
+        })));
+    }
+    if (allowed.has("approve_sequence")) {
+        server.tool("approve_sequence", "Approve a sequence for deployment. Sends first email and creates follow-up tasks.", {
+            sequenceId: z.string().uuid().describe("Sequence ID (UUID) to approve."),
+            method: sequenceApproveMethodSchema
+                .optional()
+                .describe("Deployment method. Default: resend."),
+        }, safeTool(async ({ sequenceId, method }) => trpcMutation("mcp.approveSequence", { sequenceId, method })));
+    }
+    if (allowed.has("reject_sequence")) {
+        server.tool("reject_sequence", "Reject a generated sequence with a reason.", {
+            sequenceId: z.string().uuid().describe("Sequence ID (UUID) to reject."),
+            reason: z.string().min(1).describe("Why the sequence is being rejected."),
+        }, safeTool(async ({ sequenceId, reason }) => trpcMutation("mcp.rejectSequence", { sequenceId, reason })));
+    }
+}

package/dist/tools/reporting.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerReportingTools(server: McpServer, allowed: Set<string>): void;

package/dist/tools/reporting.js

@@ -0,0 +1,41 @@
+import { trpcQuery } from "../api-client.js";
+import { safeTool } from "./_helpers.js";
+import { loopNameSchema, 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 })));
+    }
+    if (allowed.has("enrichment_coverage")) {
+        server.tool("enrichment_coverage", "Analyze lead enrichment coverage: enrichment rate, top industries, headcount distribution.", {
+            range: rangeSchema
+                .optional()
+                .describe("Time window. Default: 7d."),
+        }, safeTool(async ({ range }) => trpcQuery("mcp.enrichmentCoverage", { range })));
+    }
+    if (allowed.has("decision_explain")) {
+        server.tool("decision_explain", "Explain a specific lead's end-to-end scoring, enrichment, routing, and outreach trail. Pass a Salesforce Lead ID.", {
+            leadId: salesforceLeadIdSchema.describe("Salesforce Lead ID (e.g., 00QgL00000BQL0tUAH)."),
+        }, safeTool(async ({ leadId }) => trpcQuery("mcp.decisionExplain", { leadId })));
+    }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@loopops/mcp-server",
+  "version": "1.0.0",
+  "description": "Loop Operations MCP Server — AI skills for RevOps",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "loop-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Loop-Operations/loop.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://www.loopops.io",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@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"
+  }
+}