@lorrylurui/code-intelligence-mcp 1.0.1

package/dist/repositories/symbolRepository.js

@@ -0,0 +1,219 @@
+import { env } from '../config/env.js';
+import { getMySqlPool } from '../db/mysql.js';
+import { createEmbeddingClient } from '../services/embeddingClient.js';
+import { cosineSimilarity } from '../services/vectorMath.js';
+const inMemorySymbols = [
+    {
+        id: 1,
+        name: 'FormInput',
+        type: 'component',
+        category: 'form',
+        path: 'src/components/FormInput.tsx',
+        description: 'A reusable form input with validation',
+        content: null,
+        meta: { props: ['value', 'onChange', 'error'], hooks: ['useForm'] },
+        usageCount: 18,
+        createdAt: new Date().toISOString(),
+    },
+    {
+        id: 2,
+        name: 'formatDate',
+        type: 'util',
+        category: 'date',
+        path: 'src/utils/date.ts',
+        description: 'Format date to YYYY-MM-DD',
+        content: null,
+        meta: { params: ['input'], returnType: 'string' },
+        usageCount: 40,
+        createdAt: new Date(Date.now() - 1000 * 60 * 60 * 24 * 30).toISOString(),
+    },
+];
+function parseEmbedding(raw) {
+    if (raw == null)
+        return null;
+    if (Array.isArray(raw)) {
+        const nums = raw
+            .map((x) => Number(x))
+            .filter((n) => Number.isFinite(n));
+        return nums.length === raw.length ? nums : null;
+    }
+    if (typeof raw === 'string') {
+        try {
+            const j = JSON.parse(raw);
+            if (!Array.isArray(j))
+                return null;
+            const nums = j
+                .map((x) => Number(x))
+                .filter((n) => Number.isFinite(n));
+            return nums.length === j.length ? nums : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function mapRow(row, opts) {
+    const base = {
+        id: row.id,
+        name: row.name,
+        type: row.type,
+        category: row.category,
+        path: row.path,
+        description: row.description,
+        content: row.content,
+        meta: row.meta ? JSON.parse(row.meta) : null,
+        usageCount: row.usage_count,
+        createdAt: row.created_at ?? null,
+    };
+    if (opts?.includeEmbedding) {
+        base.embedding = parseEmbedding(row.embedding);
+    }
+    return base;
+}
+function getMetaArray(meta, key) {
+    if (!meta)
+        return [];
+    const value = meta[key];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((v) => typeof v === 'string');
+}
+export class SymbolRepository {
+    pool;
+    constructor() {
+        this.pool = getMySqlPool();
+    }
+    async search(query, type) {
+        if (!this.pool) {
+            const q = query.toLowerCase();
+            return inMemorySymbols.filter((s) => {
+                const typeOk = type ? s.type === type : true;
+                return (typeOk &&
+                    (s.name.toLowerCase().includes(q) ||
+                        (s.description ?? '').toLowerCase().includes(q)));
+            });
+        }
+        const params = [`%${query}%`];
+        let sql = `
+      SELECT id, name, type, category, path, description, content, CAST(meta AS CHAR) AS meta, usage_count, created_at
+      FROM symbols
+      WHERE (name LIKE ? OR description LIKE ?)
+    `;
+        params.push(`%${query}%`);
+        if (type) {
+            sql += ' AND type = ?';
+            params.push(type);
+        }
+        sql += ' ORDER BY usage_count DESC LIMIT 20';
+        const [rows] = await this.pool.query(sql, params);
+        return rows.map((r) => mapRow(r));
+    }
+    /**
+     * Phase 5：对自然语言查询做向量检索，返回代码块与余弦相似度（已去掉 embedding 列便于 JSON 输出）。
+     */
+    async searchSemanticHits(query, opts) {
+        if (!env.embeddingServiceUrl) {
+            throw new Error('语义检索需配置 EMBEDDING_SERVICE_URL 并启动嵌入服务');
+        }
+        if (!this.pool) {
+            return [];
+        }
+        const candidateLimit = opts?.candidateLimit ?? 3000;
+        const limit = opts?.limit ?? 20;
+        const type = opts?.type;
+        const client = createEmbeddingClient(env.embeddingServiceUrl);
+        const [queryVec] = await client.embed([query.trim()]);
+        if (!queryVec?.length) {
+            throw new Error('查询向量为空');
+        }
+        let sql = `
+      SELECT id, name, type, category, path, description, content, CAST(meta AS CHAR) AS meta, usage_count, created_at, embedding
+      FROM symbols
+      WHERE embedding IS NOT NULL
+    `;
+        const params = [];
+        if (type) {
+            sql += ' AND type = ?';
+            params.push(type);
+        }
+        sql += ' ORDER BY usage_count DESC LIMIT ?';
+        params.push(candidateLimit);
+        const [rows] = await this.pool.query(sql, params);
+        const withVec = rows
+            .map((r) => mapRow(r, { includeEmbedding: true }))
+            .filter((s) => s.embedding && s.embedding.length === queryVec.length);
+        return withVec
+            .map((s) => {
+            const sim = cosineSimilarity(queryVec, s.embedding);
+            const { embedding: _, ...rest } = s;
+            return { symbol: rest, similarity: sim };
+        })
+            .sort((a, b) => b.similarity - a.similarity)
+            .slice(0, limit);
+    }
+    async getByName(name) {
+        if (!this.pool) {
+            return (inMemorySymbols.find((s) => s.name.toLowerCase() === name.toLowerCase()) ?? null);
+        }
+        const [rows] = await this.pool.query(`
+      SELECT id, name, type, category, path, description, content, CAST(meta AS CHAR) AS meta, usage_count, created_at
+      FROM symbols
+      WHERE name = ?
+      LIMIT 1
+      `, [name]);
+        if (rows.length === 0) {
+            return null;
+        }
+        return mapRow(rows[0]);
+    }
+    async searchByStructure(fields, opts) {
+        const normalized = fields.map((f) => f.trim()).filter(Boolean);
+        if (normalized.length === 0)
+            return [];
+        const type = opts?.type;
+        const category = opts?.category?.trim();
+        const limit = opts?.limit ?? 20;
+        const matchesAll = (symbol) => {
+            const typeOk = type ? symbol.type === type : true;
+            const categoryOk = category
+                ? (symbol.category ?? '')
+                    .toLowerCase()
+                    .includes(category.toLowerCase())
+                : true;
+            if (!typeOk || !categoryOk)
+                return false;
+            const propPool = [
+                ...getMetaArray(symbol.meta, 'props'),
+                ...getMetaArray(symbol.meta, 'params'),
+                ...getMetaArray(symbol.meta, 'properties'),
+                ...getMetaArray(symbol.meta, 'hooks'),
+            ].map((v) => v.toLowerCase());
+            return normalized.every((field) => propPool.includes(field.toLowerCase()));
+        };
+        if (!this.pool) {
+            return inMemorySymbols.filter(matchesAll).slice(0, limit);
+        }
+        const params = [];
+        let sql = `
+      SELECT id, name, type, category, path, description, content, CAST(meta AS CHAR) AS meta, usage_count, created_at
+      FROM symbols
+      WHERE 1 = 1
+    `;
+        if (type) {
+            sql += ' AND type = ?';
+            params.push(type);
+        }
+        if (category) {
+            sql += ' AND category LIKE ?';
+            params.push(`%${category}%`);
+        }
+        sql += ' ORDER BY usage_count DESC LIMIT ?';
+        params.push(Math.max(limit * 5, 50));
+        const [rows] = await this.pool.query(sql, params);
+        return rows
+            .map((r) => mapRow(r))
+            .filter(matchesAll)
+            .slice(0, limit);
+    }
+}

package/dist/server/createServer.js

@@ -0,0 +1,29 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerRecommendComponentPrompt } from "../prompts/recommendComponentPrompt.js";
+import { registerReusableCodeAdvisorPrompt } from "../prompts/reusableCodeAdvisorPrompt.js";
+import { SymbolRepository } from "../repositories/symbolRepository.js";
+import { createSearchSymbolsTool } from "../tools/searchSymbols.js";
+import { createGetSymbolDetailTool } from "../tools/getSymbolDetail.js";
+import { createRecommendComponentTool } from "../tools/recommendComponent.js";
+import { createReindexTool } from "../tools/reindex.js";
+import { createSearchByStructureTool } from "../tools/searchByStructure.js";
+export function createServer() {
+    const server = new McpServer({
+        name: "code-intelligence-mcp",
+        version: "0.1.0"
+    });
+    const repository = new SymbolRepository();
+    const searchTool = createSearchSymbolsTool(repository);
+    server.tool(searchTool.name, searchTool.description, searchTool.inputSchema, searchTool.handler);
+    const detailTool = createGetSymbolDetailTool(repository);
+    server.tool(detailTool.name, detailTool.description, detailTool.inputSchema, detailTool.handler);
+    const structureTool = createSearchByStructureTool(repository);
+    server.tool(structureTool.name, structureTool.description, structureTool.inputSchema, structureTool.handler);
+    const recommendTool = createRecommendComponentTool(repository);
+    server.tool(recommendTool.name, recommendTool.description, recommendTool.inputSchema, recommendTool.handler);
+    const reindexTool = createReindexTool();
+    server.tool(reindexTool.name, reindexTool.description, reindexTool.inputSchema, reindexTool.handler);
+    registerRecommendComponentPrompt(server);
+    registerReusableCodeAdvisorPrompt(server);
+    return server;
+}

package/dist/services/embeddingClient.js

@@ -0,0 +1,37 @@
+export function createEmbeddingClient(baseUrl) {
+    const root = baseUrl.replace(/\/$/, "");
+    return {
+        async embed(texts) {
+            if (texts.length === 0)
+                return [];
+            const res = await fetch(`${root}/embed`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ texts }),
+                signal: AbortSignal.timeout(180_000)
+            });
+            if (!res.ok) {
+                const t = await res.text().catch(() => "");
+                throw new Error(`embedding service HTTP ${res.status}${t ? `: ${t.slice(0, 200)}` : ""}`);
+            }
+            const data = (await res.json());
+            if (!data.embeddings || !Array.isArray(data.embeddings)) {
+                throw new Error("embedding service returned invalid JSON (missing embeddings)");
+            }
+            return data.embeddings;
+        }
+    };
+}
+/** Chunked embed to avoid huge request bodies. */
+export async function embedAll(client, texts, chunkSize = 48) {
+    const out = [];
+    for (let i = 0; i < texts.length; i += chunkSize) {
+        const chunk = texts.slice(i, i + chunkSize);
+        const vecs = await client.embed(chunk);
+        if (vecs.length !== chunk.length) {
+            throw new Error(`embedding service returned ${vecs.length} vectors for ${chunk.length} texts`);
+        }
+        out.push(...vecs);
+    }
+    return out;
+}

