@ppdocs/mcp 3.0.7 → 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

@@ -5,7 +5,7 @@ import { wrap, formatDocMarkdown, formatTreeText, countTreeDocs, formatFileSize
 export function registerTools(server, projectId, _user) {
     // ===================== 跨项目访问 =====================
     // 0. 列出所有可访问的项目
-    server.tool('kg_list_projects', '列出所有可访问的项目(用于跨项目访问)', {}, async () => {
+    server.tool('kg_list_projects', '列出所有可访问的项目(返回name和id)。跨项目操作的第一步：先调用此工具获取项目ID，再作为其他工具的targetProject参数', {}, async () => {
         try {
             const projects = await storage.crossListProjects();
             if (projects.length === 0) {
@@ -197,10 +197,10 @@ export function registerTools(server, projectId, _user) {
         return wrap(doc ? '✅ 项目介绍已更新' : '更新失败');
     });
     // 3.6 获取项目规则
-    server.tool('kg_get_rules', '获取项目规则(可指定类型或获取全部)。支持跨项目只读访问', {
+    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或名称(不填=当前项目，跨项目只读)')
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
     }, async (args) => {
         // 跨项目访问
         if (args.targetProject) {
@@ -331,9 +331,9 @@ export function registerTools(server, projectId, _user) {
         }
     });
     // 5. 读取单个文档详情
-    server.tool('kg_read_node', '读取文档完整内容(简介、正文、版本历史、修复记录)。支持跨项目只读访问', {
+    server.tool('kg_read_node', '读取文档完整内容(简介、正文、版本历史、修复记录)。支持跨项目只读访问(需先用kg_list_projects获取项目ID)', {
         nodeId: z.string().describe('文档路径'),
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目，跨项目只读)')
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
     }, async (args) => {
         // 跨项目访问
         if (args.targetProject) {
@@ -354,8 +354,8 @@ export function registerTools(server, projectId, _user) {
         return wrap(lines.join('\n'));
     });
     // 10. 获取知识库树状图
-    server.tool('kg_get_tree', '获取知识库目录树。格式: 📄 文档名 # 简介。支持跨项目只读访问', {
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目，跨项目只读)')
+    server.tool('kg_get_tree', '获取知识库目录树。格式: 📄 文档名 # 简介。支持跨项目只读访问(需先用kg_list_projects获取项目ID)', {
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
     }, async (args) => {
         try {
             // 跨项目访问
@@ -386,9 +386,9 @@ export function registerTools(server, projectId, _user) {
         }
     });
     // 11. 按状态筛选文档
-    server.tool('kg_get_docs_by_status', '获取指定状态的文档列表。支持跨项目只读访问', {
+    server.tool('kg_get_docs_by_status', '获取指定状态的文档列表。支持跨项目只读访问(需先用kg_list_projects获取项目ID)', {
         statusList: z.array(z.string()).describe('状态列表(如["未完成","待修复"])'),
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目，跨项目只读)')
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
     }, async (args) => {
         // 跨项目访问
         if (args.targetProject) {
@@ -518,9 +518,9 @@ export function registerTools(server, projectId, _user) {
         }
     });
     // 列出项目文件
-    server.tool('project_list_files', '列出项目源码目录下的文件。需要先上传文件或项目已关联源码目录。支持跨项目只读访问(用targetProject参考其他项目的文件结构)', {
+    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或名称(不填=当前项目，跨项目只读)')
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
     }, async (args) => {
         try {
             const files = args.targetProject
@@ -543,9 +543,9 @@ export function registerTools(server, projectId, _user) {
         }
     });
     // 读取项目文件
-    server.tool('project_read_file', '读取项目源码文件内容(文本，限制1MB)。支持跨项目只读访问(用targetProject参考其他项目的代码实现)', {
+    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或名称(不填=当前项目，跨项目只读)')
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目)。ID可从kg_list_projects获取')
     }, async (args) => {
         try {
             const content = args.targetProject
@@ -558,17 +558,18 @@ export function registerTools(server, projectId, _user) {
             return wrap(`❌ ${String(e)}`);
         }
     });
-    // 下载项目目录 (zip → 自动解压)
-    server.tool('project_download_dir', '下载项目源码目录(自动打包zip并解压到本地临时目录)。支持跨项目下载(用targetProject拉取其他项目的模块代码到本地复用)', {
-        dir: z.string().describe('目录路径(如"src")'),
-        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目，跨项目只读)')
+    // 下载项目文件或目录 (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.7",
+  "version": "3.1.0",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",