jxp 4.1.1 → 5.0.0

package/templates/assets/docs.css

@@ -242,3 +242,110 @@ body.docs-body {
 	width: 100%;
 	max-width: 400px;
 }
+
+.mcp-chat-wrap {
+	border: 1px solid var(--docs-border);
+	border-radius: 0.5rem;
+	overflow: hidden;
+	background: #fafbfc;
+}
+
+.mcp-chat-thread {
+	max-height: 420px;
+	overflow-y: auto;
+	padding: 1rem;
+	display: flex;
+	flex-direction: column;
+	gap: 0.75rem;
+}
+
+.mcp-msg {
+	max-width: 92%;
+}
+
+.mcp-msg-user {
+	align-self: flex-end;
+}
+
+.mcp-msg-bot {
+	align-self: flex-start;
+}
+
+.mcp-msg-label {
+	font-size: 0.7rem;
+	font-weight: 600;
+	text-transform: uppercase;
+	letter-spacing: 0.04em;
+	color: #6c757d;
+	margin-bottom: 0.25rem;
+}
+
+.mcp-msg-body {
+	padding: 0.65rem 0.85rem;
+	border-radius: 0.5rem;
+	font-size: 0.9rem;
+}
+
+.mcp-msg-user .mcp-msg-body {
+	background: var(--docs-accent);
+	color: #fff;
+}
+
+.mcp-msg-user .mcp-msg-body code {
+	color: #fff;
+	background: rgba(255, 255, 255, 0.15);
+}
+
+.mcp-msg-bot .mcp-msg-body {
+	background: #fff;
+	border: 1px solid var(--docs-border);
+}
+
+.mcp-msg-error .mcp-msg-body {
+	border-color: #f5c2c7;
+	background: #f8d7da;
+}
+
+.mcp-result {
+	font-family: ui-monospace, monospace;
+	font-size: 0.78rem;
+	white-space: pre-wrap;
+	word-break: break-word;
+	max-height: 240px;
+	overflow: auto;
+	background: #212529;
+	color: #e9ecef;
+	padding: 0.75rem;
+	border-radius: 0.375rem;
+}
+
+.mcp-chat-input-wrap {
+	padding: 0.75rem 1rem;
+	border-top: 1px solid var(--docs-border);
+	background: #fff;
+}
+
+.mcp-tool-panel {
+	border: 1px solid var(--docs-border);
+	border-radius: 0.375rem;
+	padding: 1rem;
+	background: #fafbfc;
+}
+
+.mcp-setup-card .mcp-json-block {
+	font-family: ui-monospace, monospace;
+	font-size: 0.8rem;
+	background: #212529;
+	color: #e9ecef;
+	border-radius: 0.375rem;
+	padding: 1rem;
+	margin: 0;
+	overflow-x: auto;
+	white-space: pre;
+}
+
+.mcp-setup-card .mcp-copy-btn {
+	position: absolute;
+	top: 0.5rem;
+	right: 0.5rem;
+}

package/templates/assets/mcp-console.js