package/dist/services/ranking.js

@@ -0,0 +1,161 @@
+function clamp01(value) {
+    if (value < 0)
+        return 0;
+    if (value > 1)
+        return 1;
+    return value;
+}
+function textMatchScore(query, symbol) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return { score: 0, matchedBy: "weak" };
+    const name = symbol.name.toLowerCase();
+    const description = (symbol.description ?? "").toLowerCase();
+    if (name === q)
+        return { score: 1, matchedBy: "exact_name" };
+    if (name.includes(q))
+        return { score: 0.85, matchedBy: "name_contains" };
+    if (description.includes(q))
+        return { score: 0.65, matchedBy: "description_contains" };
+    return { score: 0.2, matchedBy: "weak" };
+}
+function usageScore(usageCount) {
+    // log scale to avoid very large usage monopolizing ranking.
+    return clamp01(Math.log10(usageCount + 1) / 3);
+}
+function recencyScore(createdAt) {
+    if (!createdAt)
+        return 0.4;
+    const ts = new Date(createdAt).getTime();
+    if (Number.isNaN(ts))
+        return 0.4;
+    const days = (Date.now() - ts) / (1000 * 60 * 60 * 24);
+    if (days <= 7)
+        return 1;
+    if (days <= 30)
+        return 0.8;
+    if (days <= 90)
+        return 0.6;
+    if (days <= 180)
+        return 0.4;
+    return 0.25;
+}
+function daysSinceCreated(createdAt) {
+    if (!createdAt)
+        return null;
+    const ts = new Date(createdAt).getTime();
+    if (Number.isNaN(ts))
+        return null;
+    return Math.floor((Date.now() - ts) / (1000 * 60 * 60 * 24));
+}
+function commonPathScore(path) {
+    const lower = path.toLowerCase();
+    return lower.includes("/common/") || lower.includes("/shared/") ? 1 : 0.35;
+}
+const RANK_WEIGHTS = {
+    textMatch: 0.5,
+    usage: 0.3,
+    recency: 0.1,
+    commonPath: 0.1
+};
+/**
+ * Phase 5：以向量余弦相似度作为主文本维度，再叠加 usage / recency / common（与 `rankSymbols` 同权重）。
+ */
+export function rankSemanticHits(hits) {
+    return hits
+        .map(({ symbol, similarity }) => {
+        const textScore = clamp01(similarity);
+        const usage = usageScore(symbol.usageCount);
+        const recency = recencyScore(symbol.createdAt);
+        const common = commonPathScore(symbol.path);
+        const score = textScore * RANK_WEIGHTS.textMatch +
+            usage * RANK_WEIGHTS.usage +
+            recency * RANK_WEIGHTS.recency +
+            common * RANK_WEIGHTS.commonPath;
+        const reasonParts = [];
+        if (textScore >= 0.55)
+            reasonParts.push("语义相似度高");
+        else if (textScore >= 0.4)
+            reasonParts.push("语义相关");
+        if (usage >= 0.6)
+            reasonParts.push("使用频率高");
+        if (common >= 1)
+            reasonParts.push("位于 shared/common 路径");
+        if (reasonParts.length === 0)
+            reasonParts.push("综合相关性较好");
+        return {
+            symbol,
+            score: Number(score.toFixed(3)),
+            reason: {
+                textMatch: {
+                    score: Number(textScore.toFixed(3)),
+                    matchedBy: "semantic"
+                },
+                usage: {
+                    score: Number(usage.toFixed(3)),
+                    usageCount: symbol.usageCount
+                },
+                recency: {
+                    score: Number(recency.toFixed(3)),
+                    daysSinceCreated: daysSinceCreated(symbol.createdAt)
+                },
+                commonPath: {
+                    score: Number(common.toFixed(3)),
+                    isCommonPath: common >= 1
+                },
+                weights: RANK_WEIGHTS,
+                summary: reasonParts.join(" + ")
+            }
+        };
+    })
+        .sort((a, b) => b.score - a.score);
+}
+export function rankSymbols(query, symbols) {
+    return symbols
+        .map((symbol) => {
+        const text = textMatchScore(query, symbol);
+        const usage = usageScore(symbol.usageCount);
+        const recency = recencyScore(symbol.createdAt);
+        const common = commonPathScore(symbol.path);
+        const score = text.score * RANK_WEIGHTS.textMatch +
+            usage * RANK_WEIGHTS.usage +
+            recency * RANK_WEIGHTS.recency +
+            common * RANK_WEIGHTS.commonPath;
+        const reasonParts = [];
+        if (text.score >= 0.85)
+            reasonParts.push("文本匹配度高");
+        else if (text.score >= 0.65)
+            reasonParts.push("描述命中");
+        if (usage >= 0.6)
+            reasonParts.push("使用频率高");
+        if (common >= 1)
+            reasonParts.push("位于 shared/common 路径");
+        if (reasonParts.length === 0)
+            reasonParts.push("综合相关性较好");
+        return {
+            symbol,
+            score: Number(score.toFixed(3)),
+            reason: {
+                textMatch: {
+                    score: Number(text.score.toFixed(3)),
+                    matchedBy: text.matchedBy
+                },
+                usage: {
+                    score: Number(usage.toFixed(3)),
+                    usageCount: symbol.usageCount
+                },
+                recency: {
+                    score: Number(recency.toFixed(3)),
+                    daysSinceCreated: daysSinceCreated(symbol.createdAt)
+                },
+                commonPath: {
+                    score: Number(common.toFixed(3)),
+                    isCommonPath: common >= 1
+                },
+                weights: RANK_WEIGHTS,
+                summary: reasonParts.join(" + ")
+            }
+        };
+    })
+        .sort((a, b) => b.score - a.score);
+}

