@loopops/mcp-server 3.42.0 → 3.43.1

package/dist/index.js

@@ -17,8 +17,11 @@ import { registerPursueTools } from "./tools/pursue.js";
 import { registerAccountMasterTools } from "./tools/account-master.js";
 import { registerPeopleMasterTools } from "./tools/people-master.js";
 import { registerScoringTools } from "./tools/scoring.js";
+import { registerCpqTools } from "./tools/cpq.js";
 import { registerSfdcSyncTools } from "./tools/sfdc-sync.js";
 import { registerTalTools } from "./tools/tal.js";
+import { parseSkillModesResponse } from "./skills/loader.js";
+import { registerSkillsAsPrompts } from "./skills/handlers.js";
 // Read our own package.json at runtime so the version baked into MCP
 // initialize-handshake `serverInfo.version` matches the published npm
 // version. Was hardcoded "1.0.0" — confusing in Claude Desktop logs and
@@ -67,5 +70,22 @@ registerDeployTools(server, allowedSkills);
 registerTalTools(server, allowedSkills);
 registerScoringTools(server, allowedSkills);
 registerSfdcSyncTools(server, allowedSkills);
+registerCpqTools(server, allowedSkills);
+// Skills framework — fetch role-visible skills from the Loop API and
+// register each as a server-provided MCP prompt. Surfaces in the
+// client's `/` menu and bundles (system prompt + tool emphasis +
+// on-load context). See docs/engineering/mcp-skills.md.
+//
+// Failure here is non-fatal: tools still work; the user just won't see
+// skills in the `/` menu until they reconnect.
+try {
+    const raw = await trpcQuery("mcp.getMySkillModes");
+    const skillModes = parseSkillModesResponse(raw);
+    registerSkillsAsPrompts(server, skillModes);
+    console.error(`[MCP] Skills registered: ${skillModes.map((s) => s.name).join(", ") || "(none for this role)"}`);
+}
+catch (err) {
+    console.error("[MCP] Failed to load skill modes — continuing without skill prompts:", err instanceof Error ? err.message : String(err));
+}
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/skills/handlers.d.ts

@@ -0,0 +1,17 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Skill } from "./loader.js";
+/**
+ * Wire each skill into the MCP server as a server-provided prompt.
+ *
+ * Clients (Claude Desktop, Claude Code, Codex CLI) discover these via
+ * the MCP `prompts/list` request and render them in their `/` menu.
+ * When the user picks a skill, the client calls `prompts/get` and the
+ * server returns the system prompt + tool hints below.
+ *
+ * Note: this registers prompts at server startup. If skills.yaml changes
+ * during a session, the user must reconnect to pick up the change. A
+ * future `prompts/list_changed` notification could make this hot-reload,
+ * but the cost of that complexity isn't worth it yet — skill changes
+ * are infrequent.
+ */
+export declare function registerSkillsAsPrompts(server: McpServer, skills: Skill[]): void;

package/dist/skills/handlers.js

@@ -0,0 +1,67 @@
+/**
+ * Wire each skill into the MCP server as a server-provided prompt.
+ *
+ * Clients (Claude Desktop, Claude Code, Codex CLI) discover these via
+ * the MCP `prompts/list` request and render them in their `/` menu.
+ * When the user picks a skill, the client calls `prompts/get` and the
+ * server returns the system prompt + tool hints below.
+ *
+ * Note: this registers prompts at server startup. If skills.yaml changes
+ * during a session, the user must reconnect to pick up the change. A
+ * future `prompts/list_changed` notification could make this hot-reload,
+ * but the cost of that complexity isn't worth it yet — skill changes
+ * are infrequent.
+ */
+export function registerSkillsAsPrompts(server, skills) {
+    for (const skill of skills) {
+        server.registerPrompt(skill.name, {
+            title: skill.title,
+            description: skill.description,
+            // No prompt args today — skills load context themselves via
+            // on_load + tools_emphasized. If we add a parametric skill in
+            // the future (e.g., `quote_review` taking a quoteId), expand
+            // here.
+        }, async () => {
+            return {
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: buildPromptText(skill),
+                        },
+                    },
+                ],
+            };
+        });
+    }
+}
+/**
+ * Compose the final text payload returned to the MCP client. The user
+ * receives this as the opening turn of the skill conversation.
+ *
+ * Three sections:
+ *   1. The skill's `system_prompt` verbatim
+ *   2. Tool hints (if any) — Claude reads these and prioritizes
+ *   3. On-load hints (if any) — instructs Claude to call these
+ *      proactively to load context before responding
+ */
+function buildPromptText(skill) {
+    const sections = [skill.system_prompt.trim()];
+    if (skill.tools_emphasized.length > 0) {
+        sections.push(`\n---\n**Tools to favor for this skill** (others remain callable but these are the primary surface):\n` +
+            skill.tools_emphasized.map((t) => `- \`${t}\``).join("\n"));
+    }
+    if (skill.on_load.length > 0) {
+        sections.push(`\n---\n**On entering this skill, call these tools first** to load context:\n` +
+            skill.on_load
+                .map((c) => {
+                const argsStr = Object.keys(c.args).length === 0
+                    ? "(no args)"
+                    : `with args ${JSON.stringify(c.args)}`;
+                return `1. \`${c.tool}\` ${argsStr}`;
+            })
+                .join("\n"));
+    }
+    return sections.join("\n");
+}

