@autobest-ui/agent 1.0.1 → 1.0.3

package/mcp/rag-mcp-bridge/index.js

@@ -4,46 +4,42 @@
  * RAG MCP bridge for the local PRD knowledge Express API.
  *
  * Responsibilities are deliberately limited to:
- * 1. Expanding file, file-array, and directory inputs into Markdown paths.
- * 2. Forwarding MCP tool calls to the local HTTP API.
+ * 1. Packaging local Markdown files and referenced images for remote ingestion.
+ * 2. Forwarding MCP tool calls to the configured HTTP API.
  *
- * Database access, Markdown parsing, embeddings, and RAG stay in Express.
+ * Requirement parsing, database access, embeddings, and RAG stay in Express.
  */
 
-import { readdir, stat } from "node:fs/promises";
-import path from "node:path";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { buildDocuments, expandMarkdownPaths, serializeRequestBody } from './documents.js';
 
 const DEFAULT_HTTP_TIMEOUT_MS = 120_000;
 
 function apiBaseUrlFromEnvironment() {
   const configuredUrl = process.env.RAG_API_BASE_URL?.trim();
   if (!configuredUrl) {
-    throw new Error(
-      "RAG_API_BASE_URL is required; configure it in the MCP server environment",
-    );
+    throw new Error('RAG_API_BASE_URL is required; configure it in the MCP server environment');
   }
 
   let url;
   try {
     url = new URL(configuredUrl);
   } catch {
-    throw new Error("RAG_API_BASE_URL must be a valid URL");
+    throw new Error('RAG_API_BASE_URL must be a valid URL');
   }
-  if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new Error("RAG_API_BASE_URL must use http or https");
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error('RAG_API_BASE_URL must use http or https');
   }
-  return url.toString().replace(/\/$/, "");
+  return url.toString().replace(/\/$/, '');
 }
 
 function httpTimeoutFromEnvironment() {
-  const configuredTimeout =
-    process.env.RAG_MCP_HTTP_TIMEOUT_MS ?? String(DEFAULT_HTTP_TIMEOUT_MS);
+  const configuredTimeout = process.env.RAG_MCP_HTTP_TIMEOUT_MS ?? String(DEFAULT_HTTP_TIMEOUT_MS);
   const timeout = Number(configuredTimeout);
   if (!Number.isSafeInteger(timeout) || timeout <= 0) {
-    throw new Error("RAG_MCP_HTTP_TIMEOUT_MS must be a positive integer");
+    throw new Error('RAG_MCP_HTTP_TIMEOUT_MS must be a positive integer');
   }
   return timeout;
 }
@@ -52,92 +48,27 @@ const API_BASE_URL = apiBaseUrlFromEnvironment();
 const HTTP_TIMEOUT_MS = httpTimeoutFromEnvironment();
 
 const pathsSchema = z
-  .union([
-    z.string().min(1),
-    z.array(z.string().min(1)).min(1),
-  ])
-  .describe("单个Markdown文件、Markdown文件数组或文件夹的绝对路径");
+  .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
+  .describe('单个Markdown文件、Markdown文件数组或文件夹的绝对路径');
 const platformSchema = z
-  .enum(["app", "california-web", "shared"])
-  .describe("知识所属平台；必须明确指定，防止APP与加州网站需求串库");
-const moduleSchema = z
-  .string()
-  .min(1)
-  .optional()
-  .describe("可选业务模块标识，例如vehicle-selector");
+  .enum(['app', 'california-web', 'shared'])
+  .describe('知识所属平台；必须明确指定，防止APP与加州网站需求串库');
+const moduleSchema = z.string().min(1).optional().describe('可选业务模块标识，例如vehicle-selector');
 const pageSchema = z
   .string()
   .min(1)
   .optional()