package/dist/services/reindex.js

@@ -0,0 +1,45 @@
+import { resolve } from "node:path";
+import { env, validateEnv } from "../config/env.js";
+import { getMySqlPool } from "../db/mysql.js";
+import { indexedRowToEmbedText } from "../indexer/embedText.js";
+import { indexProject } from "../indexer/indexProject.js";
+import { upsertSymbols } from "../indexer/persistSymbols.js";
+import { createEmbeddingClient, embedAll } from "../services/embeddingClient.js";
+export async function runReindex(options = {}) {
+    validateEnv();
+    const pool = getMySqlPool();
+    if (!pool || !env.mysqlEnabled) {
+        throw new Error("执行 reindex 前必须开启 MYSQL_ENABLED=true。");
+    }
+    await pool.query("SELECT 1");
+    const projectRoot = resolve(options.projectRoot ?? process.cwd());
+    const rows = await indexProject({
+        projectRoot,
+        globPatterns: options.globPatterns,
+        ignore: options.ignore
+    });
+    let embeddingsComputed = false;
+    let embeddingPayload;
+    if (!options.dryRun && rows.length > 0 && env.embeddingServiceUrl) {
+        try {
+            const client = createEmbeddingClient(env.embeddingServiceUrl);
+            const texts = rows.map(indexedRowToEmbedText);
+            const vecs = await embedAll(client, texts);
+            embeddingPayload = vecs;
+            embeddingsComputed = true;
+        }
+        catch (err) {
+            console.error("[reindex] embedding skipped (service error):", err);
+            embeddingPayload = rows.map(() => null);
+        }
+    }
+    if (!options.dryRun) {
+        await upsertSymbols(pool, rows, embeddingPayload);
+    }
+    return {
+        projectRoot,
+        extractedCount: rows.length,
+        upserted: !options.dryRun,
+        embeddingsComputed
+    };
+}

