@ppdocs/mcp 3.2.35 → 3.2.37

package/README.md

@@ -8,6 +8,8 @@
 
 ppdocs MCP 是一个 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，让 Claude 能够在对话中构建和查询项目知识图谱。
 
+当前 MCP 采用 `flowchart-first` 模型：节点、关系、绑定文件、任务关联和节点文档统一收敛到 `kg_flowchart(action:"...")`，不再维护独立的 `kg_doc` / `kg_search` / `kg_create_node` 一组旧接口。
+
 ```
 ┌─────────────┐     MCP      ┌─────────────┐    HTTP    ┌─────────────┐
 │  Claude AI  │ ──────────── │ @ppdocs/mcp │ ────────── │ ppdocs 桌面 │
@@ -105,28 +107,55 @@ npx @ppdocs/mcp init -p <projectId> -k <key> --codex
 
 ## 工具列表
 
-### 知识图谱工具
+### 核心工具
 
 | 工具 | 说明 |
 |------|------|
-| `kg_create_node` | 创建知识节点 |
-| `kg_update_node` | 更新节点内容 |
-| `kg_delete_node` | 删除节点 |
-| `kg_lock_node` | 锁定节点 (AI 只能锁定，解锁需前端手动) |
-| `kg_list_nodes` | 列出节点 (支持 status/edges 过滤，maxEdges=0 查孤立节点) |
-| `kg_search` | 关键词搜索 |
-| `kg_find_path` | 查找依赖路径 |
-| `kg_get_relations` | 获取节点关系 |
+| `kg_init` | 初始化项目连接与上下文 |
+| `kg_status` | 查看项目仪表盘与流程图概况 |
+| `kg_flowchart` | 统一的知识图谱入口，负责查询、更新、关系分析 |
+| `kg_rules` | 规则管理 |
+| `kg_task` | 任务管理 |
+| `kg_files` | 项目文件读写/上传下载 |
+| `kg_discuss` | 讨论区 |
+| `kg_meeting` | 多 AI 协作会议 |
+| `code_scan` | 代码扫描 |
+| `code_smart_context` | 获取符号的智能上下文 |
+| `code_full_path` | 获取两个符号之间的全路径 |
+
+### `kg_flowchart` actions
+
+| action | 说明 |
+|------|------|
+| `list` | 列出所有流程图 |
+| `get` | 获取指定流程图的节点与连线 |
+| `search` | 按关键词搜索节点、节点文档与绑定资源 |
+| `get_relations` | 查看某节点的入边/出边关系 |
+| `find_path` | 查找两个节点之间的有向路径 |
+| `get_node` | 获取节点详情、关联层级、绑定资源与文档 |
+| `update_node` | 更新节点信息并追加节点文档版本 |
+| `delete_node` | 删除节点 |
+| `batch_add` | 批量新增节点与连线 |
+| `bind` / `unbind` | 绑定或解绑文件、目录、文档、任务 |
+| `orphans` | 检查孤立参考文档 |
+| `health` | 查看节点健康度 |
+| `create_chart` | 创建子图并绑定到父节点 |
+| `delete_chart` | 删除子图 |
+
+### 常用示例
 
-### 任务管理工具
+```bash
+# 搜索相关节点
+kg_flowchart(action:"search", query:"flowchart storage")
 
