@ppdocs/mcp 2.1.0

package/dist/cli.d.ts

@@ -0,0 +1,5 @@
+/**
+ * ppdocs MCP CLI
+ * 命令: init - 初始化项目配置
+ */
+export declare function runCli(args: string[]): boolean;

package/dist/cli.js

@@ -0,0 +1,102 @@
+/**
+ * ppdocs MCP CLI
+ * 命令: init - 初始化项目配置
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+function parseArgs(args) {
+    const opts = { port: 20001, api: 'localhost' };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '-p' || arg === '--project') {
+            opts.project = args[++i];
+        }
+        else if (arg === '-k' || arg === '--key') {
+            opts.key = args[++i];
+        }
+        else if (arg === '--port') {
+            opts.port = parseInt(args[++i], 10);
+        }
+        else if (arg === '--api') {
+            opts.api = args[++i];
+        }
+    }
+    if (!opts.project || !opts.key)
+        return null;
+    return opts;
+}
+function showHelp() {
+    console.log(`
+ppdocs MCP CLI
+
+Commands:
+  init    Initialize ppdocs config in current directory
+
+Usage:
+  npx @ppdocs/mcp init -p <projectId> -k <key> [options]
+
+Options:
+  -p, --project  Project ID (required)
+  -k, --key      API key (required)
+  --port         API port (default: 20001)
+  --api          API host (default: localhost)
+
+Example:
+  npx @ppdocs/mcp init -p myproject -k abc123xyz
+`);
+}
+export function runCli(args) {
+    const cmd = args[0];
+    if (cmd === 'init') {
+        const opts = parseArgs(args.slice(1));
+        if (!opts) {
+            console.error('Error: -p (project) and -k (key) are required\n');
+            showHelp();
+            process.exit(1);
+        }
+        initProject(opts);
+        return true;
+    }
+    if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
+        showHelp();
+        return true;
+    }
+    return false; // Not a CLI command, run as MCP server
+}
+function initProject(opts) {
+    const cwd = process.cwd();
+    // Create .ppdocs config
+    const ppdocsConfig = {
+        api: `http://${opts.api}:${opts.port}`,
+        projectId: opts.project,
+        key: opts.key,
+    };
+    const ppdocsPath = path.join(cwd, '.ppdocs');
+    fs.writeFileSync(ppdocsPath, JSON.stringify(ppdocsConfig, null, 2));
+    console.log(`✅ Created ${ppdocsPath}`);
+    // Create or update .mcp.json
+    const mcpPath = path.join(cwd, '.mcp.json');
+    let mcpConfig = {};
+    if (fs.existsSync(mcpPath)) {
+        try {
+            mcpConfig = JSON.parse(fs.readFileSync(mcpPath, 'utf-8'));
+        }
+        catch {
+            // ignore parse error
+        }
+    }
+    mcpConfig.mcpServers = {
+        ...(mcpConfig.mcpServers || {}),
+        ppdocs: {
+            command: 'npx',
+            args: ['@ppdocs/mcp'],
+        },
+    };
+    fs.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2));
+    console.log(`✅ Created ${mcpPath}`);
+    console.log(`
+🎉 Done! ppdocs MCP configured for project: ${opts.project}
+
+Restart Claude Code to use ppdocs knowledge graph.
+`);
+}

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ppdocs MCP Config
+ * 读取配置: 环境变量 > .ppdocs 文件
+ */
+export interface PpdocsConfig {
+    apiUrl: string;
+    projectId: string;
+}
+/**
+ * 加载配置 (优先级: 环境变量 > .ppdocs 文件)
+ */
+export declare function loadConfig(): PpdocsConfig;

package/dist/config.js

