@lorrylurui/code-intelligence-mcp 2.0.4 → 2.0.6

package/dist/tools/queryDocs.js

@@ -0,0 +1,113 @@
+/**
+ * query_docs MCP 工具：完整的 RAG 检索 + 上下文组装入口。
+ *
+ * 调用链：
+ *   query
+ *     → ChunkRepository.searchSemantic()   向量检索 topK chunk
+ *     → ContextAssembler.assemble()         邻块扩展 → 去重 → 字符预算截断 → 文本渲染
+ *     → 返回 contextText + sources          供 LLM 合成最终回答
+ *
+ * 为什么工具只返回 contextText 而不直接生成回答？
+ *   本 MCP server 没有内置 LLM，"合成回答"由调用方（Claude/GPT 等）完成。
+ *   工具负责"检索 + 组装"，调用方负责"理解 + 生成"，职责清晰、可独立测试。
+ */
+import { z } from 'zod';
+import { ChunkRepository } from '../repositories/chunkRepository.js';
+import { ContextAssembler } from '../services/contextAssembler.js';
+import { CHUNK_TOP_K, CONTEXT_ADJACENT_RADIUS, CONTEXT_MAX_CHARS, CONTEXT_MAX_CHUNKS, } from '../config/tuning.js';
+export const queryDocsInput = z.object({
+    /** 自然语言查询，将被向量化后用于语义检索 */
+    query: z.string().min(1),
+    /** 语义检索拉取的候选 chunk 数，最终受字符预算限制 */
+    limit: z.number().int().min(1).max(50).optional().default(CHUNK_TOP_K),
+    /**
+     * 每个命中 chunk 向前后各扩展的邻块数。
+     * 0 = 不扩展（纯向量检索结果）；1 = 各取一块（推荐）；2 = 各取两块（长文档）
+     */
+    adjacentRadius: z
+        .number()
+        .int()
+        .min(0)
+        .max(3)
+        .optional()
+        .default(CONTEXT_ADJACENT_RADIUS),
+    /** 上下文总字符数预算，超出时截断末尾 chunk */
+    maxChars: z.number().int().min(500).optional().default(CONTEXT_MAX_CHARS),
+    /** 扩展后保留的最大 chunk 数量 */
+    maxChunks: z
+        .number()
+        .int()
+        .min(1)
+        .max(30)
+        .optional()
+        .default(CONTEXT_MAX_CHUNKS),
+    /** 仅检索指定文档路径下的 chunk（精确路径过滤） */
+    path: z.string().optional(),
+});
+export function createQueryDocsTool() {
+    const repo = new ChunkRepository();
+    const assembler = new ContextAssembler(repo);
+    return {
+        name: 'query_docs',
+        description: '对文档知识库进行语义检索，返回与查询最相关的文档片段（已组装为可直接注入 prompt 的上下文文本）。\n' +
+            '使用场景：\n' +
+            '- 查找 QA 文档、架构说明、设计决策等非代码知识\n' +
+            '- 需要引用具体文档原文回答时\n' +
+            '- 回答后请基于返回的 contextText 中的原文进行陈述，不要凭空补充\n' +
+            '注意：本工具检索文档 chunk，代码符号请使用 search_symbols / recommend_component。',
+        inputSchema: queryDocsInput.shape,
+        handler: async (input) => {
+            // ── 阶段1：语义检索 ─────────────────────────────────────────────
+            const hits = await repo.searchSemantic(input.query, {
+                limit: input.limit,
+                path: input.path,
+            });
+            if (hits.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                contextText: '',
+                                sources: [],
+                                hitCount: 0,
+                                totalChunks: 0,
+                                truncated: false,
+                                message: '未找到相关文档片段，请尝试调整查询或确认文档已建立索引。',
+                            }),
+                        },
+                    ],
+                };
+            }
+            // ── 阶段2：邻块扩展 + 去重 + 预算截断 + 文本渲染 ───────────────
+            const assembled = await assembler.assemble(hits, {
+                maxChars: input.maxChars,
+                adjacentRadius: input.adjacentRadius,
+                maxChunks: input.maxChunks,
+            });
+            // sources 供调用方引用来源，避免 LLM 伪造引用。
+            const sources = assembled.chunks.map((chunk) => ({
+                path: chunk.path,
+                title: chunk.title,
+                chunkIndex: chunk.chunkIndex,
+                chunkCount: chunk.chunkCount,
+                similarity: chunk.similarity ?? null,
+                summary: chunk.summary ?? null,
+            }));
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            contextText: assembled.contextText,
+                            sources,
+                            hitCount: assembled.hitCount,
+                            totalChunks: assembled.totalChunks,
+                            truncated: assembled.truncated,
+                        }),
+                    },
+                ],
+            };
+        },
+    };
+}

