@ppdocs/mcp 2.8.4 → 3.0.0

package/dist/cli.js

@@ -14,19 +14,50 @@ function parseArgs(args) {
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if (arg === '-p' || arg === '--project') {
+            if (i + 1 >= args.length || args[i + 1].startsWith('-')) {
+                console.error('Error: -p/--project requires a value');
+                return null;
+            }
             opts.project = args[++i];
         }
         else if (arg === '-k' || arg === '--key') {
+            if (i + 1 >= args.length || args[i + 1].startsWith('-')) {
+                console.error('Error: -k/--key requires a value');
+                return null;
+            }
             opts.key = args[++i];
         }
         else if (arg === '-u' || arg === '--user') {
+            if (i + 1 >= args.length || args[i + 1].startsWith('-')) {
+                console.error('Error: -u/--user requires a value');
+                return null;
+            }
             opts.user = args[++i];
         }
         else if (arg === '--port') {
-            opts.port = parseInt(args[++i], 10);
+            if (i + 1 >= args.length || args[i + 1].startsWith('-')) {
+                console.error('Error: --port requires a value');
+                return null;
+            }
+            const portVal = parseInt(args[++i], 10);
+            if (isNaN(portVal) || portVal < 1 || portVal > 65535) {
+                console.error('Error: --port must be a valid port number (1-65535)');
+                return null;
+            }
+            opts.port = portVal;
         }
         else if (arg === '--api') {
-            opts.api = args[++i];
+            if (i + 1 >= args.length || args[i + 1].startsWith('-')) {
+                console.error('Error: --api requires a value');
+                return null;
+            }
+            const apiVal = args[++i].trim();
+            if (!apiVal) {
+                console.error('Error: --api value cannot be empty');
+                return null;
+            }
+            // 移除用户可能误加的协议前缀
+            opts.api = apiVal.replace(/^https?:\/\//, '');
         }
         else if (arg === '--codex') {
             opts.codex = true;

package/dist/storage/httpClient.d.ts

@@ -4,7 +4,7 @@
  *
  * API URL 格式: http://localhost:20001/api/:projectId/:password/...
  */
-import type { DocData, DocNode, DocSearchResult, Task, TaskSummary, TaskLogType, TaskExperience } from './types.js';
+import type { DocData, DocNode, DocSearchResult, Task, TaskSummary, TaskLogType, TaskExperience, FileInfo } from './types.js';
 interface TreeNode {
     path: string;
     name: string;
@@ -42,7 +42,7 @@ export declare class PpdocsApiClient {
         id: string;
         name: string;
         description: string;
-        updated_at: string;
+        updatedAt: string;
     }[]>;
     /** 跨项目: 列出文档 */
     crossListDocs(target: string): Promise<DocNode[]>;
@@ -54,6 +54,30 @@ export declare class PpdocsApiClient {
     crossGetDocsByStatus(target: string, statusList: string[]): Promise<DocNode[]>;
     /** 跨项目: 获取规则 */
     crossGetRules(target: string, ruleType: string): Promise<string[]>;
+    /** 列出项目文件 */
+    listFiles(dir?: string): Promise<FileInfo[]>;
+    /** 读取项目文件 */
+    readFile(filePath: string): Promise<string>;
+    /** 下载项目目录 (zip) → 自动解压到 temp 目录 */
+    downloadDir(dir: string): Promise<{
+        localPath: string;
+        fileCount: number;
+    }>;
+    /** 上传本地目录到中心服务器 (打包 zip → POST) */
+    uploadFiles(localDir: string, remoteDir?: string): Promise<{
+        fileCount: number;
+    }>;
+    /** 清空项目文件存储区 */
+    clearFiles(): Promise<void>;
+    /** 跨项目: 列出文件 */
+    crossListFiles(target: string, dir?: string): Promise<FileInfo[]>;
+    /** 跨项目: 读取文件 */
+    crossReadFile(target: string, filePath: string): Promise<string>;
+    /** 跨项目: 下载目录 */
+    crossDownloadDir(target: string, dir: string): Promise<{
+        localPath: string;
+        fileCount: number;
+    }>;
 }
 export declare function initClient(apiUrl: string): void;
 export declare function listDocs(_projectId: string): Promise<DocNode[]>;
@@ -79,10 +103,26 @@ export declare function crossListProjects(): Promise<{
     id: string;
     name: string;
     description: string;
-    updated_at: 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 downloadDir(dir: 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<{
+    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

@@ -4,6 +4,57 @@
  *
  * API URL 格式: http://localhost:20001/api/:projectId/:password/...
  */
+// ============ 工具函数 ============
+/** 清理路径前缀斜杠 */
+function cleanPath(p) {
+    return p.replace(/^\//, '');
+}
+/** 排除的目录 (与 Rust 端 EXCLUDED_DIRS 保持一致) */
+const EXCLUDED_DIRS = new Set([
+    'node_modules', '.git', 'target', 'dist', 'build', '.next',
+    '__pycache__', '.venv', 'venv', '.idea', '.vs', '.vscode',
+]);
+/** 下载 zip 并解压到 temp 目录 */
+async function fetchAndExtractZip(url) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 60000);
+    try {
+        const response = await fetch(url, { signal: controller.signal });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: response.statusText }));
+            throw new Error(error.error || `HTTP ${response.status}`);
+        }
+        const buffer = Buffer.from(await response.arrayBuffer());
+        const os = await import('os');
+        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 zip = new AdmZip(buffer);
+        zip.extractAllTo(tempDir, true);
+        let fileCount = 0;
+        const countFiles = (dirPath) => {
+            for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+                if (entry.isDirectory())
+                    countFiles(path.join(dirPath, entry.name));
+                else
+                    fileCount++;
+            }
+        };
+        countFiles(tempDir);
+        return { localPath: tempDir, fileCount };
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            throw new Error('Download timeout (60s)');
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
 /** 从扁平文档列表构建目录树 */
 function buildTree(docs) {
     const root = [];
@@ -84,16 +135,13 @@ export class PpdocsApiClient {
     }
     async getDoc(docPath) {
         try {
-            // 移除开头的斜杠，API 路径会自动处理
-            const cleanPath = docPath.replace(/^\//, '');
-            return await this.request(`/docs/${cleanPath}`);
+            return await this.request(`/docs/${cleanPath(docPath)}`);
         }
         catch {
             return null;
         }
     }
     async createDoc(docPath, doc) {
-        const cleanPath = docPath.replace(/^\//, '');
         const payload = {
             summary: doc.summary || '',
             content: doc.content || '',
@@ -103,17 +151,15 @@ export class PpdocsApiClient {
                     changes: '初始创建'
                 }],
             bugfixes: doc.bugfixes || [],
-            status: doc.status || '已完成' // 默认状态
+            status: doc.status || '已完成'
         };
-        return this.request(`/docs/${cleanPath}`, {
+        return this.request(`/docs/${cleanPath(docPath)}`, {
             method: 'POST',
             body: JSON.stringify(payload)
         });
     }
     async updateDoc(docPath, updates) {
         try {
-            const cleanPath = docPath.replace(/^\//, '');
-            // 先获取现有文档
             const existing = await this.getDoc(docPath);
             if (!existing)
                 return null;
@@ -124,7 +170,7 @@ export class PpdocsApiClient {
                 bugfixes: updates.bugfixes ?? existing.bugfixes,
                 status: updates.status ?? existing.status ?? '已完成'
             };
-            return await this.request(`/docs/${cleanPath}`, {
+            return await this.request(`/docs/${cleanPath(docPath)}`, {
                 method: 'PUT',
                 body: JSON.stringify(payload)
             });
@@ -135,8 +181,7 @@ export class PpdocsApiClient {
     }
     async deleteDoc(docPath) {
         try {
-            const cleanPath = docPath.replace(/^\//, '');
-            await this.request(`/docs/${cleanPath}`, { method: 'DELETE' });
+            await this.request(`/docs/${cleanPath(docPath)}`, { method: 'DELETE' });
             return true;
         }
         catch {
@@ -244,8 +289,7 @@ export class PpdocsApiClient {
     /** 跨项目: 获取文档 */
     async crossGetDoc(target, docPath) {
         try {
-            const cleanPath = docPath.replace(/^\//, '');
-            return await this.request(`/cross/${encodeURIComponent(target)}/docs/${cleanPath}`);
+            return await this.request(`/cross/${encodeURIComponent(target)}/docs/${cleanPath(docPath)}`);
         }
         catch {
             return null;
@@ -272,6 +316,87 @@ export class PpdocsApiClient {
             return [];
         }
     }
+    // ============ 项目文件访问 ============
+    /** 列出项目文件 */
+    async listFiles(dir) {
+        const query = dir ? `?dir=${encodeURIComponent(dir)}` : '';
+        return this.request(`/files${query}`);
+    }
+    /** 读取项目文件 */
+    async readFile(filePath) {
+        return this.request(`/files/${cleanPath(filePath)}`);
+    }
+    /** 下载项目目录 (zip) → 自动解压到 temp 目录 */
+    async downloadDir(dir) {
+        return fetchAndExtractZip(`${this.baseUrl}/files-download/${cleanPath(dir)}`);
+    }
+    /** 上传本地目录到中心服务器 (打包 zip → POST) */
+    async uploadFiles(localDir, remoteDir) {
+        const fs = await import('fs');
+        const path = await import('path');
+        const AdmZip = (await import('adm-zip')).default;
+        if (!fs.existsSync(localDir) || !fs.statSync(localDir).isDirectory()) {
+            throw new Error(`本地目录不存在: ${localDir}`);
+        }
+        const zip = new AdmZip();
+        const addDir = (dirPath, zipPath) => {
+            for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+                if (entry.name.startsWith('.'))
+                    continue;
+                const fullPath = path.join(dirPath, entry.name);
+                if (entry.isDirectory()) {
+                    if (EXCLUDED_DIRS.has(entry.name))
+                        continue;
+                    addDir(fullPath, zipPath ? `${zipPath}/${entry.name}` : entry.name);
+                }
+                else {
+                    if (fs.statSync(fullPath).size > 10_485_760)
+                        continue;
+                    zip.addLocalFile(fullPath, zipPath || undefined);
+                }
+            }
+        };
+        addDir(localDir, '');
+        const buffer = zip.toBuffer();
+        if (buffer.length > 104_857_600) {
+            throw new Error('打包后超过 100MB 限制，请缩小目录范围');
+        }
+        const query = remoteDir ? `?dir=${encodeURIComponent(remoteDir)}` : '';
+        const response = await fetch(`${this.baseUrl}/files${query}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/octet-stream' },
+            body: new Uint8Array(buffer),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: response.statusText }));
+            throw new Error(error.error || `HTTP ${response.status}`);
+        }
+        const result = await response.json();
+        return { fileCount: result.data?.fileCount || 0 };
+    }
+    /** 清空项目文件存储区 */
+    async clearFiles() {
+        const url = `${this.baseUrl}/files`;
+        const response = await fetch(url, { method: 'DELETE' });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: response.statusText }));
+            throw new Error(error.error || `HTTP ${response.status}`);
+        }
+    }
+    // ============ 跨项目文件访问 (只读) ============
+    /** 跨项目: 列出文件 */
+    async crossListFiles(target, dir) {
+        const query = dir ? `?dir=${encodeURIComponent(dir)}` : '';
+        return this.request(`/cross/${encodeURIComponent(target)}/files${query}`);
+    }
+    /** 跨项目: 读取文件 */
+    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)}`);
+    }
 }
 // ============ 模块级 API ============
 let client = null;
@@ -348,3 +473,28 @@ export async function 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 downloadDir(dir) {
+    return getClient().downloadDir(dir);
+}
+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 crossDownloadDir(target, dir) {
+    return getClient().crossDownloadDir(target, dir);
+}
+export async function uploadFiles(localDir, remoteDir) {
+    return getClient().uploadFiles(localDir, remoteDir);
+}
+export async function clearFiles() {
+    return getClient().clearFiles();
+}

package/dist/storage/types.d.ts

@@ -44,6 +44,15 @@ export interface Project {
     name: string;
     description?: string;
     updatedAt: string;
+    createdAt?: string;
+    projectPath?: string;
+}
+export interface FileInfo {
+    name: string;
+    path: string;
+    isDir: boolean;
+    size: number;
+    modifiedAt?: string;
 }
 export type TaskLogType = 'progress' | 'issue' | 'solution' | 'reference';
 export interface TaskLog {

package/dist/tools/helpers.d.ts

@@ -30,4 +30,8 @@ export declare function formatTreeText(tree: TreeNode[]): string;
  * 统计树中的文档数
  */
 export declare function countTreeDocs(tree: TreeNode[]): number;
+/**
+ * 格式化文件大小
+ */
+export declare function formatFileSize(bytes: number): string;
 export {};

package/dist/tools/helpers.js

@@ -81,3 +81,14 @@ export function countTreeDocs(tree) {
     traverse(tree);
     return count;
 }
+// ==================== 文件大小格式化 ====================
+/**
+ * 格式化文件大小
+ */
+export function formatFileSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}

package/dist/tools/index.js

@@ -1,7 +1,7 @@
 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 } from './helpers.js';
+import { wrap, formatDocMarkdown, formatTreeText, countTreeDocs, formatFileSize } from './helpers.js';
 export function registerTools(server, projectId, _user) {
     // ===================== 跨项目访问 =====================
     // 0. 列出所有可访问的项目
@@ -393,4 +393,85 @@ export function registerTools(server, projectId, _user) {
         }
         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', '列出项目源码目录下的文件。需要先上传文件或项目已关联源码目录', {
+        dir: z.string().optional().describe('子目录路径(如"src/components")，不填则列出根目录'),
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目，跨项目只读)')
+    }, 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)。需要先上传文件或项目已关联源码目录', {
+        path: z.string().describe('文件路径(如"src/main.ts")'),
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目，跨项目只读)')
+    }, 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_dir', '下载项目源码目录(自动打包zip并解压到本地临时目录)。需要先上传文件或项目已关联源码目录', {
+        dir: z.string().describe('目录路径(如"src")'),
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目，跨项目只读)')
+    }, async (args) => {
+        try {
+            const result = args.targetProject
+                ? await storage.crossDownloadDir(args.targetProject, args.dir)
+                : await storage.downloadDir(args.dir);
+            const prefix = args.targetProject ? `[跨项目: ${args.targetProject}]\n\n` : '';
+            return wrap(`${prefix}✅ 目录已下载并解压\n\n- 本地路径: ${result.localPath}\n- 文件数量: ${result.fileCount}\n\n可直接读取该路径下的文件`);
+        }
+        catch (e) {
+            return wrap(`❌ ${String(e)}`);
+        }
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ppdocs/mcp",
-  "version": "2.8.4",
+  "version": "3.0.0",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",
@@ -30,12 +30,12 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "proper-lockfile": "^4.1.2",
+    "adm-zip": "^0.5.16",
     "zod": "^4.1.13"
   },
   "devDependencies": {
+    "@types/adm-zip": "^0.5.7",
     "@types/node": "^22.0.0",
-    "@types/proper-lockfile": "^4.1.4",
     "typescript": "^5.7.0"
   }
 }