@ppdocs/mcp 3.12.0 → 3.13.1

package/dist/tools/init.js

@@ -1,89 +0,0 @@
-/**
- * kg_init 工具 — 项目上下文初始化
- *
- * 解决全局共用 MCP 进程时的多项目隔离问题：
- * - 智能体调用 kg_init 传入 projectPath
- * - MCP 从该路径读取 .ppdocs 配置
- * - 重新初始化 HTTP Client 指向正确项目
- * - 更新共享 McpContext，所有工具自动获取新 projectId
- */
-import * as fs from 'fs';
-import * as path from 'path';
-import { z } from 'zod';
-import { initClient } from '../storage/httpClient.js';
-import { generateAgentId } from '../config.js';
-import { wrap, safeTool } from './shared.js';
-// 当前会话的 API URL (用于幂等检查)
-let currentApiUrl = null;
-function findPpdocsPathFrom(dir) {
-    let currentDir = path.resolve(dir);
-    while (true) {
-        const configPath = path.join(currentDir, '.ppdocs');
-        if (fs.existsSync(configPath) && fs.statSync(configPath).isFile()) {
-            return configPath;
-        }
-        const parentDir = path.dirname(currentDir);
-        if (parentDir === currentDir) {
-            return null;
-        }
-        currentDir = parentDir;
-    }
-}
-/** 尝试从指定目录读取 .ppdocs 配置 */
-function readPpdocsFrom(dir) {
-    const configPath = findPpdocsPathFrom(dir);
-    if (!configPath)
-        return null;
-    try {
-        const c = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-        if (!c.api || !c.projectId || !c.key)
-            return null;
-        return {
-            apiUrl: `${c.api}/api/${c.projectId}/${c.key}`,
-            projectId: c.projectId,
-            user: c.user || 'mcp-agent',
-        };
-    }
-    catch {
-        return null;
-    }
-}
-export function registerInitTool(server, ctx, onProjectChange) {
-    server.tool('kg_init', '🔗 项目上下文初始化 — 读取指定目录的 .ppdocs 配置，切换 MCP 连接到对应项目。首次对话必须调用。不传 projectPath 则使用当前工作目录', {
-        projectPath: z.string().optional().describe('项目根目录的绝对路径(含 .ppdocs 文件)，不传则使用 cwd'),
-    }, async ({ projectPath }) => safeTool(async () => {
-        const targetDir = projectPath || process.cwd();
-        // 1. 尝试从目标目录读取 .ppdocs
-        const config = readPpdocsFrom(targetDir);
-        if (!config) {
-            return wrap(`❌ 未在 ${targetDir} 找到 .ppdocs 配置文件\n\n` +
-                `请先在项目目录中运行:\n` +
-                `  npx @ppdocs/mcp init -p <projectId> -k <key>\n\n` +
-                `或通过 WebUI 绑定项目:\n` +
-                `  npx @ppdocs/mcp webui`);
-        }
-        // 2. 幂等检查
-        if (currentApiUrl === config.apiUrl) {
-            return wrap(`✅ 项目上下文已就绪 (无需切换)\n\n` +
-                `📂 项目: ${config.projectId}\n` +
-                `🔗 API: ${config.apiUrl.replace(/\/[^/]+$/, '/***')}\n` +
-                `👤 用户: ${config.user}`);
-        }
-        // 3. 重新初始化 HTTP Client
-        initClient(config.apiUrl);
-        currentApiUrl = config.apiUrl;
-        // 4. 更新共享上下文 — 所有工具立刻获得新 projectId
-        ctx.projectId = config.projectId;
-        ctx.user = config.user;
-        // agentId: 优先环境变量 > 保留当前值(进程启动时已生成)
-        ctx.agentId = process.env.PPDOCS_AGENT_ID || ctx.agentId || generateAgentId();
-        // 5. 通知主进程
-        onProjectChange(config.projectId, config.apiUrl);
-        return wrap(`✅ 项目上下文已初始化\n\n` +
-            `📂 项目: ${config.projectId}\n` +
-            `📁 路径: ${targetDir}\n` +
-            `🔗 API: ${config.apiUrl.replace(/\/[^/]+$/, '/***')}\n` +
-            `👤 用户: ${config.user}\n\n` +
-            `所有后续工具调用将自动连接到此项目。`);
-    }));
-}