package/dist/skills/loader.d.ts

@@ -0,0 +1,194 @@
+import { z } from "zod";
+/**
+ * Skill schema for the Loop MCP skills framework.
+ *
+ * A skill is a named workflow mode that bundles a system prompt with a
+ * subset of available tools. Skills surface in the user's MCP client as
+ * server-provided prompts (Claude Desktop's `/` menu, Claude Code slash
+ * commands, Codex CLI prompts).
+ *
+ * Source of truth: `config/mcp/skills.yaml` in the loop repo. The Loop
+ * API exposes role-filtered skills via `mcp.getMySkillModes`; the MCP
+ * server then registers each as a prompt at connect time.
+ *
+ * See docs/engineering/mcp-skills.md for the framework + tool-vs-skill
+ * decision guide.
+ */
+export declare const skillSchema: z.ZodObject<{
+    /** Slug used to invoke the skill (e.g., `/cpq_coach`). Lowercase + underscores only. */
+    name: z.ZodString;
+    /** Display title shown in the client's prompt menu. */
+    title: z.ZodString;
+    /** One-line hover description in the client's prompt menu. */
+    description: z.ZodString;
+    /**
+     * The "you are…" prompt that defines the skill's voice + workflow.
+     * Multiline; treat as a markdown-friendly system prompt.
+     */
+    system_prompt: z.ZodString;
+    /**
+     * Tools the agent should focus on for this skill. Not exclusive —
+     * other tools remain callable. A HINT to Claude; user doesn't see it.
+     */
+    tools_emphasized: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Optional turn-1 tool invocations. Rendered as "call these first"
+     * hints in the prompt response so Claude loads context proactively.
+     *
+     * Future: a stricter "auto-call" mode where the server pre-invokes
+     * these and returns the result inline.
+     */
+    on_load: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        args: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        tool: string;
+        args: Record<string, unknown>;
+    }, {
+        tool: string;
+        args?: Record<string, unknown> | undefined;
+    }>, "many">>;
+    /**
+     * Roles that can see/invoke this skill. If omitted, all authenticated
+     * roles can see it. Same role names as the MCP role system: field /
+     * ops / dev / admin.
+     */
+    roles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    name: string;
+    title: string;
+    system_prompt: string;
+    tools_emphasized: string[];
+    on_load: {
+        tool: string;
+        args: Record<string, unknown>;
+    }[];
+    roles?: string[] | undefined;
+}, {
+    description: string;
+    name: string;
+    title: string;
+    system_prompt: string;
+    tools_emphasized?: string[] | undefined;
+    on_load?: {
+        tool: string;
+        args?: Record<string, unknown> | undefined;
+    }[] | undefined;
+    roles?: string[] | undefined;
+}>;
+export type Skill = z.infer<typeof skillSchema>;
+declare const skillsFileSchema: z.ZodObject<{
+    version: z.ZodString;
+    skills: z.ZodArray<z.ZodObject<{
+        /** Slug used to invoke the skill (e.g., `/cpq_coach`). Lowercase + underscores only. */
+        name: z.ZodString;
+        /** Display title shown in the client's prompt menu. */
+        title: z.ZodString;
+        /** One-line hover description in the client's prompt menu. */
+        description: z.ZodString;
+        /**
+         * The "you are…" prompt that defines the skill's voice + workflow.
+         * Multiline; treat as a markdown-friendly system prompt.
+         */
+        system_prompt: z.ZodString;
+        /**
+         * Tools the agent should focus on for this skill. Not exclusive —
+         * other tools remain callable. A HINT to Claude; user doesn't see it.
+         */
+        tools_emphasized: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * Optional turn-1 tool invocations. Rendered as "call these first"
+         * hints in the prompt response so Claude loads context proactively.
+         *
+         * Future: a stricter "auto-call" mode where the server pre-invokes
+         * these and returns the result inline.
+         */
+        on_load: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            tool: z.ZodString;
+            args: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strip", z.ZodTypeAny, {
+            tool: string;
+            args: Record<string, unknown>;
+        }, {
+            tool: string;
+            args?: Record<string, unknown> | undefined;
+        }>, "many">>;
+        /**
+         * Roles that can see/invoke this skill. If omitted, all authenticated
+         * roles can see it. Same role names as the MCP role system: field /
+         * ops / dev / admin.
+         */
+        roles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        name: string;
+        title: string;
+        system_prompt: string;
+        tools_emphasized: string[];
+        on_load: {
+            tool: string;
+            args: Record<string, unknown>;
+        }[];
+        roles?: string[] | undefined;
+    }, {
+        description: string;
+        name: string;
+        title: string;
+        system_prompt: string;
+        tools_emphasized?: string[] | undefined;
+        on_load?: {
+            tool: string;
+            args?: Record<string, unknown> | undefined;
+        }[] | undefined;
+        roles?: string[] | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    skills: {
+        description: string;
+        name: string;
+        title: string;
+        system_prompt: string;
+        tools_emphasized: string[];
+        on_load: {
+            tool: string;
+            args: Record<string, unknown>;
+        }[];
+        roles?: string[] | undefined;
+    }[];
+}, {
+    version: string;
+    skills: {
+        description: string;
+        name: string;
+        title: string;
+        system_prompt: string;
+        tools_emphasized?: string[] | undefined;
+        on_load?: {
+            tool: string;
+            args?: Record<string, unknown> | undefined;
+        }[] | undefined;
+        roles?: string[] | undefined;
+    }[];
+}>;
+export type SkillsFile = z.infer<typeof skillsFileSchema>;
+/**
+ * Load + validate `config/mcp/skills.yaml`. Used server-side (Loop API)
+ * to source the skills registry; throws on schema violation so bad
+ * config fails the build/start rather than serving a broken skill.
+ */
+export declare function loadSkillsYaml(yamlPath: string): SkillsFile;
+/**
+ * Filter skills by the caller's role. Skills with no `roles` constraint
+ * are visible to everyone authenticated.
+ */
+export declare function skillsForRole(skills: Skill[], role: string): Skill[];
+/**
+ * Validate an API response from `mcp.getMySkillModes`. Used client-side
+ * (the @loopops/mcp-server package) when fetching the role-filtered
+ * skills from the Loop API. Returns an empty array on shape mismatch
+ * so a broken API response doesn't crash the MCP server.
+ */
+export declare function parseSkillModesResponse(raw: unknown): Skill[];
+export {};

