@ppdocs/mcp 3.1.9 → 3.2.0

package/dist/storage/httpClient.d.ts

@@ -96,6 +96,14 @@ export declare class PpdocsApiClient {
         localPath: string;
         fileCount: number;
     }>;
+    /** 扫描项目代码, 构建/更新索引 */
+    analyzerScan(projectPath: string, force?: boolean): Promise<unknown>;
+    /** 查询代码符号 (模糊匹配) */
+    analyzerQuery(projectPath: string, query: string): Promise<unknown>;
+    /** 分层影响分析 (BFS 递归, 可指定深度) */
+    analyzerImpactTree(projectPath: string, symbolName: string, depth?: number): Promise<unknown>;
+    /** 获取文件 360° 上下文 */
+    analyzerContext(projectPath: string, filePath: string): Promise<unknown>;
 }
 export declare function initClient(apiUrl: string): void;
 export declare function getClient(): PpdocsApiClient;

package/dist/storage/httpClient.js

@@ -480,6 +480,35 @@ export class PpdocsApiClient {
     async crossDownload(target, remotePath, localPath) {
         return fetchAndExtractZip(`${this.baseUrl}/cross/${encodeURIComponent(target)}/files-download/${cleanPath(remotePath)}`, localPath);
     }
+    // ============ 代码分析引擎 ============
+    /** 扫描项目代码, 构建/更新索引 */
+    async analyzerScan(projectPath, force = false) {
+        return this.request('/analyzer/scan', {
+            method: 'POST',
+            body: JSON.stringify({ project_path: projectPath, force }),
+        });
+    }
+    /** 查询代码符号 (模糊匹配) */
+    async analyzerQuery(projectPath, query) {
+        return this.request('/analyzer/query', {
+            method: 'POST',
+            body: JSON.stringify({ project_path: projectPath, query }),
+        });
+    }
+    /** 分层影响分析 (BFS 递归, 可指定深度) */
+    async analyzerImpactTree(projectPath, symbolName, depth = 2) {
+        return this.request('/analyzer/impact-tree', {
+            method: 'POST',
+            body: JSON.stringify({ project_path: projectPath, symbol_name: symbolName, depth }),
+        });
+    }
+    /** 获取文件 360° 上下文 */
+    async analyzerContext(projectPath, filePath) {
+        return this.request('/analyzer/context', {
+            method: 'POST',
+            body: JSON.stringify({ project_path: projectPath, file_path: filePath }),
+        });
+    }
 }
 // ============ 模块级 API ============
 let client = null;

package/dist/tools/analyzer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 代码分析引擎工具 (4个)
+ * code_scan, code_query, code_impact, code_context
+ *
+ * 让 AI Agent 通过 MCP 工具直接查询代码结构、依赖关系和影响范围
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAnalyzerTools(server: McpServer, projectId: string): void;

package/dist/tools/analyzer.js

