@ppdocs/mcp 2.3.0 → 2.4.0

package/README.md

@@ -0,0 +1,476 @@
+# @ppdocs/mcp
+
+> Knowledge Graph MCP Server for Claude - 让 Claude 拥有项目知识图谱记忆
+
+[![npm version](https://badge.fury.io/js/%40ppdocs%2Fmcp.svg)](https://www.npmjs.com/package/@ppdocs/mcp)
+
+## 概述
+
+ppdocs MCP 是一个 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，让 Claude 能够在对话中构建和查询项目知识图谱。
+
+```mermaid
+graph LR
+    Claude[Claude AI] -->|MCP| Server[@ppdocs/mcp]
+    Server -->|HTTP API| Backend[ppdocs 桌面应用]
+    Backend -->|文件存储| Data[(知识图谱)]
+
+    style Claude fill:#7c3aed,color:#fff
+    style Server fill:#3b82f6,color:#fff
+    style Backend fill:#10b981,color:#fff
+```
+
+### 核心功能
+
+| 功能 | 描述 |
+|------|------|
+| 📊 **知识图谱** | 创建、更新、删除、搜索节点 |
+| 🔗 **依赖追踪** | 自动计算节点间的依赖关系 |
+| 📝 **任务管理** | 记录开发任务、进度日志、经验总结 |
+| 🔍 **智能搜索** | 多关键词搜索，按相关度排序 |
+| 🛤️ **路径分析** | 查找两节点间的依赖路径 |
+
+---
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+npm install -g @ppdocs/mcp
+```
+
+### 2. 配置 Claude Desktop
+
+在 Claude Desktop 配置文件中添加：
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "ppdocs": {
+      "command": "npx",
+      "args": ["-y", "@ppdocs/mcp"],
+      "env": {
+        "PPDOCS_API_URL": "http://localhost:20001/api/项目ID/密码"
+      }
+    }
+  }
+}
+```
+
+### 3. 获取 API URL
+
+1. 打开 ppdocs 桌面应用
+2. 选择一个项目 → 点击设置图标
+3. 复制 **MCP 连接地址**
+
+```mermaid
+sequenceDiagram
+    participant U as 用户
+    participant App as ppdocs 桌面应用
+    participant Claude as Claude Desktop
+
+    U->>App: 1. 打开项目设置
+    App->>U: 2. 显示 MCP 连接地址
+    U->>Claude: 3. 配置 claude_desktop_config.json
+    Claude->>App: 4. MCP 连接成功
+```
+
+---
+
+## 工具列表
+
+### 知识图谱工具
+
+```mermaid
+mindmap
+  root((知识图谱))
+    创建
+      kg_create_node
+    修改
+      kg_update_node
+      kg_lock_node
+      kg_delete_node
+    查询
+      kg_list_nodes
+      kg_search
+      kg_find_path
+      kg_find_orphans
+      kg_get_relations
+```
+
+#### `kg_create_node` - 创建节点
+
+创建一个新的知识节点。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `title` | string | ✅ | 节点标题 |
+| `type` | enum | ✅ | 节点类型: `logic`(逻辑/函数), `data`(数据结构), `intro`(概念介绍) |
+| `description` | string | ✅ | Markdown 描述 (建议使用 Mermaid 图表 + 表格) |
+| `signature` | string | ❌ | 唯一签名，用于依赖匹配 (默认=title) |
+| `tags` | string[] | ❌ | 分类标签 |
+| `dependencies` | object[] | ❌ | 依赖列表: `[{name: "目标签名", description: "依赖说明"}]` |
+
+**示例：**
+```
+Claude, 创建一个节点记录用户认证模块
+```
+
+---
+
+#### `kg_update_node` - 更新节点
+
+更新现有节点的内容（锁定节点不可更新）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `nodeId` | string | ✅ | 节点 ID |
+| `title` | string | ❌ | 新标题 |
+| `description` | string | ❌ | 新描述 |
+| `status` | enum | ❌ | 状态: `incomplete`, `complete`, `fixing`, `refactoring`, `deprecated` |
+| `tags` | string[] | ❌ | 新标签 |
+| `dependencies` | object[] | ❌ | 新依赖列表 |
+
+---
+
+#### `kg_delete_node` - 删除节点
+
+删除指定节点（锁定节点和根节点不可删除）。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `nodeId` | string | ✅ | 节点 ID |
+
+---
+
+#### `kg_lock_node` - 锁定节点
+
+锁定节点后只能读取，不能修改或删除。
+
+> ⚠️ **安全限制**: AI 只能锁定节点，**不能解锁**。解锁需要用户在前端手动操作。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `nodeId` | string | ✅ | 节点 ID |
+
+---
+
+#### `kg_list_nodes` - 列出所有节点
+
+获取项目中所有节点的概览。
+
+无参数。
+
+---
+
+#### `kg_search` - 搜索节点
+
+使用关键词搜索节点，按相关度排序返回。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `keywords` | string[] | ✅ | 关键词列表 (OR 逻辑) |
+| `limit` | number | ❌ | 返回数量上限 (默认 20) |
+
+**示例：**
+```
+Claude, 搜索所有和数据库相关的节点
+```
+
+---
+
+#### `kg_find_path` - 查找依赖路径
+
+查找两个节点之间的依赖路径。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `startId` | string | ✅ | 起点节点 ID |
+| `endId` | string | ✅ | 终点节点 ID |
+
+---
+
+#### `kg_find_orphans` - 查找孤立节点
+
+查找没有任何连线的孤立节点，用于清理。
+
+无参数。
+
+---
+
+#### `kg_get_relations` - 获取节点关系
+
+获取指定节点的上下游关系网络。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `nodeId` | string | ✅ | 节点 ID |
+
+**返回：**
+- `outgoing`: 该节点依赖的其他节点
+- `incoming`: 依赖该节点的其他节点
+
+---
+
+### 任务管理工具
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active: task_create
+    Active --> Active: task_add_log
+    Active --> Archived: task_complete
+    Archived --> [*]
+
+    state Active {
+        progress
+        issue
+        solution
+        reference
+    }
+```
+
+#### `task_create` - 创建任务
+
+创建一个新的开发任务。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `title` | string | ✅ | 任务标题 |
+| `description` | string | ✅ | 任务描述 (Markdown) |
+| `goals` | string[] | ❌ | 目标清单 |
+| `related_nodes` | string[] | ❌ | 关联的知识节点 ID |
+
+**示例：**
+```
+Claude, 创建一个任务：实现用户登录功能
+```
+
+---
+
+#### `task_list` - 列出任务
+
+列出项目中的任务。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `status` | enum | ❌ | 筛选: `active`(进行中) 或 `archived`(已归档) |
+
+---
+
+#### `task_get` - 获取任务详情
+
+获取任务的完整信息，包含所有日志记录。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `taskId` | string | ✅ | 任务 ID |
+
+---
+
+#### `task_add_log` - 添加日志
+
+为任务记录进展、问题、方案或参考资料。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `taskId` | string | ✅ | 任务 ID |
+| `log_type` | enum | ✅ | 日志类型: `progress`, `issue`, `solution`, `reference` |
+| `content` | string | ✅ | 日志内容 (Markdown) |
+
+---
+
+#### `task_complete` - 完成任务
+
+完成任务并归档，需要填写经验总结。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `taskId` | string | ✅ | 任务 ID |
+| `summary` | string | ✅ | 经验总结 (Markdown) |
+| `difficulties` | string[] | ❌ | 遇到的困难 |
+| `solutions` | string[] | ❌ | 解决方案 |
+| `references` | object[] | ❌ | 参考资料: `[{title: "标题", url: "链接"}]` |
+
+---
+
+## 数据结构
+
+### 节点类型
+
+```mermaid
+classDiagram
+    class NodeData {
+        +string id
+        +string title
+        +NodeType type
+        +NodeStatus status
+        +string signature
+        +string description
+        +string[] categories
+        +Dependency[] dependencies
+        +boolean locked
+        +number x, y
+    }
+
+    class Dependency {
+        +string name
+        +string description
+    }
+
+    NodeData --> Dependency
+```
+
+| 类型 | 说明 | 适用场景 |
+|------|------|----------|
+| `logic` | 逻辑/函数 | 算法、处理流程、API 接口 |
+| `data` | 数据结构 | 数据库表、配置、状态定义 |
+| `intro` | 概念介绍 | 架构说明、设计决策、术语解释 |
+
+### 节点状态
+
+| 状态 | 说明 |
+|------|------|
+| `incomplete` | 未完成 (默认) |
+| `complete` | 已完成 |
+| `fixing` | 修复中 |
+| `refactoring` | 重构中 |
+| `deprecated` | 已废弃 |
+
+---
+
+## 架构说明
+
+```mermaid
+flowchart TB
+    subgraph Claude["Claude Desktop"]
+        MCP[MCP 协议]
+    end
+
+    subgraph Server["@ppdocs/mcp"]
+        Tools[工具注册]
+        HTTP[HTTP Client]
+    end
+
+    subgraph Backend["ppdocs 桌面应用"]
+        API[REST API]
+        Store[文件存储]
+    end
+
+    subgraph Data["数据目录 ~/.ppdocs"]
+        Projects[projects/]
+        Tasks[tasks/]
+        Backups[backups/]
+    end
+
+    MCP <-->|stdio| Tools
+    Tools --> HTTP
+    HTTP <-->|HTTP| API
+    API --> Store
+    Store --> Projects
+    Store --> Tasks
+    Store --> Backups
+```
+
+### 文件结构
+
+```
+~/.ppdocs/
+├── projects/
+│   └── {project-id}/
+│       ├── meta.json      # 项目元数据
+│       └── nodes/
+│           └── {node-id}.json
+├── tasks/
+│   └── {project-id}/
+│       ├── active/        # 进行中的任务
+│       └── archived/      # 已归档的任务
+└── backups/
+    └── {project-id}/
+        └── {timestamp}/
+```
+
+---
+
+## 环境变量
+
+| 变量 | 说明 | 示例 |
+|------|------|------|
+| `PPDOCS_API_URL` | API 完整地址 | `http://localhost:20001/api/myproject/abc123` |
+| `PPDOCS_PROJECT` | 项目 ID (可选) | `myproject` |
+| `PPDOCS_KEY` | 访问密钥 (可选) | `abc123` |
+| `PPDOCS_USER` | 用户名 (可选) | `developer` |
+| `PPDOCS_PORT` | API 端口 (可选) | `20001` |
+| `PPDOCS_HOST` | API 主机 (可选) | `localhost` |
+
+### 配置文件
+
+也可以在项目根目录创建 `.ppdocs` 文件：
+
+```json
+{
+  "project": "my-project",
+  "key": "abc123",
+  "user": "developer",
+  "port": 20001,
+  "api": "localhost"
+}
+```
+
+---
+
+## 常见问题
+
+### Q: 连接失败怎么办？
+
+1. 确保 ppdocs 桌面应用正在运行
+2. 检查端口是否正确 (默认 20001)
+3. 验证 API URL 格式: `http://localhost:PORT/api/项目ID/密码`
+
+### Q: 节点无法删除？
+
+可能的原因：
+- 节点被锁定 → 在 ppdocs 桌面应用中手动解锁
+- 是根节点 (isOrigin=true) → 根节点不可删除
+
+### Q: 如何备份数据？
+
+1. **桌面应用**: 设置 → 数据管理 → 导出全部项目
+2. **手动备份**: 复制 `~/.ppdocs/` 目录
+
+---
+
+## 更新日志
+
+### v2.4.0
+- 🛡️ 安全增强：`kg_lock_node` 只能锁定，解锁需前端手动操作
+- ⚡ 日志系统重构：后端自动记录操作日志，无需 AI 主动调用
+- 🐛 修复画布缩放闪烁问题
+
+### v2.3.0
+- 新增任务管理功能 (task_create, task_complete 等)
+- 优化搜索算法
+- 添加文件锁防止并发写入
+
+### v2.2.0
+- 从文件存储切换到 HTTP API
+- 支持多用户协作
+
+### v2.0.0
+- 初始 MCP 服务器版本
+
+---
+
+## 许可证
+
+MIT License
+
+---
+
+## 相关链接
+
+- [ppdocs 桌面应用](https://github.com/ppdocs/ppdocs)
+- [MCP 协议文档](https://modelcontextprotocol.io/)
+- [问题反馈](https://github.com/ppdocs/ppdocs/issues)

package/dist/storage/httpClient.d.ts

@@ -83,10 +83,3 @@ 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 interface LogEntry {
-    user: string;
-    action: string;
-    target: string;
-    node_id?: string;
-}
-export declare function appendLog(_projectId: string, entry: LogEntry): Promise<void>;

package/dist/storage/httpClient.js

@@ -14,22 +14,36 @@ export class PpdocsApiClient {
     // ============ HTTP 请求工具 ============
     async request(path, options = {}) {
         const url = `${this.baseUrl}${path}`;
-        const response = await fetch(url, {
-            ...options,
-            headers: {
-                'Content-Type': 'application/json',
-                ...options.headers
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 10000); // 10秒超时
+        try {
+            const response = await fetch(url, {
+                ...options,
+                signal: controller.signal,
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...options.headers
+                }
+            });
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({ error: response.statusText }));
+                throw new Error(error.error || `HTTP ${response.status}`);
             }
-        });
-        if (!response.ok) {
-            const error = await response.json().catch(() => ({ error: response.statusText }));
-            throw new Error(error.error || `HTTP ${response.status}`);
+            const json = await response.json();
+            if (!json.success) {
+                throw new Error(json.error || 'Unknown error');
+            }
+            return json.data;
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error('Request timeout (10s)');
+            }
+            throw err;
         }
-        const json = await response.json();
-        if (!json.success) {
-            throw new Error(json.error || 'Unknown error');
+        finally {
+            clearTimeout(timeout);
         }
-        return json.data;
     }
     // ============ 节点操作 ============
     async listNodes() {
@@ -272,15 +286,3 @@ export async function addTaskLog(_projectId, taskId, logType, content) {
 export async function completeTask(_projectId, taskId, experience) {
     return getClient().completeTask(taskId, experience);
 }
-export async function appendLog(_projectId, entry) {
-    try {
-        await getClient()['request']('/logs', {
-            method: 'POST',
-            body: JSON.stringify(entry)
-        });
-        console.error(`[LOG] ${entry.action}: ${entry.target}`);
-    }
-    catch (err) {
-        console.error(`[LOG ERROR] Failed to append log:`, err);
-    }
-}

package/dist/storage/types.d.ts

@@ -6,7 +6,7 @@ export interface Edge {
     auto?: boolean;
 }
 export type NodeType = 'logic' | 'data' | 'intro';
-export type NodeStatus = 'incomplete' | 'complete' | 'fixing' | 'refactoring' | 'deprecated' | 'locked';
+export type NodeStatus = 'incomplete' | 'complete' | 'fixing' | 'refactoring' | 'deprecated';
 export interface DataRef {
     type: string;
     description: string;

package/dist/tools/index.d.ts

@@ -1,2 +1,2 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function registerTools(server: McpServer, projectId: string, user: string): void;
+export declare function registerTools(server: McpServer, projectId: string, _user: string): void;

package/dist/tools/index.js

@@ -1,10 +1,6 @@
 import { z } from 'zod';
 import * as storage from '../storage/httpClient.js';
-export function registerTools(server, projectId, user) {
-    // 日志辅助函数
-    const log = (action, target, nodeId) => {
-        storage.appendLog(projectId, { user, action, target, node_id: nodeId });
-    };
+export function registerTools(server, projectId, _user) {
     // 1. 创建节点
     server.tool('kg_create_node', '创建知识节点。type: logic=逻辑/函数, data=数据结构, intro=概念介绍', {
         title: z.string().describe('节点标题'),
@@ -29,15 +25,11 @@ export function registerTools(server, projectId, user) {
             categories: args.tags || [],
             dependencies: args.dependencies || []
         });
-        log('create_node', args.title, node.id);
         return { content: [{ type: 'text', text: JSON.stringify(node, null, 2) }] };
     });
     // 2. 删除节点
     server.tool('kg_delete_node', '删除节点(锁定节点和根节点不可删除)', { nodeId: z.string().describe('节点ID') }, async (args) => {
-        const node = await storage.getNode(projectId, args.nodeId);
         const success = await storage.deleteNode(projectId, args.nodeId);
-        if (success)
-            log('delete_node', node?.title || args.nodeId, args.nodeId);
         return { content: [{ type: 'text', text: success ? '删除成功' : '删除失败(节点不存在/已锁定/是根节点)' }] };
     });
     // 3. 更新节点
@@ -57,18 +49,13 @@ export function registerTools(server, projectId, user) {
         // API 参数 tags 转换为内部字段 categories
         const updates = tags !== undefined ? { ...rest, categories: tags } : rest;
         const node = await storage.updateNode(projectId, nodeId, updates);
-        if (node)
-            log('update_node', node.title, nodeId);
         return { content: [{ type: 'text', text: node ? JSON.stringify(node, null, 2) : '更新失败(节点不存在或已锁定)' }] };
     });
-    // 4. 锁定/解锁节点
-    server.tool('kg_lock_node', '锁定/解锁节点(锁定后只能读取)', {
-        nodeId: z.string().describe('节点ID'),
-        locked: z.boolean().describe('true=锁定, false=解锁')
+    // 4. 锁定节点 (只能锁定，解锁需用户在前端手动操作)
+    server.tool('kg_lock_node', '锁定节点(锁定后只能读取，解锁需用户在前端手动操作)', {
+        nodeId: z.string().describe('节点ID')
     }, async (args) => {
-        const node = await storage.lockNode(projectId, args.nodeId, args.locked);
-        if (node)
-            log(args.locked ? 'lock_node' : 'unlock_node', node.title, args.nodeId);
+        const node = await storage.lockNode(projectId, args.nodeId, true); // 强制锁定
         return { content: [{ type: 'text', text: node ? JSON.stringify(node, null, 2) : '操作失败' }] };
     });
     // 5. 搜索节点
@@ -142,8 +129,7 @@ export function registerTools(server, projectId, user) {
             description: args.description,
             goals: args.goals || [],
             related_nodes: args.related_nodes
-        }, user);
-        log('create_task', args.title, task.id);
+        }, _user);
         return { content: [{ type: 'text', text: JSON.stringify(task, null, 2) }] };
     });
     // 11. 列出任务
@@ -181,7 +167,6 @@ export function registerTools(server, projectId, user) {
         if (!task) {
             return { content: [{ type: 'text', text: '添加失败(任务不存在或已归档)' }] };
         }
-        log('add_task_log', `${args.log_type}: ${args.content.slice(0, 50)}...`, args.taskId);
         return { content: [{ type: 'text', text: `日志已添加，任务共有 ${task.logs.length} 条日志` }] };
     });
     // 14. 完成任务
@@ -204,7 +189,6 @@ export function registerTools(server, projectId, user) {
         if (!task) {
             return { content: [{ type: 'text', text: '完成失败(任务不存在或已归档)' }] };
         }
-        log('complete_task', task.title, args.taskId);
         return { content: [{ type: 'text', text: `任务已完成归档: ${task.title}` }] };
     });
 }

package/package.json

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