@ppdocs/mcp 2.8.3 → 2.9.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

@@ -22,6 +22,8 @@ export declare class PpdocsApiClient {
     updateDoc(docPath: string, updates: Partial<DocData>): Promise<DocData | null>;
     deleteDoc(docPath: string): Promise<boolean>;
     searchDocs(keywords: string[], limit?: number): Promise<DocSearchResult[]>;
+    /** 按状态筛选文档 */
+    getDocsByStatus(statusList: string[]): Promise<DocNode[]>;
     /** 获取目录树结构 */
     getTree(): Promise<TreeNode[]>;
     getRulesApi(ruleType: string): Promise<string[]>;
@@ -35,6 +37,23 @@ export declare class PpdocsApiClient {
     }, creator: string): Promise<Task>;
     addTaskLog(taskId: string, logType: TaskLogType, content: string): Promise<Task | null>;
     completeTask(taskId: string, experience: TaskExperience): Promise<Task | null>;
+    /** 列出所有可访问的项目 */
+    crossListProjects(): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        updated_at: string;
+    }[]>;
+    /** 跨项目: 列出文档 */
+    crossListDocs(target: string): Promise<DocNode[]>;
+    /** 跨项目: 获取文档 */
+    crossGetDoc(target: string, docPath: string): Promise<DocData | null>;
+    /** 跨项目: 获取目录树 */
+    crossGetTree(target: string): Promise<TreeNode[]>;
+    /** 跨项目: 按状态筛选文档 */
+    crossGetDocsByStatus(target: string, statusList: string[]): Promise<DocNode[]>;
+    /** 跨项目: 获取规则 */
+    crossGetRules(target: string, ruleType: string): Promise<string[]>;
 }
 export declare function initClient(apiUrl: string): void;
 export declare function listDocs(_projectId: string): Promise<DocNode[]>;
