@ppdocs/mcp 3.1.8 → 3.1.9

package/dist/tools/projects.js

@@ -0,0 +1,52 @@
+/**
+ * 项目管理工具 (3个)
+ * kg_list_projects, kg_create_project, kg_update_root
+ */
+import { z } from 'zod';
+import { getClient } from '../storage/httpClient.js';
+import { decodeObjectStrings } from '../utils.js';
+import { wrap, safeTool } from './shared.js';
+export function registerProjectTools(server, projectId) {
+    const client = () => getClient();
+    // 列出所有可访问的项目
+    server.tool('kg_list_projects', '列出所有可访问的项目(返回name和id)。跨项目操作的第一步：先调用此工具获取项目ID，再作为其他工具的targetProject参数', {}, async () => safeTool(async () => {
+        const projects = await client().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')}`);
+    }));
+    // 创建项目
+    server.tool('kg_create_project', '创建新项目。返回项目ID和密码(密码用于MCP连接)', {
+        id: z.string().describe('项目ID(英文/数字/中文，如"my-app")'),
+        name: z.string().describe('项目名称'),
+        description: z.string().optional().describe('项目简介'),
+        projectPath: z.string().optional().describe('项目源码路径(本地绝对路径)'),
+    }, async (args) => safeTool(async () => {
+        const result = await client().createProject(args.id, args.name, args.description, args.projectPath || process.cwd());
+        return wrap(`✅ 项目创建成功\n\n- 项目ID: ${result.project.id}\n- 项目名: ${result.project.name}\n- 密码: ${result.password}\n\nMCP 连接地址: http://<服务器IP>:20001/api/${result.project.id}/${result.password}`);
+    }));
+    // 更新根文档 (项目介绍)
+    server.tool('kg_update_root', '更新项目介绍(根文档)', {
+        title: z.string().optional().describe('项目标题'),
+        description: z.string().optional().describe('项目介绍(Markdown)')
+    }, async (args) => safeTool(async () => {
+        const decoded = decodeObjectStrings(args);
+        if (decoded.title === undefined && decoded.description === undefined) {
+            return wrap('❌ 请至少提供 title 或 description');
+        }
+        const existing = await client().getDoc('/');
+        if (!existing)
+            return wrap('更新失败(根文档不存在)');
+        const updates = {};
+        if (decoded.title !== undefined)
+            updates.summary = decoded.title;
+        if (decoded.description !== undefined)
+            updates.content = decoded.description;
+        const doc = await client().updateDoc('/', updates);
+        return wrap(doc ? '✅ 项目介绍已更新' : '更新失败');
+    }));
+}

package/dist/tools/rules.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 规则管理工具 (6个)
+ * kg_get_rules, kg_save_rules, kg_get_rules_meta, kg_save_rules_meta,
+ * kg_get_global_rules_meta, kg_save_global_rules_meta
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerRuleTools(server: McpServer, projectId: string): void;

package/dist/tools/rules.js

