@ppdocs/mcp 3.1.8 → 3.1.10

package/dist/tools/index.js

@@ -1,637 +1,16 @@
-import { z } from 'zod';
-import * as storage from '../storage/httpClient.js';
-import { decodeObjectStrings, getRules, RULE_TYPE_LABELS } from '../utils.js';
-import { wrap, formatDocMarkdown, formatTreeText, countTreeDocs, formatFileSize } from './helpers.js';
-export function registerTools(server, projectId, _user) {
-    // ===================== 跨项目访问 =====================
-    // 0. 列出所有可访问的项目
-    server.tool('kg_list_projects', '列出所有可访问的项目(返回name和id)。跨项目操作的第一步：先调用此工具获取项目ID，再作为其他工具的targetProject参数', {}, async () => {
-        try {
-            const projects = await storage.crossListProjects();
-            if (projects.length === 0) {
-                return wrap('暂无可访问的项目');
-            }
-            const lines = projects.map(p => {
-                const isCurrent = p.id === projectId ? ' ★当前' : '';
-                return `- ${p.name} (${p.id})${isCurrent}`;
-            });
-            return wrap(`可访问的项目 (${projects.length} 个):\n\n${lines.join('\n')}`);
-        }
-        catch (e) {
-            return wrap(`获取项目列表失败: ${String(e)}`);
-        }
-    });
-    // 0.1 创建项目
-    server.tool('kg_create_project', '创建新项目。返回项目ID和密码(密码用于MCP连接)', {
-        id: z.string().describe('项目ID(英文/数字/中文，如"my-app")'),
-        name: z.string().describe('项目名称'),
-        description: z.string().optional().describe('项目简介'),
-        projectPath: z.string().optional().describe('项目源码路径(本地绝对路径)'),
-    }, async (args) => {
-        try {
-            const result = await storage.createProject(args.id, args.name, args.description, args.projectPath || process.cwd());
-            return wrap(`✅ 项目创建成功\n\n- 项目ID: ${result.project.id}\n- 项目名: ${result.project.name}\n- 密码: ${result.password}\n\nMCP 连接地址: http://<服务器IP>:20001/api/${result.project.id}/${result.password}`);
-        }
-        catch (e) {
-            return wrap(`❌ ${String(e)}`);
-        }
-    });
-    // ===================== 文档管理 =====================
-    // 1. 创建文档
-    server.tool('kg_create_node', '创建知识文档。使用目录路径分类，文件名作为文档名', {
-        path: z.string().min(1).describe('完整文档路径(如"/前端/组件/Modal")'),
-        summary: z.string().optional().describe('一句话简介'),
-        content: z.string().describe('Markdown内容'),
-        status: z.string().optional().describe('文档状态(默认"已完成")')
-    }, async (args) => {
-        const decoded = decodeObjectStrings(args);
-        const doc = await storage.createDoc(projectId, decoded.path, {
-            summary: decoded.summary || '',
-            content: decoded.content,
-            versions: [{
-                    version: 0.1,
-                    date: new Date().toISOString(),
-                    changes: '初始创建'
-                }],
-            bugfixes: [],
-            status: decoded.status || '已完成'
-        });
-        return wrap(`✅ 文档已创建: ${decoded.path}\n\n${JSON.stringify(doc, null, 2)}`);
-    });
-    // 2. 删除文档或目录 (支持批量)
-    server.tool('kg_delete_node', '删除文档或目录(支持批量，根不可删除，目录会递归删除)', { nodeId: z.union([z.string(), z.array(z.string())]).describe('文档路径或路径数组') }, async (args) => {
-        const paths = Array.isArray(args.nodeId) ? args.nodeId : [args.nodeId];
-        const results = [];
-        for (const path of paths) {
-            const success = await storage.deleteDoc(projectId, path);
-            results.push({ path, success });
-        }
-        const successCount = results.filter(r => r.success).length;
-        const failedPaths = results.filter(r => !r.success).map(r => r.path);
-        if (paths.length === 1) {
-            return wrap(results[0].success ? '删除成功' : '删除失败(文档不存在或是根文档)');
-        }
-        let msg = `✅ 批量删除完成: ${successCount}/${paths.length} 成功`;
-        if (failedPaths.length > 0) {
-            msg += `\n❌ 失败: ${failedPaths.join(', ')}`;
-        }
-        return wrap(msg);
-    });
-    // 3. 更新文档 (支持单个/批量两种模式)
-    server.tool('kg_update_node', '更新文档内容。【单个模式】nodeId+字段；【批量模式】仅传updates数组。两种模式二选一', {
-        nodeId: z.string().optional().describe('【单个模式】文档路径，如"/前端/组件/Button"'),
-        summary: z.string().optional().describe('【单个模式】一句话简介'),
-        content: z.string().optional().describe('【单个模式】Markdown内容'),
-        status: z.string().optional().describe('【单个模式】文档状态'),
-        versions: z.array(z.object({
-            version: z.number(),
-            date: z.string(),
-            changes: z.string()
-        })).optional().describe('【单个模式】版本记录数组'),
-        bugfixes: z.array(z.object({
-            date: z.string(),
-            issue: z.string(),
-            solution: z.string()
-        })).optional().describe('【单个模式】修复记录数组'),
-        updates: z.array(z.object({
-            nodeId: z.string().describe('文档路径'),
-            summary: z.string().optional(),
-            content: z.string().optional(),
-            status: z.string().optional(),
-            versions: z.array(z.object({
-                version: z.number(),
-                date: z.string(),
-                changes: z.string()
-            })).optional(),
-            bugfixes: z.array(z.object({
-                date: z.string(),
-                issue: z.string(),
-                solution: z.string()
-            })).optional()
-        })).optional().describe('【批量模式】更新数组，每项包含nodeId和要更新的字段')
-    }, async (args) => {
-        const decoded = decodeObjectStrings(args);
-        // 批量更新模式: 使用 updates 数组
-        if (decoded.updates && Array.isArray(decoded.updates)) {
-            const results = [];
-            for (const item of decoded.updates) {
-                if (item.nodeId === '/' || item.nodeId === '_root') {
-                    results.push({ path: item.nodeId, success: false });
-                    continue;
-                }
-                const existing = await storage.getDoc(projectId, item.nodeId);
-                if (!existing) {
-                    results.push({ path: item.nodeId, success: false });
-                    continue;
-                }
-                const updates = {};
-                if (item.summary !== undefined)
-                    updates.summary = item.summary;
-                if (item.content !== undefined)
-                    updates.content = item.content;
-                if (item.status !== undefined)
-                    updates.status = item.status;
-                if (item.versions !== undefined)
-                    updates.versions = item.versions;
-                if (item.bugfixes !== undefined)
-                    updates.bugfixes = item.bugfixes;
-                const doc = await storage.updateDoc(projectId, item.nodeId, updates);
-                results.push({ path: item.nodeId, success: !!doc });
-            }
-            const successCount = results.filter(r => r.success).length;
-            const failedPaths = results.filter(r => !r.success).map(r => r.path);
-            let msg = `✅ 批量更新完成: ${successCount}/${decoded.updates.length} 成功`;
-            if (failedPaths.length > 0) {
-                msg += `\n❌ 失败: ${failedPaths.join(', ')}`;
-            }
-            return wrap(msg);
-        }
-        // 单个更新模式: 必须提供 nodeId
-        const { nodeId, summary, content, status, versions, bugfixes } = decoded;
-        if (!nodeId) {
-            return wrap('❌ 请提供 nodeId（单个模式）或 updates 数组（批量模式）');
-        }
-        // 根文档必须使用 kg_update_root 更新
-        if (nodeId === '/' || nodeId === '_root') {
-            return wrap('❌ 根文档请使用 kg_update_root 方法更新');
-        }
-        // 获取现有文档
-        const existing = await storage.getDoc(projectId, nodeId);
-        if (!existing) {
-            return wrap('更新失败(文档不存在)');
-        }
-        // 构建更新内容
-        const updates = {};
-        if (summary !== undefined)
-            updates.summary = summary;
-        if (content !== undefined)
-            updates.content = content;
-        if (status !== undefined)
-            updates.status = status;
-        if (versions !== undefined)
-            updates.versions = versions;
-        if (bugfixes !== undefined)
-            updates.bugfixes = bugfixes;
-        const doc = await storage.updateDoc(projectId, nodeId, updates);
-        return wrap(doc ? JSON.stringify(doc, null, 2) : '更新失败');
-    });
-    // 3.5 更新根文档 (项目介绍)
-    server.tool('kg_update_root', '更新项目介绍(根文档)', {
-        title: z.string().optional().describe('项目标题'),
-        description: z.string().optional().describe('项目介绍(Markdown)')
-    }, async (args) => {
-        const decoded = decodeObjectStrings(args);
-        if (decoded.title === undefined && decoded.description === undefined) {
-            return wrap('❌ 请至少提供 title 或 description');
-        }
-        const existing = await storage.getDoc(projectId, '/');
-        if (!existing) {
-            return wrap('更新失败(根文档不存在)');
-        }
-        const updates = {};
-        if (decoded.title !== undefined)
-            updates.summary = decoded.title;
-        if (decoded.description !== undefined)
-            updates.content = decoded.description;
-        const doc = await storage.updateDoc(projectId, '/', updates);
-        return wrap(doc ? '✅ 项目介绍已更新' : '更新失败');
-    });
-    // 3.6 获取项目规则
-    server.tool('kg_get_rules', '获取项目规则(可指定类型或获取全部)。支持跨项目只读访问(需先用kg_list_projects获取项目ID)', {
-        ruleType: z.string().optional()
-            .describe('规则类型(如 userStyles, codeStyle, reviewRules, testRules, unitTests, 或自定义类型)。不传则返回全部'),
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
-    }, async (args) => {
-        // 跨项目访问
-        if (args.targetProject) {
-            const crossMeta = await storage.crossGetRulesMeta(args.targetProject);
-            if (args.ruleType) {
-                const rules = await storage.crossGetRules(args.targetProject, args.ruleType);
-                if (rules.length === 0) {
-                    const label = crossMeta[args.ruleType]?.label || args.ruleType;
-                    return { content: [{ type: 'text', text: `暂无${label}规则(项目: ${args.targetProject})` }] };
-                }
-                return { content: [{ type: 'text', text: `[跨项目: ${args.targetProject}]\n\n${rules.join('\n')}` }] };
-            }
-            // 获取全部规则 (从 meta 获取所有类型)
-            const types = Object.keys(crossMeta).length > 0 ? Object.keys(crossMeta) : Object.keys(RULE_TYPE_LABELS);
-            const allRules = [];
-            for (const type of types) {
-                const rules = await storage.crossGetRules(args.targetProject, type);
-                if (rules.length > 0) {
-                    const label = crossMeta[type]?.label || RULE_TYPE_LABELS[type] || type;
-                    allRules.push(`## ${label}\n${rules.join('\n')}`);
-                }
-            }
-            if (allRules.length === 0) {
-                return { content: [{ type: 'text', text: `暂无项目规则(项目: ${args.targetProject})` }] };
-            }
-            return { content: [{ type: 'text', text: `[跨项目: ${args.targetProject}]\n\n${allRules.join('\n\n')}` }] };
-        }
-        // 当前项目
-        const rules = await getRules(projectId, args.ruleType || undefined);
-        if (!rules || rules.trim() === '') {
-            const meta = await storage.getRulesMeta();
-            const typeName = args.ruleType ? (meta[args.ruleType]?.label || args.ruleType) : '项目';
-            return { content: [{ type: 'text', text: `暂无${typeName}规则` }] };
-        }
-        return { content: [{ type: 'text', text: rules }] };
-    });
-    // 3.7 保存项目规则 (自动合并,去重追加)
-    server.tool('kg_save_rules', '保存单个类型的项目规则(自动合并:已有规则保留,新规则去重追加)', {
-        ruleType: z.string()
-            .describe('规则类型(如 userStyles, codeStyle, reviewRules, testRules, unitTests, 或自定义类型)'),
-        rules: z.array(z.string()).describe('规则数组')
-    }, async (args) => {
-        const decoded = decodeObjectStrings(args);
-        const result = await storage.appendRules(projectId, decoded.ruleType, decoded.rules);
-        if (!result.success) {
-            return wrap('❌ 保存失败');
-        }
-        const meta = await storage.getRulesMeta();
-        const label = meta[decoded.ruleType]?.label || decoded.ruleType;
-        return wrap(`✅ ${label}已保存 (新增${result.added}条, 共${result.total}条)`);
-    });
-    // 3.8 获取规则触发配置
-    server.tool('kg_get_rules_meta', '获取规则触发配置(所有类型的标签、关键词、触发数)。用于查看/编辑 hooks 触发条件', {}, async () => {
-        try {
-            const meta = await storage.getRulesMeta();
-            if (Object.keys(meta).length === 0) {
-                return wrap('暂无规则配置');
-            }
-            const lines = Object.entries(meta).map(([type, m]) => {
-                const kw = m.keywords.length > 0 ? m.keywords.join(', ') : '(无)';
-                const trigger = m.always ? '始终触发' : `关键词≥${m.min_hits}: ${kw}`;
-                return `- **${m.label}** (${type}): ${trigger}`;
-            });
-            return wrap(`规则触发配置:\n\n${lines.join('\n')}`);
-        }
-        catch (e) {
-            return wrap(`❌ ${String(e)}`);
-        }
-    });
-    // 3.9 保存规则触发配置 (自动合并)
-    server.tool('kg_save_rules_meta', '保存规则触发配置(自动合并:已有类型更新,新类型创建,其他类型不受影响)', {
-        meta: z.record(z.string(), z.object({
-            label: z.string().describe('规则显示名称'),
-            keywords: z.array(z.string()).default([]).describe('触发关键词列表'),
-            min_hits: z.number().default(1).describe('最低触发关键词数'),
-            always: z.boolean().default(false).describe('是否始终触发(如 userStyles)')
-        })).describe('规则类型 → 触发配置的映射')
-    }, async (args) => {
-        try {
-            const decoded = decodeObjectStrings(args.meta);
-            const result = await storage.mergeRulesMeta(decoded);
-            if (!result.success) {
-                return wrap('❌ 保存失败');
-            }
-            return wrap(`✅ 触发配置已保存 (更新${Object.keys(decoded).length}个类型, 共${result.total}个类型)`);
-        }
-        catch (e) {
-            return wrap(`❌ ${String(e)}`);
-        }
-    });
-    // 3.10 获取全局默认规则触发配置
-    server.tool('kg_get_global_rules_meta', '获取全局默认规则触发配置(新项目创建时继承此配置)', {}, async () => {
-        try {
-            const meta = await storage.getGlobalRulesMeta();
-            if (Object.keys(meta).length === 0) {
-                return wrap('暂无全局默认规则配置');
-            }
-            const lines = Object.entries(meta).map(([type, m]) => {
-                const kw = m.keywords.length > 0 ? m.keywords.join(', ') : '(无)';
-                const trigger = m.always ? '始终触发' : `关键词≥${m.min_hits}: ${kw}`;
-                return `- **${m.label}** (${type}): ${trigger}`;
-            });
-            return wrap(`全局默认规则触发配置:\n\n${lines.join('\n')}`);
-        }
-        catch (e) {
-            return wrap(`❌ ${String(e)}`);
-        }
-    });
-    // 3.11 保存全局默认规则触发配置 (自动合并)
-    server.tool('kg_save_global_rules_meta', '保存全局默认触发配置(自动合并:已有类型更新,新类型创建,其他类型不受影响)', {
-        meta: z.record(z.string(), z.object({
-            label: z.string().describe('规则显示名称'),
-            keywords: z.array(z.string()).default([]).describe('触发关键词列表'),
-            min_hits: z.number().default(1).describe('最低触发关键词数'),
-            always: z.boolean().default(false).describe('是否始终触发(如 userStyles)')
-        })).describe('规则类型 → 触发配置的映射')
-    }, async (args) => {
-        try {
-            const decoded = decodeObjectStrings(args.meta);
-            const result = await storage.mergeGlobalRulesMeta(decoded);
-            if (!result.success) {
-                return wrap('❌ 保存失败');
-            }
-            return wrap(`✅ 全局触发配置已保存 (更新${Object.keys(decoded).length}个类型, 共${result.total}个类型)`);
-        }
-        catch (e) {
-            return wrap(`❌ ${String(e)}`);
-        }
-    });
-    // 5. 读取单个文档详情
-    server.tool('kg_read_node', '读取文档完整内容(简介、正文、版本历史、修复记录)。支持跨项目只读访问(需先用kg_list_projects获取项目ID)', {
-        nodeId: z.string().describe('文档路径'),
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
-    }, async (args) => {
-        // 跨项目访问
-        if (args.targetProject) {
-            const doc = await storage.crossGetDoc(args.targetProject, args.nodeId);
-            if (!doc) {
-                return wrap(`文档不存在(项目: ${args.targetProject})`);
-            }
-            const lines = formatDocMarkdown(doc, args.nodeId);
-            return wrap(`[跨项目: ${args.targetProject}]\n\n${lines.join('\n')}`);
-        }
-        // 当前项目
-        const doc = await storage.getDoc(projectId, args.nodeId);
-        if (!doc) {
-            return wrap('文档不存在');
-        }
-        // 格式化文档
-        const lines = formatDocMarkdown(doc, args.nodeId);
-        return wrap(lines.join('\n'));
-    });
-    // 10. 获取知识库树状图
-    server.tool('kg_get_tree', '获取知识库目录树。格式: 📄 文档名 # 简介。支持跨项目只读访问(需先用kg_list_projects获取项目ID)', {
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
-    }, async (args) => {
-        try {
-            // 跨项目访问
-            if (args.targetProject) {
-                const tree = await storage.crossGetTree(args.targetProject);
-                if (tree && tree.length > 0) {
-                    const treeText = formatTreeText(tree);
-                    const docCount = countTreeDocs(tree);
-                    return wrap(`[跨项目: ${args.targetProject}]\n\n共 ${docCount} 个文档\n\n${treeText}`);
-                }
-                return wrap(`知识库为空(项目: ${args.targetProject})`);
-            }
-            // 当前项目
-            const tree = await storage.getTree(projectId);
-            if (tree && tree.length > 0) {
-                const treeText = formatTreeText(tree);
-                const docCount = countTreeDocs(tree);
-                return wrap(`共 ${docCount} 个文档\n\n${treeText}`);
-            }
-            return wrap('知识库为空');
-        }
-        catch (e) {
-            return wrap(JSON.stringify({
-                error: '无法获取知识库结构',
-                message: String(e),
-                tip: '请确保软件端已启动'
-            }, null, 2));
-        }
-    });
-    // 11. 按状态筛选文档
-    server.tool('kg_get_docs_by_status', '获取指定状态的文档列表。支持跨项目只读访问(需先用kg_list_projects获取项目ID)', {
-        statusList: z.array(z.string()).describe('状态列表(如["未完成","待修复"])'),
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
-    }, async (args) => {
-        // 跨项目访问
-        if (args.targetProject) {
-            const docs = await storage.crossGetDocsByStatus(args.targetProject, args.statusList);
-            if (docs.length === 0) {
-                return wrap(`未找到状态为 [${args.statusList.join(', ')}] 的文档(项目: ${args.targetProject})`);
-            }
-            const lines = docs.map(d => `- ${d.path} (${d.status || '已完成'}): ${d.summary || '无简介'}`);
-            return wrap(`[跨项目: ${args.targetProject}]\n\n找到 ${docs.length} 个文档:\n\n${lines.join('\n')}`);
-        }
-        // 当前项目
-        const docs = await storage.getDocsByStatus(projectId, args.statusList);
-        if (docs.length === 0) {
-            return wrap(`未找到状态为 [${args.statusList.join(', ')}] 的文档`);
-        }
-        const lines = docs.map(d => `- ${d.path} (${d.status || '已完成'}): ${d.summary || '无简介'}`);
-        return wrap(`找到 ${docs.length} 个文档:\n\n${lines.join('\n')}`);
-    });
-    // 12. 跨项目复制文档到当前项目
-    server.tool('kg_copy_node', '从其他项目复制文档到当前项目。支持单个或批量复制，可指定新路径。用于跨项目协作：拉取别的项目的知识文档到当前项目', {
-        sourceProject: z.string().describe('源项目ID或名称(从kg_list_projects获取)'),
-        sourcePath: z.union([z.string(), z.array(z.string())]).describe('源文档路径(单个或数组，如"/架构/数据流"或["/架构/数据流","/MCP/tools"])'),
-        targetPath: z.string().optional().describe('目标路径前缀(如"/参考/项目B")。不填则保持原路径'),
-    }, async (args) => {
-        const decoded = decodeObjectStrings(args);
-        const paths = Array.isArray(decoded.sourcePath) ? decoded.sourcePath : [decoded.sourcePath];
-        const results = [];
-        for (const srcPath of paths) {
-            try {
-                // 从源项目读取文档
-                const doc = await storage.crossGetDoc(decoded.sourceProject, srcPath);
-                if (!doc) {
-                    results.push({ path: srcPath, success: false, error: '源文档不存在' });
-                    continue;
-                }
-                // 计算目标路径
-                const destPath = decoded.targetPath
-                    ? `${decoded.targetPath.replace(/\/$/, '')}${srcPath}`
-                    : srcPath;
-                // 检查目标是否已存在
-                const existing = await storage.getDoc(projectId, destPath);
-                if (existing) {
-                    // 已存在则更新
-                    await storage.updateDoc(projectId, destPath, {
-                        summary: doc.summary,
-                        content: doc.content,
-                    });
-                    results.push({ path: destPath, success: true });
-                }
-                else {
-                    // 不存在则创建
-                    await storage.createDoc(projectId, destPath, {
-                        summary: doc.summary,
-                        content: doc.content,
-                        status: doc.status,
-                    });
-                    results.push({ path: destPath, success: true });
-                }
-            }
-            catch (e) {
-                results.push({ path: srcPath, success: false, error: String(e) });
-            }
-        }
-        const successCount = results.filter(r => r.success).length;
-        const failedItems = results.filter(r => !r.success);
-        if (paths.length === 1) {
-            if (results[0].success) {
-                return wrap(`✅ 已复制文档: ${results[0].path}\n\n来源: [${decoded.sourceProject}] ${paths[0]}`);
-            }
-            return wrap(`❌ 复制失败: ${results[0].error}`);
-        }
-        let msg = `✅ 批量复制完成: ${successCount}/${paths.length} 成功`;
-        if (failedItems.length > 0) {
-            msg += `\n❌ 失败:\n${failedItems.map(f => `  - ${f.path}: ${f.error}`).join('\n')}`;
-        }
-        return wrap(msg);
-    });
-    // ===================== 任务管理 =====================
-    // 7. 创建任务
-    server.tool('task_create', '创建开发任务', {
-        title: z.string().describe('任务标题'),
-        description: z.string().describe('任务描述(Markdown)'),
-        goals: z.array(z.string()).optional().describe('目标清单')
-    }, async (args) => {
-        const decoded = decodeObjectStrings(args);
-        const task = await storage.createTask(projectId, {
-            title: decoded.title,
-            description: decoded.description,
-            goals: decoded.goals || []
-        }, _user);
-        return wrap(JSON.stringify(task, null, 2));
-    });
-    // 8. 读取任务
-    server.tool('task_get', '读取任务详情(按名字搜索，支持当前任务和历史任务)', {
-        title: z.string().describe('任务名称(模糊匹配)'),
-        status: z.enum(['active', 'archived', 'all']).optional().describe('状态筛选: active=进行中, archived=已归档, all=全部(默认)')
-    }, async (args) => {
-        const status = args.status || 'all';
-        const searchTitle = args.title.toLowerCase();
-        // 获取任务列表
-        let tasks;
-        if (status === 'all') {
-            const [active, archived] = await Promise.all([
-                storage.listTasks(projectId, 'active'),
-                storage.listTasks(projectId, 'archived')
-            ]);
-            tasks = [...active, ...archived];
-        }
-        else {
-            tasks = await storage.listTasks(projectId, status);
-        }
-        // 按名字模糊匹配
-        const matched = tasks.filter(t => t.title.toLowerCase().includes(searchTitle));
-        if (matched.length === 0) {
-            return wrap(`未找到匹配 "${args.title}" 的任务`);
-        }
-        // 如果只有一个匹配，返回完整详情
-        if (matched.length === 1) {
-            const task = await storage.getTask(projectId, matched[0].id);
-            return wrap(task ? JSON.stringify(task, null, 2) : '任务详情获取失败');
-        }
-        // 多个匹配，返回列表让用户选择
-        const list = matched.map(t => ({
-            id: t.id,
-            title: t.title,
-            status: t.status,
-            creator: t.creator,
-            created_at: t.created_at
-        }));
-        return wrap(`找到 ${matched.length} 个匹配任务:\n${JSON.stringify(list, null, 2)}\n\n请提供更精确的任务名称`);
-    });
-    // 9. 更新任务
-    server.tool('task_update', '更新任务(添加进展日志)', {
-        taskId: z.string().describe('任务ID'),
-        log_type: z.enum(['progress', 'issue', 'solution', 'reference']).describe('日志类型: progress=进展, issue=问题, solution=方案, reference=参考'),
-        content: z.string().describe('日志内容(Markdown)')
-    }, async (args) => {
-        const decoded = decodeObjectStrings(args);
-        const task = await storage.addTaskLog(projectId, args.taskId, decoded.log_type, decoded.content);
-        if (!task) {
-            return wrap('更新失败(任务不存在或已归档)');
-        }
-        return wrap(`✅ 日志已添加，任务共有 ${task.logs.length} 条日志`);
-    });
-    // 10. 归档任务
-    server.tool('task_archive', '归档任务(完成并填写经验总结)', {
-        taskId: z.string().describe('任务ID'),
-        summary: z.string().describe('经验总结(Markdown)'),
-        difficulties: z.array(z.string()).optional().describe('遇到的困难'),
-        solutions: z.array(z.string()).optional().describe('解决方案')
-    }, async (args) => {
-        const decoded = decodeObjectStrings(args);
-        const task = await storage.completeTask(projectId, args.taskId, {
-            summary: decoded.summary,
-            difficulties: decoded.difficulties || [],
-            solutions: decoded.solutions || [],
-            references: []
-        });
-        if (!task) {
-            return wrap('归档失败(任务不存在或已归档)');
-        }
-        return wrap(`✅ 任务已归档: ${task.title}`);
-    });
-    // ===================== 项目文件访问 =====================
-    // 上传本地目录到中心服务器
-    server.tool('project_upload', '上传本地项目目录到中心服务器(打包zip上传，自动排除node_modules/.git等)。上传后其他客户端可通过跨项目访问下载', {
-        localDir: z.string().describe('本地目录的绝对路径(如"/home/user/project/src")'),
-        remoteDir: z.string().optional().describe('上传到服务器的目标子目录(如"src")，不填则上传到根目录'),
-    }, async (args) => {
-        try {
-            const result = await storage.uploadFiles(args.localDir, args.remoteDir);
-            return wrap(`✅ 上传成功\n\n- 文件数量: ${result.fileCount}\n- 目标目录: ${args.remoteDir || '/'}\n\n其他客户端可通过 project_read_file / project_download_dir 访问`);
-        }
-        catch (e) {
-            return wrap(`❌ ${String(e)}`);
-        }
-    });
-    // 清空项目文件存储区
-    server.tool('project_clear_files', '清空当前项目在中心服务器上的文件存储区', {}, async () => {
-        try {
-            await storage.clearFiles();
-            return wrap('✅ 文件存储已清空');
-        }
-        catch (e) {
-            return wrap(`❌ ${String(e)}`);
-        }
-    });
-    // 列出项目文件
-    server.tool('project_list_files', '浏览项目源码目录结构(仅列出文件名和大小，不读内容)。目标项目需已上传文件或关联源码目录。跨项目时先用kg_list_projects获取项目ID。查看文件内容请用project_read_file', {
-        dir: z.string().optional().describe('子目录路径(如"src/components")，不填则列出根目录'),
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
-    }, async (args) => {
-        try {
-            const files = args.targetProject
-                ? await storage.crossListFiles(args.targetProject, args.dir)
-                : await storage.listFiles(args.dir);
-            if (files.length === 0) {
-                return wrap('目录为空');
-            }
-            const lines = files.map(f => {
-                const icon = f.isDir ? '📁' : '📄';
-                const size = f.isDir ? '' : ` (${formatFileSize(f.size)})`;
-                return `${icon} ${f.name}${size}`;
-            });
-            const prefix = args.targetProject ? `[跨项目: ${args.targetProject}]\n\n` : '';
-            const dirLabel = args.dir || '/';
-            return wrap(`${prefix}📂 ${dirLabel} (${files.length} 项)\n\n${lines.join('\n')}`);
-        }
-        catch (e) {
-            return wrap(`❌ ${String(e)}`);
-        }
-    });
-    // 读取项目文件
-    server.tool('project_read_file', '读取单个源码文件的文本内容(限1MB)。适合查看具体代码实现。跨项目时先用kg_list_projects获取项目ID。浏览目录结构请用project_list_files', {
-        path: z.string().describe('文件路径(如"src/main.ts")'),
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
-    }, async (args) => {
-        try {
-            const content = args.targetProject
-                ? await storage.crossReadFile(args.targetProject, args.path)
-                : await storage.readFile(args.path);
-            const prefix = args.targetProject ? `[跨项目: ${args.targetProject}]\n\n` : '';
-            return wrap(`${prefix}📄 ${args.path}\n\n\`\`\`\n${content}\n\`\`\``);
-        }
-        catch (e) {
-            return wrap(`❌ ${String(e)}`);
-        }
-    });
-    // 下载项目文件或目录 (zip → 自动解压)
-    server.tool('project_download', '下载项目源码到本地(自动识别文件/目录，打包zip解压)。目标项目需已上传文件或关联源码目录。跨项目时先用kg_list_projects获取项目ID', {
-        remotePath: z.string().describe('远程路径，可以是目录(如"src")或单个文件(如"src/main.ts")'),
-        localPath: z.string().optional().describe('本地保存路径(不填则保存到系统临时目录，目录不存在会自动创建)'),
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
-    }, async (args) => {
-        try {
-            const result = args.targetProject
-                ? await storage.crossDownload(args.targetProject, args.remotePath, args.localPath)
-                : await storage.download(args.remotePath, args.localPath);
-            const prefix = args.targetProject ? `[跨项目: ${args.targetProject}]\n\n` : '';
-            return wrap(`${prefix}✅ 已下载并解压\n\n- 本地路径: ${result.localPath}\n- 文件数量: ${result.fileCount}`);
-        }
-        catch (e) {
-            return wrap(`❌ ${String(e)}`);
-        }
-    });
+/**
+ * MCP 工具注册入口
+ * 将 25 个工具拆分为 5 个子模块，统一在此注册
+ */
+import { registerDocTools } from './docs.js';
+import { registerRuleTools } from './rules.js';
+import { registerTaskTools } from './tasks.js';
+import { registerFileTools } from './files.js';
+import { registerProjectTools } from './projects.js';
+export function registerTools(server, projectId, user) {
+    registerProjectTools(server, projectId);
+    registerDocTools(server, projectId);
+    registerRuleTools(server, projectId);
+    registerTaskTools(server, projectId, user);
+    registerFileTools(server);
 }

package/dist/tools/projects.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 项目管理工具 (3个)
+ * kg_list_projects, kg_create_project, kg_update_root
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerProjectTools(server: McpServer, projectId: string): void;