@@ -0,0 +1,136 @@
+/**
+ * 代码分析引擎工具 (4个)
+ * code_scan, code_query, code_impact, code_context
+ *
+ * 让 AI Agent 通过 MCP 工具直接查询代码结构、依赖关系和影响范围
+ */
+import { z } from 'zod';
+import { getClient } from '../storage/httpClient.js';
+import { wrap, safeTool } from './shared.js';
+// 符号图标
+const SYMBOL_ICONS = {
+    function: '𝑓', class: '𝐂', method: '𝑚', interface: '𝐈',
+    type_alias: '𝐓', enum: '𝐄', struct: '𝐒', trait: '⚡',
+    constant: '𝐊', variable: '𝑣',
+};
+const SEVERITY_ICONS = {
+    critical: '🔴', warning: '🟡', info: '🟢',
+};
+export function registerAnalyzerTools(server, projectId) {
+    const client = () => getClient();
+    // ===== code_scan: 扫描项目代码 =====
+    server.tool('code_scan', '📡 扫描项目代码, 构建索引。返回文件数、符号数、语言统计。★首次使用 code_query/code_impact/code_context 前必须先执行★', {
+        projectPath: z.string().describe('项目源码的绝对路径(如"D:/projects/myapp")'),
+        force: z.boolean().optional().describe('是否强制全量重建(默认false, 增量更新)'),
+    }, async (args) => safeTool(async () => {
+        const result = await client().analyzerScan(args.projectPath, args.force ?? false);
+        return wrap([
+            `✅ 代码扫描完成`,
+            ``,
+            `📊 索引摘要:`,
+            `- 文件数: ${result.fileCount}`,
+            `- 符号数: ${result.symbolCount}`,
+            `- 语言: ${result.languages.join(', ')}`,
+            `- 索引时间: ${result.indexedAt}`,
+        ].join('\n'));
+    }));
+    // ===== code_query: 搜索代码符号 =====
+    server.tool('code_query', '🔤 搜索代码符号(函数/类/方法/接口/类型)。返回匹配列表+文件路径+行号。定位代码位置的最快方式。需先运行 code_scan', {
+        projectPath: z.string().describe('项目源码的绝对路径'),
+        query: z.string().describe('搜索关键词(函数名/类名/方法名等)'),
+    }, async (args) => safeTool(async () => {
+        const results = await client().analyzerQuery(args.projectPath, args.query);
+        if (!results || results.length === 0) {
+            return wrap(`未找到匹配 "${args.query}" 的符号。请确认已运行 code_scan`);
+        }
+        const lines = results.map(r => {
+            const icon = SYMBOL_ICONS[r.symbol.kind] || '?';
+            const exp = r.symbol.exported ? ' [export]' : '';
+            const parent = r.symbol.parent ? ` ◀ ${r.symbol.parent}` : '';
+            return `  ${icon} ${r.symbol.name}${parent}${exp}  →  ${r.filePath}:${r.symbol.lineStart}`;
+        });
+        return wrap([
+            `🔤 找到 ${results.length} 个匹配符号:`,
+            ``,
+            ...lines,
+        ].join('\n'));
+    }));
+    // ===== code_impact: 分层影响分析 =====
+    server.tool('code_impact', '💥 爆炸半径分析 ★修改代码前必查★ 分析修改一个函数/类/类型会影响多少文件。BFS分层输出: L1🔴直接引用=必须检查, L2🟡间接引用=建议检查, L3🟢传递引用=注意。修改任何公共接口、函数签名、类型定义前务必先运行!', {
+        projectPath: z.string().describe('项目源码的绝对路径'),
+        symbolName: z.string().describe('要分析的符号名称(如"AuthService", "handleLogin")'),
+        depth: z.number().optional().describe('分析深度层级(1-5, 默认2)。1=仅直接引用, 3=深度追踪'),
+    }, async (args) => safeTool(async () => {
+        const result = await client().analyzerImpactTree(args.projectPath, args.symbolName, args.depth ?? 2);
+        if (!result) {
+            return wrap(`未找到符号 "${args.symbolName}"。请确认名称正确且已运行 code_scan`);
+        }
+        if (result.levels.length === 0) {
+            return wrap(`✅ "${args.symbolName}" 没有被其他文件引用, 修改安全`);
+        }
+        // 生成分层树形输出
+        const lines = [
+            `🎯 ${result.symbolName} (${result.symbolKind})`,
+            `📍 定义: ${result.definedIn}:${result.lineStart}`,
+            ``,
+            `📊 ${result.summary}`,
+            ``,
+        ];
+        for (const level of result.levels) {
+            const icon = SEVERITY_ICONS[level.severity] || '⚪';
+            const label = level.depth === 1 ? '直接引用 (必须检查)' :
+                level.depth === 2 ? '间接引用 (建议检查)' :
+                    '传递引用 (注意)';
+            lines.push(`### ${icon} L${level.depth} ${label} (${level.count}个)`);
+            for (const entry of level.entries) {
+                lines.push(`  ${entry.filePath}:${entry.line}  [${entry.refKind}]  ${entry.context}`);
+            }
+            lines.push('');
+        }
+        return wrap(lines.join('\n'));
+    }));
+    // ===== code_context: 文件360°上下文 =====
+    server.tool('code_context', '🔍 文件360°上下文 — 定义了什么符号、导入了什么、被谁引用。修改文件前使用, 快速了解所有依赖关系, 避免遗漏', {
+        projectPath: z.string().describe('项目源码的绝对路径'),
+        filePath: z.string().describe('目标文件的相对路径(如"src/services/auth.ts")'),
+    }, async (args) => safeTool(async () => {
+        const ctx = await client().analyzerContext(args.projectPath, args.filePath);
+        if (!ctx) {
+            return wrap(`未找到文件 "${args.filePath}"。请确认路径正确, 路径格式为相对路径(如 src/main.ts)`);
+        }
+        const lines = [
+            `📄 ${ctx.filePath}`,
+            `语言: ${ctx.language} | ${ctx.linesTotal} 行`,
+            ``,
+        ];
+        // 定义的符号
+        if (ctx.symbolsDefined.length > 0) {
+            lines.push(`### 🔤 定义的符号 (${ctx.symbolsDefined.length})`);
+            for (const sym of ctx.symbolsDefined) {
+                const icon = SYMBOL_ICONS[sym.kind] || '?';
+                const exp = sym.exported ? ' [export]' : '';
+                lines.push(`  ${icon} ${sym.name}${exp}  L${sym.lineStart}-L${sym.lineEnd}`);
+            }
+            lines.push('');
+        }
+        // 导入
+        if (ctx.imports.length > 0) {
+            lines.push(`### 📥 导入 (${ctx.imports.length})`);
+            for (const imp of ctx.imports) {
+                const specs = imp.specifiers.length > 0 ? `{ ${imp.specifiers.join(', ')} }` : '*';
+                lines.push(`  → ${imp.source}  ${specs}  L${imp.line}`);
+            }
+            lines.push('');
+        }
+        // 被谁引用
+        if (ctx.importedBy.length > 0) {
+            lines.push(`### 📤 被引用 (${ctx.importedBy.length})`);
+            for (const by of ctx.importedBy) {
+                const specs = by.specifiers.length > 0 ? `{ ${by.specifiers.join(', ')} }` : '';
+                lines.push(`  ← ${by.filePath}  ${specs}`);
+            }
+            lines.push('');
+        }
+        return wrap(lines.join('\n'));
+    }));
+}