-| 工具 | 说明 |
-|------|------|
-| `task_create` | 创建开发任务 |
-| `task_list` | 列出任务 |
-| `task_get` | 获取任务详情 |
-| `task_add_log` | 添加进度日志 |
-| `task_complete` | 完成任务并归档 |
+# 查看节点详情
+kg_flowchart(action:"get_node", chartId:"main", nodeId:"n_storage", expand:2, includeDoc:true, includeFiles:true)
+
+# 追加节点文档
+kg_flowchart(action:"update_node", chartId:"main", nodeId:"n_storage",
+  docSummary:"补充存储层职责",
+  docContent:"## 职责\n...\n## 关键流程\n...")
+```
 
 ---
 
@@ -178,18 +207,15 @@ npx @ppdocs/mcp init -p <projectId> -k <key> --codex
 
 ## 更新日志
 
-### v2.6.9
-- ✨ `kg_list_nodes` 支持 status/minEdges/maxEdges 过滤
-- 🗑️ 移除 `kg_find_orphans` (用 `kg_list_nodes(maxEdges: 0)` 替代)
+### v3.2.36
+- 统一为 `flowchart-first` MCP 接口模型
+- `kg_flowchart` 新增 `search` / `get_relations` / `find_path`
+- 文档与模板改为使用 `kg_flowchart(action:"...")`，不再引用旧 `kg_doc` / `kg_search` 等独立接口
 
 ### v2.5.0
-- ✨ 新增 CLI init 命令，自动安装工作流模板
-- ✨ 支持 Codex 模式 (--codex)
-- 📦 构建时自动复制模板
-
-### v2.4.0
-- 🛡️ `kg_lock_node` 只能锁定，解锁需前端手动操作
-- ⚡ 后端自动记录操作日志
+- 新增 CLI init 命令，自动安装工作流模板
+- 支持 Codex 模式 (`--codex`)
+- 构建时自动复制模板
 
 ### v2.3.0
 - 新增任务管理功能

package/dist/cli.js

@@ -11,7 +11,7 @@ import { PpdocsApiClient } from './storage/httpClient.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
 function parseArgs(args) {
-    const opts = { port: 20001, api: 'localhost', codex: false };
+    const opts = { port: 20099, api: 'localhost', codex: false };
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if (arg === '-p' || arg === '--project') {
@@ -100,7 +100,7 @@ Options:
   -p, --project  Project ID (required)
   -k, --key      API key (required)
   -u, --user     User name for logs (optional, auto-generated)
-  --port         API port (default: 20001)
+  --port         API port (default: 20099)
   --api          API host (default: localhost)
   --codex        Codex mode: generate AGENTS.md instead of .claude/
   --from <id>    Pull IDE configs from a template project
@@ -208,9 +208,9 @@ async function initProject(opts) {
     if (opts.from) {
         await pullTemplateProject(cwd, apiUrl, opts.from);
     }
-    // --sync: 从源项目同步知识库文档到本地
+    // --sync: 旧文档同步已废弃 (文档现在内嵌在流程图节点中)
     if (opts.sync) {
-        await syncKnowledgeBase(cwd, apiUrl, opts.sync);
+        console.log(`⚠️  --sync is deprecated. Documents are now embedded in flowchart nodes.`);
     }
     console.log(`
 🎉 Done! ppdocs MCP configured for project: ${opts.project}
@@ -236,48 +236,6 @@ async function pullTemplateProject(cwd, apiUrl, templateId) {
         console.log(`⚠️  Failed to pull from template project: ${e}`);
     }
 }
