@loopops/mcp-server 3.47.0 → 3.49.0

package/dist/api-client.js

@@ -32,7 +32,14 @@ let refreshToken = process.env.OKTA_REFRESH_TOKEN;
 // Access token cache (in-memory, subprocess-lifetime).
 let cachedAccessToken = null;
 let cachedAccessTokenExpiresAt = 0; // epoch ms
-const DEFAULT_TIMEOUT_MS = Number(process.env.API_TIMEOUT_MS || 30_000);
+// 120s default. The fast tools (cpq_context, find_opportunity, my_quotes,
+// account_show, etc.) return in <2s; the slow tools (create_prep_brief,
+// draft_quote_from_intent) chain web search + Claude composition and can
+// legitimately take 30-90s. The old 30s default tripped users on the slow
+// tools when their MCP client config didn't override. Override via
+// API_TIMEOUT_MS env (Claude Code CLI sets 300000 from `loop-ops login`;
+// Desktop config should mirror that).
+const DEFAULT_TIMEOUT_MS = Number(process.env.API_TIMEOUT_MS || 120_000);
 const SERVER_NAME = "loop-operations";
 // Refresh a little early so requests don't race token expiry at the edge.
 const ACCESS_TOKEN_EARLY_REFRESH_MS = 60 * 1000; // 1 minute

package/dist/tools/_html-ui.d.ts

@@ -0,0 +1,60 @@
+/**
+ * MCP UI extension support — render tool output as styled HTML so Claude
+ * Desktop renders it in a side panel instead of inline.
+ *
+ * Claude Desktop's `initialize` handshake declares support for the
+ * io.modelcontextprotocol/ui extension with `text/html;profile=mcp-app`.
+ * When a tool returns an `embedded_resource` with that mime type, Desktop
+ * renders it in a side panel with native copy/print/share affordances —
+ * the "create a document" UX the team wants for prep briefs and similar
+ * long-form artifacts.
+ *
+ * Clients without the UI extension (Claude Code CLI, Codex) just see the
+ * markdown text content block — same content, inline.
+ *
+ * Usage:
+ *   server.tool(name, desc, schema, safeToolUi(async args => {
+ *     const md = await trpcMutation(...);
+ *     return {
+ *       markdown: md,
+ *       title: "Customer Prep — Acme",
+ *     };
+ *   }))
+ */
+type ContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "resource";
+    resource: {
+        uri: string;
+        mimeType: string;
+        text: string;
+    };
+};
+type McpToolResult = {
+    content: ContentBlock[];
+    isError?: boolean;
+};
+interface UiResponse {
+    /** Markdown body — always returned as a text content block. */
+    markdown: string;
+    /** Title shown at the top of the HTML doc + tab. */
+    title: string;
+    /** Optional meta line under the title (e.g., "generated at … · account …"). */
+    meta?: string;
+    /** Optional uri identifier. Defaults to a synthesized one. */
+    uri?: string;
+}
+/**
+ * Tool wrapper that returns content as BOTH markdown (inline fallback)
+ * AND HTML (Desktop side-panel render). Mirrors safeTool's error handling.
+ *
+ * Use this for long-form artifacts where the user wants a document
+ * experience: prep briefs, quote previews, deal-health snapshots.
+ *
+ * Short tool outputs (status messages, counts, single-fact lookups)
+ * should stick with plain safeTool — adding HTML would just be noise.
+ */
+export declare function safeToolUi<Args>(fn: (args: Args) => Promise<UiResponse>): (args: Args) => Promise<McpToolResult>;
+export {};

package/dist/tools/_html-ui.js