package/dist/tools/meeting.d.ts

@@ -1,7 +0,0 @@
-/**
- * 多AI协作会议工具
- * kg_meeting: join | leave | post | claim | release | status
- */
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type McpContext } from './shared.js';
-export declare function registerMeetingTools(server: McpServer, ctx: McpContext): void;

package/dist/tools/meeting.js

@@ -1,97 +0,0 @@
-/**
- * 多AI协作会议工具
- * kg_meeting: join | leave | post | claim | release | status
- */
-import { z } from 'zod';
-import { getClient } from '../storage/httpClient.js';
-import { wrap, safeTool } from './shared.js';
-function formatStatus(status) {
-    const lines = [
-        `🏛️ 会议室: ${status.projectId}`,
-        ``,
-    ];
-    // 参与者
-    if (status.agents.length > 0) {
-        lines.push(`### 👥 参与者 (${status.agents.length})`);
-        for (const agent of status.agents) {
-            const ago = Math.floor((Date.now() / 1000 - agent.lastHeartbeat) / 60);
-            lines.push(`  🤖 ${agent.agentId} (${agent.agentType}) — 心跳 ${ago}分钟前`);
-        }
-        lines.push('');
-    }
-    else {
-        lines.push('📭 会议室为空');
-        lines.push('');
-    }
-    // 文件锁
-    const locks = Object.entries(status.fileLocks);
-    if (locks.length > 0) {
-        lines.push(`### 🔒 文件锁定 (${locks.length})`);
-        for (const [file, owner] of locks) {
-            lines.push(`  📄 ${file} ← ${owner}`);
-        }
-        lines.push('');
-    }
-    // 最近消息
-    if (status.recentMessages.length > 0) {
-        lines.push(`### 💬 最近消息 (${status.recentMessages.length})`);
-        for (const msg of status.recentMessages.slice(-10)) {
-            const time = new Date(msg.timestamp * 1000).toLocaleTimeString();
-            const icon = msg.msgType === 'decision' ? '⚡' : msg.msgType === 'question' ? '❓' : '💬';
-            lines.push(`  ${icon} [${time}] ${msg.agentId}: ${msg.content}`);
-        }
-    }
-    return lines.join('\n');
-}
-export function registerMeetingTools(server, ctx) {
-    const client = () => getClient();
-    server.tool('kg_meeting', '🏛️ 多AI协作会议 — 多个AI编辑器同时操作同一项目时，通过"会议室"共享状态、认领文件、发布决策。action: join(加入)|leave(离开)|post(发消息)|claim(认领文件)|release(释放文件)|status(查看状态)', {
-        action: z.enum(['join', 'leave', 'post', 'claim', 'release', 'status']).describe('操作类型'),
-        agentId: z.string().optional().describe('Agent标识(如"cursor-1", "claude-code-2")。join/leave/post/claim/release 必填'),
-        agentType: z.string().optional().describe('Agent类型(如"cursor", "claude", "kiro")。join 时使用'),
-        content: z.string().optional().describe('消息内容 (post 时必填)'),
-        msgType: z.enum(['status', 'decision', 'question']).optional().describe('消息类型 (post, 默认status)'),
-        filePath: z.string().optional().describe('文件路径 (claim/release 时必填)'),
-    }, async (args) => safeTool(async () => {
-        switch (args.action) {
-            case 'join': {
-                if (!args.agentId)
-                    return wrap('❌ join 需要 agentId');
-                const status = await client().meetingJoin(args.agentId, args.agentType || 'unknown');
-                return wrap(`✅ ${args.agentId} 已加入会议\n\n${formatStatus(status)}`);
-            }
-            case 'leave': {
-                if (!args.agentId)
-                    return wrap('❌ leave 需要 agentId');
-                const status = await client().meetingLeave(args.agentId);
-                return wrap(`✅ ${args.agentId} 已离开会议\n\n${formatStatus(status)}`);
-            }
-            case 'post': {
-                if (!args.agentId || !args.content)
-                    return wrap('❌ post 需要 agentId 和 content');
-                const status = await client().meetingPost(args.agentId, args.content, args.msgType || 'status');
-                return wrap(`✅ 消息已发送\n\n${formatStatus(status)}`);
-            }
-            case 'claim': {
-                if (!args.agentId || !args.filePath)
-                    return wrap('❌ claim 需要 agentId 和 filePath');
-                const status = await client().meetingClaim(args.agentId, args.filePath);
-                return wrap(`✅ ${args.agentId} 已认领 ${args.filePath}\n\n${formatStatus(status)}`);
-            }
-            case 'release': {
-                if (!args.agentId || !args.filePath)
-                    return wrap('❌ release 需要 agentId 和 filePath');
-                const status = await client().meetingRelease(args.agentId, args.filePath);
-                return wrap(`✅ ${args.agentId} 已释放 ${args.filePath}\n\n${formatStatus(status)}`);
-            }
-            case 'status': {
-                const status = await client().meetingStatus();
-                if (!status)
-                    return wrap('📭 该项目暂无活跃会议');
-                return wrap(formatStatus(status));
-            }
-            default:
-                return wrap(`❌ 未知 action: ${args.action}`);
-        }
-    }));
-}