@@ -0,0 +1,125 @@
+/**
+ * 规则管理工具 (6个)
+ * kg_get_rules, kg_save_rules, kg_get_rules_meta, kg_save_rules_meta,
+ * kg_get_global_rules_meta, kg_save_global_rules_meta
+ */
+import { z } from 'zod';
+import { getClient } from '../storage/httpClient.js';
+import { decodeObjectStrings, getRules, RULE_TYPE_LABELS } from '../utils.js';
+import { wrap, safeTool, crossPrefix } from './shared.js';
+export function registerRuleTools(server, projectId) {
+    const client = () => getClient();
+    // 获取项目规则
+    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或名称(不填=当前项目)。ID可从kg_list_projects获取')
+    }, async (args) => safeTool(async () => {
+        if (args.targetProject) {
+            const crossMeta = await client().crossGetRulesMeta(args.targetProject);
+            if (args.ruleType) {
+                const rules = await client().crossGetRules(args.targetProject, args.ruleType);
+                if (rules.length === 0) {
+                    const label = crossMeta[args.ruleType]?.label || args.ruleType;
+                    return wrap(`暂无${label}规则(项目: ${args.targetProject})`);
+                }
+                return wrap(`${crossPrefix(args.targetProject)}${rules.join('\n')}`);
+            }
+            const types = Object.keys(crossMeta).length > 0 ? Object.keys(crossMeta) : Object.keys(RULE_TYPE_LABELS);
+            const allRules = [];
+            for (const type of types) {
+                const rules = await client().crossGetRules(args.targetProject, type);
+                if (rules.length > 0) {
+                    const label = crossMeta[type]?.label || RULE_TYPE_LABELS[type] || type;
+                    allRules.push(`## ${label}\n${rules.join('\n')}`);
+                }
+            }
+            if (allRules.length === 0)
+                return wrap(`暂无项目规则(项目: ${args.targetProject})`);
+            return wrap(`${crossPrefix(args.targetProject)}${allRules.join('\n\n')}`);
+        }
+        const rules = await getRules(projectId, args.ruleType || undefined);
+        if (!rules || rules.trim() === '') {
+            const meta = await client().getRulesMeta();
+            const typeName = args.ruleType ? (meta[args.ruleType]?.label || args.ruleType) : '项目';
+            return wrap(`暂无${typeName}规则`);
+        }
+        return wrap(rules);
+    }));
+    // 保存项目规则 (自动合并,去重追加)
+    server.tool('kg_save_rules', '保存单个类型的项目规则(自动合并:已有规则保留,新规则去重追加)', {
+        ruleType: z.string().describe('规则类型(如 userStyles, codeStyle, reviewRules, testRules, unitTests, 或自定义类型)'),
+        rules: z.array(z.string()).describe('规则数组')
+    }, async (args) => safeTool(async () => {
+        const decoded = decodeObjectStrings(args);
+        // appendRules 逻辑内联（原 httpClient 包装函数）
+        const existing = await client().getRulesApi(decoded.ruleType);
+        const existingSet = new Set(existing.map(r => r.trim()));
+        const toAdd = decoded.rules.filter(r => !existingSet.has(r.trim()));
+        const merged = [...existing, ...toAdd];
+        const success = await client().saveRulesApi(decoded.ruleType, merged);
+        if (!success)
+            return wrap('❌ 保存失败');
+        const meta = await client().getRulesMeta();
+        const label = meta[decoded.ruleType]?.label || decoded.ruleType;
+        return wrap(`✅ ${label}已保存 (新增${toAdd.length}条, 共${merged.length}条)`);
+    }));
+    // 获取规则触发配置
+    server.tool('kg_get_rules_meta', '获取规则触发配置(所有类型的标签、关键词、触发数)。用于查看/编辑 hooks 触发条件', {}, async () => safeTool(async () => {
+        const meta = await client().getRulesMeta();
+        if (Object.keys(meta).length === 0)
+            return wrap('暂无规则配置');
+        const lines = Object.entries(meta).map(([type, m]) => {
+            const kw = m.keywords.length > 0 ? m.keywords.join(', ') : '(无)';
+            const trigger = m.always ? '始终触发' : `关键词≥${m.min_hits}: ${kw}`;
+            return `- **${m.label}** (${type}): ${trigger}`;
+        });
+        return wrap(`规则触发配置:\n\n${lines.join('\n')}`);
+    }));
+    // 保存规则触发配置 (自动合并)
+    server.tool('kg_save_rules_meta', '保存规则触发配置(自动合并:已有类型更新,新类型创建,其他类型不受影响)', {
+        meta: z.record(z.string(), z.object({
+            label: z.string().describe('规则显示名称'),
+            keywords: z.array(z.string()).default([]).describe('触发关键词列表'),
+            min_hits: z.number().default(1).describe('最低触发关键词数'),
+            always: z.boolean().default(false).describe('是否始终触发(如 userStyles)')
+        })).describe('规则类型 → 触发配置的映射')
+    }, async (args) => safeTool(async () => {
+        const decoded = decodeObjectStrings(args.meta);
+        // mergeRulesMeta 逻辑内联
+        const existing = await client().getRulesMeta();
+        const merged = { ...existing, ...decoded };
+        const success = await client().saveRulesMeta(merged);
+        if (!success)
+            return wrap('❌ 保存失败');
+        return wrap(`✅ 触发配置已保存 (更新${Object.keys(decoded).length}个类型, 共${Object.keys(merged).length}个类型)`);
+    }));
+    // 获取全局默认规则触发配置
+    server.tool('kg_get_global_rules_meta', '获取全局默认规则触发配置(新项目创建时继承此配置)', {}, async () => safeTool(async () => {
+        const meta = await client().getGlobalRulesMeta();
+        if (Object.keys(meta).length === 0)
+            return wrap('暂无全局默认规则配置');
+        const lines = Object.entries(meta).map(([type, m]) => {
+            const kw = m.keywords.length > 0 ? m.keywords.join(', ') : '(无)';
+            const trigger = m.always ? '始终触发' : `关键词≥${m.min_hits}: ${kw}`;
+            return `- **${m.label}** (${type}): ${trigger}`;
+        });
+        return wrap(`全局默认规则触发配置:\n\n${lines.join('\n')}`);
+    }));
+    // 保存全局默认规则触发配置 (自动合并)
+    server.tool('kg_save_global_rules_meta', '保存全局默认触发配置(自动合并:已有类型更新,新类型创建,其他类型不受影响)', {
+        meta: z.record(z.string(), z.object({
+            label: z.string().describe('规则显示名称'),
+            keywords: z.array(z.string()).default([]).describe('触发关键词列表'),
+            min_hits: z.number().default(1).describe('最低触发关键词数'),
+            always: z.boolean().default(false).describe('是否始终触发(如 userStyles)')
+        })).describe('规则类型 → 触发配置的映射')
+    }, async (args) => safeTool(async () => {
+        const decoded = decodeObjectStrings(args.meta);
+        const existing = await client().getGlobalRulesMeta();
+        const merged = { ...existing, ...decoded };
+        const success = await client().saveGlobalRulesMeta(merged);
+        if (!success)
+            return wrap('❌ 保存失败');
+        return wrap(`✅ 全局触发配置已保存 (更新${Object.keys(decoded).length}个类型, 共${Object.keys(merged).length}个类型)`);
+    }));
+}

