dsh-mcp-connector 0.1.0

package/lib/catalog.js

@@ -0,0 +1,88 @@
+/**
+ * 连接器目录：内置 + 远程 registry + config 注入 + 本地覆盖（上架/下架开关）。
+ * 合并键为 id，优先级：本地覆盖 > config.connectors > 远程 registry > 内置目录。
+ */
+import { readFileSync } from 'node:fs';
+import { normalizeConnectorDescriptor } from './schema.js';
+import { assertSafeUrl, assertSafeHeaderName } from './util.js';
+
+/** 读取包内内置目录 */
+export function loadBundledCatalog() {
+  try {
+    const raw = readFileSync(new URL('../catalog/catalog.json', import.meta.url), 'utf8');
+    const data = JSON.parse(raw);
+    const list = Array.isArray(data) ? data : Array.isArray(data?.connectors) ? data.connectors : [];
+    return list.map(normalizeConnectorDescriptor);
+  } catch {
+    return [];
+  }
+}
+
+/** 安全审计：目录禁止携带密钥、URL 协议白名单、header 名白名单。 */
+export function auditDescriptor(descriptor) {
+  for (const server of descriptor.servers) {
+    assertSafeUrl(server.url);
+    for (const name of Object.keys(server.headers ?? {})) {
+      assertSafeHeaderName(name);
+      if (/authorization|token|secret|api[-_]?key/i.test(name)) {
+        throw new Error(`connector "${descriptor.id}" servers[].headers 禁止携带密钥类头: ${name}`);
+      }
+    }
+  }
+  return descriptor;
+}
+
+/** 拉取远程 registry（HTTPS + TTL 缓存 + 可选 ETag） */
+export async function fetchRemoteCatalog(catalogUrl, { requestTimeoutMs, etag } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new Error('timeout')), requestTimeoutMs ?? 15_000);
+  try {
+    const headers = {};
+    if (etag) headers['If-None-Match'] = etag;
+    const response = await fetch(catalogUrl, { headers, signal: controller.signal });
+    if (response.status === 304) return { notModified: true };
+    if (!response.ok) throw new Error(`catalog fetch HTTP ${response.status}`);
+    const data = await response.json();
+    const list = Array.isArray(data) ? data : Array.isArray(data?.connectors) ? data.connectors : [];
+    const connectors = list.map((raw) => auditDescriptor(normalizeConnectorDescriptor(raw)));
+    return { notModified: false, etag: response.headers.get('etag') ?? undefined, connectors };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** 合并多层来源（sources 为低→高优先级的 descriptor 数组），再应用本地覆盖。 */
+export function mergeCatalog(sources, overrides = new Map()) {
+  const merged = new Map();
+  for (const list of sources) {
+    for (const descriptor of list) {
+      merged.set(descriptor.id, descriptor);
+    }
+  }
+  for (const [id, patch] of overrides) {
+    const current = merged.get(id);
+    if (!current) continue;
+    const next = { ...current };
+    if (typeof patch.published === 'boolean') next.published = patch.published;
+    if (typeof patch.featured === 'boolean') next.featured = patch.featured;
+    merged.set(id, next);
+  }
+  return [...merged.values()];
+}
+
+/** 目录查询（publishedOnly 默认只显示已上架） */
+export function listCatalog(merged, { category, keyword, publishedOnly = true } = {}) {
+  let list = merged;
+  if (publishedOnly) list = list.filter((d) => d.published !== false);
+  if (category) list = list.filter((d) => d.category === category);
+  if (keyword) {
+    const kw = String(keyword).toLowerCase();
+    list = list.filter((d) =>
+      [d.id, d.name, d.vendor, d.category, d.summary, d.description, ...(d.tags ?? [])]
+        .filter(Boolean)
+        .some((v) => String(v).toLowerCase().includes(kw)),
+    );
+  }
+  // 精选位优先，其余按 id 排序保持稳定
+  return [...list].sort((a, b) => (b.featured === true) - (a.featured === true) || a.id.localeCompare(b.id));
+}

package/lib/client.js

@@ -0,0 +1,366 @@
+window.__ModuleLoader__.load({
+	id: "dsh-mcp-connector",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react_jsx_runtime = require("react/jsx-runtime");
+		let react = require("react");
+		let react_dom = require("react-dom");
+		let _deepseek_ai_dsh_client_runtime_client = require("@deepseek-ai/dsh-client-runtime/client");
+		let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
+
+		/** 客户端所需服务：槽位、工作区、会话及对话输入机。 */
+		const inject = [
+			"slots",
+			"sessions",
+			"workspaces",
+			"conversation"
+		];
+		const PROMPT_REQUEST_TYPE = "mcp-connector:start-session";
+		const PROMPT_RESULT_TYPE = "mcp-connector:start-session-result";
+
+		/**
+		 * Desktop 内置的社区插件市场也注册在 sidebar.footer.action。
+		 * 该 list slot 的宿主容器默认横排，会把两个本应占满侧边栏宽度的
+		 * launcher 挤在同一行。覆盖 SlotOutlet 的 display: contents，让所有
+		 * footer action 在 Web 与 Desktop 中都按独立行纵向排列。
+		 */
+		const SIDEBAR_STYLE_ID = "dsh-mcp-connector-sidebar";
+		const sidebarCss = `
+[data-slot="sidebar.footer.action"] {
+	display: flex !important;
+	flex-direction: column;
+	min-width: 0;
+	width: 100%;
+}
+
+.mcpConnectorLauncher {
+	flex: none;
+	box-sizing: border-box;
+	width: calc(100% + 4px);
+	height: 42px;
+	margin: 4px -2px;
+	padding: 0 10px 0 8px;
+	justify-content: flex-start;
+	overflow: hidden;
+	border-radius: 12px;
+	white-space: nowrap;
+}
+
+.mcpConnectorLauncher[data-wide="false"] {
+	width: 36px;
+	height: 36px;
+	margin: 8px 0 10px;
+	padding: 0;
+	justify-content: center;
+	border-radius: 50%;
+}
+
+.mcpConnectorTopMount {
+	flex: none;
+	min-width: 0;
+	width: 100%;
+}
+
+.mcpConnectorTopEntry {
+	box-sizing: border-box;
+	width: 100%;
+	padding-right: var(--dsh-sidebar-inline-padding, 12px);
+}
+
+.mcpConnectorTopEntry .mcpConnectorLauncher {
+	width: 100%;
+	margin: 0 0 8px;
+}
+
+.mcpConnectorTopEntry[data-wide="false"] {
+	width: 36px;
+	padding-right: 0;
+}
+
+.mcpConnectorTopEntry[data-wide="false"] .mcpConnectorLauncher {
+	margin: 0 0 8px;
+}
+`;
+		const SIDEBAR_WORKSPACES_SELECTOR = '[data-slot="sidebar.workspaces"]';
+		const TOP_MOUNT_SELECTOR = '[data-mcp-connector-top-mount="true"]';
+
+		function installSidebarStyles() {
+			if (document.querySelector(`style[data-plugin="${SIDEBAR_STYLE_ID}"]`) !== null) return () => {};
+			const style = document.createElement("style");
+			style.dataset.plugin = SIDEBAR_STYLE_ID;
+			style.textContent = sidebarCss;
+			document.head.append(style);
+			return () => { style.remove(); };
+		}
+
+		/**
+		 * DSH rc.7 没有公开的「新会话与工作区之间」插槽。插件仍注册在公开的
+		 * footer list slot 中保证生命周期与降级可用，再把实际按钮 Portal 到
+		 * sidebar.workspaces 前。只依赖稳定的 data-slot，不依赖构建生成的 CSS 类名。
+		 */
+		function ensureTopLauncherMount() {
+			const workspaceSlot = document.querySelector(SIDEBAR_WORKSPACES_SELECTOR);
+			const parent = workspaceSlot?.parentElement;
+			if (workspaceSlot === null || parent === null || parent === void 0) return null;
+			let mount = parent.querySelector(TOP_MOUNT_SELECTOR);
+			if (mount === null) {
+				mount = document.createElement("div");
+				mount.dataset.mcpConnectorTopMount = "true";
+				mount.className = "mcpConnectorTopMount";
+			}
+			if (mount.nextSibling !== workspaceSlot) parent.insertBefore(mount, workspaceSlot);
+			return mount;
+		}
+
+		/** 创建弹框 store（使用 DSH defineStore，与社区插件市场一致）。 */
+		function createMarketViewStore() {
+			return (0, _deepseek_ai_dsh_client_runtime_client.defineStore)({
+				init: () => ({ open: false, detailOpen: false }),
+				actions: {
+					open: (draft) => { draft.open = true; },
+					close: (draft) => { draft.open = false; draft.detailOpen = false; },
+					detailOpened: (draft) => { draft.detailOpen = true; },
+					detailClosed: (draft) => { draft.detailOpen = false; }
+				}
+			});
+		}
+
+		/**
+		 * 用 DSH 自身的工作区/会话/输入机把示例 Prompt 带入新会话。
+		 * connectWorkspace 与 DSH 的「新会话」按钮同源：优先复用当前工作区的
+		 * 空白会话，没有时创建一个；返回时 binding 已就绪，可在导航前写入草稿。
+		 */
+		async function startPromptSession(ctx, promptText) {
+			if (typeof promptText !== "string" || promptText.trim() === "") {
+				throw new Error("Prompt 不能为空");
+			}
+			const workspace = ctx.workspaces.list.getSnapshot();
+			const current = ctx.sessions.list.getSnapshot().current;
+			const currentWorkspaceId = current === void 0
+				? void 0
+				: workspace.items.find((item) => item.sessionIds.includes(current))?.workspaceId;
+			const targetWorkspaceId = currentWorkspaceId ?? workspace.recentWorkspaceId;
+			if (targetWorkspaceId === void 0) {
+				throw new Error("请先选择一个工作空间，再使用示例 Prompt");
+			}
+			const sessionId = await ctx.workspaces.connectWorkspace(targetWorkspaceId);
+			const conversation = ctx.get("conversation");
+			if (conversation === void 0) {
+				throw new Error("DSH 对话服务尚未就绪，请稍后重试");
+			}
+			conversation.input.shell(sessionId).setDraft(promptText);
+			ctx.sessions.open(sessionId);
+			return sessionId;
+		}
+
+		/** 弹框组件：居中显示市场 SPA（浅色主题）。 */
+		function MarketOverlay(props) {
+			const { wide, useStore, actions, startPromptSession: launchPromptSession } = props;
+			const open = useStore((state) => state.open);
+			const detailOpen = useStore((state) => state.detailOpen);
+			const frameRef = (0, react.useRef)(null);
+			(0, react.useEffect)(() => {
+				const onMessage = (event) => {
+					if (event.origin !== window.location.origin) return;
+					if (event.source !== frameRef.current?.contentWindow) return;
+					if (event.data?.type === "mcp-connector:detail-state") {
+						if (event.data.open === true) actions.detailOpened();
+						else actions.detailClosed();
+						return;
+					}
+					if (event.data?.type !== PROMPT_REQUEST_TYPE) return;
+					const requestId = typeof event.data.requestId === "string" ? event.data.requestId : "";
+					const prompt = event.data.prompt;
+					const reply = (ok, message) => {
+						frameRef.current?.contentWindow?.postMessage({
+							type: PROMPT_RESULT_TYPE,
+							requestId,
+							ok,
+							message
+						}, window.location.origin);
+					};
+					if (requestId === "" || typeof prompt !== "string") {
+						reply(false, "无效的 Prompt 请求");
+						return;
+					}
+					Promise.resolve(launchPromptSession(prompt)).then(() => {
+						reply(true, "已带入新会话");
+						window.requestAnimationFrame(() => { actions.close(); });
+					}, (error) => {
+						const message = error instanceof Error ? error.message : String(error);
+						console.error("[mcp-connector] start prompt session failed:", error);
+						reply(false, message);
+					});
+				};
+				window.addEventListener("message", onMessage);
+				return () => { window.removeEventListener("message", onMessage); };
+			}, [actions, launchPromptSession]);
+			if (!open) return null;
+			const src = window.location.origin + "/mcp-connector/ui/";
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				style: {
+					position: "fixed",
+					inset: 0,
+					background: "rgba(0,0,0,0.4)",
+					display: "flex",
+					alignItems: "center",
+					justifyContent: "center",
+					zIndex: 1000
+				},
+				onClick: (event) => { if (event.target === event.currentTarget) actions.close(); },
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						style: {
+							background: "#ffffff",
+							borderRadius: 16,
+							width: "min(800px, 90%)",
+							height: "min(800px, 85%)",
+							display: "flex",
+							flexDirection: "column",
+							boxShadow: "0 20px 60px rgba(0,0,0,0.15)",
+							overflow: "hidden"
+						},
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								style: {
+									display: "flex",
+									alignItems: "center",
+									justifyContent: "space-between",
+									padding: "20px 24px",
+									borderBottom: "1px solid #e5e7eb",
+									flexShrink: 0,
+									filter: detailOpen ? "brightness(0.5)" : "none",
+									pointerEvents: detailOpen ? "none" : "auto",
+									transition: "filter 0.2s ease"
+								},
+								children: [
+									/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+										style: { display: "flex", alignItems: "center", gap: 10 },
+										children: [
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { style: { fontSize: 22 }, children: "\u{1F9E9}" }),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { style: { fontSize: 18, fontWeight: 600, color: "#111827" }, children: "MCP连接器" })
+										]
+									}),
+									/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+										type: "button",
+										onClick: () => actions.close(),
+										style: {
+											background: "transparent",
+											border: "none",
+											color: "#6b7280",
+											fontSize: 22,
+											cursor: "pointer",
+											padding: "4px 8px",
+											borderRadius: 6,
+											lineHeight: 1
+										},
+										onMouseEnter: (e) => { e.currentTarget.style.background = "#f3f4f6"; },
+										onMouseLeave: (e) => { e.currentTarget.style.background = "transparent"; },
+										children: "\u00D7"
+									})
+								]
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("iframe", {
+								ref: frameRef,
+								src,
+								title: "MCP连接器",
+								style: {
+									flex: 1,
+									width: "100%",
+									border: "none",
+									background: "#ffffff"
+								}
+							})
+						]
+					})
+				]
+			});
+		}
+
+		/** 左栏入口按钮：使用 DSH Button 组件，与社区插件市场一致。 */
+		function SidebarEntry(props) {
+			const { wide, useStore, actions } = props;
+			const open = useStore((state) => state.open);
+			const [topMount, setTopMount] = (0, react.useState)(null);
+			(0, react.useEffect)(() => {
+				let disposed = false;
+				const ownedMounts = new Set();
+				const syncMount = () => {
+					if (disposed) return;
+					const mount = ensureTopLauncherMount();
+					if (mount !== null) ownedMounts.add(mount);
+					setTopMount((current) => current === mount ? current : mount);
+				};
+				syncMount();
+				let observer = null;
+				if (typeof window.MutationObserver === "function" && document.body !== null) {
+					observer = new window.MutationObserver(syncMount);
+					observer.observe(document.body, { childList: true, subtree: true });
+				}
+				return () => {
+					disposed = true;
+					observer?.disconnect();
+					for (const mount of ownedMounts) mount.remove();
+				};
+			}, []);
+			const launcher = /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
+				variant: "ghost",
+				className: "mcpConnectorLauncher",
+				"data-wide": wide,
+				"aria-label": "MCP连接器",
+				"aria-haspopup": "dialog",
+				"aria-expanded": open,
+				onClick: () => { try { actions.open(); } catch (error) { console.error('[mcp-connector] open failed:', error); } },
+				children: wide ? "🧩 MCP连接器" : "🧩"
+			});
+			if (topMount === null || typeof react_dom.createPortal !== "function") return launcher;
+			return react_dom.createPortal(/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+				className: "mcpConnectorTopEntry",
+				"data-wide": wide,
+				children: launcher
+			}), topMount);
+		}
+
+		function apply(ctx) {
+			console.log('[mcp-connector] client apply() called');
+			try {
+				const marketView = createMarketViewStore();
+				ctx.effect(() => installSidebarStyles(), "mcp-connector: sidebar styles");
+
+				// 弹框：注册到 shell.overlay（类似社区插件市场）
+				ctx.slots.inject("shell.overlay", () => {
+					console.log('[mcp-connector] registering shell.overlay slot');
+					return ctx.slots.register({
+						name: "shell.overlay",
+						id: "mcp-connector",
+						order: 100,
+						store: marketView,
+						inject: () => ({
+							startPromptSession: (promptText) => startPromptSession(ctx, promptText)
+						})
+					}, MarketOverlay);
+				});
+
+				// 左栏：公开 footer slot 托管生命周期；组件会 Portal 到工作区列表上方。
+				ctx.slots.inject("sidebar.footer.action", () => {
+					console.log('[mcp-connector] registering sidebar.footer.action slot');
+					return ctx.slots.register({
+						name: "sidebar.footer.action",
+						id: "mcp-connector",
+						order: 0,
+						store: marketView
+					}, SidebarEntry);
+				});
+				console.log('[mcp-connector] client apply() completed');
+			} catch (error) {
+				console.error('[mcp-connector] client apply() failed:', error);
+			}
+		}
+
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});

