@ppdocs/mcp 3.1.7 → 3.1.9

package/dist/cli.js

@@ -356,13 +356,22 @@ function createMcpConfigAt(mcpPath, apiUrl) {
     }
     // Windows 需要 cmd /c 包装才能执行 npx
     const isWindows = process.platform === 'win32';
-    const ppdocsServer = {
-        command: isWindows ? 'cmd' : 'npx',
-        args: isWindows ? ['/c', 'npx', '-y', '@ppdocs/mcp@latest'] : ['-y', '@ppdocs/mcp@latest'],
-        env: {
-            "PPDOCS_API_URL": apiUrl
-        }
-    };
+    // 对于 Mac/Linux，IDE 可能没有用户的完整 PATH，导致找不到 npx
+    const ppdocsServer = isWindows
+        ? {
+            command: 'cmd',
+            args: ['/c', 'npx', '-y', '@ppdocs/mcp@latest'],
+            env: { "PPDOCS_API_URL": apiUrl }
+        }
+        : {
+            command: 'npx',
+            args: ['-y', '@ppdocs/mcp@latest'],
+            env: {
+                "PPDOCS_API_URL": apiUrl,
+                // 强行注入常见路径，防止找不到 node/npx
+                "PATH": "$PATH:/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:$HOME/.nvm/versions/node/current/bin:$HOME/.local/share/fnm/aliases/default/bin"
+            }
+        };
     mcpConfig.mcpServers = {
         ...(mcpConfig.mcpServers || {}),
         "ppdocs-kg": ppdocsServer,

package/dist/config.d.ts

@@ -7,7 +7,7 @@ export interface PpdocsConfig {
     projectId: string;
     user: string;
 }
-export declare const PPDOCS_DIR = ".ppdocs";
+export declare const PPDOCS_CONFIG_FILE = ".ppdocs";
 /** 生成随机用户名 (8位字母数字) */
 export declare function generateUser(): string;
 /**

package/dist/config.js

@@ -4,7 +4,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-export const PPDOCS_DIR = '.ppdocs';
+export const PPDOCS_CONFIG_FILE = '.ppdocs';
 /** 生成随机用户名 (8位字母数字) */
 export function generateUser() {
     const chars = 'abcdefghjkmnpqrstuvwxyz23456789';

package/dist/storage/httpClient.d.ts

@@ -99,74 +99,4 @@ export declare class PpdocsApiClient {
 }
 export declare function initClient(apiUrl: string): void;
 export declare function getClient(): PpdocsApiClient;
-export declare function listDocs(_projectId: string): Promise<DocNode[]>;
-export declare function getDoc(_projectId: string, docPath: string): Promise<DocData | null>;
-export declare function createDoc(_projectId: string, docPath: string, doc: Partial<DocData>): Promise<DocData>;
-export declare function updateDoc(_projectId: string, docPath: string, updates: Partial<DocData>): Promise<DocData | null>;
-export declare function deleteDoc(_projectId: string, docPath: string): Promise<boolean>;
-export declare function searchDocs(_projectId: string, keywords: string[], limit?: number): Promise<DocSearchResult[]>;
-export declare function getDocsByStatus(_projectId: string, statusList: string[]): Promise<DocNode[]>;
-export declare function getTree(_projectId: string): Promise<TreeNode[]>;
-export declare function getRules(_projectId: string, ruleType: string): Promise<string[]>;
-export declare function saveRules(_projectId: string, ruleType: string, rules: string[]): Promise<boolean>;
-export declare function appendRules(_projectId: string, ruleType: string, newRules: string[]): Promise<{
-    success: boolean;
-    total: number;
-    added: number;
-}>;
-export declare function getRulesMeta(): Promise<Record<string, RuleMeta>>;
-export declare function saveRulesMeta(meta: Record<string, RuleMeta>): Promise<boolean>;
-export declare function mergeRulesMeta(newMeta: Record<string, RuleMeta>): Promise<{
-    success: boolean;
-    total: number;
-}>;
-export declare function crossGetRulesMeta(target: string): Promise<Record<string, RuleMeta>>;
-export declare function getGlobalRulesMeta(): Promise<Record<string, RuleMeta>>;
-export declare function saveGlobalRulesMeta(meta: Record<string, RuleMeta>): Promise<boolean>;
-export declare function mergeGlobalRulesMeta(newMeta: Record<string, RuleMeta>): Promise<{
-    success: boolean;
-    total: number;
-}>;
-export declare function listTasks(_projectId: string, status?: 'active' | 'archived'): Promise<TaskSummary[]>;
-export declare function getTask(_projectId: string, taskId: string): Promise<Task | null>;
-export declare function createTask(_projectId: string, task: {
-    title: string;
-    description: string;
-    goals: string[];
-}, creator: string): Promise<Task>;
-export declare function addTaskLog(_projectId: string, taskId: string, logType: TaskLogType, content: string): Promise<Task | null>;
-export declare function completeTask(_projectId: string, taskId: string, experience: TaskExperience): Promise<Task | null>;
-export declare function createProject(id: string, name: string, description?: string, projectPath?: string): Promise<{
-    project: {
-        id: string;
-        name: string;
-    };
-    password: string;
-}>;
-export declare function crossListProjects(): Promise<{
-    id: string;
-    name: string;
-    description: string;
-    updatedAt: string;
-}[]>;
-export declare function crossGetDoc(target: string, docPath: string): Promise<DocData | null>;
-export declare function crossGetTree(target: string): Promise<TreeNode[]>;
-export declare function crossGetDocsByStatus(target: string, statusList: string[]): Promise<DocNode[]>;
-export declare function crossGetRules(target: string, ruleType: string): Promise<string[]>;
-export declare function listFiles(dir?: string): Promise<FileInfo[]>;
-export declare function readFile(filePath: string): Promise<string>;
-export declare function download(remotePath: string, localPath?: string): Promise<{
-    localPath: string;
-    fileCount: number;
-}>;
-export declare function crossListFiles(target: string, dir?: string): Promise<FileInfo[]>;
-export declare function crossReadFile(target: string, filePath: string): Promise<string>;
-export declare function crossDownload(target: string, remotePath: string, localPath?: string): Promise<{
-    localPath: string;
-    fileCount: number;
-}>;
-export declare function uploadFiles(localDir: string, remoteDir?: string): Promise<{
-    fileCount: number;
-}>;
-export declare function clearFiles(): Promise<void>;
 export type { TreeNode };

package/dist/storage/httpClient.js

@@ -492,131 +492,3 @@ export function getClient() {
     }
     return client;
 }
-// ============ 文档管理 ============
-export async function listDocs(_projectId) {
-    return getClient().listDocs();
-}
-export async function getDoc(_projectId, docPath) {
-    return getClient().getDoc(docPath);
-}
-export async function createDoc(_projectId, docPath, doc) {
-    return getClient().createDoc(docPath, doc);
-}
-export async function updateDoc(_projectId, docPath, updates) {
-    return getClient().updateDoc(docPath, updates);
-}
-export async function deleteDoc(_projectId, docPath) {
-    return getClient().deleteDoc(docPath);
-}
-export async function searchDocs(_projectId, keywords, limit) {
-    return getClient().searchDocs(keywords, limit);
-}
-export async function getDocsByStatus(_projectId, statusList) {
-    return getClient().getDocsByStatus(statusList);
-}
-export async function getTree(_projectId) {
-    return getClient().getTree();
-}
-// ============ 规则管理 ============
-export async function getRules(_projectId, ruleType) {
-    return getClient().getRulesApi(ruleType);
-}
-export async function saveRules(_projectId, ruleType, rules) {
-    return getClient().saveRulesApi(ruleType, rules);
-}
-export async function appendRules(_projectId, ruleType, newRules) {
-    const existing = await getClient().getRulesApi(ruleType);
-    const existingSet = new Set(existing.map(r => r.trim()));
-    const toAdd = newRules.filter(r => !existingSet.has(r.trim()));
-    const merged = [...existing, ...toAdd];
-    const success = await getClient().saveRulesApi(ruleType, merged);
-    return { success, total: merged.length, added: toAdd.length };
-}
-export async function getRulesMeta() {
-    return getClient().getRulesMeta();
-}
-export async function saveRulesMeta(meta) {
-    return getClient().saveRulesMeta(meta);
-}
-export async function mergeRulesMeta(newMeta) {
-    const existing = await getClient().getRulesMeta();
-    const merged = { ...existing, ...newMeta };
-    const success = await getClient().saveRulesMeta(merged);
-    return { success, total: Object.keys(merged).length };
-}
-export async function crossGetRulesMeta(target) {
-    return getClient().crossGetRulesMeta(target);
-}
-export async function getGlobalRulesMeta() {
-    return getClient().getGlobalRulesMeta();
-}
-export async function saveGlobalRulesMeta(meta) {
-    return getClient().saveGlobalRulesMeta(meta);
-}
-export async function mergeGlobalRulesMeta(newMeta) {
-    const existing = await getClient().getGlobalRulesMeta();
-    const merged = { ...existing, ...newMeta };
-    const success = await getClient().saveGlobalRulesMeta(merged);
-    return { success, total: Object.keys(merged).length };
-}
-// ============ 任务管理 ============
-export async function listTasks(_projectId, status) {
-    return getClient().listTasks(status);
-}
-export async function getTask(_projectId, taskId) {
-    return getClient().getTask(taskId);
-}
-export async function createTask(_projectId, task, creator) {
-    return getClient().createTask(task, creator);
-}
-export async function addTaskLog(_projectId, taskId, logType, content) {
-    return getClient().addTaskLog(taskId, logType, content);
-}
-export async function completeTask(_projectId, taskId, experience) {
-    return getClient().completeTask(taskId, experience);
-}
-// ============ 项目管理 ============
-export async function createProject(id, name, description, projectPath) {
-    return getClient().createProject(id, name, description, projectPath);
-}
-// ============ 跨项目只读访问 ============
-export async function crossListProjects() {
-    return getClient().crossListProjects();
-}
-export async function crossGetDoc(target, docPath) {
-    return getClient().crossGetDoc(target, docPath);
-}
-export async function crossGetTree(target) {
-    return getClient().crossGetTree(target);
-}
-export async function crossGetDocsByStatus(target, statusList) {
-    return getClient().crossGetDocsByStatus(target, statusList);
-}
-export async function crossGetRules(target, ruleType) {
-    return getClient().crossGetRules(target, ruleType);
-}
-// ============ 项目文件访问 ============
-export async function listFiles(dir) {
-    return getClient().listFiles(dir);
-}
-export async function readFile(filePath) {
-    return getClient().readFile(filePath);
-}
-export async function download(remotePath, localPath) {
-    return getClient().download(remotePath, localPath);
-}
-export async function crossListFiles(target, dir) {
-    return getClient().crossListFiles(target, dir);
-}
-export async function crossReadFile(target, filePath) {
-    return getClient().crossReadFile(target, filePath);
-}
-export async function crossDownload(target, remotePath, localPath) {
-    return getClient().crossDownload(target, remotePath, localPath);
-}
-export async function uploadFiles(localDir, remoteDir) {
-    return getClient().uploadFiles(localDir, remoteDir);
-}
-export async function clearFiles() {
-    return getClient().clearFiles();
-}

package/dist/tools/docs.d.ts

@@ -0,0 +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
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDocTools(server: McpServer, projectId: string): void;

package/dist/tools/docs.js

@@ -0,0 +1,217 @@
+/**
+ * 文档管理工具 (7个)
+ * kg_create_node, kg_delete_node, kg_update_node, kg_read_node,
+ * kg_get_tree, kg_get_docs_by_status, kg_copy_node
+ */
+import { z } from 'zod';
+import { getClient } from '../storage/httpClient.js';
+import { decodeObjectStrings } from '../utils.js';
+import { wrap, safeTool, crossPrefix, formatDocMarkdown, formatTreeText, countTreeDocs } from './shared.js';
+export function registerDocTools(server, projectId) {
+    const client = () => getClient();
+    // 创建文档
+    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) => safeTool(async () => {
+        const d = decodeObjectStrings(args);
+        const doc = await client().createDoc(d.path, {
+            summary: d.summary || '',
+            content: d.content,
+            versions: [{ version: 0.1, date: new Date().toISOString(), changes: '初始创建' }],
+            bugfixes: [],
+            status: d.status || '已完成'
+        });
+        return wrap(`✅ 文档已创建: ${d.path}\n\n${JSON.stringify(doc, null, 2)}`);
+    }));
+    // 删除文档或目录 (支持批量)
+    server.tool('kg_delete_node', '删除文档或目录(支持批量，根不可删除，目录会递归删除)', { nodeId: z.union([z.string(), z.array(z.string())]).describe('文档路径或路径数组') }, async (args) => safeTool(async () => {
+        const paths = Array.isArray(args.nodeId) ? args.nodeId : [args.nodeId];
+        const results = [];
+        for (const p of paths) {
+            results.push({ path: p, success: await client().deleteDoc(p) });
+        }
+        const successCount = results.filter(r => r.success).length;
+        if (paths.length === 1) {
+            return wrap(results[0].success ? '删除成功' : '删除失败(文档不存在或是根文档)');
+        }
+        const failedPaths = results.filter(r => !r.success).map(r => r.path);
+        let msg = `✅ 批量删除完成: ${successCount}/${paths.length} 成功`;
+        if (failedPaths.length > 0)
+            msg += `\n❌ 失败: ${failedPaths.join(', ')}`;
+        return wrap(msg);
+    }));
+    // 更新文档 (支持单个/批量)
+    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) => safeTool(async () => {
+        const decoded = decodeObjectStrings(args);
+        // 批量更新模式
+        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 client().getDoc(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 client().updateDoc(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);
+        }
+        // 单个更新模式
+        const { nodeId, summary, content, status, versions, bugfixes } = decoded;
+        if (!nodeId)
+            return wrap('❌ 请提供 nodeId（单个模式）或 updates 数组（批量模式）');
+        if (nodeId === '/' || nodeId === '_root')
+            return wrap('❌ 根文档请使用 kg_update_root 方法更新');
+        const existing = await client().getDoc(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 client().updateDoc(nodeId, updates);
+        return wrap(doc ? JSON.stringify(doc, null, 2) : '更新失败');
+    }));
+    // 读取单个文档详情
+    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) => safeTool(async () => {
+        const doc = args.targetProject
+            ? await client().crossGetDoc(args.targetProject, args.nodeId)
+            : await client().getDoc(args.nodeId);
+        if (!doc)
+            return wrap(args.targetProject ? `文档不存在(项目: ${args.targetProject})` : '文档不存在');
+        const lines = formatDocMarkdown(doc, args.nodeId);
+        return wrap(args.targetProject ? crossPrefix(args.targetProject) + lines.join('\n') : lines.join('\n'));
+    }));
+    // 获取知识库树状图
+    server.tool('kg_get_tree', '获取知识库目录树。格式: 📄 文档名 # 简介。支持跨项目只读访问(需先用kg_list_projects获取项目ID)', {
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
+    }, async (args) => safeTool(async () => {
+        const tree = args.targetProject
+            ? await client().crossGetTree(args.targetProject)
+            : await client().getTree();
+        if (!tree || tree.length === 0) {
+            return wrap(args.targetProject ? `知识库为空(项目: ${args.targetProject})` : '知识库为空');
+        }
+        const treeText = formatTreeText(tree);
+        const docCount = countTreeDocs(tree);
+        const prefix = args.targetProject ? crossPrefix(args.targetProject) : '';
+        return wrap(`${prefix}共 ${docCount} 个文档\n\n${treeText}`);
+    }));
+    // 按状态筛选文档
+    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) => safeTool(async () => {
+        const docs = args.targetProject
+            ? await client().crossGetDocsByStatus(args.targetProject, args.statusList)
+            : await client().getDocsByStatus(args.statusList);
+        if (docs.length === 0) {
+            return wrap(`未找到状态为 [${args.statusList.join(', ')}] 的文档${args.targetProject ? `(项目: ${args.targetProject})` : ''}`);
+        }
+        const lines = docs.map(d => `- ${d.path} (${d.status || '已完成'}): ${d.summary || '无简介'}`);
+        const prefix = args.targetProject ? crossPrefix(args.targetProject) : '';
+        return wrap(`${prefix}找到 ${docs.length} 个文档:\n\n${lines.join('\n')}`);
+    }));
+    // 跨项目复制文档
+    server.tool('kg_copy_node', '从其他项目复制文档到当前项目。支持单个或批量复制，可指定新路径。用于跨项目协作：拉取别的项目的知识文档到当前项目', {
+        sourceProject: z.string().describe('源项目ID或名称(从kg_list_projects获取)'),
+        sourcePath: z.union([z.string(), z.array(z.string())]).describe('源文档路径(单个或数组)'),
+        targetPath: z.string().optional().describe('目标路径前缀(如"/参考/项目B")。不填则保持原路径'),
+    }, async (args) => safeTool(async () => {
+        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 client().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 client().getDoc(destPath);
+                if (existing) {
+                    await client().updateDoc(destPath, { summary: doc.summary, content: doc.content });
+                }
+                else {
+                    await client().createDoc(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;
+        if (paths.length === 1) {
+            return wrap(results[0].success
+                ? `✅ 已复制文档: ${results[0].path}\n\n来源: [${decoded.sourceProject}] ${paths[0]}`
+                : `❌ 复制失败: ${results[0].error}`);
+        }
+        const failedItems = results.filter(r => !r.success);
+        let msg = `✅ 批量复制完成: ${successCount}/${paths.length} 成功`;
+        if (failedItems.length > 0) {
+            msg += `\n❌ 失败:\n${failedItems.map(f => `  - ${f.path}: ${f.error}`).join('\n')}`;
+        }
+        return wrap(msg);
+    }));
+}

package/dist/tools/files.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 项目文件访问工具 (5个)
+ * project_upload, project_clear_files, project_list_files,
+ * project_read_file, project_download
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerFileTools(server: McpServer): void;

package/dist/tools/files.js

@@ -0,0 +1,66 @@
+/**
+ * 项目文件访问工具 (5个)
+ * project_upload, project_clear_files, project_list_files,
+ * project_read_file, project_download
+ */
+import { z } from 'zod';
+import { getClient } from '../storage/httpClient.js';
+import { wrap, safeTool, crossPrefix, formatFileSize } from './shared.js';
+export function registerFileTools(server) {
+    const client = () => getClient();
+    // 上传本地目录到中心服务器
+    server.tool('project_upload', '上传本地项目目录到中心服务器(打包zip上传，自动排除node_modules/.git等)。上传后其他客户端可通过跨项目访问下载', {
+        localDir: z.string().describe('本地目录的绝对路径(如"/home/user/project/src")'),
+        remoteDir: z.string().optional().describe('上传到服务器的目标子目录(如"src")，不填则上传到根目录'),
+    }, async (args) => safeTool(async () => {
+        const result = await client().uploadFiles(args.localDir, args.remoteDir);
+        return wrap(`✅ 上传成功\n\n- 文件数量: ${result.fileCount}\n- 目标目录: ${args.remoteDir || '/'}\n\n其他客户端可通过 project_read_file / project_download 访问`);
+    }));
+    // 清空项目文件存储区
+    server.tool('project_clear_files', '清空当前项目在中心服务器上的文件存储区', {}, async () => safeTool(async () => {
+        await client().clearFiles();
+        return wrap('✅ 文件存储已清空');
+    }));
+    // 列出项目文件
+    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) => safeTool(async () => {
+        const files = args.targetProject
+            ? await client().crossListFiles(args.targetProject, args.dir)
+            : await client().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 ? crossPrefix(args.targetProject) : '';
+        const dirLabel = args.dir || '/';
+        return wrap(`${prefix}📂 ${dirLabel} (${files.length} 项)\n\n${lines.join('\n')}`);
+    }));
+    // 读取项目文件
+    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) => safeTool(async () => {
+        const content = args.targetProject
+            ? await client().crossReadFile(args.targetProject, args.path)
+            : await client().readFile(args.path);
+        const prefix = args.targetProject ? crossPrefix(args.targetProject) : '';
+        return wrap(`${prefix}📄 ${args.path}\n\n\`\`\`\n${content}\n\`\`\``);
+    }));
+    // 下载项目文件或目录
+    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) => safeTool(async () => {
+        const result = args.targetProject
+            ? await client().crossDownload(args.targetProject, args.remotePath, args.localPath)
+            : await client().download(args.remotePath, args.localPath);
+        const prefix = args.targetProject ? crossPrefix(args.targetProject) : '';
+        return wrap(`${prefix}✅ 已下载并解压\n\n- 本地路径: ${result.localPath}\n- 文件数量: ${result.fileCount}`);
+    }));
+}

package/dist/tools/index.d.ts

@@ -1,2 +1,6 @@
+/**
+ * MCP 工具注册入口
+ * 将 25 个工具拆分为 5 个子模块，统一在此注册
+ */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function registerTools(server: McpServer, projectId: string, _user: string): void;
+export declare function registerTools(server: McpServer, projectId: string, user: string): void;