package/dist/services/vectorMath.js

@@ -0,0 +1,17 @@
+/** Cosine similarity for equal-length numeric vectors. */
+export function cosineSimilarity(a, b) {
+    if (a.length === 0 || b.length !== a.length)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    const denom = Math.sqrt(na) * Math.sqrt(nb);
+    if (denom === 0)
+        return 0;
+    return dot / denom;
+}

package/dist/skills/rankSymbols.js

@@ -0,0 +1,24 @@
+function keywordScore(query, symbol) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return 0.5;
+    if (symbol.name.toLowerCase().includes(q))
+        return 1;
+    if ((symbol.description ?? "").toLowerCase().includes(q))
+        return 0.8;
+    return 0.4;
+}
+export function rankSymbols(query, symbols) {
+    return symbols
+        .map((item) => {
+        const text = keywordScore(query, item);
+        const usage = Math.min(item.usageCount, 100) / 100;
+        const score = text * 0.7 + usage * 0.3;
+        return {
+            ...item,
+            score: Number(score.toFixed(3)),
+            reason: "text match + usage weight"
+        };
+    })
+        .sort((a, b) => b.score - a.score);
+}

package/dist/skills/recommendComponent.js

@@ -0,0 +1,39 @@
+import { rankSymbols } from "../services/ranking.js";
+export async function recommendComponent(query, repository, options = {}) {
+    const requestedProps = options.props?.map((p) => p.trim()).filter(Boolean) ?? [];
+    const limit = options.limit ?? 3;
+    // Step 1: keyword candidate search
+    const keywordCandidates = await repository.search(query, "component");
+    // Step 2: optional structure filter
+    const structureCandidates = requestedProps.length > 0
+        ? await repository.searchByStructure(requestedProps, {
+            type: "component",
+            limit: Math.max(limit * 3, 20)
+        })
+        : [];
+    const byName = new Map();
+    for (const row of keywordCandidates)
+        byName.set(row.name, row);
+    for (const row of structureCandidates)
+        byName.set(row.name, row);
+    // Step 3: ranking
+    const ranked = rankSymbols(query, [...byName.values()]).slice(0, Math.max(limit * 3, 10));
+    // Step 4: detail enrichment
+    const enriched = await Promise.all(ranked.map(async (item) => {
+        const detail = await repository.getByName(item.symbol.name);
+        return {
+            name: item.symbol.name,
+            path: item.symbol.path,
+            score: item.score,
+            reason: item.reason.summary,
+            reasonDetail: item.reason,
+            detail
+        };
+    }));
+    // Step 5: return top-N with reasons
+    return {
+        query,
+        requestedProps,
+        results: enriched.slice(0, limit)
+    };
+}