package/dist/tools/pitfalls.d.ts

@@ -1,6 +0,0 @@
-/**
- * 💡 kg_pitfall — 踩坑经验管理
- * 记录项目中遇到的问题、根因和解决方案，避免重复踩坑
- */
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function registerPitfallTools(server: McpServer): void;

package/dist/tools/pitfalls.js

@@ -1,190 +0,0 @@
-/**
- * 💡 kg_pitfall — 踩坑经验管理
- * 记录项目中遇到的问题、根因和解决方案，避免重复踩坑
- */
-import { z } from 'zod';
-import { getClient } from '../storage/httpClient.js';
-import { decodeObjectStrings } from '../utils.js';
-import { safeTool, wrap } from './shared.js';
-const SEVERITY_ICONS = {
-    critical: '🔴',
-    warning: '🟡',
-    info: '🔵',
-};
-const STATUS_ICONS = {
-    open: '🔓',
-    resolved: '✅',
-    recurring: '🔄',
-};
-export function registerPitfallTools(server) {
-    const client = () => getClient();
-    server.tool('kg_pitfall', '💡 踩坑经验 — 记录和查询项目中的踩坑经验，避免重复踩坑。\n' +
-        '遇到问题时用 create 记录现象和根因，找到方案后用 resolve 标记解决。\n' +
-        '下次遇到类似问题先 search 查历史经验。\n' +
-        'actions: create|get|update|search|resolve|list|delete', {
-        action: z.enum(['create', 'get', 'update', 'search', 'resolve', 'list', 'delete'])
-            .describe('操作类型'),
-        id: z.string().optional().describe('踩坑经验 ID (get/update/resolve/delete)'),
-        title: z.string().optional().describe('标题 (create)'),
-        category: z.string().optional().describe('分类: protocol/concurrency/config/logic/ui/other (create/update/search)'),
-        symptom: z.string().optional().describe('现象描述 Markdown (create/update)'),
-        root_cause: z.string().optional().describe('根因分析 Markdown (create/update)'),
-        solution: z.string().optional().describe('解决方案 Markdown (create/update/resolve)'),
-        prevention: z.string().optional().describe('预防措施 (create/update)'),
-        severity: z.string().optional().describe('严重程度: critical/warning/info (create/update)'),
-        related_nodes: z.array(z.string()).optional().describe('关联流程图节点 ID 列表 (create/update)'),
-        source_task: z.string().optional().describe('来源任务 ID (create)'),
-        tags: z.array(z.string()).optional().describe('标签列表 (create/update)'),
-        query: z.string().optional().describe('搜索关键词 (search)'),
-        status: z.string().optional().describe('状态过滤: open/resolved/recurring (search/list)'),
-    }, async (args) => safeTool(async () => {
-        const decoded = decodeObjectStrings(args);
-        switch (decoded.action) {
-            case 'list': {
-                const pitfalls = decoded.status || decoded.category
-                    ? await client().searchPitfalls('', decoded.status, decoded.category)
-                    : await client().listPitfalls();
-                if (pitfalls.length === 0)
-                    return wrap('当前没有踩坑经验记录');
-                const lines = [
-                    `💡 踩坑经验 (${pitfalls.length})`,
-                    '',
-                    '| 状态 | 严重 | 标题 | 分类 | 标签 | 更新 |',
-                    '|:-----|:-----|:-----|:-----|:-----|:-----|',
-                ];
-                for (const p of pitfalls) {
-                    const statusIcon = STATUS_ICONS[p.status] || p.status;
-                    const sevIcon = SEVERITY_ICONS[p.severity] || p.severity;
-                    const tags = p.tags.length > 0 ? p.tags.join(',') : '-';
-                    const date = p.updated_at.substring(0, 10);
-                    lines.push(`| ${statusIcon} | ${sevIcon} | ${p.title} | ${p.category} | ${tags} | ${date} |`);
-                }
-                return wrap(lines.join('\n'));
-            }
-            case 'get': {
-                if (!decoded.id)
-                    return wrap('❌ get 需要 id');
-                const p = await client().getPitfall(decoded.id);
-                if (!p)
-                    return wrap(`未找到踩坑经验: ${decoded.id}`);
-                const sevIcon = SEVERITY_ICONS[p.severity] || p.severity;
-                const statusIcon = STATUS_ICONS[p.status] || p.status;
-                const lines = [
-                    `# ${sevIcon} ${p.title}`,
-                    '',
-                    `| 字段 | 值 |`,
-                    `|:---|:---|`,
-                    `| ID | ${p.id} |`,
-                    `| 状态 | ${statusIcon} ${p.status} |`,
-                    `| 严重程度 | ${sevIcon} ${p.severity} |`,
-                    `| 分类 | ${p.category} |`,
-                    `| 标签 | ${p.tags.join(', ') || '-'} |`,
-                    `| 关联节点 | ${p.related_nodes.join(', ') || '-'} |`,
-                ];
-                if (p.source_task)
-                    lines.push(`| 来源任务 | ${p.source_task} |`);
-                lines.push(`| 创建 | ${p.created_at.substring(0, 19)} |`);
-                lines.push(`| 更新 | ${p.updated_at.substring(0, 19)} |`);
-                if (p.resolved_at)
-                    lines.push(`| 解决 | ${p.resolved_at.substring(0, 19)} |`);
-                if (p.symptom) {
-                    lines.push('', '## 现象', '', p.symptom);
-                }
-                if (p.root_cause) {
-                    lines.push('', '## 根因', '', p.root_cause);
-                }
-                if (p.solution) {
-                    lines.push('', '## 解决方案', '', p.solution);
-                }
-                if (p.prevention) {
-                    lines.push('', '## 预防措施', '', p.prevention);
-                }
-                return wrap(lines.join('\n'));
-            }
-            case 'create': {
-                if (!decoded.title)
-                    return wrap('❌ create 需要 title');
-                const pitfall = await client().createPitfall({
-                    title: decoded.title,
-                    category: decoded.category,
-                    symptom: decoded.symptom,
-                    root_cause: decoded.root_cause,
-                    solution: decoded.solution,
-                    prevention: decoded.prevention,
-                    severity: decoded.severity,
-                    related_nodes: decoded.related_nodes,
-                    source_task: decoded.source_task,
-                    tags: decoded.tags,
-                });
-                return wrap(`✅ 踩坑经验已创建\n\n- ID: ${pitfall.id}\n- 标题: ${pitfall.title}\n- 分类: ${pitfall.category}\n- 严重程度: ${pitfall.severity}`);
-            }
-            case 'update': {
-                if (!decoded.id)
-                    return wrap('❌ update 需要 id');
-                const existing = await client().getPitfall(decoded.id);
-                if (!existing)
-                    return wrap(`❌ 未找到踩坑经验: ${decoded.id}`);
-                const updated = {
-                    ...existing,
-                    ...(decoded.title && { title: decoded.title }),
-                    ...(decoded.category && { category: decoded.category }),
-                    ...(decoded.symptom && { symptom: decoded.symptom }),
-                    ...(decoded.root_cause && { root_cause: decoded.root_cause }),
-                    ...(decoded.solution && { solution: decoded.solution }),
-                    ...(decoded.prevention && { prevention: decoded.prevention }),
-                    ...(decoded.severity && { severity: decoded.severity }),
-                    ...(decoded.related_nodes && { related_nodes: decoded.related_nodes }),
-                    ...(decoded.tags && { tags: decoded.tags }),
-                    updated_at: new Date().toISOString(),
-                };
-                await client().savePitfall(updated);
-                return wrap(`✅ 踩坑经验已更新 (${decoded.id})`);
-            }
-            case 'resolve': {
-                if (!decoded.id)
-                    return wrap('❌ resolve 需要 id');
-                const existing = await client().getPitfall(decoded.id);
-                if (!existing)
-                    return wrap(`❌ 未找到踩坑经验: ${decoded.id}`);
-                const now = new Date().toISOString();
-                const resolved = {
-                    ...existing,
-                    status: 'resolved',
-                    resolved_at: now,
-                    updated_at: now,
-                    ...(decoded.solution && { solution: decoded.solution }),
-                    ...(decoded.prevention && { prevention: decoded.prevention }),
-                };
-                await client().savePitfall(resolved);
-                return wrap(`✅ 踩坑经验已标记为解决 (${decoded.id})`);
-            }
-            case 'search': {
-                const query = decoded.query || '';
-                const results = await client().searchPitfalls(query, decoded.status, decoded.category);
-                if (results.length === 0)
-                    return wrap(`未找到匹配的踩坑经验 (搜索: "${query}")`);
-                const lines = [
-                    `💡 搜索结果: "${query}" (${results.length} 条)`,
-                    '',
-                    '| 状态 | 严重 | 标题 | 分类 | ID |',
-                    '|:-----|:-----|:-----|:-----|:---|',
-                ];
-                for (const p of results) {
-                    const statusIcon = STATUS_ICONS[p.status] || p.status;
-                    const sevIcon = SEVERITY_ICONS[p.severity] || p.severity;
-                    lines.push(`| ${statusIcon} | ${sevIcon} | ${p.title} | ${p.category} | ${p.id} |`);
-                }
-                lines.push('', '> 用 `kg_pitfall(get, id:"xxx")` 查看详情');
-                return wrap(lines.join('\n'));
-            }
-            case 'delete': {
-                if (!decoded.id)
-                    return wrap('❌ delete 需要 id');
-                const ok = await client().deletePitfall(decoded.id);
-                return wrap(ok ? `✅ 踩坑经验已删除 (${decoded.id})` : `ℹ️ 未找到踩坑经验 (${decoded.id})`);
-            }
-            default:
-                return wrap(`❌ 未知 action: ${decoded.action}`);
-        }
-    }));
-}