@@ -0,0 +1,64 @@
+/**
+ * ppdocs MCP Config
+ * 读取配置: 环境变量 > .ppdocs 文件
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * 从 .ppdocs 文件读取配置
+ */
+function readPpdocsFile() {
+    const cwd = process.cwd();
+    const configPath = path.join(cwd, '.ppdocs');
+    if (!fs.existsSync(configPath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(configPath, 'utf-8');
+        const config = JSON.parse(content);
+        if (!config.api || !config.projectId || !config.key) {
+            return null;
+        }
+        return {
+            apiUrl: `${config.api}/api/${config.projectId}/${config.key}`,
+            projectId: config.projectId,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 从环境变量读取配置
+ */
+function readEnvConfig() {
+    const apiUrl = process.env.PPDOCS_API_URL;
+    if (!apiUrl)
+        return null;
+    // URL 格式: http://localhost:20001/api/{projectId}/{password}
+    const match = apiUrl.match(/\/api\/([^/]+)\/[^/]+\/?$/);
+    const projectId = match?.[1] || 'unknown';
+    return { apiUrl, projectId };
+}
+/**
+ * 加载配置 (优先级: 环境变量 > .ppdocs 文件)
+ */
+export function loadConfig() {
+    // 1. 尝试环境变量
+    const envConfig = readEnvConfig();
+    if (envConfig)
+        return envConfig;
+    // 2. 尝试 .ppdocs 文件
+    const fileConfig = readPpdocsFile();
+    if (fileConfig)
+        return fileConfig;
+    // 3. 报错
+    console.error('ERROR: ppdocs config not found');
+    console.error('');
+    console.error('Option 1: Run init command in your project directory:');
+    console.error('  npx @ppdocs/mcp init -p <projectId> -k <key>');
+    console.error('');
+    console.error('Option 2: Set environment variable:');
+    console.error('  PPDOCS_API_URL=http://localhost:20001/api/{projectId}/{key}');
+    process.exit(1);
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * ppdocs MCP - Knowledge Graph for Claude
+ *
+ * 使用方式:
+ * 1. CLI 初始化: npx @ppdocs/mcp init -p <projectId> -k <key>
+ * 2. MCP 服务: 自动读取 .ppdocs 配置或 PPDOCS_API_URL 环境变量
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * ppdocs MCP - Knowledge Graph for Claude
+ *
+ * 使用方式:
+ * 1. CLI 初始化: npx @ppdocs/mcp init -p <projectId> -k <key>
+ * 2. MCP 服务: 自动读取 .ppdocs 配置或 PPDOCS_API_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';
+// 检查是否为 CLI 命令
+const args = process.argv.slice(2);
+if (args.length > 0 && runCli(args)) {
+    process.exit(0);
+}
+// 运行 MCP 服务
+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 transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`ppdocs MCP v2.1 | project: ${config.projectId}`);
+}
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});

package/dist/storage/fileStorage.d.ts

@@ -0,0 +1,41 @@
+import type { NodeData, Project, SearchResult, PathResult, BugfixRecord } from './types.js';
+export declare function listProjects(): Promise<Project[]>;
+export declare function ensureProject(projectId: string): Promise<Project>;
+export declare function createProject(name: string): Promise<Project>;
+export declare function getChangeMarkerTime(projectId: string): Promise<number>;
+export declare function listNodes(projectId: string): Promise<NodeData[]>;
+export declare function getNode(projectId: string, nodeId: string): Promise<NodeData | null>;
+type CreateNodeInput = Omit<NodeData, 'id' | 'x' | 'y'> & {
+    x?: number;
+    y?: number;
+};
+export declare function createNode(projectId: string, node: CreateNodeInput): Promise<NodeData>;
+export declare function updateNode(projectId: string, nodeId: string, updates: Partial<NodeData>): Promise<NodeData | null>;
+export declare function deleteNode(projectId: string, nodeId: string): Promise<boolean>;
+export declare function lockNode(projectId: string, nodeId: string, locked: boolean): Promise<NodeData | null>;
+export declare function searchNodes(projectId: string, keywords: string[], limit?: number): Promise<SearchResult[]>;
+export declare function findPath(projectId: string, startId: string, endId: string): Promise<PathResult | null>;
+export interface OrphanNode {
+    id: string;
+    title: string;
+    type: string;
+    status: string;
+}
+export interface RelationNode {
+    nodeId: string;
+    title: string;
+    description: string;
+    edgeType: string;
+    direction: 'outgoing' | 'incoming';
+}
+/** 查找孤立节点（没有任何边连接的节点） */
+export declare function findOrphans(projectId: string): Promise<OrphanNode[]>;
+/** 查询节点关系网（所有直接连接的节点） */
+export declare function getRelations(projectId: string, nodeId: string): Promise<RelationNode[]>;
+/** 添加错误修复记录到节点 */
+export declare function addBugfix(projectId: string, nodeId: string, bugfix: {
+    issue: string;
+    solution: string;
+    impact?: string;
+}): Promise<BugfixRecord | null>;
+export {};

package/dist/storage/fileStorage.js

@@ -0,0 +1,458 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { homedir } from 'os';
+import lockfile from 'proper-lockfile';
+const DATA_DIR = path.join(homedir(), '.ppdocs');
+// 文件锁配置
+const LOCK_OPTIONS = {
+    stale: 10000, // 锁超时 10秒 (防止死锁)
+    retries: {
+        retries: 5, // 最多重试 5 次
+        minTimeout: 100, // 最小等待 100ms
+        maxTimeout: 500 // 最大等待 500ms
+    }
+};
+async function ensureDir(dir) {
+    await fs.mkdir(dir, { recursive: true });
+}
+async function readJSON(filePath, defaultValue) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return defaultValue;
+    }
+}
+// 带文件锁的写入 (防止并发数据丢失)
+async function writeJSON(filePath, data) {
+    await ensureDir(path.dirname(filePath));
+    // 确保文件存在 (lockfile 需要文件存在)
+    try {
+        await fs.access(filePath);
+    }
+    catch {
+        await fs.writeFile(filePath, '{}');
+    }
+    let release = null;
+    try {
+        release = await lockfile.lock(filePath, LOCK_OPTIONS);
+        await fs.writeFile(filePath, JSON.stringify(data, null, 2));
+    }
+    finally {
+        if (release)
+            await release();
+    }
+}
+// ============ 项目操作 ============
+export async function listProjects() {
+    const filePath = path.join(DATA_DIR, 'projects.json');
+    return readJSON(filePath, []);
+}
+export async function ensureProject(projectId) {
+    const projects = await listProjects();
+    const existing = projects.find(p => p.id === projectId);
+    if (existing)
+        return existing;
+    // 创建新项目
+    const project = { id: projectId, name: projectId, updatedAt: new Date().toISOString() };
+    projects.push(project);
+    await writeJSON(path.join(DATA_DIR, 'projects.json'), projects);
+    // 创建根节点
+    const rootNode = {
+        id: 'root',
+        title: projectId,
+        type: 'intro',
+        status: 'complete',
+        x: 0, y: 0, // 根节点为坐标原点
+        locked: true,
+        isOrigin: true,
+        signature: projectId,
+        categories: ['logic'], // 与 Frontend/Rust 统一
+        description: `# ${projectId}\n\n项目根节点`,
+        dependencies: []
+    };
+    const meta = { projectId, projectName: projectId, updatedAt: project.updatedAt, edges: [] };
+    const projectDir = path.join(DATA_DIR, 'projects', projectId);
+    await writeJSON(path.join(projectDir, 'meta.json'), meta);
+    await writeJSON(path.join(projectDir, 'nodes', 'root.json'), rootNode);
+    return project;
+}
+export async function createProject(name) {
+    const id = `project-${Date.now()}`;
+    return ensureProject(id);
+}
+// 自动计算边 (基于 dependencies.name 匹配 signature)
+function computeAutoEdges(nodes) {
+    const signatureList = [];
+    nodes.forEach(n => {
+        if (n.signature) {
+            signatureList.push({ sig: n.signature.toLowerCase(), id: n.id });
+        }
+    });
+    const edges = [];
+    const edgeSet = new Set();
+    nodes.forEach(node => {
+        node.dependencies?.forEach(dep => {
+            const depName = dep.name.toLowerCase();
+            const match = signatureList.find(s => s.sig.startsWith(depName));
+            if (match && match.id !== node.id) {
+                const key = `${node.id}->${match.id}`;
+                if (!edgeSet.has(key)) {
+                    edgeSet.add(key);
+                    edges.push({ source: node.id, target: match.id, type: 'uses' });
+                }
+            }
+        });
+    });
+    return edges;
+}
+function calculateAutoPosition(nodes, dependencies) {
+    const root = nodes.find(n => n.isOrigin);
+    if (!root)
+        return { x: 200, y: 200 };
+    // 无依赖 → 随机环绕 root
+    if (!dependencies?.length) {
+        const angle = Math.random() * 2 * Math.PI;
+        const radius = 200 + Math.random() * 100;
+        return {
+            x: Math.round(root.x + Math.cos(angle) * radius),
+            y: Math.round(root.y + Math.sin(angle) * radius)
+        };
+    }
+    // 找距 root 最远的依赖节点作为 parent
+    let parent = null;
+    let maxDist = -1;
+    for (const dep of dependencies) {
+        const depName = dep.name.toLowerCase();
+        const match = nodes.find(n => n.signature?.toLowerCase().startsWith(depName));
+        if (match) {
+            const dist = Math.hypot(match.x - root.x, match.y - root.y);
+            if (dist > maxDist) {
+                maxDist = dist;
+                parent = match;
+            }
+        }
+    }
+    // 无匹配依赖 → 随机环绕 root
+    if (!parent) {
+        const angle = Math.random() * 2 * Math.PI;
+        const radius = 200 + Math.random() * 100;
+        return {
+            x: Math.round(root.x + Math.cos(angle) * radius),
+            y: Math.round(root.y + Math.sin(angle) * radius)
+        };
+    }
+    // 计算方向向量 (root → parent)
+    let dx = parent.x - root.x;
+    let dy = parent.y - root.y;
+    const len = Math.hypot(dx, dy);
+    if (len < 10) {
+        const angle = Math.random() * 2 * Math.PI;
+        dx = Math.cos(angle);
+        dy = Math.sin(angle);
+    }
+    else {
+        dx /= len;
+        dy /= len;
+    }
+    // 新位置 = parent + 方向 * 150 (加小随机偏移防重叠)
+    const offset = 150 + (Math.random() - 0.5) * 30;
+    const angleOffset = (Math.random() - 0.5) * 0.3;
+    const cos = Math.cos(angleOffset), sin = Math.sin(angleOffset);
+    return {
+        x: Math.round(parent.x + (dx * cos - dy * sin) * offset),
+        y: Math.round(parent.y + (dx * sin + dy * cos) * offset)
+    };
+}
+// ============ 节点操作 ============
+function getNodePath(projectId, nodeId) {
+    return path.join(DATA_DIR, 'projects', projectId, 'nodes', `${nodeId}.json`);
+}
+function getMetaPath(projectId) {
+    return path.join(DATA_DIR, 'projects', projectId, 'meta.json');
+}
+function getChangeMarkerPath(projectId) {
+    return path.join(DATA_DIR, 'projects', projectId, '.changed');
+}
+// 更新变更标记 (前端用于检测 MCP 变更)
+async function touchChangeMarker(projectId) {
+    const markerPath = getChangeMarkerPath(projectId);
+    await ensureDir(path.dirname(markerPath));
+    await fs.writeFile(markerPath, Date.now().toString());
+}
+// 获取变更标记时间戳 (前端轮询用)
+export async function getChangeMarkerTime(projectId) {
+    const markerPath = getChangeMarkerPath(projectId);
+    try {
+        const content = await fs.readFile(markerPath, 'utf-8');
+        return parseInt(content, 10) || 0;
+    }
+    catch {
+        return 0;
+    }
+}
+// 更新节点的最后访问时间 (触发前端发光效果)
+async function touchNode(projectId, nodeId) {
+    const nodePath = getNodePath(projectId, nodeId);
+    try {
+        const node = await readJSON(nodePath, null);
+        if (node) {
+            node.lastAccessedAt = new Date().toISOString();
+            await writeJSON(nodePath, node);
+        }
+    }
+    catch { /* ignore */ }
+}
+// 批量更新访问时间 (同时更新变更标记)
+async function touchNodes(projectId, nodeIds) {
+    await Promise.all(nodeIds.map(id => touchNode(projectId, id)));
+    await touchChangeMarker(projectId);
+}
+export async function listNodes(projectId) {
+    const nodesDir = path.join(DATA_DIR, 'projects', projectId, 'nodes');
+    try {
+        const files = await fs.readdir(nodesDir);
+        const nodes = [];
+        for (const file of files) {
+            if (file.endsWith('.json')) {
+                const node = await readJSON(path.join(nodesDir, file), null);
+                if (node)
+                    nodes.push(node);
+            }
+        }
+        return nodes;
+    }
+    catch {
+        return [];
+    }
+}
+export async function getNode(projectId, nodeId) {
+    return readJSON(getNodePath(projectId, nodeId), null);
+}
+export async function createNode(projectId, node) {
+    const id = `node-${Date.now()}`;
+    const now = new Date().toISOString();
+    // 自动布局: 未指定位置时计算
+    let x = node.x;
+    let y = node.y;
+    if (x === undefined || y === undefined) {
+        const nodes = await listNodes(projectId);
+        const pos = calculateAutoPosition(nodes, node.dependencies || []);
+        x = pos.x;
+        y = pos.y;
+    }
+    const fullNode = {
+        ...node,
+        id,
+        x,
+        y,
+        updatedAt: now,
+        versions: [{ version: 1, date: now, changes: '初始创建' }],
+        bugfixes: []
+    };
+    await writeJSON(getNodePath(projectId, id), fullNode);
+    await touchChangeMarker(projectId);
+    return fullNode;
+}
+export async function updateNode(projectId, nodeId, updates) {
+    const node = await readJSON(getNodePath(projectId, nodeId), null);
+    if (!node)
+        return null;
+    if (node.locked && !('locked' in updates))
+        return null; // 锁定节点只能改locked
+    const now = new Date().toISOString();
+    // 自动检测变更字段
+    const changes = [];
+    if (updates.title !== undefined && updates.title !== node.title)
+        changes.push('标题');
+    if (updates.description !== undefined && updates.description !== node.description)
+        changes.push('描述');
+    if (updates.status !== undefined && updates.status !== node.status)
+        changes.push('状态');
+    if (updates.categories !== undefined && JSON.stringify(updates.categories) !== JSON.stringify(node.categories))
+        changes.push('分类');
+    if (updates.dependencies !== undefined && JSON.stringify(updates.dependencies) !== JSON.stringify(node.dependencies))
+        changes.push('依赖');
+    if (updates.signature !== undefined && updates.signature !== node.signature)
+        changes.push('签名');
+    // 合并更新
+    const updated = { ...node, ...updates, updatedAt: now };
+    // 有变更时自动追加版本记录
+    if (changes.length > 0) {
+        const currentVersion = node.versions?.[0]?.version || 0;
+        const newVersion = {
+            version: currentVersion + 1,
+            date: now,
+            changes: `更新: ${changes.join(', ')}`
+        };
+        updated.versions = [newVersion, ...(node.versions || [])].slice(0, 10);
+    }
+    await writeJSON(getNodePath(projectId, nodeId), updated);
+    await touchChangeMarker(projectId);
+    return updated;
+}
+export async function deleteNode(projectId, nodeId) {
+    const node = await getNode(projectId, nodeId);
+    if (!node || node.isOrigin || node.locked)
+        return false;
+    try {
+        await fs.unlink(getNodePath(projectId, nodeId));
+        await touchChangeMarker(projectId);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function lockNode(projectId, nodeId, locked) {
+    const node = await getNode(projectId, nodeId);
+    if (!node || node.isOrigin)
+        return null;
+    const updated = { ...node, locked };
+    await writeJSON(getNodePath(projectId, nodeId), updated);
+    await touchChangeMarker(projectId);
+    return updated;
+}
+// ============ 搜索 ============
+export async function searchNodes(projectId, keywords, limit = 20) {
+    const nodes = await listNodes(projectId);
+    const results = [];
+    for (const node of nodes) {
+        let score = 0;
+        const matches = [];
+        const lowerKeywords = keywords.map(k => k.toLowerCase());
+        for (const keyword of lowerKeywords) {
+            if (node.title?.toLowerCase().includes(keyword)) {
+                score += 3;
+                matches.push(`title: ${node.title}`);
+            }
+            if (node.signature?.toLowerCase().includes(keyword)) {
+                score += 2;
+                matches.push(`signature: ${node.signature}`);
+            }
+            if (node.categories?.some(t => t.toLowerCase().includes(keyword))) {
+                score += 2.5;
+                matches.push(`categories: ${node.categories.join(', ')}`);
+            }
+            if (node.description?.toLowerCase().includes(keyword)) {
+                score += 1;
+                matches.push('description');
+            }
+        }
+        if (score > 0)
+            results.push({ node, score, matches: [...new Set(matches)] });
+    }
+    const finalResults = results.sort((a, b) => b.score - a.score).slice(0, limit);
+    // 触发发光效果
+    await touchNodes(projectId, finalResults.map(r => r.node.id));
+    return finalResults;
+}
+// ============ 路径查找 (BFS) ============
+export async function findPath(projectId, startId, endId) {
+    const nodes = await listNodes(projectId);
+    const edges = computeAutoEdges(nodes);
+    const nodeMap = new Map(nodes.map(n => [n.id, n]));
+    if (!nodeMap.has(startId) || !nodeMap.has(endId))
+        return null;
+    // 建立邻接表 (双向)
+    const adj = new Map();
+    for (const edge of edges) {
+        if (!adj.has(edge.source))
+            adj.set(edge.source, []);
+        if (!adj.has(edge.target))
+            adj.set(edge.target, []);
+        adj.get(edge.source).push({ nodeId: edge.target, edge });
+        adj.get(edge.target).push({ nodeId: edge.source, edge });
+    }
+    // BFS
+    const visited = new Set([startId]);
+    const queue = [{ nodeId: startId, path: [startId], edges: [] }];
+    while (queue.length > 0) {
+        const { nodeId, path, edges: pathEdges } = queue.shift();
+        if (nodeId === endId) {
+            // 触发发光效果
+            await touchNodes(projectId, path);
+            return { path: path.map(id => nodeMap.get(id)), edges: pathEdges };
+        }
+        for (const { nodeId: nextId, edge } of adj.get(nodeId) || []) {
+            if (!visited.has(nextId)) {
+                visited.add(nextId);
+                queue.push({ nodeId: nextId, path: [...path, nextId], edges: [...pathEdges, edge] });
+            }
+        }
+    }
+    return null;
+}
+/** 查找孤立节点（没有任何边连接的节点） */
+export async function findOrphans(projectId) {
+    const nodes = await listNodes(projectId);
+    const edges = computeAutoEdges(nodes);
+    // 收集所有有边连接的节点ID
+    const connected = new Set();
+    for (const edge of edges) {
+        connected.add(edge.source);
+        connected.add(edge.target);
+    }
+    // 过滤出孤立节点
+    return nodes
+        .filter(n => !connected.has(n.id))
+        .map(n => ({ id: n.id, title: n.title, type: n.type, status: n.status }));
+}
+/** 查询节点关系网（所有直接连接的节点） */
+export async function getRelations(projectId, nodeId) {
+    const nodes = await listNodes(projectId);
+    const edges = computeAutoEdges(nodes);
+    const nodeMap = new Map(nodes.map(n => [n.id, n]));
+    const relations = [];
+    for (const edge of edges) {
+        let relatedId = null;
+        let direction = null;
+        if (edge.source === nodeId) {
+            relatedId = edge.target;
+            direction = 'outgoing';
+        }
+        else if (edge.target === nodeId) {
+            relatedId = edge.source;
+            direction = 'incoming';
+        }
+        if (relatedId && direction) {
+            const node = nodeMap.get(relatedId);
+            if (node) {
+                relations.push({
+                    nodeId: relatedId,
+                    title: node.title,
+                    description: node.description.slice(0, 100),
+                    edgeType: edge.type,
+                    direction
+                });
+            }
+        }
+    }
+    // 触发发光效果 (当前节点 + 所有关联节点)
+    const touchList = [nodeId, ...relations.map(r => r.nodeId)];
+    await touchNodes(projectId, touchList);
+    return relations;
+}
+// ============ 错误修复记录 ============
+/** 添加错误修复记录到节点 */
+export async function addBugfix(projectId, nodeId, bugfix) {
+    const node = await getNode(projectId, nodeId);
+    if (!node || node.locked)
+        return null;
+    const newBugfix = {
+        id: `bug-${Date.now()}`,
+        date: new Date().toISOString(),
+        issue: bugfix.issue,
+        solution: bugfix.solution,
+        impact: bugfix.impact
+    };
+    const updated = {
+        ...node,
+        bugfixes: [newBugfix, ...(node.bugfixes || [])].slice(0, 20), // 保留最近 20 条
+        updatedAt: new Date().toISOString()
+    };
+    await writeJSON(getNodePath(projectId, nodeId), updated);
+    await touchChangeMarker(projectId);
+    return newBugfix;
+}

package/dist/storage/httpClient.d.ts

@@ -0,0 +1,65 @@
+/**
+ * ppdocs MCP HTTP API Client
+ * 通过 HTTP API 调用主程序，替代直接文件访问
+ *
+ * API URL 格式: http://localhost:20001/api/:projectId/:password/...
+ */
+import type { NodeData, SearchResult, PathResult, BugfixRecord } from './types.js';
+export declare class PpdocsApiClient {
+    private baseUrl;
+    constructor(apiUrl: string);
+    private request;
+    listNodes(): Promise<NodeData[]>;
+    getNode(nodeId: string): Promise<NodeData | null>;
+    createNode(node: Partial<NodeData>): Promise<NodeData>;
+    updateNode(nodeId: string, updates: Partial<NodeData>): Promise<NodeData | null>;
+    deleteNode(nodeId: string): Promise<boolean>;
+    lockNode(nodeId: string, locked: boolean): Promise<NodeData | null>;
+    searchNodes(keywords: string[], limit?: number): Promise<SearchResult[]>;
+    findPath(startId: string, endId: string): Promise<PathResult | null>;
+    findOrphans(): Promise<Array<{
+        id: string;
+        title: string;
+        type: string;
+        status: string;
+    }>>;
+    getRelations(nodeId: string): Promise<Array<{
+        nodeId: string;
+        title: string;
+        description: string;
+        edgeType: string;
+        direction: 'outgoing' | 'incoming';
+    }>>;
+    addBugfix(nodeId: string, bugfix: {
+        issue: string;
+        solution: string;
+        impact?: string;
+    }): Promise<BugfixRecord | null>;
+}
+export declare function initClient(apiUrl: string): void;
+export declare function listNodes(_projectId: string): Promise<NodeData[]>;
+export declare function getNode(_projectId: string, nodeId: string): Promise<NodeData | null>;
+export declare function createNode(_projectId: string, node: Partial<NodeData>): Promise<NodeData>;
+export declare function updateNode(_projectId: string, nodeId: string, updates: Partial<NodeData>): Promise<NodeData | null>;
+export declare function deleteNode(_projectId: string, nodeId: string): Promise<boolean>;
+export declare function lockNode(_projectId: string, nodeId: string, locked: boolean): Promise<NodeData | null>;
+export declare function searchNodes(_projectId: string, keywords: string[], limit?: number): Promise<SearchResult[]>;
+export declare function findPath(_projectId: string, startId: string, endId: string): Promise<PathResult | null>;
+export declare function findOrphans(_projectId: string): Promise<Array<{
+    id: string;
+    title: string;
+    type: string;
+    status: string;
+}>>;
+export declare function getRelations(_projectId: string, nodeId: string): Promise<Array<{
+    nodeId: string;
+    title: string;
+    description: string;
+    edgeType: string;
+    direction: 'outgoing' | 'incoming';
+}>>;
+export declare function addBugfix(_projectId: string, nodeId: string, bugfix: {
+    issue: string;
+    solution: string;
+    impact?: string;
+}): Promise<BugfixRecord | null>;

package/dist/storage/httpClient.js

@@ -0,0 +1,207 @@
+/**
+ * ppdocs MCP HTTP API Client
+ * 通过 HTTP API 调用主程序，替代直接文件访问
+ *
+ * API URL 格式: http://localhost:20001/api/:projectId/:password/...
+ */
+// API 客户端类
+export class PpdocsApiClient {
+    baseUrl; // http://localhost:20001/api/projectId/password
+    constructor(apiUrl) {
+        // 移除末尾斜杠
+        this.baseUrl = apiUrl.replace(/\/$/, '');
+    }
+    // ============ HTTP 请求工具 ============
+    async request(path, options = {}) {
+        const url = `${this.baseUrl}${path}`;
+        const response = await fetch(url, {
+            ...options,
+            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}`);
+        }
+        const json = await response.json();
+        if (!json.success) {
+            throw new Error(json.error || 'Unknown error');
+        }
+        return json.data;
+    }
+    // ============ 节点操作 ============
+    async listNodes() {
+        return this.request('/nodes');
+    }
+    async getNode(nodeId) {
+        try {
+            return await this.request(`/nodes/${nodeId}`);
+        }
+        catch {
+            return null;
+        }
+    }
+    async createNode(node) {
+        // 自动布局: 未指定位置时服务端会计算
+        const payload = {
+            id: '', // 服务端自动生成
+            title: node.title || '',
+            type: node.type || 'logic',
+            status: node.status || 'incomplete',
+            x: node.x ?? 0,
+            y: node.y ?? 0,
+            locked: false,
+            signature: node.signature || node.title || '',
+            categories: node.categories || [],
+            description: node.description || '',
+            dependencies: node.dependencies || [],
+            relatedFiles: [],
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            lastAccessedAt: new Date().toISOString(),
+            versions: [],
+            bugfixes: []
+        };
+        return this.request('/nodes', {
+            method: 'POST',
+            body: JSON.stringify(payload)
+        });
+    }
+    async updateNode(nodeId, updates) {
+        // 先获取现有节点，合并更新
+        const existing = await this.getNode(nodeId);
+        if (!existing)
+            return null;
+        const payload = {
+            ...existing,
+            ...updates,
+            updatedAt: new Date().toISOString()
+        };
+        try {
+            return await this.request(`/nodes/${nodeId}`, {
+                method: 'PUT',
+                body: JSON.stringify(payload)
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+    async deleteNode(nodeId) {
+        try {
+            await this.request(`/nodes/${nodeId}`, { method: 'DELETE' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async lockNode(nodeId, locked) {
+        try {
+            return await this.request(`/nodes/${nodeId}/lock`, {
+                method: 'PUT',
+                body: JSON.stringify({ locked })
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+    // ============ 搜索与路径 ============
+    async searchNodes(keywords, limit = 20) {
+        return this.request('/search', {
+            method: 'POST',
+            body: JSON.stringify({ keywords, limit })
+        });
+    }
+    async findPath(startId, endId) {
+        try {
+            return await this.request('/path', {
+                method: 'POST',
+                body: JSON.stringify({ start_id: startId, end_id: endId })
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+    async findOrphans() {
+        return this.request('/orphans');
+    }
+    async getRelations(nodeId) {
+        const result = await this.request(`/relations/${nodeId}`);
+        // 转换字段名 (API 返回 type，前端期望 edgeType)
+        return result.map(r => ({
+            nodeId: r.nodeId,
+            title: r.title,
+            description: r.description,
+            edgeType: r.type,
+            direction: r.direction
+        }));
+    }
+    // ============ Bugfix ============
+    async addBugfix(nodeId, bugfix) {
+        // 添加 bugfix 需要先获取节点，追加 bugfix，然后更新
+        const node = await this.getNode(nodeId);
+        if (!node || node.locked)
+            return null;
+        const newBugfix = {
+            id: `bug-${Date.now()}`,
+            date: new Date().toISOString(),
+            issue: bugfix.issue,
+            solution: bugfix.solution,
+            impact: bugfix.impact
+        };
+        const updated = await this.updateNode(nodeId, {
+            bugfixes: [newBugfix, ...(node.bugfixes || [])].slice(0, 20)
+        });
+        return updated ? newBugfix : null;
+    }
+}
+// ============ 模块级 API (兼容现有 tools/index.ts) ============
+let client = null;
+export function initClient(apiUrl) {
+    client = new PpdocsApiClient(apiUrl);
+}
+function getClient() {
+    if (!client) {
+        throw new Error('API client not initialized. Call initClient(apiUrl) first.');
+    }
+    return client;
+}
+// 导出与 fileStorage 相同的函数签名
+export async function listNodes(_projectId) {
+    return getClient().listNodes();
+}
+export async function getNode(_projectId, nodeId) {
+    return getClient().getNode(nodeId);
+}
+export async function createNode(_projectId, node) {
+    return getClient().createNode(node);
+}
+export async function updateNode(_projectId, nodeId, updates) {
+    return getClient().updateNode(nodeId, updates);
+}
+export async function deleteNode(_projectId, nodeId) {
+    return getClient().deleteNode(nodeId);
+}
+export async function lockNode(_projectId, nodeId, locked) {
+    return getClient().lockNode(nodeId, locked);
+}
+export async function searchNodes(_projectId, keywords, limit) {
+    return getClient().searchNodes(keywords, limit);
+}
+export async function findPath(_projectId, startId, endId) {
+    return getClient().findPath(startId, endId);
+}
+export async function findOrphans(_projectId) {
+    return getClient().findOrphans();
+}
+export async function getRelations(_projectId, nodeId) {
+    return getClient().getRelations(nodeId);
+}
+export async function addBugfix(_projectId, nodeId, bugfix) {
+    return getClient().addBugfix(nodeId, bugfix);
+}

package/dist/storage/types.d.ts

@@ -0,0 +1,73 @@
+export type EdgeType = 'contains' | 'uses' | 'extends' | 'implements';
+export interface Edge {
+    source: string;
+    target: string;
+    type: EdgeType;
+    auto?: boolean;
+}
+export type NodeType = 'logic' | 'data' | 'intro';
+export type NodeStatus = 'incomplete' | 'complete' | 'fixing' | 'refactoring' | 'deprecated' | 'locked';
+export interface DataRef {
+    type: string;
+    description: string;
+    formatPath?: string;
+}
+export interface Dependency {
+    name: string;
+    description: string;
+    nodePath?: string;
+}
+export interface VersionRecord {
+    version: number;
+    date: string;
+    changes: string;
+}
+export interface BugfixRecord {
+    id: string;
+    date: string;
+    issue: string;
+    solution: string;
+    impact?: string;
+}
+export interface NodeData {
+    id: string;
+    title: string;
+    type: NodeType;
+    status: NodeStatus;
+    x: number;
+    y: number;
+    locked: boolean;
+    isOrigin?: boolean;
+    signature: string;
+    categories: string[];
+    description: string;
+    dataInput?: DataRef;
+    dataOutput?: DataRef;
+    dependencies: Dependency[];
+    relatedFiles?: string[];
+    createdAt?: string;
+    updatedAt?: string;
+    lastAccessedAt?: string;
+    versions?: VersionRecord[];
+    bugfixes?: BugfixRecord[];
+}
+export interface ProjectMeta {
+    projectId: string;
+    projectName: string;
+    updatedAt: string;
+    edges: Edge[];
+}
+export interface Project {
+    id: string;
+    name: string;
+    updatedAt: string;
+}
+export interface SearchResult {
+    node: NodeData;
+    score: number;
+    matches: string[];
+}
+export interface PathResult {
+    path: NodeData[];
+    edges: Edge[];
+}

package/dist/storage/types.js

@@ -0,0 +1,2 @@
+// 知识图谱类型定义 - 与 UI 和 Tauri 后端保持同步
+export {};

package/dist/tools/index.d.ts

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

package/dist/tools/index.js

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+import * as storage from '../storage/httpClient.js';
+export function registerTools(server, projectId) {
+    // 1. 创建节点
+    server.tool('kg_create_node', '创建新节点', {
+        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('标签列表'),
+        dependencies: z.array(z.object({
+            name: z.string().describe('依赖名称(匹配其他节点signature)'),
+            description: z.string().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,
+            locked: false,
+            signature: args.signature || args.title,
+            categories: args.tags || [], // API 参数名保持 tags，内部存储为 categories
+            dependencies: args.dependencies || []
+        });
+        return { content: [{ type: 'text', text: JSON.stringify(node, null, 2) }] };
+    });
+    // 2. 删除节点
+    server.tool('kg_delete_node', '删除节点(锁定节点和根节点不可删除)', { nodeId: z.string().describe('节点ID') }, async (args) => {
+        const success = await storage.deleteNode(projectId, args.nodeId);
+        return { content: [{ type: 'text', text: success ? '删除成功' : '删除失败(节点不存在/已锁定/是根节点)' }] };
+    });
+    // 3. 更新节点
+    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(),
+        dependencies: z.array(z.object({
+            name: z.string().describe('依赖名称'),
+            description: z.string().describe('依赖说明')
+        })).optional().describe('依赖列表')
+    }, async (args) => {
+        const { nodeId, tags, ...rest } = args;
+        // API 参数 tags 转换为内部字段 categories
+        const updates = tags !== undefined ? { ...rest, categories: tags } : rest;
+        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=解锁')
+    }, async (args) => {
+        const node = await storage.lockNode(projectId, args.nodeId, args.locked);
+        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)')
+    }, async (args) => {
+        const results = await storage.searchNodes(projectId, args.keywords, args.limit);
+        const output = results.map(r => ({
+            id: r.node.id, title: r.node.title, type: r.node.type,
+            status: r.node.status, score: r.score.toFixed(1), matches: r.matches
+        }));
+        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')
+    }, async (args) => {
+        const result = await storage.findPath(projectId, args.startId, args.endId);
+        if (!result)
+            return { content: [{ type: 'text', text: '未找到路径' }] };
+        const output = {
+            pathLength: result.path.length,
+            nodes: result.path.map(n => ({ id: n.id, title: n.title, type: n.type })),
+            edges: result.edges.map(e => ({ from: e.source, to: e.target, type: e.type }))
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
+    });
+    // 7. 列出所有节点
+    server.tool('kg_list_nodes', '列出当前项目所有节点(返回id,title,type,status,locked)', {}, 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 () => {
+        const orphans = await storage.findOrphans(projectId);
+        if (orphans.length === 0) {
+            return { content: [{ type: 'text', text: '没有孤立节点' }] };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(orphans, null, 2) }] };
+    });
+    // 9. 查询节点关系网
+    server.tool('kg_get_relations', '查询节点关系网（所有直接连接的节点及其介绍）', {
+        nodeId: z.string().describe('节点ID')
+    }, async (args) => {
+        const relations = await storage.getRelations(projectId, args.nodeId);
+        if (relations.length === 0) {
+            return { content: [{ type: 'text', text: '该节点没有任何连线' }] };
+        }
+        // 分组显示
+        const outgoing = relations.filter(r => r.direction === 'outgoing');
+        const incoming = relations.filter(r => r.direction === 'incoming');
+        const output = {
+            outgoing: outgoing.map(r => ({ id: r.nodeId, title: r.title, desc: r.description, edge: r.edgeType })),
+            incoming: incoming.map(r => ({ id: r.nodeId, title: r.title, desc: r.description, edge: r.edgeType }))
+        };
+        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('影响范围')
+    }, async (args) => {
+        const bugfix = await storage.addBugfix(projectId, args.nodeId, {
+            issue: args.issue,
+            solution: args.solution,
+            impact: args.impact
+        });
+        return { content: [{ type: 'text', text: bugfix ? JSON.stringify(bugfix, null, 2) : '添加失败(节点不存在或已锁定)' }] };
+    });
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@ppdocs/mcp",
+  "version": "2.1.0",
+  "description": "ppdocs MCP Server - Knowledge Graph for Claude",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ppdocs-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "keywords": ["mcp", "claude", "knowledge-graph", "ppdocs"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ppdocs/ppdocs"
+  },
+  "license": "MIT",
+  "files": ["dist", "README.md"],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "proper-lockfile": "^4.1.2",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "typescript": "^5.7.0"
+  }
+}