package/dist/tools/getSymbolDetail.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+export const getSymbolDetailInput = z.object({
+    name: z.string().min(1),
+});
+export function createGetSymbolDetailTool(repository) {
+    return {
+        name: 'get_symbol_detail',
+        description: '按名称获取单个代码块的完整详情。',
+        inputSchema: getSymbolDetailInput.shape,
+        handler: async (input) => {
+            const symbol = await repository.getByName(input.name);
+            if (!symbol) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `未找到代码块：${input.name}`,
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(symbol, null, 2),
+                    },
+                ],
+            };
+        },
+    };
+}

package/dist/tools/recommendComponent.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { recommendComponent } from "../skills/recommendComponent.js";
+export const recommendComponentInput = z.object({
+    query: z.string().min(1),
+    props: z.array(z.string().min(1)).optional(),
+    limit: z.number().int().min(1).max(20).optional().default(3)
+});
+export function createRecommendComponentTool(repository) {
+    return {
+        name: "recommend_component",
+        description: "基于关键词检索 + 可选结构过滤 + 排序 + 详情补全，推荐最合适的可复用组件。",
+        inputSchema: recommendComponentInput.shape,
+        handler: async (input) => {
+            const result = await recommendComponent(input.query, repository, {
+                props: input.props,
+                limit: input.limit
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2)
+                    }
+                ]
+            };
+        }
+    };
+}

package/dist/tools/reindex.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { runReindex } from '../services/reindex.js';
+export const reindexInput = z.object({
+    projectRoot: z.string().optional(),
+    globPatterns: z.array(z.string().min(1)).optional(),
+    ignore: z.array(z.string().min(1)).optional(),
+    dryRun: z.boolean().optional().default(false),
+});
+export function createReindexTool() {
+    return {
+        name: 'reindex',
+        description: '重建源码代码块索引并写入 MySQL；设置 dryRun=true 时仅预览抽取数量，不落库、不调用嵌入服务。若配置 EMBEDDING_SERVICE_URL，非 dryRun 时会写入向量列。',
+        inputSchema: reindexInput.shape,
+        handler: async (input) => {
+            const startedAt = Date.now();
+            const result = await runReindex({
+                projectRoot: input.projectRoot,
+                globPatterns: input.globPatterns,
+                ignore: input.ignore,
+                dryRun: input.dryRun,
+            });
+            const elapsedMs = Date.now() - startedAt;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            ok: true,
+                            ...result,
+                            elapsedMs,
+                        }, null, 2),
+                    },
+                ],
+            };
+        },
+    };
+}