@@ -43,6 +62,7 @@ export declare function createDoc(_projectId: string, docPath: string, doc: Part
 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>;
@@ -55,4 +75,14 @@ export declare function createTask(_projectId: string, task: {
 }, 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 crossListProjects(): Promise<{
+    id: string;
+    name: string;
+    description: string;
+    updated_at: 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 type { TreeNode };

package/dist/storage/httpClient.js

@@ -102,7 +102,8 @@ export class PpdocsApiClient {
                     date: new Date().toISOString(),
                     changes: '初始创建'
                 }],
-            bugfixes: doc.bugfixes || []
+            bugfixes: doc.bugfixes || [],
+            status: doc.status || '已完成' // 默认状态
         };
         return this.request(`/docs/${cleanPath}`, {
             method: 'POST',
@@ -120,7 +121,8 @@ export class PpdocsApiClient {
                 summary: updates.summary ?? existing.summary,
                 content: updates.content ?? existing.content,
                 versions: updates.versions ?? existing.versions,
-                bugfixes: updates.bugfixes ?? existing.bugfixes
+                bugfixes: updates.bugfixes ?? existing.bugfixes,
+                status: updates.status ?? existing.status ?? '已完成'
             };
             return await this.request(`/docs/${cleanPath}`, {
                 method: 'PUT',
@@ -147,6 +149,13 @@ export class PpdocsApiClient {
             body: JSON.stringify({ keywords, limit })
         });
     }
+    /** 按状态筛选文档 */
+    async getDocsByStatus(statusList) {
+        return this.request('/docs/by-status', {
+            method: 'POST',
+            body: JSON.stringify({ status_list: statusList })
+        });
+    }
     /** 获取目录树结构 */
     async getTree() {
         const docs = await this.listDocs();
@@ -223,6 +232,46 @@ export class PpdocsApiClient {
             return null;
         }
     }
+    // ============ 跨项目只读访问 ============
+    /** 列出所有可访问的项目 */
+    async crossListProjects() {
+        return this.request('/cross/projects');
+    }
+    /** 跨项目: 列出文档 */
+    async crossListDocs(target) {
+        return this.request(`/cross/${encodeURIComponent(target)}/docs`);
+    }
+    /** 跨项目: 获取文档 */
+    async crossGetDoc(target, docPath) {
+        try {
+            const cleanPath = docPath.replace(/^\//, '');
+            return await this.request(`/cross/${encodeURIComponent(target)}/docs/${cleanPath}`);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** 跨项目: 获取目录树 */
+    async crossGetTree(target) {
+        const docs = await this.crossListDocs(target);
+        return buildTree(docs);
+    }
+    /** 跨项目: 按状态筛选文档 */
+    async crossGetDocsByStatus(target, statusList) {
+        return this.request(`/cross/${encodeURIComponent(target)}/docs/by-status`, {
+            method: 'POST',
+            body: JSON.stringify({ status_list: statusList })
+        });
+    }
+    /** 跨项目: 获取规则 */
+    async crossGetRules(target, ruleType) {
+        try {
+            return await this.request(`/cross/${encodeURIComponent(target)}/rules/${ruleType}`);
+        }
+        catch {
+            return [];
+        }
+    }
 }
 // ============ 模块级 API ============
 let client = null;
@@ -254,6 +303,9 @@ export async function deleteDoc(_projectId, 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();
 }
@@ -280,3 +332,19 @@ export async function addTaskLog(_projectId, taskId, logType, content) {
 export async function completeTask(_projectId, taskId, experience) {
     return getClient().completeTask(taskId, experience);
 }
+// ============ 跨项目只读访问 ============
+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);
+}

package/dist/storage/types.d.ts

@@ -10,12 +10,13 @@ export interface BugfixRecord {
     issue: string;
     solution: string;
 }
-/** 文档数据 (4个核心字段) */
+/** 文档数据 (5个核心字段) */
 export interface DocData {
     summary: string;
     content: string;
     versions: VersionRecord[];
     bugfixes: BugfixRecord[];
+    status?: string;
 }
 /** 文档节点 (含路径信息，用于列表展示) */
 export interface DocNode {
@@ -23,6 +24,7 @@ export interface DocNode {
     name: string;
     summary: string;
     isDir: boolean;
+    status?: string;
 }
 /** 文档搜索结果 */
 export interface DocSearchResult {

package/dist/tools/helpers.js

@@ -55,7 +55,7 @@ export function formatTreeText(tree) {
             const connector = isLast ? '└── ' : '├── ';
             const childPrefix = isLast ? '    ' : '│   ';
             const icon = node.isDir ? '📁' : '📄';
-            const summary = node.summary ? `(${node.summary})` : '';
+            const summary = node.summary ? ` # ${node.summary}` : '';
             lines.push(`${prefix}${connector}${icon} ${node.name}${summary}`);
             if (node.children && node.children.length > 0) {
                 lines.push(...format(node.children, prefix + childPrefix));

package/dist/tools/index.js

@@ -3,12 +3,31 @@ import * as storage from '../storage/httpClient.js';
 import { decodeObjectStrings, getRules, RULE_TYPE_LABELS } from '../utils.js';
 import { wrap, formatDocMarkdown, formatTreeText, countTreeDocs } from './helpers.js';
 export function registerTools(server, projectId, _user) {
+    // ===================== 跨项目访问 =====================
+    // 0. 列出所有可访问的项目
+    server.tool('kg_list_projects', '列出所有可访问的项目(用于跨项目访问)', {}, 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)}`);
+        }
+    });
     // ===================== 文档管理 =====================
     // 1. 创建文档
     server.tool('kg_create_node', '创建知识文档。使用目录路径分类，文件名作为文档名', {
         path: z.string().min(1).describe('完整文档路径(如"/前端/组件/Modal")'),
         summary: z.string().optional().describe('一句话简介'),
-        content: z.string().describe('Markdown内容')
+        content: z.string().describe('Markdown内容'),
+        status: z.string().optional().describe('文档状态(默认"已完成")')
     }, async (args) => {
         const decoded = decodeObjectStrings(args);
         const doc = await storage.createDoc(projectId, decoded.path, {
@@ -19,7 +38,8 @@ export function registerTools(server, projectId, _user) {
                     date: new Date().toISOString(),
                     changes: '初始创建'
                 }],
-            bugfixes: []
+            bugfixes: [],
+            status: decoded.status || '已完成'
         });
         return wrap(`✅ 文档已创建: ${decoded.path}\n\n${JSON.stringify(doc, null, 2)}`);
     });
@@ -47,6 +67,7 @@ export function registerTools(server, projectId, _user) {
         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(),
@@ -61,6 +82,7 @@ export function registerTools(server, projectId, _user) {
             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(),
@@ -92,6 +114,8 @@ export function registerTools(server, projectId, _user) {
                     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)
@@ -108,7 +132,7 @@ export function registerTools(server, projectId, _user) {
             return wrap(msg);
         }
         // 单个更新模式: 必须提供 nodeId
-        const { nodeId, summary, content, versions, bugfixes } = decoded;
+        const { nodeId, summary, content, status, versions, bugfixes } = decoded;
         if (!nodeId) {
             return wrap('❌ 请提供 nodeId（单个模式）或 updates 数组（批量模式）');
         }
@@ -127,6 +151,8 @@ export function registerTools(server, projectId, _user) {
             updates.summary = summary;
         if (content !== undefined)
             updates.content = content;
+        if (status !== undefined)
+            updates.status = status;
         if (versions !== undefined)
             updates.versions = versions;
         if (bugfixes !== undefined)
@@ -156,10 +182,34 @@ export function registerTools(server, projectId, _user) {
         return wrap(doc ? '✅ 项目介绍已更新' : '更新失败');
     });
     // 3.6 获取项目规则
-    server.tool('kg_get_rules', '获取项目规则(可指定类型或获取全部)', {
+    server.tool('kg_get_rules', '获取项目规则(可指定类型或获取全部)。支持跨项目只读访问', {
         ruleType: z.enum(['userStyles', 'testRules', 'reviewRules', 'codeStyle', 'unitTests']).optional()
-            .describe('规则类型: userStyles=用户沟通规则, codeStyle=编码风格规则, reviewRules=代码审查规则, testRules=错误分析规则, unitTests=代码测试规则。不传则返回全部')
+            .describe('规则类型: userStyles=用户沟通规则, codeStyle=编码风格规则, reviewRules=代码审查规则, testRules=错误分析规则, unitTests=代码测试规则。不传则返回全部'),
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目，跨项目只读)')
     }, async (args) => {
+        // 跨项目访问
+        if (args.targetProject) {
+            if (args.ruleType) {
+                const rules = await storage.crossGetRules(args.targetProject, args.ruleType);
+                if (rules.length === 0) {
+                    return { content: [{ type: 'text', text: `暂无${RULE_TYPE_LABELS[args.ruleType]}规则(项目: ${args.targetProject})` }] };
+                }
+                return { content: [{ type: 'text', text: `[跨项目: ${args.targetProject}]\n\n${rules.join('\n')}` }] };
+            }
+            // 获取全部规则
+            const allRules = [];
+            for (const type of ['userStyles', 'codeStyle', 'reviewRules', 'testRules', 'unitTests']) {
+                const rules = await storage.crossGetRules(args.targetProject, type);
+                if (rules.length > 0) {
+                    allRules.push(`## ${RULE_TYPE_LABELS[type]}\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);
         if (!rules || rules.trim() === '') {
             const typeName = args.ruleType ? RULE_TYPE_LABELS[args.ruleType] : '项目';
@@ -181,9 +231,20 @@ export function registerTools(server, projectId, _user) {
         return wrap(`✅ ${RULE_TYPE_LABELS[decoded.ruleType]}已保存 (${decoded.rules.length} 条)`);
     });
     // 5. 读取单个文档详情
-    server.tool('kg_read_node', '读取文档完整内容(简介、正文、版本历史、修复记录)', {
-        nodeId: z.string().describe('文档路径')
+    server.tool('kg_read_node', '读取文档完整内容(简介、正文、版本历史、修复记录)。支持跨项目只读访问', {
+        nodeId: z.string().describe('文档路径'),
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目，跨项目只读)')
     }, 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('文档不存在');
@@ -193,8 +254,21 @@ export function registerTools(server, projectId, _user) {
         return wrap(lines.join('\n'));
     });
     // 10. 获取知识库树状图
-    server.tool('kg_get_tree', '获取知识库的目录树结构(按 path 分组)', {}, async () => {
+    server.tool('kg_get_tree', '获取知识库目录树。格式: 📄 文档名 # 简介。支持跨项目只读访问', {
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目，跨项目只读)')
+    }, 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);
@@ -211,6 +285,28 @@ export function registerTools(server, projectId, _user) {
             }, null, 2));
         }
     });
+    // 11. 按状态筛选文档
+    server.tool('kg_get_docs_by_status', '获取指定状态的文档列表。支持跨项目只读访问', {
+        statusList: z.array(z.string()).describe('状态列表(如["未完成","待修复"])'),
+        targetProject: z.string().optional().describe('目标项目ID或名称(不填=当前项目，跨项目只读)')
+    }, 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')}`);
+    });
     // ===================== 任务管理 =====================
     // 7. 创建任务
     server.tool('task_create', '创建开发任务', {

package/package.json

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