@@ -0,0 +1,343 @@
+(function () {
+	"use strict";
+
+	const STORAGE_KEY = "jxp_docs_api_key";
+	const STORAGE_REMEMBER = "jxp_docs_remember_key";
+
+	function getApiKey() {
+		const input = document.getElementById("docs-api-key");
+		return input ? input.value.trim() : "";
+	}
+
+	function loadStoredKey() {
+		if (localStorage.getItem(STORAGE_REMEMBER) !== "1") return;
+		const key = localStorage.getItem(STORAGE_KEY);
+		if (!key) return;
+		const input = document.getElementById("docs-api-key");
+		const remember = document.getElementById("docs-remember-key");
+		if (input) input.value = key;
+		if (remember) remember.checked = true;
+	}
+
+	function saveKeyIfRemembered() {
+		const remember = document.getElementById("docs-remember-key");
+		const input = document.getElementById("docs-api-key");
+		if (!remember || !input) return;
+		if (remember.checked) {
+			localStorage.setItem(STORAGE_REMEMBER, "1");
+			localStorage.setItem(STORAGE_KEY, input.value.trim());
+		} else {
+			localStorage.removeItem(STORAGE_REMEMBER);
+			localStorage.removeItem(STORAGE_KEY);
+		}
+		updateMcpConfigSnippets();
+	}
+
+	function getMcpSetup() {
+		const card = document.querySelector(".mcp-setup-card");
+		const fromWindow = window.__MCP_SETUP__ || {};
+		const baseUrl =
+			fromWindow.baseUrl ||
+			card?.dataset.baseUrl ||
+			window.location.origin;
+		const mcpPath = fromWindow.mcpPath || card?.dataset.mcpPath || "/mcp";
+		const base = String(baseUrl).replace(/\/$/, "");
+		const path = mcpPath.startsWith("/") ? mcpPath : `/${mcpPath}`;
+		const mcpUrl = fromWindow.mcpUrl || card?.dataset.mcpUrl || `${base}${path}`;
+		return {
+			baseUrl: base,
+			mcpUrl,
+			serverSlug: fromWindow.serverSlug || card?.dataset.serverSlug || "jxp",
+		};
+	}
+
+	function buildMcpJsonConfig(kind, apiKey) {
+		const setup = getMcpSetup();
+		const key = apiKey || "YOUR_API_KEY";
+		const slug = setup.serverSlug || "jxp";
+		if (kind === "stdio") {
+			return JSON.stringify(
+				{
+					mcpServers: {
+						[slug]: {
+							command: "npx",
+							args: ["-y", "jxp-mcp"],
+							env: {
+								JXP_URL: setup.baseUrl,
+								JXP_API_KEY: key,
+							},
+						},
+					},
+				},
+				null,
+				2
+			);
+		}
+		return JSON.stringify(
+			{
+				mcpServers: {
+					[slug]: {
+						url: setup.mcpUrl,
+						headers: { "X-API-Key": key },
+					},
+				},
+			},
+			null,
+			2
+		);
+	}
+
+	function updateMcpConfigSnippets() {
+		const apiKey = getApiKey();
+		const httpEl = document.getElementById("mcpJsonHttp");
+		const stdioEl = document.getElementById("mcpJsonStdio");
+		if (httpEl) httpEl.textContent = buildMcpJsonConfig("http", apiKey);
+		if (stdioEl) stdioEl.textContent = buildMcpJsonConfig("stdio", apiKey);
+	}
+
+	async function copyMcpConfig(targetId, btn) {
+		const el = document.getElementById(targetId);
+		if (!el) return;
+		try {
+			await navigator.clipboard.writeText(el.textContent || "");
+			const label = btn.innerHTML;
+			btn.innerHTML = '<i class="bi bi-check2 me-1"></i>Copied';
+			setTimeout(function () {
+				btn.innerHTML = label;
+			}, 1500);
+		} catch {
+			/* ignore */
+		}
+	}
+
+	function escapeHtml(text) {
+		return String(text)
+			.replace(/&/g, "&amp;")
+			.replace(/</g, "&lt;")
+			.replace(/>/g, "&gt;")
+			.replace(/"/g, "&quot;");
+	}
+
+	function formatBody(text) {
+		if (!text) return "";
+		try {
+			return JSON.stringify(JSON.parse(text), null, 2);
+		} catch {
+			return text;
+		}
+	}
+
+	function appendMessage(thread, role, bodyHtml, isError) {
+		const wrap = document.createElement("div");
+		wrap.className = "mcp-msg mcp-msg-" + role + (isError ? " mcp-msg-error" : "");
+		const label = document.createElement("div");
+		label.className = "mcp-msg-label";
+		label.textContent = role === "user" ? "You" : "Assistant";
+		const body = document.createElement("div");
+		body.className = "mcp-msg-body";
+		body.innerHTML = bodyHtml;
+		wrap.appendChild(label);
+		wrap.appendChild(body);
+		thread.appendChild(wrap);
+		thread.scrollTop = thread.scrollHeight;
+	}
+
+	function appendToolNote(thread, toolName, args) {
+		const argsText = Object.keys(args).length ? JSON.stringify(args) : "{}";
+		appendMessage(
+			thread,
+			"user",
+			`<p class="mb-0"><code>${escapeHtml(toolName)}</code> <span class="text-muted">${escapeHtml(argsText)}</span></p>`,
+			false
+		);
+	}
+
+	function appendResult(thread, text, isError) {
+		const formatted = escapeHtml(formatBody(text));
+		appendMessage(thread, "bot", `<pre class="mcp-result mb-0">${formatted}</pre>`, isError);
+	}
+
+	async function callMcpTool(name, args) {
+		const headers = { "Content-Type": "application/json", Accept: "application/json" };
+		const apiKey = getApiKey();
+		if (apiKey) headers["X-API-Key"] = apiKey;
+
+		const res = await fetch("/docs/mcp/call", {
+			method: "POST",
+			credentials: "same-origin",
+			headers,
+			body: JSON.stringify({ name, arguments: args }),
+		});
+		const payload = await res.json().catch(() => ({ text: res.statusText, isError: true }));
+		if (!res.ok) {
+			const msg = payload.message || payload.text || res.statusText;
+			throw new Error(msg);
+		}
+		return payload;
+	}
+
+	async function runTool(thread, name, args) {
+		appendToolNote(thread, name, args);
+		try {
+			const result = await callMcpTool(name, args);
+			appendResult(thread, result.text || "", !!result.isError);
+		} catch (err) {
+			appendResult(thread, String(err.message || err), true);
+		}
+	}
+
+	function parseLimit(text) {
+		const match = text.match(/\blimit\s*=\s*(\d+)/i);
+		return match ? parseInt(match[1], 10) : 5;
+	}
+
+	function parseCommand(input) {
+		const text = input.trim();
+		if (!text) return null;
+
+		const lower = text.toLowerCase();
+		if (lower === "help" || lower === "?") {
+			return {
+				help: true,
+				html:
+					"<p>Commands:</p><ul class=\"mb-0\"><li><code>list models</code></li>" +
+					"<li><code>describe MODEL</code></li><li><code>count MODEL</code></li>" +
+					"<li><code>find MODEL</code> or <code>find MODEL limit=10</code></li></ul>",
+			};
+		}
+
+		if (/^list\s+models?$/i.test(text)) {
+			return { tool: "jxp_list_models", args: {} };
+		}
+
+		const describeMatch = text.match(/^describe\s+(\S+)/i);
+		if (describeMatch) {
+			return { tool: "jxp_describe_model", args: { model: describeMatch[1] } };
+		}
+
+		const countMatch = text.match(/^count\s+(\S+)/i);
+		if (countMatch) {
+			return { tool: "jxp_count", args: { model: countMatch[1] } };
+		}
+
+		const findMatch = text.match(/^find\s+(\S+)/i);
+		if (findMatch) {
+			return {
+				tool: "jxp_find",
+				args: { model: findMatch[1], limit: parseLimit(text) },
+			};
+		}
+
+		return {
+			error:
+				"I didn't understand that. Try <code>list models</code>, <code>describe MODEL</code>, " +
+				"<code>count MODEL</code>, or <code>find MODEL limit=5</code>. Type <code>help</code> for more.",
+		};
+	}
+
+	async function handleUserInput(thread, input) {
+		const text = input.trim();
+		if (!text) return;
+
+		appendMessage(thread, "user", `<p class="mb-0">${escapeHtml(text)}</p>`, false);
+
+		const parsed = parseCommand(text);
+		if (!parsed) return;
+
+		if (parsed.help) {
+			appendMessage(thread, "bot", parsed.html, false);
+			return;
+		}
+		if (parsed.error) {
+			appendMessage(thread, "bot", `<p class="mb-0">${parsed.error}</p>`, true);
+			return;
+		}
+
+		await runTool(thread, parsed.tool, parsed.args);
+	}
+
+	async function loadSessionApiKey() {
+		const access = document.documentElement.dataset.docsAccess;
+		if (access !== "protected") return;
+		try {
+			const res = await fetch("/docs/session", { credentials: "same-origin" });
+			if (!res.ok) return;
+			const data = await res.json();
+			if (!data.apikey) return;
+			const input = document.getElementById("docs-api-key");
+			if (input) input.value = data.apikey;
+			updateMcpConfigSnippets();
+		} catch {
+			/* ignore */
+		}
+	}
+
+	document.addEventListener("DOMContentLoaded", function () {
+		const access = document.documentElement.dataset.docsAccess;
+		const thread = document.getElementById("mcpChatThread");
+		const form = document.getElementById("mcpChatForm");
+		const chatInput = document.getElementById("mcpChatInput");
+		const toolSelect = document.getElementById("mcpToolSelect");
+		const toolArgs = document.getElementById("mcpToolArgs");
+		const toolRun = document.getElementById("mcpToolRun");
+
+		if (!thread) return;
+
+		loadSessionApiKey().then(function () {
+			if (access !== "protected") loadStoredKey();
+			updateMcpConfigSnippets();
+		});
+
+		const keyInput = document.getElementById("docs-api-key");
+		const remember = document.getElementById("docs-remember-key");
+		if (keyInput) {
+			keyInput.addEventListener("change", saveKeyIfRemembered);
+			keyInput.addEventListener("input", updateMcpConfigSnippets);
+		}
+		if (remember) remember.addEventListener("change", saveKeyIfRemembered);
+
+		document.querySelectorAll(".mcp-copy-btn").forEach(function (btn) {
+			btn.addEventListener("click", function () {
+				const target = btn.getAttribute("data-target");
+				if (target) copyMcpConfig(target, btn);
+			});
+		});
+
+		if (form && chatInput) {
+			form.addEventListener("submit", function (e) {
+				e.preventDefault();
+				saveKeyIfRemembered();
+				const value = chatInput.value;
+				chatInput.value = "";
+				handleUserInput(thread, value);
+			});
+		}
+
+		document.querySelectorAll(".mcp-quick-btn").forEach(function (btn) {
+			btn.addEventListener("click", function () {
+				saveKeyIfRemembered();
+				const cmd = btn.getAttribute("data-cmd") || "";
+				if (chatInput) chatInput.value = cmd;
+				handleUserInput(thread, cmd);
+				if (chatInput) chatInput.value = "";
+			});
+		});
+
+		if (toolRun && toolSelect && toolArgs) {
+			toolRun.addEventListener("click", function () {
+				saveKeyIfRemembered();
+				let args = {};
+				const raw = toolArgs.value.trim();
+				if (raw) {
+					try {
+						args = JSON.parse(raw);
+					} catch (err) {
+						appendResult(thread, "Invalid JSON arguments: " + err.message, true);
+						return;
+					}
+				}
+				runTool(thread, toolSelect.value, args);
+			});
+		}
+	});
+})();

package/templates/diagnostics.pug

@@ -0,0 +1,94 @@
+extends layout
+
+block content
+  h1.h3.mb-1 Index diagnostics
+  p.text-muted.mb-4
+    | Compare schema indexes to MongoDB, review slow-query samples, and sync indexes.
+    | Requires an 
+    strong admin
+    |  API key (filled automatically after docs sign-in, or paste into the top bar).
+
+  ul#diag-tabs.nav.nav-tabs(role="tablist")
+    li.nav-item(role="presentation")
+      button.nav-link.active#tab-indexes-btn(type="button" data-bs-toggle="tab" data-bs-target="#tab-indexes" role="tab") Indexes
+    li.nav-item(role="presentation")
+      button.nav-link#tab-queries-btn(type="button" data-bs-toggle="tab" data-bs-target="#tab-queries" role="tab") Query log
+
+  .tab-content.mt-3
+    #tab-indexes.tab-pane.fade.show.active(role="tabpanel")
+      .d-flex.flex-wrap.gap-2.mb-3
+        button#diag-refresh-indexes.btn.btn-primary.btn-sm(type="button")
+          i.bi.bi-arrow-clockwise.me-1
+          | Refresh audit
+        .form-check.form-check-inline.mb-0.align-self-center
+          input#diag-unused.form-check-input(type="checkbox")
+          label.form-check-label(for="diag-unused") Include unused ($indexStats)
+      #diag-indexes-status.small.text-muted.mb-2
+      #diag-indexes-summary
+      .table-responsive
+        table#diag-indexes-table.table.table-sm.table-hover.d-none
+          thead
+            tr
+              th Model
+              th Collection
+              th Status
+              th Missing
+              th Extra
+          tbody
+
+      hr.mt-4
+      h2.h5 Sync indexes
+      p.small.text-muted
+        | Creates indexes defined in Mongoose schemas and drops DB indexes not in the schema.
+        | Type 
+        code= sync_confirm
+        |  to confirm.
+      .row.g-2.align-items-end
+        .col-md-6
+          input#diag-sync-confirm.form-control.form-control-sm(type="text" placeholder=sync_confirm autocomplete="off")
+        .col-auto
+          button#diag-sync-btn.btn.btn-outline-danger.btn-sm(type="button" disabled) Sync indexes
+
+    #tab-queries.tab-pane.fade(role="tabpanel")
+      .d-flex.flex-wrap.gap-2.mb-3
+        button#diag-refresh-queries.btn.btn-primary.btn-sm(type="button")
+          i.bi.bi-arrow-clockwise.me-1
+          | Refresh log
+        select#diag-query-severity.form-select.form-select-sm(style="width:auto")
+          option(value="") All severities
+          option(value="alert") alert
+          option(value="warn") warn
+        .diag-model-filter(style="min-width:10rem;max-width:14rem")
+          input#diag-query-model.form-control.form-control-sm(
+            type="text"
+            list="diag-query-model-list"
+            placeholder="All models"
+            autocomplete="off"
+            aria-label="Filter by model"
+          )
+          datalist#diag-query-model-list
+            each opt in model_filter_options
+              option(value=opt.value)= opt.label
+      #diag-queries-status.small.text-muted.mb-2
+      #diag-monitor-config.small.mb-2
+      #diag-query-monitor-help.d-none
+      .table-responsive
+        table#diag-queries-table.table.table-sm.table-hover.d-none
+          thead
+            tr
+              th When
+              th Model
+              th Op
+              th Severity
+              th Docs examined
+              th Returned
+              th Scan
+              th Reason
+              th Filter
+          tbody
+
+block javascripts
+  script.
+    window.JXP_DIAG_SYNC_CONFIRM = !{JSON.stringify(sync_confirm)};
+    window.JXP_DIAG_MODEL_FILTER_OPTIONS = !{JSON.stringify(model_filter_options)};
+  script(src="/docs/assets/diagnostics.js" defer)