package/dist/tools/shared.d.ts

@@ -0,0 +1,25 @@
+/**
+ * MCP 工具共享模块
+ * 合并原 helpers.ts + 新增 safeTool / withCross 模式
+ */
+import type { DocData } from '../storage/types.js';
+export declare function wrap(text: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function safeTool(fn: () => Promise<ReturnType<typeof wrap>>): Promise<ReturnType<typeof wrap>>;
+export declare function crossPrefix(target: string): string;
+export declare function formatDocMarkdown(doc: DocData, path: string): string[];
+interface TreeNode {
+    path: string;
+    name: string;
+    summary?: string;
+    isDir: boolean;
+    children?: TreeNode[];
+}
+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/shared.js

@@ -0,0 +1,88 @@
+/**
+ * MCP 工具共享模块
+ * 合并原 helpers.ts + 新增 safeTool / withCross 模式
+ */
+// ==================== MCP 返回包装 ====================
+export function wrap(text) {
+    return { content: [{ type: 'text', text }] };
+}
+// ==================== 安全工具包装 ====================
+export async function safeTool(fn) {
+    try {
+        return await fn();
+    }
+    catch (e) {
+        return wrap(`❌ ${String(e)}`);
+    }
+}
+// ==================== 跨项目高阶函数 ====================
+export function crossPrefix(target) {
+    return `[跨项目: ${target}]\n\n`;
+}
+// ==================== 文档格式化 ====================
+export function formatDocMarkdown(doc, path) {
+    const lines = [];
+    const name = path.split('/').pop() || path;
+    lines.push(`## ${name}\n`);
+    if (doc.summary)
+        lines.push(`> ${doc.summary}\n`);
+    if (doc.content) {
+        lines.push('**内容**');
+        lines.push(doc.content);
+        lines.push('');
+    }
+    if (doc.versions && doc.versions.length > 0) {
+        lines.push('**更新历史**');
+        lines.push('| 版本 | 日期 | 变更 |');
+        lines.push('|:---|:---|:---|');
+        doc.versions.forEach((v) => lines.push(`| ${v.version} | ${v.date} | ${v.changes} |`));
+        lines.push('');
+    }
+    if (doc.bugfixes && doc.bugfixes.length > 0) {
+        lines.push('**修复历史**');
+        lines.push('| 日期 | 问题 | 方案 |');
+        lines.push('|:---|:---|:---|');
+        doc.bugfixes.forEach((b) => lines.push(`| ${b.date} | ${b.issue} | ${b.solution} |`));
+        lines.push('');
+    }
+    return lines;
+}
+export function formatTreeText(tree) {
+    function format(nodes, prefix = '') {
+        const lines = [];
+        nodes.forEach((node, index) => {
+            const isLast = index === nodes.length - 1;
+            const connector = isLast ? '└── ' : '├── ';
+            const childPrefix = isLast ? '    ' : '│   ';
+            const icon = node.isDir ? '📁' : '📄';
+            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));
+            }
+        });
+        return lines;
+    }
+    return format(tree).join('\n');
+}
+export function countTreeDocs(tree) {
+    let count = 0;
+    function traverse(nodes) {
+        for (const node of nodes) {
+            if (!node.isDir)
+                count++;
+            if (node.children)
+                traverse(node.children);
+        }
+    }
+    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/tasks.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 任务管理工具 (4个)
+ * task_create, task_get, task_update, task_archive
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerTaskTools(server: McpServer, projectId: string, user: string): void;

package/dist/tools/tasks.js

@@ -0,0 +1,86 @@
+/**
+ * 任务管理工具 (4个)
+ * task_create, task_get, task_update, task_archive
+ */
+import { z } from 'zod';
+import { getClient } from '../storage/httpClient.js';
+import { decodeObjectStrings } from '../utils.js';
+import { wrap, safeTool } from './shared.js';
+export function registerTaskTools(server, projectId, user) {
+    const client = () => getClient();
+    // 创建任务
+    server.tool('task_create', '创建开发任务', {
+        title: z.string().describe('任务标题'),
+        description: z.string().describe('任务描述(Markdown)'),
+        goals: z.array(z.string()).optional().describe('目标清单')
+    }, async (args) => safeTool(async () => {
+        const decoded = decodeObjectStrings(args);
+        const task = await client().createTask({
+            title: decoded.title,
+            description: decoded.description,
+            goals: decoded.goals || []
+        }, user);
+        return wrap(JSON.stringify(task, null, 2));
+    }));
+    // 读取任务
+    server.tool('task_get', '读取任务详情(按名字搜索，支持当前任务和历史任务)', {
+        title: z.string().describe('任务名称(模糊匹配)'),
+        status: z.enum(['active', 'archived', 'all']).optional().describe('状态筛选: active=进行中, archived=已归档, all=全部(默认)')
+    }, async (args) => safeTool(async () => {
+        const status = args.status || 'all';
+        const searchTitle = args.title.toLowerCase();
+        let tasks;
+        if (status === 'all') {
+            const [active, archived] = await Promise.all([
+                client().listTasks('active'),
+                client().listTasks('archived')
+            ]);
+            tasks = [...active, ...archived];
+        }
+        else {
+            tasks = await client().listTasks(status);
+        }
+        const matched = tasks.filter(t => t.title.toLowerCase().includes(searchTitle));
+        if (matched.length === 0)
+            return wrap(`未找到匹配 "${args.title}" 的任务`);
+        if (matched.length === 1) {
+            const task = await client().getTask(matched[0].id);
+            return wrap(task ? JSON.stringify(task, null, 2) : '任务详情获取失败');
+        }
+        const list = matched.map(t => ({
+            id: t.id, title: t.title, status: t.status,
+            creator: t.creator, created_at: t.created_at
+        }));
+        return wrap(`找到 ${matched.length} 个匹配任务:\n${JSON.stringify(list, null, 2)}\n\n请提供更精确的任务名称`);
+    }));
+    // 更新任务
+    server.tool('task_update', '更新任务(添加进展日志)', {
+        taskId: z.string().describe('任务ID'),
+        log_type: z.enum(['progress', 'issue', 'solution', 'reference']).describe('日志类型: progress=进展, issue=问题, solution=方案, reference=参考'),
+        content: z.string().describe('日志内容(Markdown)')
+    }, async (args) => safeTool(async () => {
+        const decoded = decodeObjectStrings(args);
+        const task = await client().addTaskLog(args.taskId, decoded.log_type, decoded.content);
+        if (!task)
+            return wrap('更新失败(任务不存在或已归档)');
+        return wrap(`✅ 日志已添加，任务共有 ${task.logs.length} 条日志`);
+    }));
+    // 归档任务
+    server.tool('task_archive', '归档任务(完成并填写经验总结)', {
+        taskId: z.string().describe('任务ID'),
+        summary: z.string().describe('经验总结(Markdown)'),
+        difficulties: z.array(z.string()).optional().describe('遇到的困难'),
+        solutions: z.array(z.string()).optional().describe('解决方案')
+    }, async (args) => safeTool(async () => {
+        const decoded = decodeObjectStrings(args);
+        const task = await client().completeTask(args.taskId, {
+            summary: decoded.summary,
+            difficulties: decoded.difficulties || [],
+            solutions: decoded.solutions || [],
+            references: []
+        });
+        if (!task)
+            return wrap('归档失败(任务不存在或已归档)');
+        return wrap(`✅ 任务已归档: ${task.title}`);
+    }));
+}

package/dist/utils.js

@@ -1,7 +1,7 @@
 /**
  * MCP Server 工具函数
  */
-import * as storage from './storage/httpClient.js';
+import { getClient } from './storage/httpClient.js';
 // 默认规则类型标签 (fallback)
 const DEFAULT_LABELS = {
     userStyles: '用户沟通规则',
@@ -24,9 +24,10 @@ function formatRulesList(rules) {
  * 获取指定类型的规则 (动态: 从 meta 获取标签)
  */
 export async function getRules(projectId, ruleType) {
-    const meta = await storage.getRulesMeta();
+    const client = getClient();
+    const meta = await client.getRulesMeta();
     if (ruleType) {
-        const rules = await storage.getRules(projectId, ruleType);
+        const rules = await client.getRulesApi(ruleType);
         if (!rules || rules.length === 0)
             return '';
         const label = meta[ruleType]?.label || DEFAULT_LABELS[ruleType] || ruleType;
@@ -36,7 +37,7 @@ export async function getRules(projectId, ruleType) {
     const types = Object.keys(meta).length > 0 ? Object.keys(meta) : Object.keys(DEFAULT_LABELS);
     const allRules = [];
     for (const type of types) {
-        const rules = await storage.getRules(projectId, type);
+        const rules = await client.getRulesApi(type);
         if (rules && rules.length > 0) {
             const label = meta[type]?.label || DEFAULT_LABELS[type] || type;
             allRules.push(`[${label}]\n${formatRulesList(rules)}`);

package/package.json

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