pit-docs-mcp 1.0.2

package/dist/tools.js

@@ -0,0 +1,258 @@
+import fs from "fs/promises";
+import path from "path";
+import { z } from "zod";
+import { DOCS_PATH } from "./constants.js";
+import { grepSearch, extractPropsSection, getCachedFileContent, getDocCatalog, pathToUri, uriToFilePath, safePath, } from "./utils.js";
+import { loadCodegenSpec, extractSections, getComponentDocs, } from "./codegen.js";
+export function registerTools(server) {
+    registerSearchDocsTool(server);
+    registerReadDocTool(server);
+    registerListDocsTool(server);
+    registerGetCodegenSpecTool(server);
+}
+// --- search_docs ---
+function registerSearchDocsTool(server) {
+    const schema = z.object({
+        keyword: z
+            .string()
+            .describe("要搜索的关键字，支持多个词用空格分隔（OR 语义）。如：pit-document-preview 参数"),
+        maxResults: z.number().optional().default(20).describe("最大返回结果数量"),
+        contextLines: z
+            .number()
+            .optional()
+            .default(3)
+            .describe("匹配行前后的上下文行数，便于获取完整片段"),
+    });
+    server.registerTool("search_docs", {
+        title: "Search Docs",
+        description: `在 pitBusinessUi 和 pitElementUi 两个内部组件库的文档中搜索。当用户询问 pit 组件（如 pit-document-preview、pit-table、pit-button）的用法、参数、Props、示例时，必须使用此工具。
+
+本工具返回匹配片段及文档 URI。若需完整文档（如 Props 表格、示例代码），请使用返回的 pit-docs:// URI 调用 read_doc 获取全文。多关键词按 OR 语义匹配，如「pit-document-preview 参数」。`,
+        inputSchema: schema.shape,
+    }, async ({ keyword, maxResults, contextLines }) => {
+        const keywords = keyword.split(/\s+/).map((k) => k.trim()).filter(Boolean);
+        if (keywords.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "请输入有效关键字。可尝试组件名（如 pit-document-preview）或技术词（如 props、参数）。",
+                    },
+                ],
+            };
+        }
+        const results = await grepSearch(keywords, { contextLines });
+        const limited = results.slice(0, maxResults);
+        const lines = [];
+        for (const r of limited) {
+            let block = `- **${r.path}:${r.line}**\n  \`${r.content}\``;
+            if (r.contextBefore?.length) {
+                block += `\n  ← 上文: ${r.contextBefore.join(" | ")}`;
+            }
+            if (r.contextAfter?.length) {
+                block += `\n  → 下文: ${r.contextAfter.join(" | ")}`;
+            }
+            lines.push(block);
+        }
+        const summary = results.length > maxResults
+            ? `\n\n... 共 ${results.length} 条匹配，仅显示前 ${maxResults} 条`
+            : "";
+        const hitPaths = [...new Set(limited.map((r) => r.path))];
+        const uris = hitPaths.map((p) => pathToUri(p));
+        const uriHint = uris.length > 0
+            ? `\n\n【读取完整文档】请使用 read_doc 工具，传入以下 URI 之一：\n${uris.map((u) => `- ${u}`).join("\n")}`
+            : "";
+        const propsSections = [];
+        for (const relPath of hitPaths.slice(0, 2)) {
+            try {
+                const content = await getCachedFileContent(relPath);
+                const props = extractPropsSection(content);
+                if (props) {
+                    propsSections.push(`### ${relPath} - Props/参数\n\`\`\`\n${props}\n\`\`\``);
+                }
+            }
+            catch {
+                // 忽略
+            }
+        }
+        const propsBlock = propsSections.length > 0
+            ? `\n\n【Props/参数 摘要】\n${propsSections.join("\n\n")}`
+            : "";
+        const text = lines.length > 0
+            ? `找到 ${results.length} 条匹配:\n\n${lines.join("\n\n")}${summary}${uriHint}${propsBlock}`
+            : `未找到包含 "${keywords.join(" ")}" 的文档内容。可尝试其他关键字（如仅用组件名 pit-xxx），或使用 list_docs 获取文档目录清单。`;
+        return {
+            content: [{ type: "text", text }],
+        };
+    });
+}
+// --- read_doc ---
+function registerReadDocTool(server) {
+    const schema = z.object({
+        pathOrUri: z
+            .string()
+            .describe("文档路径（如 pitBusinessUi/document-preview.md）或完整 URI（如 pit-docs:///pitBusinessUi/document-preview.md）"),
+    });
+    server.registerTool("read_doc", {
+        title: "Read Doc",
+        description: `读取 pitBusinessUi 或 pitElementUi 文档的完整内容。当 search_docs 找到匹配但片段不足以回答（如用户问「有哪些参数」）时，使用本工具传入 pit-docs:// URI 或文档路径（如 pitBusinessUi/document-preview.md）获取全文。`,
+        inputSchema: schema.shape,
+    }, async ({ pathOrUri }) => {
+        let relPath;
+        const trimmed = pathOrUri.trim();
+        if (trimmed.startsWith("pit-docs://")) {
+            try {
+                const fullPath = uriToFilePath(trimmed);
+                relPath = path.relative(DOCS_PATH, fullPath).replace(/\\/g, "/");
+            }
+            catch {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `无效的 URI: ${trimmed}。请使用 pit-docs:///path/to/doc.md 格式。`,
+                        },
+                    ],
+                };
+            }
+        }
+        else {
+            relPath = trimmed.replace(/\\/g, "/");
+            if (relPath.startsWith("/"))
+                relPath = relPath.slice(1);
+        }
+        const fullPath = safePath(relPath);
+        try {
+            const content = await fs.readFile(fullPath, "utf-8");
+            const uri = pathToUri(relPath);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `## ${relPath}\n\nURI: ${uri}\n\n---\n\n${content}`,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `无法读取文档 "${relPath}": ${msg}。请检查路径或使用 list_docs 获取有效文档列表。`,
+                    },
+                ],
+            };
+        }
+    });
+}
+// --- list_docs ---
+function registerListDocsTool(server) {
+    const schema = z.object({
+        category: z
+            .string()
+            .optional()
+            .describe("按目录筛选。仅支持 pitBusinessUi 或 pitElementUi，不传则返回全部"),
+        offset: z.number().optional().default(0).describe("跳过前 N 条记录（分页偏移）"),
+        limit: z.number().optional().default(50).describe("最多返回条数，默认 50"),
+    });
+    server.registerTool("list_docs", {
+        title: "List Docs",
+        description: `获取 pitBusinessUi 和 pitElementUi 的文档目录清单。组件名按 pit-{name} 映射：如 pit-image 对应 image.md，pit-dic 对应 dic.md。返回组件名、文档路径及 pit-docs:// URI，便于定位并读取具体文档。`,
+        inputSchema: schema.shape,
+    }, async ({ category, offset, limit }) => {
+        const catalog = await getDocCatalog(category);
+        const total = catalog.length;
+        if (total === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: category
+                            ? `目录 ${category} 下暂无组件文档。`
+                            : "暂无可用的组件文档。",
+                    },
+                ],
+            };
+        }
+        const paged = catalog.slice(offset, offset + limit);
+        const byCategory = new Map();
+        for (const item of paged) {
+            if (!byCategory.has(item.category)) {
+                byCategory.set(item.category, []);
+            }
+            byCategory.get(item.category).push(item);
+        }
+        const lines = [];
+        for (const [cat, items] of byCategory) {
+            lines.push(`\n### ${cat}`);
+            for (const item of items) {
+                lines.push(`- **${item.component}** → \`${item.docPath}\` (URI: ${item.uri})`);
+            }
+        }
+        const paginationHint = total > offset + limit
+            ? `\n\n... 共 ${total} 个文档，当前显示第 ${offset + 1}-${offset + paged.length} 条。传入 offset=${offset + limit} 获取下一页。`
+            : "";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `PIT 组件文档清单（共 ${total} 个）\n${lines.join("\n")}${paginationHint}\n\n使用 read_doc 工具传入上述 URI 或路径可读取完整文档内容。`,
+                },
+            ],
+        };
+    });
+}
+// --- get_codegen_spec ---
+function registerGetCodegenSpecTool(server) {
+    const pageTypes = ["standard", "left-tree", "flow", "all"];
+    const schema = z.object({
+        pageType: z
+            .enum(pageTypes)
+            .optional()
+            .default("all")
+            .describe('页面类型。standard=标准CRUD页面，left-tree=左树右表页面，flow=流程表单页面，all=返回全部规范。默认 all'),
+        includeComponentDocs: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("是否附带相关组件的 Props/参数文档摘要，默认 true"),
+    });
+    server.registerTool("get_codegen_spec", {
+        title: "Get Codegen Spec",
+        description: `获取 pit-simplify-web 后台管理页面的代码生成规范。返回页面骨架模板、组件使用规范、数据准备规范、API 文件模板、反模式清单及验收基准。
+
+使用场景：当用户要求生成后台管理 CRUD 页面（标准页面、左树右表页面、流程审批页面）时，先调用此工具获取完整的编码规范和组件文档，然后按规范生成代码。
+
+输入格式提示：用户通常会提供「表结构 SQL + 服务名 + 模块名 + 字典字段信息」。
+
+若需要某个组件的更详细文档，可再用 search_docs 或 read_doc 工具补充查阅。`,
+        inputSchema: schema.shape,
+    }, async ({ pageType, includeComponentDocs }) => {
+        try {
+            const fullSpec = await loadCodegenSpec();
+            const spec = extractSections(fullSpec, pageType);
+            const parts = [];
+            parts.push(`# pit-simplify-web 代码生成规范（${pageType}）\n\n${spec}`);
+            if (includeComponentDocs) {
+                const docs = await getComponentDocs(pageType);
+                parts.push(`\n\n---\n\n# 相关组件 Props/参数文档\n\n> 以下为 ${pageType} 页面涉及的核心组件文档摘要。若需完整文档，请使用 read_doc 工具。\n\n${docs}`);
+            }
+            return {
+                content: [{ type: "text", text: parts.join("") }],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `无法加载代码生成规范: ${msg}。请确认 docs/codegen/pit-simplify-web.md 文件存在。`,
+                    },
+                ],
+            };
+        }
+    });
+}