-  .describe(
-    "业务页面键，例如home、pl、pn、pd、name-search；录入多个文件时不要传，由后端按文件名分别推断",
-  );
-const docKeySchema = z
-  .string()
-  .min(1)
-  .optional()
-  .describe("需要限定到单一文档时传knowledge_doc.doc_key绝对路径");
-
-/** Recursively collects Markdown files from a directory in stable order. */
-async function scanMarkdownDirectory(directoryPath) {
-  const markdownFiles = [];
-  const entries = await readdir(directoryPath, { withFileTypes: true });
-  entries.sort((left, right) => left.name.localeCompare(right.name));
-
-  for (const entry of entries) {
-    const entryPath = path.join(directoryPath, entry.name);
-    if (entry.isDirectory()) {
-      markdownFiles.push(...(await scanMarkdownDirectory(entryPath)));
-    } else if (entry.isFile() && path.extname(entry.name).toLowerCase() === ".md") {
-      markdownFiles.push(path.resolve(entryPath));
-    }
-  }
-  return markdownFiles;
-}
-
-/** Normalizes all supported path inputs to a unique array of absolute .md files. */
-async function expandMarkdownPaths(pathsInput) {
-  const inputs = Array.isArray(pathsInput) ? pathsInput : [pathsInput];
-  const markdownFiles = [];
-
-  for (const input of inputs) {
-    if (typeof input !== "string" || !input.trim()) {
-      throw new Error("paths中的每一项都必须是非空字符串");
-    }
-    if (!path.isAbsolute(input.trim())) {
-      throw new Error(`必须使用绝对路径: ${input}`);
-    }
-
-    const absolutePath = path.resolve(input.trim());
-    const pathStat = await stat(absolutePath);
-    if (pathStat.isDirectory()) {
-      markdownFiles.push(...(await scanMarkdownDirectory(absolutePath)));
-    } else if (
-      pathStat.isFile() &&
-      path.extname(absolutePath).toLowerCase() === ".md"
-    ) {
-      markdownFiles.push(absolutePath);
-    } else {
-      throw new Error(`路径不是Markdown文件或文件夹: ${absolutePath}`);
-    }
-  }
-
-  const uniquePaths = [...new Set(markdownFiles)].sort((left, right) =>
-    left.localeCompare(right),
-  );
-  if (uniquePaths.length === 0) {
-    throw new Error("指定路径中没有找到任何.md文件");
-  }
-  return uniquePaths;
-}
+  .describe('业务页面键，例如home、pl、pn、pd、name-search；录入多个文件时不要传，由后端按文件名分别推断');
+const docKeySchema = z.string().min(1).optional().describe('需要限定到单一文档时传knowledge_doc.doc_key绝对路径');
 
 /** Posts JSON to Express and returns its parsed response body. */
 async function postJson(endpoint, body) {
+  const serializedBody = serializeRequestBody(body);
   const response = await fetch(`${API_BASE_URL}${endpoint}`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify(body),
-    signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: serializedBody,
+    signal: AbortSignal.timeout(HTTP_TIMEOUT_MS)
   });
   const responseText = await response.text();
   let responseBody;
@@ -148,10 +79,7 @@ async function postJson(endpoint, body) {
   }
 
   if (!response.ok) {
-    const details =
-      typeof responseBody === "string"
-        ? responseBody
-        : JSON.stringify(responseBody);
+    const details = typeof responseBody === 'string' ? responseBody : JSON.stringify(responseBody);
     throw new Error(`Express后端返回HTTP ${response.status}: ${details}`);
   }
   return responseBody;