package/dist/skills/loader.js

@@ -0,0 +1,93 @@
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import yaml from "yaml";
+/**
+ * Skill schema for the Loop MCP skills framework.
+ *
+ * A skill is a named workflow mode that bundles a system prompt with a
+ * subset of available tools. Skills surface in the user's MCP client as
+ * server-provided prompts (Claude Desktop's `/` menu, Claude Code slash
+ * commands, Codex CLI prompts).
+ *
+ * Source of truth: `config/mcp/skills.yaml` in the loop repo. The Loop
+ * API exposes role-filtered skills via `mcp.getMySkillModes`; the MCP
+ * server then registers each as a prompt at connect time.
+ *
+ * See docs/engineering/mcp-skills.md for the framework + tool-vs-skill
+ * decision guide.
+ */
+export const skillSchema = z.object({
+    /** Slug used to invoke the skill (e.g., `/cpq_coach`). Lowercase + underscores only. */
+    name: z
+        .string()
+        .regex(/^[a-z][a-z0-9_]*$/, "name must be snake_case and start with a letter"),
+    /** Display title shown in the client's prompt menu. */
+    title: z.string().min(1),
+    /** One-line hover description in the client's prompt menu. */
+    description: z.string().min(1),
+    /**
+     * The "you are…" prompt that defines the skill's voice + workflow.
+     * Multiline; treat as a markdown-friendly system prompt.
+     */
+    system_prompt: z.string().min(1),
+    /**
+     * Tools the agent should focus on for this skill. Not exclusive —
+     * other tools remain callable. A HINT to Claude; user doesn't see it.
+     */
+    tools_emphasized: z.array(z.string()).default([]),
+    /**
+     * Optional turn-1 tool invocations. Rendered as "call these first"
+     * hints in the prompt response so Claude loads context proactively.
+     *
+     * Future: a stricter "auto-call" mode where the server pre-invokes
+     * these and returns the result inline.
+     */
+    on_load: z
+        .array(z.object({
+        tool: z.string(),
+        args: z.record(z.unknown()).default({}),
+    }))
+        .default([]),
+    /**
+     * Roles that can see/invoke this skill. If omitted, all authenticated
+     * roles can see it. Same role names as the MCP role system: field /
+     * ops / dev / admin.
+     */
+    roles: z.array(z.string()).optional(),
+});
+const skillsFileSchema = z.object({
+    version: z.string(),
+    skills: z.array(skillSchema),
+});
+/**
+ * Load + validate `config/mcp/skills.yaml`. Used server-side (Loop API)
+ * to source the skills registry; throws on schema violation so bad
+ * config fails the build/start rather than serving a broken skill.
+ */
+export function loadSkillsYaml(yamlPath) {
+    const raw = readFileSync(yamlPath, "utf-8");
+    const parsed = yaml.parse(raw);
+    return skillsFileSchema.parse(parsed);
+}
+/**
+ * Filter skills by the caller's role. Skills with no `roles` constraint
+ * are visible to everyone authenticated.
+ */
+export function skillsForRole(skills, role) {
+    return skills.filter((s) => !s.roles || s.roles.includes(role));
+}
+/**
+ * Validate an API response from `mcp.getMySkillModes`. Used client-side
+ * (the @loopops/mcp-server package) when fetching the role-filtered
+ * skills from the Loop API. Returns an empty array on shape mismatch
+ * so a broken API response doesn't crash the MCP server.
+ */
+export function parseSkillModesResponse(raw) {
+    const arraySchema = z.object({ skills: z.array(skillSchema) });
+    const parsed = arraySchema.safeParse(raw);
+    if (!parsed.success) {
+        console.error("[skills] Unexpected response shape from mcp.getMySkillModes:", parsed.error.message);
+        return [];
+    }
+    return parsed.data.skills;
+}