package/dist/utils.d.ts

@@ -0,0 +1,26 @@
+export declare function getCachedDocFiles(): Promise<string[]>;
+export declare function getCachedFileContent(relPath: string): Promise<string>;
+export declare function safePath(relPath: string): string;
+export declare function uriToFilePath(uri: string): string;
+export declare function pathToUri(relPath: string): string;
+export declare function docNameToComponentName(docBasename: string, category?: string): string;
+export declare function getDocCatalog(category?: string): Promise<{
+    category: string;
+    component: string;
+    docPath: string;
+    uri: string;
+}[]>;
+export declare function getComponentsInCategory(category: string): Promise<string[]>;
+export type SearchMatch = {
+    path: string;
+    line: number;
+    content: string;
+    score: number;
+    contextBefore?: string[];
+    contextAfter?: string[];
+};
+export declare function grepSearch(keywords: string[], options?: {
+    contextLines?: number;
+}): Promise<SearchMatch[]>;
+export declare function extractPropsSection(content: string): string | null;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAUA,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAQ3D;AAID,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAc3E;AA6BD,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMhD;AAID,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGjD;AAID,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAGrF;AAID,wBAAsB,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAC7D;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,CACxE,CAuBA;AAED,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAcjF;AAID,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB,CAAC;AAcF,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GAClC,OAAO,CAAC,WAAW,EAAE,CAAC,CAoCxB;AAID,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAwBlE"}

