jxp 4.2.0 → 5.0.2

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/index.pug

@@ -11,6 +11,12 @@ 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
 
@@ -35,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

package/templates/mcp.pug

@@ -0,0 +1,112 @@
+extends layout
+
+block content
+  h1.mb-1 MCP assistant
+  p.text-muted.mb-4
+    | Connect Cursor or LM Studio to this API, then try the playground below.
+
+  .card.mb-4.mcp-setup-card(
+    data-mcp-url=mcp_url
+    data-base-url=base_url
+    data-mcp-path=mcp_path
+    data-server-slug=mcp_server_slug
+  )
+    .card-header.fw-semibold
+      i.bi.bi-plug.me-1
+      | Add to your MCP config
+    .card-body
+      p.mb-2
+        | Merge into 
+        code mcp.json
+        |  (Cursor: 
+        strong Cursor Settings → MCP
+        | ; LM Studio: server settings). Your API key is filled in from your session.
+      ul.nav.nav-tabs#mcpConfigTabs(role="tablist")
+        li.nav-item(role="presentation")
+          button.nav-link.active#mcp-http-tab(data-bs-toggle="tab" data-bs-target="#mcp-http-pane" type="button" role="tab" aria-controls="mcp-http-pane" aria-selected="true") Cursor / HTTP
+        li.nav-item(role="presentation")
+          button.nav-link#mcp-stdio-tab(data-bs-toggle="tab" data-bs-target="#mcp-stdio-pane" type="button" role="tab" aria-controls="mcp-stdio-pane" aria-selected="false") stdio (jxp-mcp)
+      .tab-content.border.border-top-0.rounded-bottom.p-3.bg-light#mcpConfigTabContent
+        .tab-pane.fade.show.active#mcp-http-pane(role="tabpanel" aria-labelledby="mcp-http-tab" tabindex="0")
+          p.small.text-muted.mb-2 Recommended for Cursor — receives server instructions on connect.
+          .position-relative
+            pre.mcp-json-block.mb-2#mcpJsonHttp(data-config="http")= mcp_http_json
+            button.btn.btn-sm.btn-outline-secondary.mcp-copy-btn(type="button" data-target="mcpJsonHttp")
+              i.bi.bi-clipboard.me-1
+              | Copy
+        .tab-pane.fade#mcp-stdio-pane(role="tabpanel" aria-labelledby="mcp-stdio-tab" tabindex="0")
+          p.small.text-muted.mb-2 Uses 
+            code npx jxp-mcp
+            |  to proxy stdio → HTTP (tools, resources, instructions).
+          .position-relative
+            pre.mcp-json-block.mb-2#mcpJsonStdio(data-config="stdio")= mcp_stdio_json
+            button.btn.btn-sm.btn-outline-secondary.mcp-copy-btn(type="button" data-target="mcpJsonStdio")
+              i.bi.bi-clipboard.me-1
+              | Copy
+      p.small.text-muted.mb-0.mt-3
+        | HTTP endpoint: 
+        code= mcp_url
+        |  · 
+        a(href="/docs/md/mcp.md") Full MCP docs
+
+  h2.h5.mb-3 Try it here
+  p.text-muted.mb-3.small
+    | Same read-only tools and permissions as 
+    code GET /api
+    | . Commands below call 
+    code POST /docs/mcp/call
+    |  with your signed-in key.
+
+  .mcp-chat-wrap
+    .mcp-chat-thread#mcpChatThread(role="log" aria-live="polite" aria-label="MCP conversation")
+      .mcp-msg.mcp-msg-bot
+        .mcp-msg-label Assistant
+        .mcp-msg-body
+          p.mb-2 Ask about your data — or try:
+          ul.small.mb-0
+            li
+              code list models
+            li
+              code describe MODEL
+            li
+              code count MODEL
+            li
+              code find MODEL limit=5
+            li
+              code help
+
+    .mcp-chat-input-wrap
+      .d-flex.flex-wrap.gap-2.mb-2
+        each action in [{label: 'List models', cmd: 'list models'}, {label: 'Help', cmd: 'help'}]
+          button.btn.btn-sm.btn-outline-secondary.mcp-quick-btn(type="button" data-cmd=action.cmd)= action.label
+      form#mcpChatForm
+        .input-group
+          input#mcpChatInput.form-control(type="text" placeholder="Ask about your data…" autocomplete="off" aria-label="MCP message")
+          button.btn.btn-primary(type="submit")
+            i.bi.bi-send-fill.me-1
+            | Send
+
+  details.mt-4
+    summary.fw-semibold Advanced — call a tool directly
+    p.small.text-muted.mt-2 Pick a tool and pass JSON arguments (same as Cursor/LM Studio MCP clients).
+    .mcp-tool-panel.mt-2
+      .row.g-2.mb-2
+        .col-md-4
+          label.form-label.small.fw-semibold Tool
+          select#mcpToolSelect.form-select.form-select-sm
+            option(value="jxp_list_models") jxp_list_models
+            option(value="jxp_describe_model") jxp_describe_model
+            option(value="jxp_find") jxp_find
+            option(value="jxp_count") jxp_count
+            option(value="jxp_export_csv") jxp_export_csv
+        .col-md-8
+          label.form-label.small.fw-semibold Arguments (JSON)
+          textarea#mcpToolArgs.form-control.form-control-sm.font-monospace(rows="4") {}
+      button.btn.btn-sm.btn-outline-primary#mcpToolRun(type="button")
+        i.bi.bi-play-fill.me-1
+        | Run tool
+
+block javascripts
+  script.
+    window.__MCP_SETUP__ = !{JSON.stringify({ mcpUrl: mcp_url || '', baseUrl: base_url || '', mcpPath: mcp_path || '/mcp', serverSlug: mcp_server_slug || 'jxp' })};
+  script(src="/docs/assets/mcp-console.js" defer)

package/templates/navbar.pug

@@ -7,6 +7,8 @@ header.docs-topbar.navbar.navbar-expand-lg.sticky-top
     .ms-auto.d-flex.align-items-center.gap-2.flex-wrap
       if docs_access === 'protected' && !docs_authenticated
         a.btn.btn-sm.btn-outline-primary(href="/docs/login?next=/docs/api") Explore API
+        if mcp_enabled
+          a.btn.btn-sm.btn-outline-primary(href="/docs/login?next=/docs/mcp") Ask MCP
       if docs_access !== 'disabled' && (docs_access !== 'protected' || docs_authenticated)
         .docs-api-key-wrap
           label.visually-hidden(for="docs-api-key") API Key

package/templates/sidebar.pug

@@ -7,6 +7,10 @@ nav.docs-sidebar#docsSidebarDesktop(aria-label="Documentation navigation")
       a.docs-nav-link(href="/docs/md/" + file class=(active_guide === file ? 'active' : ''))= label
   .docs-sidebar-section
     .docs-sidebar-title Operations
+    if mcp_enabled
+      a.docs-nav-link(href="/docs/mcp" class=(active_section === 'mcp' ? 'active' : ''))
+        i.bi.bi-robot.me-1
+        | MCP assistant
     a.docs-nav-link(href="/docs/diagnostics" class=(active_section === 'diagnostics' ? 'active' : ''))
       i.bi.bi-speedometer2.me-1
       | Index diagnostics