package/dist/skills/loader.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/skills/loader.test.js

@@ -0,0 +1,159 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { loadSkillsYaml, skillsForRole, parseSkillModesResponse } from "./loader.js";
+function writeTempYaml(content) {
+    const dir = mkdtempSync(join(tmpdir(), "skills-test-"));
+    const path = join(dir, "skills.yaml");
+    writeFileSync(path, content, "utf-8");
+    return {
+        path,
+        cleanup: () => rmSync(dir, { recursive: true, force: true }),
+    };
+}
+test("loadSkillsYaml: parses a minimal skill", () => {
+    const { path, cleanup } = writeTempYaml(`
+version: "0.1.0"
+skills:
+  - name: hello
+    title: "Hello"
+    description: "A greeting skill"
+    system_prompt: "Say hi to the user."
+`);
+    try {
+        const parsed = loadSkillsYaml(path);
+        assert.equal(parsed.skills.length, 1);
+        assert.equal(parsed.skills[0].name, "hello");
+        assert.deepEqual(parsed.skills[0].tools_emphasized, []);
+        assert.deepEqual(parsed.skills[0].on_load, []);
+    }
+    finally {
+        cleanup();
+    }
+});
+test("loadSkillsYaml: parses a fully-specified skill", () => {
+    const { path, cleanup } = writeTempYaml(`
+version: "0.1.0"
+skills:
+  - name: cpq_coach
+    title: "CPQ Coach"
+    description: "Build quotes"
+    system_prompt: "You are a CPQ coach."
+    tools_emphasized: [cpq_context, quote_show]
+    on_load:
+      - tool: cpq_context
+        args: {}
+    roles: [field, ops]
+`);
+    try {
+        const parsed = loadSkillsYaml(path);
+        const skill = parsed.skills[0];
+        assert.equal(skill.name, "cpq_coach");
+        assert.deepEqual(skill.tools_emphasized, ["cpq_context", "quote_show"]);
+        assert.equal(skill.on_load[0].tool, "cpq_context");
+        assert.deepEqual(skill.roles, ["field", "ops"]);
+    }
+    finally {
+        cleanup();
+    }
+});
+test("loadSkillsYaml: rejects bad slug (caps + dashes)", () => {
+    const { path, cleanup } = writeTempYaml(`
+version: "0.1.0"
+skills:
+  - name: CPQ-Coach
+    title: "Bad"
+    description: "Bad"
+    system_prompt: "x"
+`);
+    try {
+        assert.throws(() => loadSkillsYaml(path));
+    }
+    finally {
+        cleanup();
+    }
+});
+test("loadSkillsYaml: rejects empty system_prompt", () => {
+    const { path, cleanup } = writeTempYaml(`
+version: "0.1.0"
+skills:
+  - name: empty
+    title: "x"
+    description: "x"
+    system_prompt: ""
+`);
+    try {
+        assert.throws(() => loadSkillsYaml(path));
+    }
+    finally {
+        cleanup();
+    }
+});
+const SKILLS = [
+    {
+        name: "public",
+        title: "Public",
+        description: "Everyone",
+        system_prompt: "x",
+        tools_emphasized: [],
+        on_load: [],
+    },
+    {
+        name: "field_only",
+        title: "Field Only",
+        description: "Field reps",
+        system_prompt: "x",
+        tools_emphasized: [],
+        on_load: [],
+        roles: ["field"],
+    },
+    {
+        name: "ops_admin",
+        title: "Ops + Admin",
+        description: "Privileged",
+        system_prompt: "x",
+        tools_emphasized: [],
+        on_load: [],
+        roles: ["ops", "admin"],
+    },
+];
+test("skillsForRole: includes public + role-matching skills", () => {
+    const fieldSkills = skillsForRole(SKILLS, "field");
+    const names = fieldSkills.map((s) => s.name).sort();
+    assert.deepEqual(names, ["field_only", "public"]);
+});
+test("skillsForRole: excludes role-gated skills the caller doesn't have", () => {
+    const fieldSkills = skillsForRole(SKILLS, "field");
+    assert.equal(fieldSkills.find((s) => s.name === "ops_admin"), undefined);
+});
+test("skillsForRole: multi-role skills visible when caller matches any role", () => {
+    const adminSkills = skillsForRole(SKILLS, "admin");
+    assert.ok(adminSkills.some((s) => s.name === "ops_admin"));
+});
+test("skillsForRole: caller with no match sees only public skills", () => {
+    const guestSkills = skillsForRole(SKILLS, "stranger");
+    assert.deepEqual(guestSkills.map((s) => s.name), ["public"]);
+});
+test("parseSkillModesResponse: extracts skills from a well-formed response", () => {
+    const raw = {
+        skills: [
+            {
+                name: "test_skill",
+                title: "Test",
+                description: "Test skill",
+                system_prompt: "test",
+                tools_emphasized: ["a", "b"],
+                on_load: [],
+            },
+        ],
+    };
+    const skills = parseSkillModesResponse(raw);
+    assert.equal(skills.length, 1);
+    assert.equal(skills[0].name, "test_skill");
+});
+test("parseSkillModesResponse: returns empty array on bad shape", () => {
+    const skills = parseSkillModesResponse({ wrong: "shape" });
+    assert.deepEqual(skills, []);
+});