package/dist/utils.js

@@ -0,0 +1,198 @@
+import fs from "fs/promises";
+import path from "path";
+import { DOCS_PATH, DOC_EXTENSIONS, RESOURCE_URI_PREFIX } from "./constants.js";
+// --- 缓存层 ---
+const FILE_LIST_CACHE_TTL = 60_000;
+const CONTENT_CACHE_MAX = 50;
+let fileListCache = null;
+export async function getCachedDocFiles() {
+    const now = Date.now();
+    if (fileListCache && now - fileListCache.ts < FILE_LIST_CACHE_TTL) {
+        return fileListCache.data;
+    }
+    const data = await getAllDocFiles(DOCS_PATH);
+    fileListCache = { data, ts: now };
+    return data;
+}
+const contentCache = new Map();
+export async function getCachedFileContent(relPath) {
+    const now = Date.now();
+    const cached = contentCache.get(relPath);
+    if (cached && now - cached.ts < FILE_LIST_CACHE_TTL) {
+        return cached.text;
+    }
+    const fullPath = path.join(DOCS_PATH, relPath);
+    const text = await fs.readFile(fullPath, "utf-8");
+    if (contentCache.size >= CONTENT_CACHE_MAX) {
+        const oldest = [...contentCache.entries()].sort((a, b) => a[1].ts - b[1].ts)[0];
+        if (oldest)
+            contentCache.delete(oldest[0]);
+    }
+    contentCache.set(relPath, { text, ts: now });
+    return text;
+}
+// --- 文件扫描 ---
+async function getAllDocFiles(dir, baseDir = dir) {
+    const files = [];
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "node_modules" || entry.name.startsWith("."))
+                    continue;
+                files.push(...(await getAllDocFiles(fullPath, baseDir)));
+            }
+            else if (entry.isFile()) {
+                const ext = path.extname(entry.name).toLowerCase();
+                if (DOC_EXTENSIONS.has(ext)) {
+                    files.push(path.relative(baseDir, fullPath));
+                }
+            }
+        }
+    }
+    catch (err) {
+        console.error(`[pit-docs-mcp] 无法读取目录 ${dir}:`, err);
+    }
+    return files;
+}
+// --- 路径安全 ---
+export function safePath(relPath) {
+    const resolved = path.resolve(DOCS_PATH, relPath);
+    if (!resolved.startsWith(path.resolve(DOCS_PATH) + path.sep) && resolved !== path.resolve(DOCS_PATH)) {
+        throw new Error(`路径越界，拒绝访问: ${relPath}`);
+    }
+    return resolved;
+}
+// --- URI 转换 ---
+export function uriToFilePath(uri) {
+    const match = uri.match(/^pit-docs:\/\/(.+)$/);
+    if (!match)
+        throw new Error(`无效的文档 URI: ${uri}`);
+    let relPath = decodeURIComponent(match[1]);
+    if (relPath.startsWith("/"))
+        relPath = relPath.slice(1);
+    return safePath(relPath);
+}
+export function pathToUri(relPath) {
+    const normalized = relPath.replace(/\\/g, "/");
+    return `${RESOURCE_URI_PREFIX}/${normalized}`;
+}
+// --- 组件名映射 ---
+export function docNameToComponentName(docBasename, category) {
+    const prefix = category === "pitElementUi" ? "el" : "pit";
+    return `${prefix}-${docBasename}`;
+}
+// --- 文档目录 ---
+export async function getDocCatalog(category) {
+    const files = await getCachedDocFiles();
+    const mdFiles = files.filter((f) => f.endsWith(".md") && !f.endsWith("README.md"));
+    const catalog = [];
+    for (const relPath of mdFiles) {
+        const dir = path.dirname(relPath);
+        const basename = path.basename(relPath, ".md");
+        if (category && dir !== category)
+            continue;
+        const component = docNameToComponentName(basename, dir);
+        const normalizedPath = relPath.replace(/\\/g, "/");
+        catalog.push({
+            category: dir,
+            component,
+            docPath: normalizedPath,
+            uri: pathToUri(normalizedPath),
+        });
+    }
+    catalog.sort((a, b) => a.category.localeCompare(b.category) || a.component.localeCompare(b.component));
+    return catalog;
+}
+export async function getComponentsInCategory(category) {
+    const categoryPath = path.join(DOCS_PATH, category);
+    try {
+        const entries = await fs.readdir(categoryPath, { withFileTypes: true });
+        const components = [];
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.endsWith(".md") && entry.name !== "README.md") {
+                components.push(path.basename(entry.name, ".md"));
+            }
+        }
+        return components.sort();
+    }
+    catch {
+        return [];
+    }
+}
+function scoreMatch(line, keywords) {
+    let score = 1;
+    const lower = line.toLowerCase();
+    if (/^#+\s/.test(line))
+        score += 5;
+    if (/^\|/.test(line))
+        score += 2;
+    for (const kw of keywords) {
+        const count = lower.split(kw.toLowerCase()).length - 1;
+        if (count > 1)
+            score += count;
+    }
+    return score;
+}
+export async function grepSearch(keywords, options) {
+    const results = [];
+    const files = await getCachedDocFiles();
+    const ctx = options?.contextLines ?? 3;
+    const lowerKeywords = keywords.map((k) => k.trim().toLowerCase()).filter(Boolean);
+    if (lowerKeywords.length === 0)
+        return results;
+    const lineMatches = (line) => lowerKeywords.some((kw) => line.toLowerCase().includes(kw));
+    for (const relPath of files) {
+        try {
+            const content = await getCachedFileContent(relPath);
+            const lines = content.split("\n");
+            const normPath = relPath.replace(/\\/g, "/");
+            lines.forEach((line, index) => {
+                if (lineMatches(line)) {
+                    const ctxBefore = ctx > 0 ? lines.slice(Math.max(0, index - ctx), index) : [];
+                    const ctxAfter = ctx > 0 ? lines.slice(index + 1, index + 1 + ctx) : [];
+                    results.push({
+                        path: normPath,
+                        line: index + 1,
+                        content: line.trim(),
+                        score: scoreMatch(line, lowerKeywords),
+                        contextBefore: ctxBefore.length > 0 ? ctxBefore.map((l) => l.trim()) : undefined,
+                        contextAfter: ctxAfter.length > 0 ? ctxAfter.map((l) => l.trim()) : undefined,
+                    });
+                }
+            });
+        }
+        catch {
+            // 忽略无法读取的文件
+        }
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results;
+}
+// --- Markdown 解析 ---
+export function extractPropsSection(content) {
+    const lines = content.split("\n");
+    const propsHeaders = ["## Props", "## 参数", "### Props", "### 参数", "## 属性"];
+    let startIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const h = lines[i].trim();
+        if (propsHeaders.some((ph) => h === ph || h.startsWith(ph + " "))) {
+            startIdx = i;
+            break;
+        }
+    }
+    if (startIdx < 0)
+        return null;
+    const matchLevel = lines[startIdx].match(/^(#+)\s/)?.[1].length ?? 2;
+    const collected = [];
+    for (let i = startIdx; i < lines.length; i++) {
+        const line = lines[i];
+        const headingMatch = line.match(/^(#+)\s/);
+        if (i > startIdx && headingMatch && headingMatch[1].length <= matchLevel) {
+            break;
+        }
+        collected.push(line);
+    }
+    return collected.length > 0 ? collected.join("\n") : null;
+}