@ppdocs/mcp 3.0.8 → 3.1.0

package/dist/storage/httpClient.d.ts

@@ -72,8 +72,8 @@ export declare class PpdocsApiClient {
     listFiles(dir?: string): Promise<FileInfo[]>;
     /** 读取项目文件 */
     readFile(filePath: string): Promise<string>;
-    /** 下载项目目录 (zip) → 自动解压到 temp 目录 */
-    downloadDir(dir: string): Promise<{
+    /** 下载项目文件或目录 (zip) → 自动解压到指定目录或 temp 目录 */
+    download(remotePath: string, localPath?: string): Promise<{
         localPath: string;
         fileCount: number;
     }>;
@@ -87,8 +87,8 @@ export declare class PpdocsApiClient {
     crossListFiles(target: string, dir?: string): Promise<FileInfo[]>;
     /** 跨项目: 读取文件 */
     crossReadFile(target: string, filePath: string): Promise<string>;
-    /** 跨项目: 下载目录 */
-    crossDownloadDir(target: string, dir: string): Promise<{
+    /** 跨项目: 下载文件或目录 */
+    crossDownload(target: string, remotePath: string, localPath?: string): Promise<{
         localPath: string;
         fileCount: number;
     }>;
@@ -137,13 +137,13 @@ export declare function crossGetDocsByStatus(target: string, statusList: string[
 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 downloadDir(dir: string): Promise<{
+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 crossDownloadDir(target: string, dir: string): Promise<{
+export declare function crossDownload(target: string, remotePath: string, localPath?: string): Promise<{
     localPath: string;
     fileCount: number;
 }>;

package/dist/storage/httpClient.js

@@ -14,8 +14,8 @@ const EXCLUDED_DIRS = new Set([
     'node_modules', '.git', 'target', 'dist', 'build', '.next',
     '__pycache__', '.venv', 'venv', '.idea', '.vs', '.vscode',
 ]);
-/** 下载 zip 并解压到 temp 目录 */
-async function fetchAndExtractZip(url) {
+/** 下载 zip 并解压到指定目录或 temp 目录 */
+async function fetchAndExtractZip(url, localPath) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 60000);
     try {
@@ -29,10 +29,10 @@ async function fetchAndExtractZip(url) {
         const path = await import('path');
         const fs = await import('fs');
         const AdmZip = (await import('adm-zip')).default;
-        const tempDir = path.join(os.tmpdir(), `ppdocs-files-${Date.now()}`);
-        fs.mkdirSync(tempDir, { recursive: true });
+        const targetDir = localPath || path.join(os.tmpdir(), `ppdocs-files-${Date.now()}`);
+        fs.mkdirSync(targetDir, { recursive: true });
         const zip = new AdmZip(buffer);
-        zip.extractAllTo(tempDir, true);
+        zip.extractAllTo(targetDir, true);
         let fileCount = 0;
         const countFiles = (dirPath) => {
             for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
@@ -42,8 +42,8 @@ async function fetchAndExtractZip(url) {
                     fileCount++;
             }
         };
-        countFiles(tempDir);
-        return { localPath: tempDir, fileCount };
+        countFiles(targetDir);
+        return { localPath: targetDir, fileCount };
     }
     catch (err) {
         if (err instanceof Error && err.name === 'AbortError') {
@@ -393,9 +393,9 @@ export class PpdocsApiClient {
     async readFile(filePath) {
         return this.request(`/files/${cleanPath(filePath)}`);
     }
-    /** 下载项目目录 (zip) → 自动解压到 temp 目录 */
-    async downloadDir(dir) {
-        return fetchAndExtractZip(`${this.baseUrl}/files-download/${cleanPath(dir)}`);
+    /** 下载项目文件或目录 (zip) → 自动解压到指定目录或 temp 目录 */
+    async download(remotePath, localPath) {
+        return fetchAndExtractZip(`${this.baseUrl}/files-download/${cleanPath(remotePath)}`, localPath);
     }
     /** 上传本地目录到中心服务器 (打包 zip → POST) */
     async uploadFiles(localDir, remoteDir) {
@@ -460,9 +460,9 @@ export class PpdocsApiClient {
     async crossReadFile(target, filePath) {
         return this.request(`/cross/${encodeURIComponent(target)}/files/${cleanPath(filePath)}`);
     }
-    /** 跨项目: 下载目录 */
-    async crossDownloadDir(target, dir) {
-        return fetchAndExtractZip(`${this.baseUrl}/cross/${encodeURIComponent(target)}/files-download/${cleanPath(dir)}`);
+    /** 跨项目: 下载文件或目录 */
+    async crossDownload(target, remotePath, localPath) {
+        return fetchAndExtractZip(`${this.baseUrl}/cross/${encodeURIComponent(target)}/files-download/${cleanPath(remotePath)}`, localPath);
     }
 }
 // ============ 模块级 API ============
@@ -566,8 +566,8 @@ export async function listFiles(dir) {
 export async function readFile(filePath) {
     return getClient().readFile(filePath);
 }
-export async function downloadDir(dir) {
-    return getClient().downloadDir(dir);
+export async function download(remotePath, localPath) {
+    return getClient().download(remotePath, localPath);
 }
 export async function crossListFiles(target, dir) {
     return getClient().crossListFiles(target, dir);
@@ -575,8 +575,8 @@ export async function crossListFiles(target, dir) {
 export async function crossReadFile(target, filePath) {
     return getClient().crossReadFile(target, filePath);
 }
-export async function crossDownloadDir(target, dir) {
-    return getClient().crossDownloadDir(target, dir);
+export async function crossDownload(target, remotePath, localPath) {
+    return getClient().crossDownload(target, remotePath, localPath);
 }
 export async function uploadFiles(localDir, remoteDir) {
     return getClient().uploadFiles(localDir, remoteDir);

package/dist/tools/index.js

@@ -558,17 +558,18 @@ export function registerTools(server, projectId, _user) {
             return wrap(`❌ ${String(e)}`);
         }
     });
-    // 下载项目目录 (zip → 自动解压)
-    server.tool('project_download_dir', '下载整个源码目录到本地临时目录(自动打包zip解压)。适合需要本地复用代码的场景，仅浏览代码请用project_read_file。跨项目时先用kg_list_projects获取项目ID', {
-        dir: z.string().describe('目录路径(如"src")'),
+    // 下载项目文件或目录 (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.crossDownloadDir(args.targetProject, args.dir)
-                : await storage.downloadDir(args.dir);
+                ? 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}\n\n可直接读取该路径下的文件`);
+            return wrap(`${prefix}✅ 已下载并解压\n\n- 本地路径: ${result.localPath}\n- 文件数量: ${result.fileCount}`);
         }
         catch (e) {
             return wrap(`❌ ${String(e)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ppdocs/mcp",
-  "version": "3.0.8",
+  "version": "3.1.0",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",