package/dist/tools/cpq.d.ts

@@ -0,0 +1,13 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * CPQ tools — surface for the cpq_coach skill.
+ *
+ * The skill in config/mcp/skills.yaml bundles these into a workflow
+ * mode (system prompt + tool emphasis + auto-load context). When a
+ * user invokes /cpq_coach, the MCP client loads the prompt + Claude
+ * is told to call `cpq_context` as turn-1.
+ *
+ * Authorization gates: each tool is conditionally registered based on
+ * the user's role grant from config/mcp/role-tool-grants.yaml.
+ */
+export declare function registerCpqTools(server: McpServer, allowed: Set<string>): void;

package/dist/tools/cpq.js

@@ -0,0 +1,18 @@
+import { trpcQuery } from "../api-client.js";
+import { safeTool } from "./_helpers.js";
+/**
+ * CPQ tools — surface for the cpq_coach skill.
+ *
+ * The skill in config/mcp/skills.yaml bundles these into a workflow
+ * mode (system prompt + tool emphasis + auto-load context). When a
+ * user invokes /cpq_coach, the MCP client loads the prompt + Claude
+ * is told to call `cpq_context` as turn-1.
+ *
+ * Authorization gates: each tool is conditionally registered based on
+ * the user's role grant from config/mcp/role-tool-grants.yaml.
+ */
+export function registerCpqTools(server, allowed) {
+    if (allowed.has("cpq_context")) {
+        server.tool("cpq_context", "Loads the full ClickHouse CPQ context: the playbook (tier guidance, sizing heuristics, commit strategy, discount approach, validation rules, common mistakes, FAQ), the product catalog (16 products with rates), and the discount schedule (commit × term grid). Call this ONCE per CPQ conversation before answering any pricing or quote-building question. The cpq_coach skill auto-loads this.", {}, safeTool(async () => trpcQuery("mcp.cpqContext")));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopops/mcp-server",
-  "version": "3.42.0",
+  "version": "3.43.1",
   "description": "Loop Operations MCP Server — AI skills for RevOps",
   "license": "UNLICENSED",
   "type": "module",
@@ -20,18 +20,20 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "pnpm build"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
+    "yaml": "^2.6.0",
     "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"
   }
-}
+}