package/dist/tools/recommendComponent.js

@@ -1,4 +1,66 @@
 import { z } from 'zod';
+function formatCallers(callers) {
+    if (!callers.length)
+        return '新增';
+    return callers.map((caller) => `${caller.name}(${caller.path})`).join('; ');
+}
+function formatSideEffects(sideEffects) {
+    return sideEffects.length ? sideEffects.join('/') : '无';
+}
+function formatHasResult(result) {
+    const recommended = result.recommended;
+    if (!recommended)
+        return '';
+    const reasons = [];
+    if (recommended.matchedProps.length) {
+        reasons.push(`匹配到必需 props：${recommended.matchedProps.join(', ')}`);
+    }
+    if (recommended.matchedHooks.length) {
+        reasons.push(`匹配到必需 hooks：${recommended.matchedHooks.join(', ')}`);
+    }
+    if (reasons.length < 2) {
+        reasons.push('综合语义、结构字段和可复用性排序后为首选。');
+    }
+    const alternatives = result.alternatives.length
+        ? result.alternatives
+            .map((item) => `${item.name}（${formatSideEffects(item.sideEffects)}）`)
+            .join('; ')
+        : '无';
+    return `首选：${recommended.name} — ${recommended.path}
+symbolId：${recommended.id}
+使用范围：${formatCallers(recommended.callers)}
+副作用：${formatSideEffects(recommended.sideEffects)}
+理由：
+1. ${reasons[0] ?? '匹配度最高，适合直接复用。'}
+2. ${reasons[1] ?? 'API 形态与需求一致，接入成本低。'}
+其他候选：${alternatives}
+用法提示：
+\`\`\`tsx
+<${recommended.name} value={value} onChange={handleChange} />
+\`\`\`
+是否采纳（**请在聊天框输入 1 或 2**）：
+1️⃣ 采纳推荐 — 自动调用 inc_usage 记录使用
+2️⃣ 取消`;
+}
+function formatNoResult() {
+    return `首选：未找到已有实现
+使用范围：无
+副作用：无
+理由：
+1. 当前索引中没有满足条件的组件（例如必须包含 onChange）
+2. 已尝试可用检索方式，仍无可用候选
+其他候选：无
+用法提示：
+\`\`\`tsx
+// 可先创建一个受控 Input 组件，至少暴露 value + onChange
+\`\`\`
+是否采纳（**请在聊天框输入 1 或 2**）：
+1️⃣ 新建最小可复用组件
+2️⃣ 取消`;
+}
+function formatReply(result) {
+    return result.recommended ? formatHasResult(result) : formatNoResult();
+}
 export const recommendComponentInput = z.object({
     query: z.string().min(1),
     requiredProps: z.array(z.string().min(1)).optional(),
@@ -10,18 +72,32 @@ export const recommendComponentInput = z.object({
 export function createRecommendComponentTool(recommendationService) {
     return {
         name: 'recommend_component',
-        description: '高层推荐工具：当用户想找可复用 UI 组件时优先调用本工具。输入用户需求、必需 props/hooks 后，工具会自动完成候选搜索、结构过滤和首选推荐。',
+        description: '【降级链第一步，唯一首选工具】当用户询问有没有可复用的组件/函数/util，或需要找仓库中现有实现时，必须先调用本工具。\n' +
+            '本工具会自动完成候选搜索、结构过滤和首选推荐，无需再调其他搜索工具。\n' +
+            '⚠️ 输出约束（必须严格遵守）：\n' +
+            '- recommended != null：立即将工具返回的文本原样输出给用户，完全停止，不得调用任何其他工具，不得改写为散文或追加说明。\n' +
+            '- recommended = null：进入降级链第二步，调用 search_symbols（semantic=true）。\n' +
+            '- 任何情况下禁止调用 grep/read file/file search 作为本工具的后续动作。',
         inputSchema: recommendComponentInput.shape,
         handler: async (input) => {
-            const result = await recommendationService.recommendComponent(input);
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify(result, null, 2),
-                    },
-                ],
-            };
+            console.error('[code-intelligence-mcp] tool.recommend_component.called query=%s requiredProps=%s requiredHooks=%s category=%s semantic=%s limit=%s', input.query, JSON.stringify(input.requiredProps ?? []), JSON.stringify(input.requiredHooks ?? []), input.category ?? '', String(input.semantic ?? true), String(input.limit ?? 5));
+            try {
+                const result = await recommendationService.recommendComponent(input);
+                console.error('[code-intelligence-mcp] tool.recommend_component.done recommended=%s alternatives=%s queriedBy=%s', result.recommended ? 'yes' : 'no', String(result.alternatives.length), result.queriedBy);
+                const formattedReply = formatReply(result);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: formattedReply,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                console.error('[code-intelligence-mcp] tool.recommend_component.error', error);
+                throw error;
+            }
         },
     };
 }

package/dist/tools/searchByStructure.js

@@ -15,7 +15,8 @@ export function createSearchByStructureTool(repository) {
         name: 'search_by_structure',
         description: '按代码块的结构字段（props/params/hooks）检索，适合已知接口形态时使用。\n' +
             '示例：需要一个接受 value、onChange、error 三个 prop 的输入组件 → fields: ["value", "onChange", "error"], type: "component"\n' +
-            '与 search_symbols 配合：先语义检索候选，再用本工具做 API 结构过滤以精确匹配。',
+            '与 search_symbols 配合：先语义检索候选，再用本工具做 API 结构过滤以精确匹配。\n' +
+            '约束：当用户是在问“有没有可复用组件/帮我找组件”时，默认不要调用本工具；仅在用户明确要求二次验证时使用。',
         inputSchema: searchByStructureInput.shape,
         handler: async (input) => {
             const rows = await repository.searchByStructure(input.fields, {

package/dist/tools/searchSymbols.js

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import { rankSemanticHits, rankSymbols } from '../services/ranking.js';
+import { isReusableCandidate } from '../services/recommendationService.js';
+import { SEARCH_SCORE_THRESHOLD, SEARCH_TOP_K } from '../config/tuning.js';
 export const searchSymbolsInput = z.object({
     query: z.string().min(1),
     type: z
@@ -10,16 +12,35 @@ export const searchSymbolsInput = z.object({
     semantic: z.boolean().optional().default(false),
     limit: z.number().int().min(1).max(100).optional().default(20),
 });
-const SCORE_THRESHOLD_FOR_FINAL = 0.45; // 综合排序分阈值（语义相似度占50%权重，原始0.5相似度 ≈ 综合0.35起）
-const TOP_K_FOR_FINAL_RESULTS = 20; // 结果上限,返回相似度高的，保证数据质量
+const SCORE_THRESHOLD_FOR_FINAL = SEARCH_SCORE_THRESHOLD; // 综合排序分阈値（语义相似度占50%权重，原始0.5相似度≈综合60.35起）
+const TOP_K_FOR_FINAL_RESULTS = SEARCH_TOP_K; // 结果上限,返回相似度高的，保证数据质量
+function toRankedResult(item) {
+    return {
+        id: item.symbol.id,
+        name: item.symbol.name,
+        type: item.symbol.type,
+        path: item.symbol.path,
+        description: item.symbol.description,
+        usageCount: item.symbol.usageCount,
+        score: item.score,
+        reason: item.reason.summary,
+        reasonDetail: item.reason,
+    };
+}
+function filterReusableSymbols(items) {
+    return items.filter((item) => isReusableCandidate(item.symbol));
+}
 export function createSearchSymbolsTool(repository) {
     return {
         name: 'search_symbols',
-        description: '搜索项目中已有的可复用代码块（函数、组件、Hook、类型等）。在生成新代码之前必须先调用本工具，确认是否已有实现。\n' +
+        description: '【降级链第二步，非首选工具】搜索项目中已有的可复用代码块（函数、组件、Hook、类型等）。\n' +
+            '⚠️ 调用顺序约束：对于"帮我找 X 组件/util/函数"类问题，第一步必须是 recommend_component，不得跳过直接调用本工具。\n' +
+            '本工具仅在 recommend_component 返回 null（无推荐）后才允许调用，作为第二级降级检索。\n' +
             '- 有明确名称时（如 "useDebounce"）：semantic=false（默认），直接关键词检索\n' +
-            '- 描述功能意图时（如 "防抖"、"处理表单提交"）：semantic=true，进行语义检索（需 embedding 服务已就绪）\n' +
-            '- 不确定 type 时省略该参数，不要猜测\n' +
-            '- 返回结果含 semanticSimilarity 字段：>0.85 高置信度可直接推荐，0.6-0.85 需结合 description 判断，<0.6 说明可能无合适实现',
+            '- 描述功能意图时（如 "防抖"、"处理表单提交"）：semantic=true，进行语义检索\n' +
+            '- 不确定 type 时省略该参数\n' +
+            '- 本工具返回结果后，必须立即按固定模板输出，停止所有后续工具调用。\n' +
+            '- 本工具返回空结果后，输出无结果模板，完全停止，禁止 grep/read file/文件系统兜底。',
         inputSchema: searchSymbolsInput.shape,
         handler: async (input) => {
             if (input.semantic) {
@@ -27,9 +48,34 @@ export function createSearchSymbolsTool(repository) {
                     type: input.type,
                     limit: input.limit,
                 });
-                const simById = new Map(hits.map((h) => [h.symbol.id, h.similarity]));
+                const reusableHits = filterReusableSymbols(hits);
+                if (reusableHits.length === 0) {
+                    const keywordRows = (await repository.search(input.query, input.type)).filter((row) => isReusableCandidate(row));
+                    const fallbackRows = input.ranked
+                        ? rankSymbols(input.query, keywordRows)
+                            .map(toRankedResult)
+                            .filter((x) => x.score >= SCORE_THRESHOLD_FOR_FINAL)
+                            .slice(0, TOP_K_FOR_FINAL_RESULTS)
+                        : keywordRows.map((r) => ({
+                            id: r.id,
+                            name: r.name,
+                            type: r.type,
+                            path: r.path,
+                            description: r.description,
+                            usageCount: r.usageCount,
+                        }));
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify(fallbackRows, null, 2),
+                            },
+                        ],
+                    };
+                }
+                const simById = new Map(reusableHits.map((h) => [h.symbol.id, h.similarity]));
                 const resultRows = input.ranked
-                    ? rankSemanticHits(hits)
+                    ? rankSemanticHits(reusableHits, input.query)
                         .map((item) => ({
                         id: item.symbol.id,
                         name: item.symbol.name,
@@ -44,7 +90,7 @@ export function createSearchSymbolsTool(repository) {
                     }))
                         .filter((x) => x.score >= SCORE_THRESHOLD_FOR_FINAL) // 基于综合排序分过滤，保留 usage/recency 高的结果
                         .slice(0, TOP_K_FOR_FINAL_RESULTS)
-                    : hits.map((h) => ({
+                    : reusableHits.map((h) => ({
                         id: h.symbol.id,
                         name: h.symbol.name,
                         type: h.symbol.type,
@@ -62,20 +108,10 @@ export function createSearchSymbolsTool(repository) {
                     ],
                 };
             }
-            const rows = await repository.search(input.query, input.type);
+            const rows = (await repository.search(input.query, input.type)).filter((row) => isReusableCandidate(row));
             const resultRows = input.ranked
                 ? rankSymbols(input.query, rows)
-                    .map((item) => ({
-                    id: item.symbol.id,
-                    name: item.symbol.name,
-                    type: item.symbol.type,
-                    path: item.symbol.path,
-                    description: item.symbol.description,
-                    usageCount: item.symbol.usageCount,
-                    score: item.score,
-                    reason: item.reason.summary,
-                    reasonDetail: item.reason,
-                }))
+                    .map(toRankedResult)
                     .filter((x) => x.score >= SCORE_THRESHOLD_FOR_FINAL) // 基于综合排序分过滤
                     .slice(0, TOP_K_FOR_FINAL_RESULTS)
                 : rows.map((r) => ({

package/dist/types/chunk.js

@@ -0,0 +1 @@
+export {};

package/dist/workers/embeddingWorker.js

@@ -67,7 +67,6 @@ async function processEmbedJob(job, pool) {
     const meta = typeof row.meta === 'string' ? JSON.parse(row.meta) : (row.meta ?? {});
     const rowObj = { ...row, meta };
     console.error(`[worker] 🔄 embedding  [${ts()}]  table=${table}  hash=${shortHash}…  ${row.path}:${row.name}`);
-    // 与 reindex 保持一致：优先用 content（语义模板），降级用 indexedRowToEmbedText
     const doc = row.content ?? indexedRowToEmbedText(rowObj);
     const vectors = await embedClient.embed([doc]);
     vector = vectors[0];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lorrylurui/code-intelligence-mcp",
-    "version": "2.0.4",
+    "version": "2.0.6",
     "private": false,
     "description": "MCP server 提供仓库内可复用代码块（ts/tsx/js/jsx/css/less）的索引和查询能力，支持基于代码上下文的智能推荐。",
     "type": "module",