jxp 4.2.0 → 5.0.0

package/docs/mcp.md

@@ -0,0 +1,134 @@
+# MCP (Model Context Protocol)
+
+JXP can expose a **read-only** MCP server on the same HTTP port as the REST API. This lets AI clients (Cursor, LM Studio, RevEngine2 admin proxy) query your data with the same permissions as the REST API.
+
+## Enable
+
+```bash
+MCP_ENABLED=true
+```
+
+Optional settings (all prefixed `MCP_`):
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MCP_PATH` | `/mcp` | HTTP endpoint |
+| `MCP_REQUIRE_API_KEY` | `true` | Reject unauthenticated MCP |
+| `MCP_MODEL_WHITELIST` | _(empty)_ | Expose default-hidden models (e.g. `user`) |
+| `MCP_MODEL_BLACKLIST` | _(empty)_ | Always hide models |
+| `MCP_DEFAULT_HIDDEN_MODELS` | builtin auth slugs | Override default-deny list |
+| `MCP_DEFAULT_LIMIT` | `20` | Default row limit |
+| `MCP_MAX_LIMIT` | `100` | Hard cap on `limit` |
+| `MCP_MAX_RESPONSE_SIZE` | `256kb` | JSON response cap |
+| `MCP_MAX_CSV_SIZE` | `512kb` | CSV export cap |
+| `MCP_TRUNCATE_STRINGS_AT` | `4000` | Truncate long string fields in JSON |
+| `MCP_DISABLE_AUTOPOPULATE` | `true` | Ignore expensive autopopulate |
+| `MCP_INSTRUCTIONS_APPEND` | _(empty)_ | Text appended to server instructions (initialize) |
+| `MCP_GUIDE_FILES` | _(empty)_ | Comma-separated markdown files merged into `jxp-guide` resource |
+
+## LLM guidance
+
+On connect, the MCP `initialize` response includes **server instructions** — a short workflow summary injected for the LLM.
+
+For the full guide, read the fixed MCP resource **`jxp-guide`** (`jxp://guide`, markdown). Content is merged in order:
+
+1. Built-in [`default.md`](https://github.com/WorkSpaceMan/jxp/blob/main/src/libs/mcp/guides/default.md)
+2. `JXPConfig.mcp.guideFiles` (app config)
+3. `MCP_GUIDE_FILES` (env)
+
+### App extension (`JXPConfig.mcp`)
+
+```typescript
+apiconfig.mcp = {
+  instructions: "Short app-specific note appended to server instructions.",
+  guideFiles: [path.join(__dirname, "../../mcp/guide.md")],
+};
+```
+
+Example: [revengine-api `mcp/guide.md`](https://github.com/WorkSpaceMan/revengine-api) adds domain context for `reader`, `segment`, etc.
+
+## Tools (fixed)
+
+1. **`jxp_list_models`** — models the caller can read via MCP
+2. **`jxp_describe_model`** — field types, links, populate hints
+3. **`jxp_find`** — list or get by `id`; supports `filter`, `search`, `populate`, `fields`, `sort`, `limit`, `page`
+4. **`jxp_count`** — count with optional `filter` / `search`
+5. **`jxp_export_csv`** — CSV text export (use `fields` + low `limit`)
+
+Tools never change when you add models — agents call `jxp_list_models` first.
+
+## Authentication
+
+Send the user's API key on every MCP HTTP request:
+
+```
+X-API-Key: <apikey>
+```
+
+Bearer tokens also work. MCP uses the same permission rules as `GET /api/:model`.
+
+## Docs playground
+
+When `MCP_ENABLED=true`, the built-in docs UI includes **`/docs/mcp`** — a chat-style assistant that calls the same five MCP tools (protected by the same login as **Browse API**). Use the API key field in the top bar or sign in; tool calls go through `POST /docs/mcp/call` with your permissions.
+
+Default-hidden models (unless whitelisted): built-in auth collections (`user`, `apikey`, `token`, etc.) and schemas with `internal: true`.
+
+## Cursor / LM Studio (stdio)
+
+Use the `jxp-mcp` bridge (proxies stdio → HTTP, including tools, resources, and instructions):
+
+```json
+{
+  "mcpServers": {
+    "jxp": {
+      "command": "npx",
+      "args": ["-y", "jxp-mcp"],
+      "env": {
+        "JXP_URL": "http://localhost:4001",
+        "JXP_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+For Cursor, direct HTTP MCP also works and receives instructions automatically:
+
+```json
+{
+  "mcpServers": {
+    "jxp": {
+      "url": "http://localhost:4001/mcp",
+      "headers": { "X-API-Key": "your-api-key" }
+    }
+  }
+}
+```
+
+## RevEngine2 / server proxy
+
+Backend connects to `{API_URL}/mcp` with the logged-in user's API key and proxies MCP between the admin UI and JXP. JXP's own docs UI also exposes `/docs/mcp` for local exploration.
+
+## Deploying `jxp-mcp`
+
+`jxp-mcp` is **not** a separate npm package. It ships as a **CLI binary on the `jxp` package** (since v5.0.0):
+
+```bash
+npm install jxp@5          # or depend on jxp in your app
+npx jxp-mcp                # stdio MCP → your HTTP /mcp endpoint
+```
+
+| Component | Where it runs | Role |
+|-----------|---------------|------|
+| **JXP HTTP API** | Your server (e.g. RevEngine Docker on port 4001) | Serves REST + `/mcp` when `MCP_ENABLED=true` |
+| **`jxp-mcp` bridge** | Developer's machine (Cursor, LM Studio) | stdio proxy; needs `JXP_URL` + `JXP_API_KEY` pointing at the HTTP server |
+
+**Production API containers** do not need to run `jxp-mcp`. Enable MCP on the API (`MCP_ENABLED=true`) and connect from the IDE via HTTP or stdio.
+
+**Publish order:** `npm publish` **jxp@5** first, then bump app dependencies (e.g. `revengine-api` `jxp: ^5.0.0`) and rebuild Docker images.
+
+## v1 limitations
+
+- Read-only (no mutations)
+- No `POST /query`, `/aggregate`, or `/call`
+- No per-model `mcp:` schema flag (env lists only)

package/mkdocs.yml

@@ -16,5 +16,6 @@ nav:
   - Index diagnostics: index_diagnostics.md
   - Websocket: websocket.md
   - Special Features: special.md
+  - MCP: mcp.md
   - Changelog: changelog.md
 theme: readthedocs

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "jxp",
 	"description": "An opinionated RESTful API library based on Mongoose and Restify. Make an API by just writing Mongoose models.",
-	"version": "4.2.0",
+	"version": "5.0.0",
 	"private": false,
 	"main": "dist/libs/jxp.js",
 	"types": "dist/libs/jxp.d.ts",
@@ -50,12 +50,12 @@
 		}
 	},
 	"scripts": {
-		"build": "tsc -p tsconfig.build.json",
+		"build": "tsc -p tsconfig.build.json && node -e \"require('fs').cpSync('src/libs/mcp/guides','dist/libs/mcp/guides',{recursive:true})\"",
 		"prepublishOnly": "npm run build",
 		"prepare": "node -e \"require('fs').existsSync('src')&&require('child_process').execSync('npm run build',{stdio:'inherit'})\"",
 		"start": "node dist/bin/server.js",
 		"dev": "nodemon --watch src --ext ts --exec 'npm run build && node dist/bin/server.js'",
-		"test": "npm run build && mocha --require test/env.js test/builtin_models.test.js test/bulkwrite_guard.test.js test/index_diagnostics.test.js test/parse_byte_size.test.js test/query_limits.test.js test/request_log.test.js test/test.js --timeout 1000 -b --exit",
+		"test": "npm run build && mocha --require test/env.js test/builtin_models.test.js test/bulkwrite_guard.test.js test/index_diagnostics.test.js test/mcp_guides.test.js test/mcp_visibility.test.js test/parse_byte_size.test.js test/query_limits.test.js test/request_log.test.js test/test.js --timeout 1000 -b --exit",
 		"setup": "node dist/bin/setup.js",
 		"indexes": "node dist/bin/index_audit.js"
 	},
@@ -63,7 +63,8 @@
 		"jxp": "dist/bin/setup.js",
 		"jxp-setup": "dist/bin/setup.js",
 		"jxp-add-admin": "dist/bin/init_db.js",
-		"jxp-indexes": "dist/bin/index_audit.js"
+		"jxp-indexes": "dist/bin/index_audit.js",
+		"jxp-mcp": "dist/bin/mcp-stdio-bridge.js"
 	},
 	"repository": {
 		"type": "git",
@@ -80,7 +81,11 @@
 		"url": "https://github.com/WorkSpaceMan/jxp/issues"
 	},
 	"dependencies": {
+		"@cfworker/json-schema": "^4.1.1",
 		"@json2csv/plainjs": "^7.0.6",
+		"@modelcontextprotocol/client": "^2.0.0-alpha.2",
+		"@modelcontextprotocol/node": "^2.0.0-alpha.2",
+		"@modelcontextprotocol/server": "^2.0.0-alpha.2",
 		"bcryptjs": "^3.0.2",
 		"bytes": "^3.1.2",
 		"commander": "^13.1.0",
@@ -104,7 +109,8 @@
 		"restify-errors": "^8.0.2",
 		"traverse": "^0.6.11",
 		"underscore": "^1.13.8",
-		"ws": "^8.18.1"
+		"ws": "^8.18.1",
+		"zod": "^4.4.3"
 	},
 	"devDependencies": {
 		"@types/bcryptjs": "^2.4.6",

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/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