package/dist/tools/discussion.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 💬 kg_discuss (6→1)
+ * 合并: kg_discussion_list, kg_discussion_read, kg_discussion_create,
+ *       kg_discussion_reply, kg_discussion_close_and_archive, kg_discussion_delete
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDiscussionTools(server: McpServer, projectId: string): void;

package/dist/tools/discussion.js

@@ -0,0 +1,111 @@
+/**
+ * 💬 kg_discuss (6→1)
+ * 合并: kg_discussion_list, kg_discussion_read, kg_discussion_create,
+ *       kg_discussion_reply, kg_discussion_close_and_archive, kg_discussion_delete
+ */
+import { z } from 'zod';
+import { getClient } from '../storage/httpClient.js';
+import { decodeObjectStrings } from '../utils.js';
+import { wrap, safeTool } from './shared.js';
+import { DiscussionManager } from '../storage/discussion.js';
+export function registerDiscussionTools(server, projectId) {
+    const client = () => getClient();
+    server.tool('kg_discuss', '💬 跨项目讨论 — 发起、回复、归档协同讨论。action: list(列出活跃讨论)|read(读取详情)|create(发起)|reply(回复)|close(结案归档)|delete(删除)', {
+        action: z.enum(['list', 'read', 'create', 'reply', 'close', 'delete'])
+            .describe('操作类型'),
+        id: z.string().optional()
+            .describe('讨论哈希ID (read/reply/close/delete)'),
+        ids: z.array(z.string()).optional()
+            .describe('批量读取的讨论ID数组 (read)'),
+        title: z.string().optional()
+            .describe('讨论标题 (create)'),
+        participants: z.array(z.string()).optional()
+            .describe('参与项目ID数组 (create, 不含自己)'),
+        content: z.string().optional()
+            .describe('消息内容Markdown (create/reply)'),
+        conclusion: z.string().optional()
+            .describe('结案总结 (close)'),
+        newSummary: z.string().optional()
+            .describe('更新进展摘要 (reply)'),
+    }, async (args) => safeTool(async () => {
+        const decoded = decodeObjectStrings(args);
+        switch (decoded.action) {
+            case 'list': {
+                const cleaned = DiscussionManager.cleanExpired(7);
+                const active = DiscussionManager.listActive();
+                const cleanMsg = cleaned > 0 ? `\n⚠️ 已自动清理 ${cleaned} 条超过7天不活跃的讨论` : '';
+                if (active.length === 0)
+                    return wrap(`当前无活跃的讨论 (本项目ID: ${projectId})${cleanMsg}`);
+                return wrap(`本项目ID: ${projectId}\n活跃讨论区 (${active.length} 个):${cleanMsg}\n\n` + JSON.stringify(active, null, 2));
+            }
+            case 'read': {
+                const readIds = decoded.ids || (decoded.id ? [decoded.id] : []);
+                if (readIds.length === 0)
+                    return wrap('❌ read 需要 id 或 ids');
+                const discussions = DiscussionManager.readByIds(readIds);
+                if (discussions.length === 0)
+                    return wrap('未找到对应的讨论记录');
+                return wrap(JSON.stringify(discussions, null, 2));
+            }
+            case 'create': {
+                if (!decoded.title)
+                    return wrap('❌ create 需要 title');
+                if (!decoded.participants)
+                    return wrap('❌ create 需要 participants');
+                if (!decoded.content)
+                    return wrap('❌ create 需要 content');
+                const count = DiscussionManager.activeCount();
+                if (count >= 10)
+                    return wrap('❌ 活跃讨论已达上限(10条)');
+                const id = DiscussionManager.create(decoded.title, projectId, decoded.participants, decoded.content);
+                return wrap(`✅ 讨论已发起，ID: ${id}\n发起方: ${projectId}\n参与方: ${decoded.participants.join(', ')}`);
+            }
+            case 'reply': {
+                if (!decoded.id)
+                    return wrap('❌ reply 需要 id');
+                if (!decoded.content)
+                    return wrap('❌ reply 需要 content');
+                const success = DiscussionManager.reply(decoded.id, projectId, decoded.content, decoded.newSummary);
+                return wrap(success ? `✅ 回复成功 (ID: ${decoded.id})` : `❌ 回复失败，讨论不存在或已关闭`);
+            }
+            case 'close': {
+                if (!decoded.id)
+                    return wrap('❌ close 需要 id');
+                if (!decoded.conclusion)
+                    return wrap('❌ close 需要 conclusion');
+                const topic = DiscussionManager.getAndRemove(decoded.id);
+                if (!topic)
+                    return wrap('❌ 讨论不存在或已被归档清理');
+                let md = `# 跨项目协同: ${topic.title}\n\n`;
+                md += `**发起方**: ${topic.initiator}\n`;
+                md += `**参与方**: ${topic.participants.join(', ')}\n`;
+                md += `**结案总结**: ${decoded.conclusion}\n\n`;
+                md += `## 讨论还原 (Timeline)\n\n`;
+                for (const msg of topic.messages) {
+                    md += `### [${msg.sender}] (${msg.timestamp})\n${msg.content}\n\n`;
+                }
+                const safeTitle = topic.title.replace(/[\/\\?%*:|"<>]/g, '_');
+                const path = `/跨项目协同记录/${decoded.id}_${safeTitle}`;
+                try {
+                    await client().createDoc(path, {
+                        summary: decoded.conclusion, content: md,
+                        versions: [{ version: 1.0, date: new Date().toISOString(), changes: '结案归档' }],
+                        bugfixes: [], status: '已完成'
+                    });
+                    return wrap(`✅ 讨论已结案并归档: \`${path}\``);
+                }
+                catch (err) {
+                    return wrap(`⚠️ 讨论已清除，但归档失败: ${err}\n\n${md}`);
+                }
+            }
+            case 'delete': {
+                if (!decoded.id)
+                    return wrap('❌ delete 需要 id');
+                const success = DiscussionManager.delete(decoded.id);
+                return wrap(success ? `✅ 讨论已删除 (ID: ${decoded.id})` : `❌ 讨论不存在或已被删除`);
+            }
+            default:
+                return wrap(`❌ 未知 action: ${decoded.action}`);
+        }
+    }));
+}

package/dist/tools/docs.d.ts

@@ -1,7 +1,7 @@
 /**
- * 文档管理工具 (7个)
- * kg_create_node, kg_delete_node, kg_update_node, kg_read_node,
- * kg_get_tree, kg_get_docs_by_status, kg_copy_node
+ * 📄 kg_doc (5合1) + 🏗️ kg_tree (2合1)
+ * 合并: kg_create_node, kg_delete_node, kg_update_node, kg_read_node, kg_copy_node
+ *       kg_get_tree, kg_get_docs_by_status
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function registerDocTools(server: McpServer, projectId: string): void;