@ppdocs/mcp 2.6.22 → 2.6.24

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++) {

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,
@@ -140,16 +142,33 @@ export function registerTools(server, projectId, _user) {
         return wrap(projectId, node ? JSON.stringify(node, null, 2) : '操作失败');
     });
     // 5. 搜索节点
-    server.tool('kg_search', '关键词搜索节点,按命中率排序返回', {
-        keywords: z.array(z.string()).describe('关键词列表(OR逻辑)'),
+    server.tool('kg_search', '关键词搜索节点,按命中率排序返回。空白关键词[""]返回全部节点', {
+        keywords: z.array(z.string()).describe('关键词列表(OR逻辑),空白[""]返回全部'),
         limit: z.number().optional().describe('返回数量(默认10)')
     }, 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) 获取节点详情`);
+    });
+    // 5.5 列出所有标签
+    server.tool('kg_list_tags', '获取所有节点使用过的标签列表(去重)', {}, async () => {
+        const nodes = await storage.listNodes(projectId);
+        const tagSet = new Set();
+        for (const node of nodes) {
+            if (node.categories && Array.isArray(node.categories)) {
+                node.categories.forEach(cat => tagSet.add(cat));
+            }
+        }
+        const tags = Array.from(tagSet).sort();
+        return wrap(projectId, JSON.stringify({ total: tags.length, tags }, null, 2));
     });
     // 6. 路径查找
     server.tool('kg_find_path', '查找两节点间的依赖路径', {
@@ -176,7 +195,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 +235,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 +247,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 +295,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.22",
+  "version": "2.6.24",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",