@@ -161,12 +89,12 @@ async function postJson(endpoint, body) {
 async function getJson(endpoint, query) {
   const url = new URL(`${API_BASE_URL}${endpoint}`);
   for (const [name, value] of Object.entries(query)) {
-    if (value === undefined || value === null || value === "") continue;
+    if (value === undefined || value === null || value === '') continue;
     url.searchParams.set(name, value);
   }
   const response = await fetch(url, {
-    method: "GET",
-    signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+    method: 'GET',
+    signal: AbortSignal.timeout(HTTP_TIMEOUT_MS)
   });
   const responseText = await response.text();
   let responseBody;
@@ -176,10 +104,7 @@ async function getJson(endpoint, query) {
     responseBody = responseText;
   }
   if (!response.ok) {
-    const details =
-      typeof responseBody === "string"
-        ? responseBody
-        : JSON.stringify(responseBody);
+    const details = typeof responseBody === 'string' ? responseBody : JSON.stringify(responseBody);
     throw new Error(`Express后端返回HTTP ${response.status}: ${details}`);
   }
   return responseBody;
@@ -189,10 +114,10 @@ function toolSuccess(payload) {
   return {
     content: [
       {
-        type: "text",
-        text: JSON.stringify(payload, null, 2),
-      },
-    ],
+        type: 'text',
+        text: JSON.stringify(payload, null, 2)
+      }
+    ]
   };
 }
 