@@ -0,0 +1,205 @@
+/**
+ * MCP UI extension support — render tool output as styled HTML so Claude
+ * Desktop renders it in a side panel instead of inline.
+ *
+ * Claude Desktop's `initialize` handshake declares support for the
+ * io.modelcontextprotocol/ui extension with `text/html;profile=mcp-app`.
+ * When a tool returns an `embedded_resource` with that mime type, Desktop
+ * renders it in a side panel with native copy/print/share affordances —
+ * the "create a document" UX the team wants for prep briefs and similar
+ * long-form artifacts.
+ *
+ * Clients without the UI extension (Claude Code CLI, Codex) just see the
+ * markdown text content block — same content, inline.
+ *
+ * Usage:
+ *   server.tool(name, desc, schema, safeToolUi(async args => {
+ *     const md = await trpcMutation(...);
+ *     return {
+ *       markdown: md,
+ *       title: "Customer Prep — Acme",
+ *     };
+ *   }))
+ */
+import { marked } from "marked";
+import { ApiAuthError, ApiHttpError, ApiNetworkError, ApiTimeoutError, } from "../api-client.js";
+const MCP_APP_MIME = "text/html;profile=mcp-app";
+/**
+ * Convert a markdown brief / quote / report into a styled, self-contained
+ * HTML document for Desktop's side-panel render.
+ *
+ * Self-contained means no external assets — all styles inlined. Lets the
+ * client cache + share the doc without hot-linking.
+ */
+function renderMcpAppHtml(opts) {
+    const body = marked.parse(opts.markdown, { gfm: true, breaks: false });
+    const safeTitle = escapeHtml(opts.title);
+    const safeMeta = opts.meta ? escapeHtml(opts.meta) : "";
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${safeTitle}</title>
+<style>
+  :root {
+    --bg: #ffffff;
+    --fg: #0f172a;
+    --muted: #64748b;
+    --line: #e2e8f0;
+    --code-bg: #f1f5f9;
+    --pre-bg: #f8fafc;
+    --accent: #0ea5e9;
+    --blockquote: #475569;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #0f172a;
+      --fg: #f1f5f9;
+      --muted: #94a3b8;
+      --line: #1e293b;
+      --code-bg: #1e293b;
+      --pre-bg: #0b1224;
+      --accent: #38bdf8;
+      --blockquote: #cbd5e1;
+    }
+  }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; background: var(--bg); color: var(--fg); }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "Inter", system-ui, sans-serif;
+    font-size: 15px;
+    line-height: 1.6;
+    max-width: 760px;
+    margin: 0 auto;
+    padding: 40px 32px 80px;
+  }
+  h1 { font-size: 26px; margin: 0 0 8px; line-height: 1.25; }
+  h2 { font-size: 20px; margin: 32px 0 12px; padding-bottom: 6px; border-bottom: 1px solid var(--line); }
+  h3 { font-size: 16px; margin: 24px 0 8px; }
+  p { margin: 12px 0; }
+  ul, ol { padding-left: 24px; }
+  li { margin: 4px 0; }
+  blockquote {
+    margin: 16px 0;
+    padding: 8px 16px;
+    border-left: 3px solid var(--accent);
+    color: var(--blockquote);
+    background: var(--code-bg);
+    border-radius: 0 4px 4px 0;
+  }
+  code {
+    background: var(--code-bg);
+    padding: 2px 6px;
+    border-radius: 4px;
+    font-family: "SF Mono", Menlo, monospace;
+    font-size: 0.92em;
+  }
+  pre {
+    background: var(--pre-bg);
+    padding: 16px;
+    border-radius: 8px;
+    overflow-x: auto;
+    border: 1px solid var(--line);
+  }
+  pre code { background: transparent; padding: 0; }
+  table { border-collapse: collapse; width: 100%; margin: 16px 0; }
+  th, td { border: 1px solid var(--line); padding: 8px 12px; text-align: left; vertical-align: top; }
+  th { background: var(--code-bg); font-weight: 600; }
+  hr { border: 0; border-top: 1px solid var(--line); margin: 32px 0; }
+  a { color: var(--accent); text-decoration: none; }
+  a:hover { text-decoration: underline; }
+  .header { border-bottom: 1px solid var(--line); padding-bottom: 16px; margin-bottom: 24px; }
+  .meta { color: var(--muted); font-size: 13px; margin-top: 4px; }
+  @media print {
+    body { padding: 0; max-width: none; }
+    .no-print { display: none; }
+  }
+</style>
+</head>
+<body>
+<div class="header">
+  <h1>${safeTitle}</h1>
+  ${safeMeta ? `<div class="meta">${safeMeta}</div>` : ""}
+</div>
+<div class="content">
+${body}
+</div>
+</body>
+</html>`;
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+/**
+ * Tool wrapper that returns content as BOTH markdown (inline fallback)
+ * AND HTML (Desktop side-panel render). Mirrors safeTool's error handling.
+ *
+ * Use this for long-form artifacts where the user wants a document
+ * experience: prep briefs, quote previews, deal-health snapshots.
+ *
+ * Short tool outputs (status messages, counts, single-fact lookups)
+ * should stick with plain safeTool — adding HTML would just be noise.
+ */
+export function safeToolUi(fn) {
+    return async (args) => {
+        try {
+            const result = await fn(args);
+            const html = renderMcpAppHtml(result);
+            const uri = result.uri ?? `loop://artifacts/${slugify(result.title)}`;
+            return {
+                content: [
+                    { type: "text", text: result.markdown },
+                    {
+                        type: "resource",
+                        resource: {
+                            uri,
+                            mimeType: MCP_APP_MIME,
+                            text: html,
+                        },
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const text = formatErrorForUser(err);
+            console.error("[MCP] Tool error:", err);
+            return { content: [{ type: "text", text }], isError: true };
+        }
+    };
+}
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 80);
+}
+/**
+ * Reused from _helpers — keep one canonical error formatter. Slight
+ * duplication is fine; not worth a cross-file import for 20 lines.
+ */
+function formatErrorForUser(err) {
+    if (err instanceof ApiAuthError) {
+        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 timed out after ${err.timeoutMs}ms. Slow tools (create_prep_brief, draft_quote_from_intent) can take 30-90s; if you keep hitting this, ask Revenue Operations to raise API_TIMEOUT_MS in your MCP client config.`;
+    }
+    if (err instanceof ApiHttpError) {
+        return `Loop API returned HTTP ${err.status}: ${err.body.slice(0, 300) || "(no body)"}.`;
+    }
+    if (err instanceof ApiNetworkError) {
+        return `Couldn't reach the Loop API: ${err.message}.`;
+    }
+    return `Tool failed: ${err instanceof Error ? err.message : String(err)}`;
+}