package/dist/tools/projects.d.ts

@@ -1,7 +0,0 @@
-/**
- * 📋 kg_projects
- * 列出所有可访问的项目(返回名称和ID)
- */
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type McpContext } from './shared.js';
-export declare function registerProjectTools(server: McpServer, ctx: McpContext): void;

package/dist/tools/projects.js

@@ -1,19 +0,0 @@
-/**
- * 📋 kg_projects
- * 列出所有可访问的项目(返回名称和ID)
- */
-import { getClient } from '../storage/httpClient.js';
-import { wrap, safeTool } from './shared.js';
-export function registerProjectTools(server, ctx) {
-    const client = () => getClient();
-    server.tool('kg_projects', '📋 列出所有可访问的项目(返回名称和ID)。跨项目操作的第一步: 获取项目ID后用于其他工具的 targetProject 参数', {}, async () => safeTool(async () => {
-        const projects = await client().crossListProjects();
-        if (projects.length === 0)
-            return wrap('暂无可访问的项目');
-        const lines = projects.map(p => {
-            const isCurrent = p.id === ctx.projectId ? ' ★当前' : '';
-            return `- ${p.name} (${p.id})${isCurrent}`;
-        });
-        return wrap(`可访问的项目 (${projects.length} 个):\n\n${lines.join('\n')}`);
-    }));
-}