@@ -200,154 +125,138 @@ function toolError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return {
     isError: true,
-    content: [{ type: "text", text: message }],
+    content: [{ type: 'text', text: message }]
   };
 }
 
 const server = new McpServer(
-  { name: "rag-mcp-bridge", version: "1.0.0" },
+  { name: 'rag-mcp-bridge', version: '1.0.0' },
   {
     instructions:
-      "Use retrieve_knowledge before implementing requirement-sensitive code. " +
-      "Every tool call requires an explicit platform: app, california-web, or shared. " +
-      "add_prd_file and update_spec_file accept one file, an array of files, or a directory. " +
-      "Only call update_spec_file after the PR is merged and leader review confirms the spec is effective.",
-  },
+      'Use retrieve_knowledge before implementing requirement-sensitive code. ' +
+      'Every tool call requires an explicit platform: app, california-web, or shared. ' +
+      'add_prd_file and update_spec_file accept one file, an array of files, or a directory. ' +
+      'Only call update_spec_file after the PR is merged and leader review confirms the spec is effective.'
+  }
 );
 
 server.registerTool(
-  "add_prd_file",
+  'add_prd_file',
   {
-    title: "录入或更新PRD基线",
+    title: '录入或更新PRD基线',
     description:
-      "录入/更新PRD基线。paths支持单个md绝对路径、md绝对路径数组或文件夹绝对路径；文件夹会递归扫描全部.md文件。后端负责解析截图并将旧文档标记为作废。",
+      '录入/更新PRD基线。paths支持单个md绝对路径、md绝对路径数组或文件夹绝对路径；文件夹会递归扫描全部.md文件。后端负责解析截图并将旧文档标记为作废。',
     inputSchema: {
       paths: pathsSchema,
       platform: platformSchema,
       module: moduleSchema,
-      page: pageSchema,
+      page: pageSchema
     },
     annotations: {
       readOnlyHint: false,
       destructiveHint: false,
       idempotentHint: false,
-      openWorldHint: false,
-    },
+      openWorldHint: false
+    }
   },
   async ({ paths, platform, module, page }) => {
     try {
       const expandedPaths = await expandMarkdownPaths(paths);
+      const documents = await buildDocuments(expandedPaths);
       return toolSuccess(
-        await postJson("/add-prd", {
-          paths: expandedPaths,
+        await postJson('/add-prd', {
+          documents,
           platform,
           module,
-          page,
-        }),
+          page: documents.length === 1 ? page : undefined
+        })
       );
     } catch (error) {
       return toolError(error);
     }
-  },
+  }
 );
 
 server.registerTool(
-  "update_spec_file",
+  'update_spec_file',
   {
-    title: "录入迭代变更Spec",
+    title: '录入迭代变更Spec',
     description:
-      "仅在PR合并且leader review确认生效后调用。paths支持单个spec.md绝对路径、路径数组或文件夹；只需传改动spec。sprintVersion必须递增，数值越大需求越新。",
+      '仅在PR合并且leader review确认生效后调用。paths支持单个spec.md绝对路径、路径数组或文件夹；只需传改动spec。sprintVersion必须递增，数值越大需求越新。',
     inputSchema: {
       paths: pathsSchema,
       sprintVersion: z.number().int().positive(),
       iterationTag: z.string().min(1),
       platform: platformSchema,
       module: moduleSchema,
-      page: pageSchema,
+      page: pageSchema
     },
     annotations: {
       readOnlyHint: false,
       destructiveHint: false,
       idempotentHint: false,
-      openWorldHint: false,
-    },
+      openWorldHint: false
+    }
   },
   async ({ paths, sprintVersion, iterationTag, platform, module, page }) => {
     try {
       const expandedPaths = await expandMarkdownPaths(paths);
+      const documents = await buildDocuments(expandedPaths);
       return toolSuccess(
-        await postJson("/add-spec", {
-          paths: expandedPaths,
+        await postJson('/add-spec', {
+          documents,
           sprintVersion,
           iterationTag,
           platform,
           module,
-          page,
-        }),
+          page: documents.length === 1 ? page : undefined
+        })
       );
     } catch (error) {
       return toolError(error);
     }
-  },
+  }
 );
 
 server.registerTool(
-  "retrieve_knowledge",
+  'retrieve_knowledge',
   {
-    title: "检索PRD与迭代Spec",
+    title: '检索PRD与迭代Spec',
     description:
-      "Codex编写需求相关代码前调用。后端执行向量+BM25-RRF混合检索并按sprint_version业务排序。enableStruct=true时才生成结构化PRD；includeImages=true时才保留图片并替换为数据库图片URL，两者默认均为false。",
+      'Codex编写需求相关代码前调用。后端执行向量+BM25-RRF混合检索并按sprint_version业务排序。enableStruct=true时才生成结构化PRD；includeImages=true时才保留图片并替换为数据库图片URL，两者默认均为false。',
     inputSchema: {
       query: z.string().min(1),
       platform: platformSchema,
-      module: moduleSchema.describe(
-        "可选业务模块硬过滤，例如vehicle-selector",
-      ),
-      page: pageSchema.describe(
-        "可选页面硬过滤，例如首页传home；不传时后端会从明确的查询词自动推断",
-      ),
+      module: moduleSchema.describe('可选业务模块硬过滤，例如vehicle-selector'),
+      page: pageSchema.describe('可选页面硬过滤，例如首页传home；不传时后端会从明确的查询词自动推断'),
       docKey: docKeySchema,
-      enableStruct: z
-        .boolean()
-        .default(false)
-        .describe("是否调用LLM生成structuredPrd，默认false"),
-      includeImages: z
-        .boolean()
-        .default(false)
-        .describe("是否返回可供UI显示的数据库图片URL，默认false"),
+      enableStruct: z.boolean().default(false).describe('是否调用LLM生成structuredPrd，默认false'),
+      includeImages: z.boolean().default(false).describe('是否返回可供UI显示的数据库图片URL，默认false')
     },
     annotations: {
       readOnlyHint: true,
       destructiveHint: false,
       idempotentHint: true,
-      openWorldHint: false,
-    },
+      openWorldHint: false
+    }
   },
-  async ({
-    query,
-    platform,
-    module,
-    page,
-    docKey,
-    enableStruct = false,
-    includeImages = false,
-  }) => {
+  async ({ query, platform, module, page, docKey, enableStruct = false, includeImages = false }) => {
     try {
       return toolSuccess(
-        await getJson("/search", {
+        await getJson('/search', {
           query: query.trim(),
           platform,
           module,
           page,
           docKey,
           enableStruct: String(enableStruct === true),
-          includeImages: String(includeImages === true),
-        }),
+          includeImages: String(includeImages === true)
+        })
       );
     } catch (error) {
       return toolError(error);
     }
-  },
+  }
 );
 
 async function main() {
@@ -355,7 +264,7 @@ async function main() {
   await server.connect(transport);
 }
 
-main().catch((error) => {
-  console.error("Failed to start rag-mcp-bridge:", error);
+main().catch(error => {
+  console.error('Failed to start rag-mcp-bridge:', error);
   process.exitCode = 1;
 });