package/lib/connectors/json-connector.js

@@ -0,0 +1,137 @@
+/**
+ * 通道三：粘贴 JSON 配置（兼容 { mcpServers: {...} } 与 { connections: [...] }）。
+ * 批量预校验，任一非法整体拒绝；stdio 类（command/args）显式跳过并提示。
+ */
+import { JSON_CONNECTOR_ID } from '../constants.js';
+import { assertSafeUrl, assertSafeHeaderName, slugServerName } from '../util.js';
+
+function parseInput(input) {
+  if (typeof input === 'string') {
+    try {
+      return JSON.parse(input);
+    } catch (error) {
+      throw new Error(`JSON 解析失败: ${error.message}`);
+    }
+  }
+  return input;
+}
+
+function coerceHeaders(headers) {
+  const out = {};
+  for (const [key, value] of Object.entries(headers ?? {})) out[assertSafeHeaderName(key)] = String(value);
+  return out;
+}
+
+/** 静态 headers 中的 Authorization: Bearer ... 提升为 auth.bearer，其余保留为静态头 */
+function extractAuth(headers) {
+  const h = coerceHeaders(headers);
+  const authKey = Object.keys(h).find((k) => k.toLowerCase() === 'authorization');
+  if (authKey && /^Bearer\s+(.+)$/i.test(h[authKey])) {
+    const token = h[authKey].replace(/^Bearer\s+/i, '');
+    delete h[authKey];
+    return { auth: { mode: 'bearer', bearerToken: token }, headers: h };
+  }
+  return { auth: undefined, headers: h };
+}
+
+function authFromFields(item) {
+  const authMode = item.authMode ?? 'none';
+  if (authMode === 'bearer') {
+    return { mode: 'bearer', bearerToken: String(item.bearerToken ?? '') };
+  }
+  if (authMode === 'api-key') {
+    return {
+      mode: 'api-key',
+      apiKeyHeader: assertSafeHeaderName(item.apiKeyHeader ?? 'X-Api-Key'),
+      apiKeyValue: String(item.apiKeyValue ?? ''),
+    };
+  }
+  if (authMode === 'none') return undefined;
+  throw new Error(`unsupported authMode: ${authMode}`);
+}
+
+/**
+ * @param {string|object} input
+ * @returns {{ records: object[], skipped: string[] }}
+ */
+export function normalizeJsonImport(input) {
+  const obj = parseInput(input);
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) throw new Error('JSON 顶层必须是对象');
+
+  const records = [];
+  const skipped = [];
+
+  if (obj.mcpServers && typeof obj.mcpServers === 'object') {
+    for (const [name, cfg] of Object.entries(obj.mcpServers)) {
+      if (!cfg || typeof cfg !== 'object') {
+        skipped.push(`${name}(非法条目)`);
+        continue;
+      }
+      if (cfg.command || cfg.args) {
+        skipped.push(`${name}(stdio 暂不支持)`);
+        continue;
+      }
+      if (!cfg.url) {
+        skipped.push(`${name}(缺 url)`);
+        continue;
+      }
+      const transport = cfg.transport ?? cfg.type ?? 'streamable-http';
+      const { auth, headers } = extractAuth(cfg.headers ?? cfg.httpHeaders);
+      records.push({
+        key: `json-${slugServerName(cfg.serverName ?? name)}`,
+        connectorId: JSON_CONNECTOR_ID,
+        kind: 'json',
+        name: cfg.name ?? name,
+        transport: transport === 'sse' ? 'sse' : 'streamable-http',
+        url: assertSafeUrl(cfg.url).toString(),
+        serverName: slugServerName(cfg.serverName ?? name),
+        headers,
+        auth,
+        enabled: true,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      });
+    }
+  } else if (Array.isArray(obj.connections)) {
+    for (const item of obj.connections) {
+      if (!item || typeof item !== 'object') {
+        skipped.push('(非法条目)');
+        continue;
+      }
+      if (item.command || item.args) {
+        skipped.push(`${item.name ?? '(未命名)'}(stdio 暂不支持)`);
+        continue;
+      }
+      if (!item.url) {
+        skipped.push(`${item.name ?? '(未命名)'}(缺 url)`);
+        continue;
+      }
+      const name = String(item.name ?? item.serverName ?? '');
+      if (!name) {
+        skipped.push('(缺 name/serverName)');
+        continue;
+      }
+      records.push({
+        key: `json-${slugServerName(item.serverName ?? name)}`,
+        connectorId: JSON_CONNECTOR_ID,
+        kind: 'json',
+        name,
+        transport: item.transport === 'sse' ? 'sse' : 'streamable-http',
+        url: assertSafeUrl(item.url).toString(),
+        serverName: slugServerName(item.serverName ?? name),
+        headers: coerceHeaders(item.headers),
+        auth: authFromFields(item),
+        enabled: true,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      });
+    }
+  } else {
+    throw new Error('不支持的 JSON 格式：期望 { mcpServers: {...} } 或 { connections: [...] }');
+  }
+
+  if (records.length === 0) {
+    throw new Error(`没有可导入的连接${skipped.length ? `（跳过：${skipped.join('、')}）` : ''}`);
+  }
+  return { records, skipped };
+}