package/templates/index.pug

@@ -11,6 +11,13 @@ block content
       if first_guide_url
         a.btn.btn-primary(href=first_guide_url) Get started
       a.btn.btn-outline-primary(href="/docs/api") Browse API
+      if mcp_enabled
+        a.btn.btn-outline-primary(href="/docs/mcp")
+          i.bi.bi-robot.me-1
+          | Ask MCP
+      else
+        a.btn.btn-outline-secondary(href="/docs/md/mcp.md") MCP setup
+      a.btn.btn-outline-secondary(href="/docs/diagnostics") Index diagnostics
       a.btn.btn-outline-secondary(href="/docs/md/api.md") REST reference
 
   .row.g-4.mb-4
@@ -34,6 +41,37 @@ block content
               |  panels on API resource pages. Keys are stored in the browser only when “Remember” is checked.
     .col-md-6
       .card.h-100
+        .card-header.fw-semibold
+          if mcp_enabled
+            | MCP for AI agents
+          else
+            | MCP (Model Context Protocol)
+        .card-body
+          if mcp_enabled
+            p.mb-2
+              | This server exposes read-only MCP tools at 
+              code= mcp_path
+              |  — use them from Cursor, LM Studio, or the built-in assistant.
+            pre.mb-3
+              code.
+                MCP_ENABLED=true
+                # Cursor: npx -y jxp-mcp
+            a.btn.btn-sm.btn-primary(href="/docs/mcp") Open MCP assistant
+            a.btn.btn-sm.btn-outline-secondary.ms-2(href="/docs/md/mcp.md") Setup guide
+          else
+            p.mb-2
+              | Enable 
+              code MCP_ENABLED=true 
+              |  to expose five fixed read-only tools (
+              code jxp_list_models
+              | , 
+              code jxp_find
+              | , …) for AI clients and a built-in docs playground.
+            a.btn.btn-sm.btn-outline-primary(href="/docs/md/mcp.md") Read MCP docs
+
+  .row.g-4.mb-4
+    .col-12
+      .card
         .card-header.fw-semibold API at a glance
         .card-body
           p.mb-2