-/** 从源项目同步知识库文档到本地 ./docs/ppdocs/ */
-async function syncKnowledgeBase(cwd, apiUrl, sourceId) {
-    console.log(`📚 Syncing knowledge base from project: ${sourceId}...`);
-    try {
-        const client = new PpdocsApiClient(apiUrl);
-        const docs = await client.crossListDocs(sourceId);
-        const docNodes = docs.filter(d => !d.isDir);
-        if (docNodes.length === 0) {
-            console.log(`⚠️  Project "${sourceId}" has no knowledge base documents`);
-            return;
-        }
-        const docsDir = path.join(cwd, 'docs', 'ppdocs', sourceId);
-        fs.mkdirSync(docsDir, { recursive: true });
-        let synced = 0;
-        for (const node of docNodes) {
-            const doc = await client.crossGetDoc(sourceId, node.path);
-            if (!doc)
-                continue;
-            // 将文档路径转为本地文件路径 (e.g. "/前端/组件/Modal" → "前端/组件/Modal.md")
-            const safePath = node.path.replace(/^\//, '').replace(/[<>:"|?*]/g, '_');
-            const localFile = path.join(docsDir, `${safePath}.md`);
-            const localDir = path.dirname(localFile);
-            if (!fs.existsSync(localDir)) {
-                fs.mkdirSync(localDir, { recursive: true });
-            }
-            // 生成 Markdown 文件内容
-            const content = [
-                `# ${node.name}`,
-                '',
-                doc.summary ? `> ${doc.summary}` : '',
-                '',
-                doc.content || '',
-            ].filter(Boolean).join('\n');
-            fs.writeFileSync(localFile, content, 'utf-8');
-            synced++;
-        }
-        console.log(`✅ Synced ${synced} documents from "${sourceId}" to docs/ppdocs/${sourceId}/`);
-    }
-    catch (e) {
-        console.log(`⚠️  Failed to sync knowledge base: ${e}`);
-    }
-}
 /** 检测命令是否存在 */
 function commandExists(cmd) {
     try {
@@ -432,9 +390,7 @@ function generateMcpPermissions() {
         // 初始化 + 导航
         'kg_init',
         'kg_status',
-        'kg_tree',
         // 知识管理
-        'kg_doc',
         'kg_projects',
         'kg_rules',
         // 工作流

package/dist/storage/httpClient.d.ts

@@ -2,30 +2,14 @@
  * ppdocs MCP HTTP API Client
  * 通过 HTTP API 调用主程序，替代直接文件访问
  *
- * API URL 格式: http://localhost:20001/api/:projectId/:password/...
+ * API URL 格式: http://localhost:20099/api/:projectId/:password/...
  */
-import type { DocData, DocNode, Task, TaskSummary, TaskLogType, TaskExperience, FileInfo, RuleMeta } from './types.js';
-interface TreeNode {
-    path: string;
-    name: string;
-    summary?: string;
-    isDir: boolean;
-    children?: TreeNode[];
-}
+import type { Task, TaskSummary, TaskLogType, TaskExperience, FileInfo, RuleMeta } from './types.js';
 export declare class PpdocsApiClient {
     private baseUrl;
     private serverUrl;
     constructor(apiUrl: string);
     private request;
-    listDocs(): Promise<DocNode[]>;
-    getDoc(docPath: string): Promise<DocData | null>;
-    createDoc(docPath: string, doc: Partial<DocData>): Promise<DocData>;
-    updateDoc(docPath: string, updates: Partial<DocData>): Promise<DocData | null>;
-    deleteDoc(docPath: string): Promise<boolean>;
-    /** 按状态筛选文档 */
-    getDocsByStatus(statusList: string[]): Promise<DocNode[]>;
-    /** 获取目录树结构 */
-    getTree(): Promise<TreeNode[]>;
     getRulesApi(ruleType: string): Promise<string[]>;
     saveRulesApi(ruleType: string, rules: string[]): Promise<boolean>;
     getRulesMeta(): Promise<Record<string, RuleMeta>>;
@@ -62,14 +46,6 @@ export declare class PpdocsApiClient {
         description: string;
         updatedAt: 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[]>;
     /** 列出项目文件 */
@@ -149,4 +125,3 @@ export declare class PpdocsApiClient {
 }
 export declare function initClient(apiUrl: string): void;
 export declare function getClient(): PpdocsApiClient;
-export type { TreeNode };

package/dist/storage/httpClient.js

@@ -2,7 +2,7 @@
  * ppdocs MCP HTTP API Client
  * 通过 HTTP API 调用主程序，替代直接文件访问
  *
- * API URL 格式: http://localhost:20001/api/:projectId/:password/...
+ * API URL 格式: http://localhost:20099/api/:projectId/:password/...
  */
 // ============ 工具函数 ============
 /** 清理路径前缀斜杠 */
@@ -55,43 +55,10 @@ async function fetchAndExtractZip(url, localPath) {
         clearTimeout(timeout);
     }
 }
-/** 从扁平文档列表构建目录树 */
-function buildTree(docs) {
-    const root = [];
-    const pathMap = new Map();
-    // 按路径深度排序，确保父目录先处理
-    const sorted = [...docs].sort((a, b) => {
-        const depthA = (a.path.match(/\//g) || []).length;
-        const depthB = (b.path.match(/\//g) || []).length;
-        return depthA - depthB;
-    });
-    for (const doc of sorted) {
-        const node = {
-            path: doc.path,
-            name: doc.name,
-            summary: doc.summary,
-            isDir: doc.isDir,
-            children: doc.isDir ? [] : undefined
-        };
-        // 找父路径
-        const lastSlash = doc.path.lastIndexOf('/');
-        const parentPath = lastSlash > 0 ? doc.path.substring(0, lastSlash) : '';
-        if (parentPath && pathMap.has(parentPath)) {
-            pathMap.get(parentPath).children.push(node);
-        }
-        else {
-            root.push(node);
-        }
-        if (doc.isDir) {
-            pathMap.set(doc.path, node);
-        }
-    }
-    return root;
-}
 // API 客户端类
 export class PpdocsApiClient {
-    baseUrl; // http://localhost:20001/api/projectId/password
-    serverUrl; // http://localhost:20001
+    baseUrl; // http://localhost:20099/api/projectId/password
+    serverUrl; // http://localhost:20099
     constructor(apiUrl) {
         this.baseUrl = apiUrl.replace(/\/$/, '');
         // 从 /api/projectId/password 提取服务器根地址
@@ -132,77 +99,6 @@ export class PpdocsApiClient {
             clearTimeout(timeout);
         }
     }
-    // ============ 文档操作 ============
-    async listDocs() {
-        return this.request('/docs');
-    }
-    async getDoc(docPath) {
-        try {
-            return await this.request(`/docs/${cleanPath(docPath)}`);
-        }
-        catch {
-            return null;
-        }
-    }
-    async createDoc(docPath, doc) {
-        const payload = {
-            summary: doc.summary || '',
-            content: doc.content || '',
-            versions: doc.versions || [{
-                    version: 0.1,
-                    date: new Date().toISOString(),
-                    changes: '初始创建'
-                }],
-            bugfixes: doc.bugfixes || [],
-            status: doc.status || '已完成'
-        };
-        return this.request(`/docs/${cleanPath(docPath)}`, {
-            method: 'POST',
-            body: JSON.stringify(payload)
-        });
-    }
-    async updateDoc(docPath, updates) {
-        try {
-            const existing = await this.getDoc(docPath);
-            if (!existing)
-                return null;
-            const payload = {
-                summary: updates.summary ?? existing.summary,
-                content: updates.content ?? existing.content,
-                versions: updates.versions ?? existing.versions,
-                bugfixes: updates.bugfixes ?? existing.bugfixes,
-                status: updates.status ?? existing.status ?? '已完成'
-            };
-            return await this.request(`/docs/${cleanPath(docPath)}`, {
-                method: 'PUT',
-                body: JSON.stringify(payload)
-            });
-        }
-        catch {
-            return null;
-        }
-    }
-    async deleteDoc(docPath) {
-        try {
-            await this.request(`/docs/${cleanPath(docPath)}`, { method: 'DELETE' });
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-    /** 按状态筛选文档 */
-    async getDocsByStatus(statusList) {
-        return this.request('/docs/by-status', {
-            method: 'POST',
-            body: JSON.stringify({ status_list: statusList })
-        });
-    }
-    /** 获取目录树结构 */
-    async getTree() {
-        const docs = await this.listDocs();
-        return buildTree(docs);
-    }
     // ============ 规则 API ============
     async getRulesApi(ruleType) {
         try {
@@ -389,31 +285,6 @@ export class PpdocsApiClient {
     async crossListProjects() {
         return this.request('/cross/projects');
     }
-    /** 跨项目: 列出文档 */
-    async crossListDocs(target) {
-        return this.request(`/cross/${encodeURIComponent(target)}/docs`);
-    }
-    /** 跨项目: 获取文档 */
-    async crossGetDoc(target, docPath) {
-        try {
-            return await this.request(`/cross/${encodeURIComponent(target)}/docs/${cleanPath(docPath)}`);
-        }
-        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 {

package/dist/storage/types.d.ts

@@ -1,31 +1,3 @@
-/** 版本记录 */
-export interface VersionRecord {
-    version: number;
-    date: string;
-    changes: string;
-}
-/** 错误修复记录 */
-export interface BugfixRecord {
-    date: string;
-    issue: string;
-    solution: string;
-}
-/** 文档数据 (5个核心字段) */
-export interface DocData {
-    summary: string;
-    content: string;
-    versions: VersionRecord[];
-    bugfixes: BugfixRecord[];
-    status?: string;
-}
-/** 文档节点 (含路径信息，用于列表展示) */
-export interface DocNode {
-    path: string;
-    name: string;
-    summary: string;
-    isDir: boolean;
-    status?: string;
-}
 export interface RuleMeta {
     label: string;
     keywords: string[];

package/dist/storage/types.js

@@ -1,2 +1,2 @@
-// ppdocs - 文档类型定义 (简化版)
+// ppdocs - 类型定义
 export {};

package/dist/tools/flowchart.d.ts

@@ -1,7 +1,3 @@
-/**
- * 🔀 kg_flowchart — 逻辑流程图批量操作
- * AI 一次提交所有节点+边, 后端原子处理, 返回孤立检测结果
- */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type McpContext } from './shared.js';
-export declare function registerFlowchartTools(server: McpServer, ctx: McpContext): void;
+export declare function registerFlowchartTools(server: McpServer, _ctx: McpContext): void;