package/lib/connectors/manual-connector.js

@@ -0,0 +1,63 @@
+/**
+ * 通道二：自定义配置连接（表单式填 transport/url/serverName/鉴权）。
+ */
+import { CUSTOM_CONNECTOR_ID } from '../constants.js';
+import { assertSafeUrl, assertSafeHeaderName, slugServerName } from '../util.js';
+
+function parseHeadersJson(headersJson) {
+  if (headersJson === undefined || headersJson === null || headersJson === '') return {};
+  let obj;
+  if (typeof headersJson === 'string') {
+    try {
+      obj = JSON.parse(headersJson);
+    } catch {
+      throw new Error('headersJson 不是合法 JSON');
+    }
+  } else {
+    obj = headersJson;
+  }
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) throw new Error('headersJson 必须是 JSON 对象');
+  const out = {};
+  for (const [key, value] of Object.entries(obj)) out[assertSafeHeaderName(key)] = String(value);
+  return out;
+}
+
+/**
+ * @param {object} params { name, url, transport?, serverName?, authMode?, bearerToken?, apiKeyHeader?, apiKeyValue?, headersJson? }
+ */
+export function buildManualRecord(params = {}) {
+  const name = String(params.name ?? '').trim();
+  if (!name) throw new Error('name 必填');
+  const url = assertSafeUrl(params.url).toString();
+  const serverName = slugServerName(params.serverName ?? name);
+  const transport = params.transport === 'sse' ? 'sse' : 'streamable-http';
+  const headers = parseHeadersJson(params.headersJson);
+
+  const authMode = params.authMode ?? 'none';
+  let auth;
+  if (authMode === 'bearer') {
+    if (!params.bearerToken) throw new Error('authMode=bearer 时 bearerToken 必填');
+    auth = { mode: 'bearer', bearerToken: String(params.bearerToken) };
+  } else if (authMode === 'api-key') {
+    const apiKeyHeader = assertSafeHeaderName(params.apiKeyHeader ?? 'X-Api-Key');
+    if (params.apiKeyValue === undefined || params.apiKeyValue === '') throw new Error('authMode=api-key 时 apiKeyValue 必填');
+    auth = { mode: 'api-key', apiKeyHeader, apiKeyValue: String(params.apiKeyValue) };
+  } else if (authMode !== 'none') {
+    throw new Error(`unsupported authMode: ${authMode}`);
+  }
+
+  return {
+    key: `custom-${serverName}`,
+    connectorId: CUSTOM_CONNECTOR_ID,
+    kind: 'manual',
+    name,
+    transport,
+    url,
+    serverName,
+    headers,
+    auth,
+    enabled: true,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  };
+}