package/dist/tools/reporting.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { trpcMutation, trpcQuery } from "../api-client.js";
 import { safeTool } from "./_helpers.js";
+import { safeToolUi } from "./_html-ui.js";
 import { rangeSchema, salesforceLeadIdSchema, } from "./_schemas.js";
 export function registerReportingTools(server, allowed) {
     // loop_health retired 2026-05-06 — replaced by ClickHouse parameterized
@@ -50,12 +51,27 @@ export function registerReportingTools(server, allowed) {
                 .enum(["concise", "standard", "detailed"])
                 .optional()
                 .describe("Output verbosity. concise ~400 words; standard ~900 (default); detailed ~1500."),
-        }, safeTool(async ({ accountDomain, conversationType, meetingContext, localContent, style }) => trpcMutation("mcp.createPrepBrief", {
-            accountDomain,
-            conversationType,
-            meetingContext,
-            localContent,
-            style: style ?? "standard",
-        })));
+        }, safeToolUi(async ({ accountDomain, conversationType, meetingContext, localContent, style }) => {
+            const markdown = await trpcMutation("mcp.createPrepBrief", {
+                accountDomain,
+                conversationType,
+                meetingContext,
+                localContent,
+                style: style ?? "standard",
+            });
+            // Pretty title for the document tab + heading.
+            const conversationLabel = conversationType
+                .split("_")
+                .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+                .join(" ");
+            return {
+                markdown,
+                title: `${accountDomain} — ${conversationLabel} prep`,
+                meta: meetingContext
+                    ? `Meeting context: ${meetingContext}`
+                    : undefined,
+                uri: `loop://briefs/${accountDomain}/${conversationType}/${Date.now()}`,
+            };
+        }));
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopops/mcp-server",
-  "version": "3.47.0",
+  "version": "3.49.0",
   "description": "Loop Operations MCP Server — AI skills for RevOps",
   "license": "UNLICENSED",
   "type": "module",
@@ -28,6 +28,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
+    "marked": "^18.0.4",
     "yaml": "^2.6.0",
     "zod": "^3.24.4"
   },