@ppdocs/mcp 2.6.21 → 2.6.23

package/dist/cli.js

@@ -6,13 +6,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
+import { generateUser } from './config.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
-/** 生成随机用户名 (8位字母数字) */
-function generateUser() {
-    const chars = 'abcdefghjkmnpqrstuvwxyz23456789';
-    return Array.from({ length: 8 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');
-}
 function parseArgs(args) {
     const opts = { port: 20001, api: 'localhost', codex: false };
     for (let i = 0; i < args.length; i++) {
@@ -151,12 +147,26 @@ function autoRegisterMcp(apiUrl, user) {
         detected.push('Claude');
         try {
             console.log(`✅ Detected Claude CLI, registering MCP...`);
-            execSilent(`claude mcp remove ${serverName}`);
-            const cmd = `claude mcp add ${serverName} -- npx -y @ppdocs/mcp@latest`;
-            execSync(cmd, { stdio: 'inherit' });
+            // 先检查是否已存在
+            const checkResult = execSync(`claude mcp list`, { encoding: 'utf-8' });
+            if (checkResult.includes(serverName)) {
+                console.log(`✅ Claude MCP already configured`);
+            }
+            else {
+                const cmd = `claude mcp add ${serverName} -- npx -y @ppdocs/mcp@latest`;
+                execSync(cmd, { stdio: 'inherit' });
+            }
         }
         catch (e) {
-            console.log(`⚠️  Claude MCP registration failed: ${e}`);
+            // 如果 list 失败，尝试添加
+            try {
+                execSilent(`claude mcp remove ${serverName}`);
+                const cmd = `claude mcp add ${serverName} -- npx -y @ppdocs/mcp@latest`;
+                execSync(cmd, { stdio: 'inherit' });
+            }
+            catch {
+                console.log(`⚠️  Claude MCP registration failed`);
+            }
         }
     }
     // 检测 Codex CLI (OpenAI)
@@ -246,6 +256,33 @@ function generateHooksConfig() {
         }
     };
 }
+/** 生成 MCP 权限配置 (允许全部 ppdocs-kg 方法) */
+function generateMcpPermissions() {
+    const mcpMethods = [
+        // 知识图谱操作
+        'kg_create_node',
+        'kg_delete_node',
+        'kg_update_node',
+        'kg_update_root',
+        'kg_get_rules',
+        'kg_save_rules',
+        'kg_lock_node',
+        'kg_search',
+        'kg_find_path',
+        'kg_list_nodes',
+        'kg_get_relations',
+        'kg_read_node',
+        'kg_get_tree',
+        'kg_find_by_file',
+        // 任务管理
+        'task_create',
+        'task_list',
+        'task_get',
+        'task_add_log',
+        'task_complete',
+    ];
+    return mcpMethods.map(m => `mcp__ppdocs-kg__${m}`);
+}
 /** 安装 Claude Code 模板 */
 function installClaudeTemplates(cwd) {
     const claudeDir = path.join(cwd, '.claude');
@@ -273,13 +310,24 @@ function installClaudeTemplates(cwd) {
         catch { /* ignore */ }
     }
     const hooksConfig = generateHooksConfig();
+    // 合并 MCP 权限到 permissions.allow
+    const existingPermissions = existingSettings.permissions || {};
+    const existingAllow = existingPermissions.allow || [];
+    const mcpPermissions = generateMcpPermissions();
+    // 去重合并
+    const mergedAllow = [...new Set([...existingAllow, ...mcpPermissions])];
     const mergedSettings = {
         ...existingSettings,
-        ...hooksConfig
+        ...hooksConfig,
+        permissions: {
+            ...existingPermissions,
+            allow: mergedAllow,
+        }
     };
     fs.mkdirSync(claudeDir, { recursive: true });
     fs.writeFileSync(settingsPath, JSON.stringify(mergedSettings, null, 2));
     console.log(`✅ Configured .claude/settings.json hooks (${process.platform})`);
+    console.log(`✅ Added ${mcpPermissions.length} MCP method permissions`);
 }
 /** 安装 Codex 模板 (生成 AGENTS.md) */
 function installCodexTemplates(cwd) {

package/dist/config.d.ts

@@ -7,6 +7,8 @@ export interface PpdocsConfig {
     projectId: string;
     user: string;
 }
+/** 生成随机用户名 (8位字母数字) */
+export declare function generateUser(): string;
 /**
  * 加载配置 (优先级: 环境变量 > .ppdocs 文件)
  */

package/dist/config.js

@@ -5,7 +5,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 /** 生成随机用户名 (8位字母数字) */
-function generateUser() {
+export function generateUser() {
     const chars = 'abcdefghjkmnpqrstuvwxyz23456789';
     return Array.from({ length: 8 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');
 }

package/dist/index.js

@@ -6,12 +6,19 @@
  * 1. CLI 初始化: npx @ppdocs/mcp init -p <projectId> -k <key>
  * 2. MCP 服务: 自动读取 .ppdocs 配置或 PPDOCS_API_URL 环境变量
  */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { registerTools } from './tools/index.js';
 import { initClient } from './storage/httpClient.js';
 import { runCli } from './cli.js';
 import { loadConfig } from './config.js';
+// 从 package.json 读取版本号
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
+const VERSION = pkg.version;
 // 检查是否为 CLI 命令
 const args = process.argv.slice(2);
 if (args.length > 0 && runCli(args)) {
@@ -21,11 +28,11 @@ if (args.length > 0 && runCli(args)) {
 async function main() {
     const config = loadConfig();
     initClient(config.apiUrl);
-    const server = new McpServer({ name: `ppdocs [${config.projectId}]`, version: '2.3.0' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: `ppdocs [${config.projectId}]`, version: VERSION }, { capabilities: { tools: {} } });
     registerTools(server, config.projectId, config.user);
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error(`ppdocs MCP v2.3 | project: ${config.projectId} | user: ${config.user}`);
+    console.error(`ppdocs MCP v${VERSION} | project: ${config.projectId} | user: ${config.user}`);
 }
 main().catch((err) => {
     console.error('Fatal error:', err);

package/dist/storage/types.d.ts

@@ -42,6 +42,7 @@ export interface NodeData {
     categories: string[];
     path: string;
     description: string;
+    summary?: string;
     dataInput?: DataRef;
     dataOutput?: DataRef;
     dependencies: Dependency[];

package/dist/tools/index.js

@@ -1,20 +1,20 @@
 import { z } from 'zod';
 import * as storage from '../storage/httpClient.js';
-import { decodeUnicodeEscapes, decodeObjectStrings, wrapResult, getRules, RULE_TYPE_LABELS } from '../utils.js';
+import { decodeUnicodeEscapes, decodeObjectStrings, getRules, RULE_TYPE_LABELS } from '../utils.js';
 // 辅助函数: 包装返回结果
-async function wrap(projectId, text) {
-    const wrapped = await wrapResult(projectId, text);
-    return { content: [{ type: 'text', text: wrapped }] };
+function wrap(_projectId, text) {
+    return { content: [{ type: 'text', text }] };
 }
 export function registerTools(server, projectId, _user) {
     // 1. 创建节点
-    server.tool('kg_create_node', '创建知识节点。type: logic=逻辑/函数, data=数据结构, intro=概念介绍', {
+    server.tool('kg_create_node', '创建知识节点。type: logic=逻辑/函数, data=数据结构, intro=概念介绍。⚠️ tags至少提供3个分类标签', {
         title: z.string().describe('节点标题'),
-        type: z.enum(['logic', 'data', 'intro']).describe('节点类型'),
+        type: z.enum(['logic', 'data', 'intro']).describe('节点类型(logic/data/intro)'),
         description: z.string().describe('Markdown描述(用Mermaid流程图+表格,禁止纯文字)'),
         path: z.string().min(1).describe('目录路径(必填,如"/前端/组件")'),
-        tags: z.array(z.string()).min(3).describe('分类标签(至少3个)'),
+        tags: z.array(z.string()).min(3).describe('⚠️ 分类标签(必填,至少3个)'),
         signature: z.string().optional().describe('唯一签名(用于依赖匹配,默认=title)'),
+        summary: z.string().optional().describe('一句话简介(显示在标题下方)'),
         dependencies: z.array(z.object({
             name: z.string().describe('目标节点的signature'),
             description: z.string().describe('依赖说明')
@@ -27,6 +27,7 @@ export function registerTools(server, projectId, _user) {
             type: decoded.type,
             status: 'incomplete',
             description: decoded.description || '',
+            summary: decoded.summary || '',
             // x, y 不传递，由 httpClient 智能计算位置
             locked: false,
             signature: decoded.signature || decoded.title,
@@ -43,16 +44,17 @@ export function registerTools(server, projectId, _user) {
         return wrap(projectId, success ? '删除成功' : '删除失败(节点不存在/已锁定/是根节点)');
     });
     // 3. 更新节点
-    server.tool('kg_update_node', '更新节点内容(锁定节点不可更新)', {
+    server.tool('kg_update_node', '更新节点内容(锁定节点不可更新)。⚠️ 更新tags时至少提供3个分类标签', {
         nodeId: z.string().describe('节点ID'),
         title: z.string().optional().describe('新标题'),
         signature: z.string().optional().describe('新签名'),
         description: z.string().optional().describe('新描述(Markdown)'),
+        summary: z.string().optional().describe('一句话简介(显示在标题下方)'),
         path: z.string().optional().describe('目录路径(如"/前端/组件")'),
         x: z.number().optional().describe('X坐标'),
         y: z.number().optional().describe('Y坐标'),
         status: z.enum(['incomplete', 'complete', 'fixing', 'refactoring', 'deprecated']).optional().describe('状态'),
-        tags: z.array(z.string()).min(3).optional().describe('分类标签(至少3个)'),
+        tags: z.array(z.string()).min(3).optional().describe('⚠️ 分类标签(更新时至少3个)'),
         dependencies: z.array(z.object({
             name: z.string(),
             description: z.string()
@@ -99,7 +101,7 @@ export function registerTools(server, projectId, _user) {
     }, async (args) => {
         const decoded = decodeObjectStrings(args);
         if (decoded.title === undefined && decoded.description === undefined) {
-            return wrap(projectId, '❌ ���至少提供 title 或 description');
+            return wrap(projectId, '❌ 请至少提供 title 或 description');
         }
         const node = await storage.updateRoot(projectId, {
             title: decoded.title,
@@ -146,10 +148,15 @@ export function registerTools(server, projectId, _user) {
     }, async (args) => {
         const results = await storage.searchNodes(projectId, args.keywords, args.limit || 10);
         const output = results.map(r => ({
-            id: r.node.id, title: r.node.title, type: r.node.type,
-            status: r.node.status, hitRate: `${Math.round(r.score)}%`
+            id: r.node.id,
+            title: r.node.title,
+            tags: r.node.categories || [],
+            status: r.node.status,
+            summary: r.node.summary || '',
+            hitRate: `${Math.round(r.score)}%`
         }));
-        return wrap(projectId, JSON.stringify(output, null, 2));
+        const json = JSON.stringify(output, null, 2);
+        return wrap(projectId, `${json}\n\n💡 需要详细内容请使用 kg_read_node(nodeId) 获取节点详情`);
     });
     // 6. 路径查找
     server.tool('kg_find_path', '查找两节点间的依赖路径', {
@@ -176,7 +183,7 @@ export function registerTools(server, projectId, _user) {
             ? { status: args.status, minEdges: args.minEdges, maxEdges: args.maxEdges }
             : undefined;
         const nodes = await storage.listNodes(projectId, filter);
-        const output = nodes.map(n => ({ id: n.id, title: n.title, type: n.type, status: n.status, locked: n.locked }));
+        const output = nodes.map(n => ({ id: n.id, title: n.title, type: n.type, status: n.status, locked: n.locked, summary: n.summary || '' }));
         return wrap(projectId, JSON.stringify(output, null, 2));
     });
     // 8. 查询节点关系网 (支持多层)
@@ -216,8 +223,9 @@ export function registerTools(server, projectId, _user) {
         return wrap(projectId, JSON.stringify({ outgoing, incoming }, null, 2));
     });
     // 9. 读取单个节点详情
-    server.tool('kg_read_node', '读取单个节点的完整内容(描述、关联文件、依赖、历史记录)', {
-        nodeId: z.string().describe('节点ID')
+    server.tool('kg_read_node', '读取单个节点的完整内容(描述、关联文件、依赖、历史记录)，可选包含上下游关系', {
+        nodeId: z.string().describe('节点ID'),
+        depth: z.number().min(0).max(3).optional().describe('关系查询层数(0=不含关系，1-3=含上下游关系，默认0)')
     }, async (args) => {
         const node = await storage.getNode(projectId, args.nodeId);
         if (!node) {
@@ -227,6 +235,9 @@ export function registerTools(server, projectId, _user) {
         const lines = [];
         // 基础信息
         lines.push(`## ${node.title}\n`);
+        if (node.summary) {
+            lines.push(`> ${node.summary}\n`);
+        }
         lines.push('**基础信息**');
         lines.push(`| 字段 | 值 |`);
         lines.push(`|:---|:---|`);
@@ -272,6 +283,44 @@ export function registerTools(server, projectId, _user) {
             node.bugfixes.forEach(b => lines.push(`| ${b.id} | ${b.date} | ${b.issue} | ${b.solution} |`));
             lines.push('');
         }
+        // 上下游关系 (depth > 0 时获取)
+        const depth = args.depth || 0;
+        if (depth > 0) {
+            const visited = new Set();
+            const outgoing = [];
+            const incoming = [];
+            async function fetchRelations(nodeId, currentDepth, direction) {
+                if (currentDepth > depth || visited.has(`${nodeId}-${direction}`))
+                    return;
+                visited.add(`${nodeId}-${direction}`);
+                const relations = await storage.getRelations(projectId, nodeId);
+                for (const r of relations) {
+                    if (r.direction === 'outgoing' && (direction === 'outgoing' || direction === 'both')) {
+                        if (!outgoing.some(o => o.id === r.nodeId)) {
+                            outgoing.push({ id: r.nodeId, title: r.title, edge: r.edgeType });
+                            await fetchRelations(r.nodeId, currentDepth + 1, 'outgoing');
+                        }
+                    }
+                    if (r.direction === 'incoming' && (direction === 'incoming' || direction === 'both')) {
+                        if (!incoming.some(i => i.id === r.nodeId)) {
+                            incoming.push({ id: r.nodeId, title: r.title, edge: r.edgeType });
+                            await fetchRelations(r.nodeId, currentDepth + 1, 'incoming');
+                        }
+                    }
+                }
+            }
+            await fetchRelations(args.nodeId, 1, 'both');
+            if (outgoing.length > 0 || incoming.length > 0) {
+                lines.push('**上下游关系**');
+                if (outgoing.length > 0) {
+                    lines.push(`- 依赖 (${outgoing.length}): ${outgoing.map(o => o.title).join(', ')}`);
+                }
+                if (incoming.length > 0) {
+                    lines.push(`- 被依赖 (${incoming.length}): ${incoming.map(i => i.title).join(', ')}`);
+                }
+                lines.push('');
+            }
+        }
         return wrap(projectId, lines.join('\n'));
     });
     // 10. 获取知识库树状图

package/dist/utils.d.ts

@@ -7,18 +7,6 @@ export declare const RULE_TYPE_LABELS: Record<RuleType, string>;
  * 获取指定类型的规则 (从独立文件读取)
  */
 export declare function getRules(projectId: string, ruleType?: RuleType): Promise<string>;
-/**
- * 获取根节点的用户风格 (兼容旧接口)
- */
-export declare function getRootStyle(projectId: string): Promise<string>;
-/**
- * 清除规则缓存 (保留接口兼容性，实际无需缓存)
- */
-export declare function clearStyleCache(): void;
-/**
- * 包装工具返回结果 (不再自动注入规则，使用 kg_get_rules 按需获取)
- */
-export declare function wrapResult(_projectId: string, result: string): Promise<string>;
 /**
  * 解码 Unicode 转义序列
  * 将 \uXXXX 格式的转义序列转换为实际字符

package/dist/utils.js

@@ -39,24 +39,6 @@ export async function getRules(projectId, ruleType) {
     }
     return allRules.join('\n\n---\n\n');
 }
-/**
- * 获取根节点的用户风格 (兼容旧接口)
- */
-export async function getRootStyle(projectId) {
-    return getRules(projectId, 'userStyles');
-}
-/**
- * 清除规则缓存 (保留接口兼容性，实际无需缓存)
- */
-export function clearStyleCache() {
-    // 独立文件存储无需缓存
-}
-/**
- * 包装工具返回结果 (不再自动注入规则，使用 kg_get_rules 按需获取)
- */
-export async function wrapResult(_projectId, result) {
-    return result;
-}
 /**
  * 解码 Unicode 转义序列
  * 将 \uXXXX 格式的转义序列转换为实际字符

package/package.json

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