@ppdocs/mcp 2.1.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/cli.js

@@ -4,6 +4,11 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+/** 生成随机用户名 (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' };
     for (let i = 0; i < args.length; i++) {
@@ -14,6 +19,9 @@ function parseArgs(args) {
         else if (arg === '-k' || arg === '--key') {
             opts.key = args[++i];
         }
+        else if (arg === '-u' || arg === '--user') {
+            opts.user = args[++i];
+        }
         else if (arg === '--port') {
             opts.port = parseInt(args[++i], 10);
         }
@@ -23,6 +31,9 @@ function parseArgs(args) {
     }
     if (!opts.project || !opts.key)
         return null;
+    // 如果没设置 user，自动生成
+    if (!opts.user)
+        opts.user = generateUser();
     return opts;
 }
 function showHelp() {
@@ -38,11 +49,13 @@ Usage:
 Options:
   -p, --project  Project ID (required)
   -k, --key      API key (required)
+  -u, --user     User name for logs (optional, auto-generated if not set)
   --port         API port (default: 20001)
   --api          API host (default: localhost)
 
 Example:
   npx @ppdocs/mcp init -p myproject -k abc123xyz
+  npx @ppdocs/mcp init -p myproject -k abc123xyz -u alice
 `);
 }
 export function runCli(args) {
@@ -70,6 +83,7 @@ function initProject(opts) {
         api: `http://${opts.api}:${opts.port}`,
         projectId: opts.project,
         key: opts.key,
+        user: opts.user,
     };
     const ppdocsPath = path.join(cwd, '.ppdocs');
     fs.writeFileSync(ppdocsPath, JSON.stringify(ppdocsConfig, null, 2));
@@ -96,6 +110,7 @@ function initProject(opts) {
     console.log(`✅ Created ${mcpPath}`);
     console.log(`
 🎉 Done! ppdocs MCP configured for project: ${opts.project}
+   User: ${opts.user}
 
 Restart Claude Code to use ppdocs knowledge graph.
 `);

package/dist/config.d.ts

@@ -5,6 +5,7 @@
 export interface PpdocsConfig {
     apiUrl: string;
     projectId: string;
+    user: string;
 }
 /**
  * 加载配置 (优先级: 环境变量 > .ppdocs 文件)

package/dist/config.js

@@ -4,6 +4,11 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+/** 生成随机用户名 (8位字母数字) */
+function generateUser() {
+    const chars = 'abcdefghjkmnpqrstuvwxyz23456789';
+    return Array.from({ length: 8 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');
+}
 /**
  * 从 .ppdocs 文件读取配置
  */
@@ -22,6 +27,7 @@ function readPpdocsFile() {
         return {
             apiUrl: `${config.api}/api/${config.projectId}/${config.key}`,
             projectId: config.projectId,
+            user: config.user || generateUser(),
         };
     }
     catch {
@@ -38,7 +44,8 @@ function readEnvConfig() {
     // URL 格式: http://localhost:20001/api/{projectId}/{password}
     const match = apiUrl.match(/\/api\/([^/]+)\/[^/]+\/?$/);
     const projectId = match?.[1] || 'unknown';
-    return { apiUrl, projectId };
+    const user = process.env.PPDOCS_USER || generateUser();
+    return { apiUrl, projectId, user };
 }
 /**
  * 加载配置 (优先级: 环境变量 > .ppdocs 文件)

package/dist/index.js

@@ -21,11 +21,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.1.0' }, { capabilities: { tools: {} } });
-    registerTools(server, config.projectId);
+    const server = new McpServer({ name: `ppdocs [${config.projectId}]`, version: '2.3.0' }, { capabilities: { tools: {} } });
+    registerTools(server, config.projectId, config.user);
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error(`ppdocs MCP v2.1 | project: ${config.projectId}`);
+    console.error(`ppdocs MCP v2.3 | project: ${config.projectId} | user: ${config.user}`);
 }
 main().catch((err) => {
     console.error('Fatal error:', err);

package/dist/storage/httpClient.d.ts

@@ -4,7 +4,7 @@
  *
  * API URL 格式: http://localhost:20001/api/:projectId/:password/...
  */
-import type { NodeData, SearchResult, PathResult, BugfixRecord } from './types.js';
+import type { NodeData, SearchResult, PathResult, BugfixRecord, Task, TaskSummary, TaskLogType, TaskExperience } from './types.js';
 export declare class PpdocsApiClient {
     private baseUrl;
     constructor(apiUrl: string);
@@ -35,6 +35,16 @@ export declare class PpdocsApiClient {
         solution: string;
         impact?: string;
     }): Promise<BugfixRecord | null>;
+    listTasks(status?: 'active' | 'archived'): Promise<TaskSummary[]>;
+    getTask(taskId: string): Promise<Task | null>;
+    createTask(task: {
+        title: string;
+        description: string;
+        goals: string[];
+        related_nodes?: string[];
+    }, creator: string): Promise<Task>;
+    addTaskLog(taskId: string, logType: TaskLogType, content: string): Promise<Task | null>;
+    completeTask(taskId: string, experience: TaskExperience): Promise<Task | null>;
 }
 export declare function initClient(apiUrl: string): void;
 export declare function listNodes(_projectId: string): Promise<NodeData[]>;
@@ -63,3 +73,13 @@ export declare function addBugfix(_projectId: string, nodeId: string, bugfix: {
     solution: string;
     impact?: string;
 }): Promise<BugfixRecord | null>;
+export declare function listTasks(_projectId: string, status?: 'active' | 'archived'): Promise<TaskSummary[]>;
+export declare function getTask(_projectId: string, taskId: string): Promise<Task | null>;
+export declare function createTask(_projectId: string, task: {
+    title: string;
+    description: string;
+    goals: string[];
+    related_nodes?: string[];
+}, 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>;

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() {
@@ -159,6 +173,57 @@ export class PpdocsApiClient {
         });
         return updated ? newBugfix : null;
     }
+    // ============ 任务管理 ============
+    async listTasks(status) {
+        const query = status ? `?status=${status}` : '';
+        return this.request(`/tasks${query}`);
+    }
+    async getTask(taskId) {
+        try {
+            return await this.request(`/tasks/${taskId}`);
+        }
+        catch {
+            return null;
+        }
+    }
+    async createTask(task, creator) {
+        const now = new Date().toISOString();
+        const payload = {
+            title: task.title,
+            creator,
+            detail: {
+                description: task.description,
+                goals: task.goals,
+                related_nodes: task.related_nodes || []
+            }
+        };
+        return this.request('/tasks', {
+            method: 'POST',
+            body: JSON.stringify(payload)
+        });
+    }
+    async addTaskLog(taskId, logType, content) {
+        try {
+            return await this.request(`/tasks/${taskId}/logs`, {
+                method: 'POST',
+                body: JSON.stringify({ log_type: logType, content })
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+    async completeTask(taskId, experience) {
+        try {
+            return await this.request(`/tasks/${taskId}/complete`, {
+                method: 'POST',
+                body: JSON.stringify(experience)
+            });
+        }
+        catch {
+            return null;
+        }
+    }
 }
 // ============ 模块级 API (兼容现有 tools/index.ts) ============
 let client = null;
@@ -205,3 +270,19 @@ export async function getRelations(_projectId, nodeId) {
 export async function addBugfix(_projectId, nodeId, bugfix) {
     return getClient().addBugfix(nodeId, bugfix);
 }
+// ============ 任务管理 ============
+export async function listTasks(_projectId, status) {
+    return getClient().listTasks(status);
+}
+export async function getTask(_projectId, taskId) {
+    return getClient().getTask(taskId);
+}
+export async function createTask(_projectId, task, creator) {
+    return getClient().createTask(task, creator);
+}
+export async function addTaskLog(_projectId, taskId, logType, content) {
+    return getClient().addTaskLog(taskId, logType, content);
+}
+export async function completeTask(_projectId, taskId, experience) {
+    return getClient().completeTask(taskId, experience);
+}

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;
@@ -71,3 +71,46 @@ export interface PathResult {
     path: NodeData[];
     edges: Edge[];
 }
+export type TaskLogType = 'progress' | 'issue' | 'solution' | 'reference';
+export interface TaskLog {
+    time: string;
+    log_type: TaskLogType;
+    content: string;
+}
+export interface TaskReference {
+    title: string;
+    url?: string;
+}
+export interface TaskExperience {
+    summary: string;
+    difficulties: string[];
+    solutions: string[];
+    references: TaskReference[];
+}
+export interface TaskDetail {
+    description: string;
+    goals: string[];
+    related_nodes: string[];
+}
+export interface Task {
+    id: string;
+    title: string;
+    status: 'active' | 'archived';
+    creator: string;
+    project_id: string;
+    created_at: string;
+    updated_at: string;
+    completed_at?: string;
+    detail: TaskDetail;
+    logs: TaskLog[];
+    experience?: TaskExperience;
+}
+export interface TaskSummary {
+    id: string;
+    title: string;
+    status: string;
+    creator: string;
+    created_at: string;
+    updated_at: string;
+    last_log?: 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): void;
+export declare function registerTools(server: McpServer, projectId: string, _user: string): void;

package/dist/tools/index.js

@@ -1,43 +1,28 @@
 import { z } from 'zod';
 import * as storage from '../storage/httpClient.js';
-export function registerTools(server, projectId) {
+export function registerTools(server, projectId, _user) {
     // 1. 创建节点
-    server.tool('kg_create_node', '创建新节点', {
+    server.tool('kg_create_node', '创建知识节点。type: logic=逻辑/函数, data=数据结构, intro=概念介绍', {
         title: z.string().describe('节点标题'),
         type: z.enum(['logic', 'data', 'intro']).describe('节点类型'),
-        description: z.string().describe(`节点描述(Markdown格式)。要求使用可视化元素：
-
-1. **流程图用Mermaid**:
-\`\`\`mermaid
-graph LR
-  A[输入] --> B{判断} --> C[输出]
-\`\`\`
-
-2. **接口用表格**:
-| 参数 | 类型 | 说明 |
-|-----|------|-----|
-| id | string | 唯一标识 |
-
-3. **禁止纯文字堆砌**`),
-        signature: z.string().optional().describe('方法签名(用于自动关联,默认=title)'),
-        x: z.number().optional().describe('X坐标'),
-        y: z.number().optional().describe('Y坐标'),
-        tags: z.array(z.string()).optional().describe('标签列表'),
+        description: z.string().describe('Markdown描述(用Mermaid流程图+表格,禁止纯文字)'),
+        signature: z.string().optional().describe('唯一签名(用于依赖匹配,默认=title)'),
+        tags: z.array(z.string()).optional().describe('分类标签'),
         dependencies: z.array(z.object({
-            name: z.string().describe('依赖名称(匹配其他节点signature)'),
+            name: z.string().describe('目标节点的signature'),
             description: z.string().describe('依赖说明')
-        })).optional().describe('依赖列表(自动渲染连线)')
+        })).optional().describe('依赖列表(自动生成连线)')
     }, async (args) => {
         const node = await storage.createNode(projectId, {
             title: args.title,
             type: args.type,
             status: 'incomplete',
             description: args.description || '',
-            x: args.x, // undefined 时由 fileStorage 自动布局
-            y: args.y,
+            x: 0, // 服务端自动布局
+            y: 0,
             locked: false,
             signature: args.signature || args.title,
-            categories: args.tags || [], // API 参数名保持 tags，内部存储为 categories
+            categories: args.tags || [],
             dependencies: args.dependencies || []
         });
         return { content: [{ type: 'text', text: JSON.stringify(node, null, 2) }] };
@@ -48,16 +33,16 @@ graph LR
         return { content: [{ type: 'text', text: success ? '删除成功' : '删除失败(节点不存在/已锁定/是根节点)' }] };
     });
     // 3. 更新节点
-    server.tool('kg_update_node', '更新节点(锁定节点不可更新)', {
+    server.tool('kg_update_node', '更新节点内容(锁定节点不可更新)', {
         nodeId: z.string().describe('节点ID'),
         title: z.string().optional().describe('新标题'),
-        signature: z.string().optional().describe('新方法签名(用于自动关联)'),
-        description: z.string().optional().describe('新描述(Markdown格式，用Mermaid流程图+表格，禁止纯文字)'),
-        status: z.enum(['incomplete', 'complete', 'fixing', 'refactoring', 'deprecated']).optional(),
-        tags: z.array(z.string()).optional(),
+        signature: z.string().optional().describe('新签名'),
+        description: z.string().optional().describe('新描述(Markdown)'),
+        status: z.enum(['incomplete', 'complete', 'fixing', 'refactoring', 'deprecated']).optional().describe('状态'),
+        tags: z.array(z.string()).optional().describe('分类标签'),
         dependencies: z.array(z.object({
-            name: z.string().describe('依赖名称'),
-            description: z.string().describe('依赖说明')
+            name: z.string(),
+            description: z.string()
         })).optional().describe('依赖列表')
     }, async (args) => {
         const { nodeId, tags, ...rest } = args;
@@ -66,18 +51,17 @@ graph LR
         const node = await storage.updateNode(projectId, nodeId, updates);
         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);
+        const node = await storage.lockNode(projectId, args.nodeId, true); // 强制锁定
         return { content: [{ type: 'text', text: node ? JSON.stringify(node, null, 2) : '操作失败' }] };
     });
     // 5. 搜索节点
-    server.tool('kg_search', '多关键词搜索节点(OR逻辑),按权重排序(title:3>tags:2.5>signature:2>desc:1)', {
-        keywords: z.array(z.string()).describe('搜索关键词列表'),
-        limit: z.number().optional().describe('返回数量限制(默认20)')
+    server.tool('kg_search', '关键词搜索节点,按相关度排序返回', {
+        keywords: z.array(z.string()).describe('关键词列表(OR逻辑)'),
+        limit: z.number().optional().describe('返回数量(默认20)')
     }, async (args) => {
         const results = await storage.searchNodes(projectId, args.keywords, args.limit);
         const output = results.map(r => ({
@@ -87,9 +71,9 @@ graph LR
         return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
     });
     // 6. 路径查找
-    server.tool('kg_find_path', '查找两个节点之间的逻辑流路径,返回中间所有节点和边', {
-        startId: z.string().describe('起始节点ID'),
-        endId: z.string().describe('目标节点ID')
+    server.tool('kg_find_path', '查找两节点间的依赖路径', {
+        startId: z.string().describe('起点节点ID'),
+        endId: z.string().describe('终点节点ID')
     }, async (args) => {
         const result = await storage.findPath(projectId, args.startId, args.endId);
         if (!result)
@@ -102,13 +86,13 @@ graph LR
         return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
     });
     // 7. 列出所有节点
-    server.tool('kg_list_nodes', '列出当前项目所有节点(返回id,title,type,status,locked)', {}, async () => {
+    server.tool('kg_list_nodes', '列出项目全部节点概览', {}, async () => {
         const nodes = await storage.listNodes(projectId);
         const output = nodes.map(n => ({ id: n.id, title: n.title, type: n.type, status: n.status, locked: n.locked }));
         return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
     });
     // 8. 查找孤立节点
-    server.tool('kg_find_orphans', '查找孤立节点（没有任何连线的节点）', {}, async () => {
+    server.tool('kg_find_orphans', '查找无连线的孤立节点(用于清理)', {}, async () => {
         const orphans = await storage.findOrphans(projectId);
         if (orphans.length === 0) {
             return { content: [{ type: 'text', text: '没有孤立节点' }] };
@@ -116,7 +100,7 @@ graph LR
         return { content: [{ type: 'text', text: JSON.stringify(orphans, null, 2) }] };
     });
     // 9. 查询节点关系网
-    server.tool('kg_get_relations', '查询节点关系网（所有直接连接的节点及其介绍）', {
+    server.tool('kg_get_relations', '获取节点的上下游关系(谁依赖它/它依赖谁)', {
         nodeId: z.string().describe('节点ID')
     }, async (args) => {
         const relations = await storage.getRelations(projectId, args.nodeId);
@@ -132,18 +116,79 @@ graph LR
         };
         return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
     });
-    // 10. 添加错误修复记录
-    server.tool('kg_add_bugfix', '添加错误修复记录到节点(自动生成ID和时间戳)', {
-        nodeId: z.string().describe('节点ID'),
-        issue: z.string().describe('问题描述'),
-        solution: z.string().describe('解决方案'),
-        impact: z.string().optional().describe('影响范围')
+    // ===================== 任务管理工具 =====================
+    // 10. 创建任务
+    server.tool('task_create', '创建开发任务,记录目标和关联节点', {
+        title: z.string().describe('任务标题'),
+        description: z.string().describe('任务描述(Markdown)'),
+        goals: z.array(z.string()).optional().describe('目标清单'),
+        related_nodes: z.array(z.string()).optional().describe('关联节点ID')
+    }, async (args) => {
+        const task = await storage.createTask(projectId, {
+            title: args.title,
+            description: args.description,
+            goals: args.goals || [],
+            related_nodes: args.related_nodes
+        }, _user);
+        return { content: [{ type: 'text', text: JSON.stringify(task, null, 2) }] };
+    });
+    // 11. 列出任务
+    server.tool('task_list', '列出任务(active=进行中,archived=已归档)', {
+        status: z.enum(['active', 'archived']).optional().describe('状态筛选')
+    }, async (args) => {
+        const tasks = await storage.listTasks(projectId, args.status);
+        const output = tasks.map(t => ({
+            id: t.id,
+            title: t.title,
+            status: t.status,
+            creator: t.creator,
+            created_at: t.created_at,
+            last_log: t.last_log
+        }));
+        return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
+    });
+    // 12. 获取任务详情
+    server.tool('task_get', '获取任务完整信息(含全部日志)', {
+        taskId: z.string().describe('任务ID')
+    }, async (args) => {
+        const task = await storage.getTask(projectId, args.taskId);
+        if (!task) {
+            return { content: [{ type: 'text', text: '任务不存在' }] };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(task, null, 2) }] };
+    });
+    // 13. 添加任务日志
+    server.tool('task_add_log', '记录任务进展/问题/方案/参考', {
+        taskId: z.string().describe('任务ID'),
+        log_type: z.enum(['progress', 'issue', 'solution', 'reference']).describe('日志类型'),
+        content: z.string().describe('日志内容(Markdown)')
     }, async (args) => {
-        const bugfix = await storage.addBugfix(projectId, args.nodeId, {
-            issue: args.issue,
-            solution: args.solution,
-            impact: args.impact
+        const task = await storage.addTaskLog(projectId, args.taskId, args.log_type, args.content);
+        if (!task) {
+            return { content: [{ type: 'text', text: '添加失败(任务不存在或已归档)' }] };
+        }
+        return { content: [{ type: 'text', text: `日志已添加，任务共有 ${task.logs.length} 条日志` }] };
+    });
+    // 14. 完成任务
+    server.tool('task_complete', '完成任务并归档,填写经验总结', {
+        taskId: z.string().describe('任务ID'),
+        summary: z.string().describe('经验总结(Markdown)'),
+        difficulties: z.array(z.string()).optional().describe('遇到的困难'),
+        solutions: z.array(z.string()).optional().describe('解决方案'),
+        references: z.array(z.object({
+            title: z.string(),
+            url: z.string().optional()
+        })).optional().describe('参考资料')
+    }, async (args) => {
+        const task = await storage.completeTask(projectId, args.taskId, {
+            summary: args.summary,
+            difficulties: args.difficulties || [],
+            solutions: args.solutions || [],
+            references: args.references || []
         });
-        return { content: [{ type: 'text', text: bugfix ? JSON.stringify(bugfix, null, 2) : '添加失败(节点不存在或已锁定)' }] };
+        if (!task) {
+            return { content: [{ type: 'text', text: '完成失败(任务不存在或已归档)' }] };
+        }
+        return { content: [{ type: 'text', text: `任务已完成归档: ${task.title}` }] };
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ppdocs/mcp",
-  "version": "2.1.0",
+  "version": "2.4.0",
   "description": "ppdocs MCP Server - Knowledge Graph for Claude",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,7 @@
     "url": "https://github.com/ppdocs/ppdocs"
   },
   "license": "MIT",
-  "files": ["dist", "README.md"],
+  "files": ["dist", "templates", "README.md"],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "proper-lockfile": "^4.1.2",

package/templates/AGENT.md

@@ -0,0 +1,30 @@
+# AGENT.md - ppdocs Knowledge Graph Agent
+
+> TODO: 完善此提示词内容
+
+## Role
+
+你是一个项目知识管理助手，负责与 ppdocs 知识图谱交互。
+
+## 核心原则
+
+1. **知识优先**: 修改代码前先查询知识库
+2. **同步更新**: 代码变更后更新对应知识节点
+3. **结构化记录**: 使用 Mermaid 流程图 + 表格
+
+## 可用工具
+
+- `kg_search` - 搜索知识节点
+- `kg_create_node` - 创建新节点
+- `kg_update_node` - 更新节点
+- `kg_get_relations` - 查询节点关系
+
+## 工作流程
+
+```
+查询知识库 → 分析现状 → 执行任务 → 更新知识库
+```
+
+---
+
+*此文件由 `npx @ppdocs/mcp init --agent` 生成*

package/templates/README.md

@@ -0,0 +1,57 @@
+# MCP Templates
+
+此目录包含 `npx @ppdocs/mcp init` 安装时使用的模板文件。
+
+## 文件说明
+
+| 文件 | 用途 | 安装参数 | 目标路径 |
+|-----|------|---------|---------|
+| `AGENT.md` | Codex/通用 Agent 提示词 | `--agent` | `./AGENT.md` |
+| `claude-hooks.json` | Claude Code hooks 配置 | `--hooks` | `.claude/settings.local.json` |
+
+## 安装命令
+
+```bash
+# 基础安装 (只生成 .ppdocs + .mcp.json)
+npx @ppdocs/mcp init -p <projectId> -k <key>
+
+# 安装 + Claude hooks
+npx @ppdocs/mcp init -p <projectId> -k <key> --hooks
+
+# 安装 + AGENT.md
+npx @ppdocs/mcp init -p <projectId> -k <key> --agent
+
+# 完整安装 (全部文件)
+npx @ppdocs/mcp init -p <projectId> -k <key> --all
+```
+
+## 配置合并逻辑
+
+### Claude Hooks (`--hooks`)
+
+安装时会**合并**到 `.claude/settings.local.json`：
+- 如果文件不存在：创建新文件
+- 如果文件存在：保留用户配置，只追加/更新 hooks 部分
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "command": "cat path/to/prompt.md"
+      }
+    ]
+  }
+}
+```
+
+### AGENT.md (`--agent`)
+
+直接复制到项目根目录，如已存在会提示是否覆盖。
+
+## TODO
+
+- [ ] 完善 AGENT.md 提示词内容
+- [ ] 完善 claude-hooks.json 工作流配置
+- [ ] 更新 CLI 支持 --hooks/--agent/--all 参数

package/templates/claude-hooks.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://raw.githubusercontent.com/anthropics/claude-code/main/schema/settings.json",
+  "_comment": "TODO: 完善 hooks 配置",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "command": "echo '## ppdocs Knowledge Graph\\n请结合知识库进行分析和开发'"
+      }
+    ]
+  }
+}