@ppdocs/mcp 3.2.6 → 3.2.7

package/dist/config.d.ts

@@ -11,4 +11,4 @@ export interface PpdocsConfig {
 export declare const PPDOCS_CONFIG_FILE = ".ppdocs";
 /** 生成随机用户名 */
 export declare function generateUser(): string;
-export declare function loadConfig(): Promise<PpdocsConfig>;
+export declare function loadConfig(): Promise<PpdocsConfig | null>;

package/dist/config.js

@@ -42,14 +42,6 @@ export async function loadConfig() {
     const fileConfig = readPpdocsFile();
     if (fileConfig)
         return fileConfig;
-    // 无配置 → 提示用户去 Agent WebUI 绑定
-    console.error('ERROR: 未找到 .ppdocs 配置');
-    console.error('');
-    console.error('  请在 Agent WebUI 绑定此项目:');
-    console.error('  1. 启动 Agent:  npx @ppdocs/mcp webui');
-    console.error('  2. 打开浏览器:  http://localhost:20010');
-    console.error('  3. 添加项目 → 选择本地目录和远程知识库 → 自动生成 .ppdocs');
-    console.error('');
-    console.error('  或手动设置环境变量: PPDOCS_API_URL=http://host:port/api/projectId/key');
-    process.exit(1);
+    // 无配置 → 返回 null，由调用方决定行为 (MCP 模式下等待 kg_init)
+    return null;
 }

package/dist/index.js

@@ -35,22 +35,34 @@ if (args.length > 0) {
 // 运行 MCP 服务
 async function main() {
     const config = await loadConfig();
-    initClient(config.apiUrl);
-    const server = new McpServer({ name: `ppdocs [${config.projectId}]`, version: VERSION }, { capabilities: { tools: {} } });
-    registerTools(server, config.projectId, config.user);
+    // 有配置 → 自动初始化 (环境变量 / .ppdocs)
+    if (config) {
+        initClient(config.apiUrl);
+        console.error(`ppdocs MCP v${VERSION} | project: ${config.projectId} | user: ${config.user}`);
+    }
+    else {
+        console.error(`ppdocs MCP v${VERSION} | ⏳ 等待 kg_init 初始化项目上下文...`);
+    }
+    const projectId = config?.projectId || 'pending';
+    const user = config?.user || 'agent';
+    const server = new McpServer({ name: `ppdocs [${projectId}]`, version: VERSION }, { capabilities: { tools: {} } });
+    registerTools(server, projectId, user, (newProjectId, newApiUrl) => {
+        console.error(`[kg_init] 项目已切换: ${newProjectId}`);
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error(`ppdocs MCP v${VERSION} | project: ${config.projectId} | user: ${config.user}`);
     // [M2 修复] beacon 变量提升到外部，支持优雅关闭
     let beacon = null;
-    // 启动后台代码同步引擎 (Code Beacon)
-    try {
-        const { SyncBeacon } = await import('./sync/beacon.js');
-        beacon = new SyncBeacon(process.cwd(), config.projectId);
-        beacon.start();
-    }
-    catch (err) {
-        console.error(`[Code Beacon] Failed to start:`, err);
+    // 启动后台代码同步引擎 (Code Beacon) — 仅在有配置时启动
+    if (config) {
+        try {
+            const { SyncBeacon } = await import('./sync/beacon.js');
+            beacon = new SyncBeacon(process.cwd(), config.projectId);
+            beacon.start();
+        }
+        catch (err) {
+            console.error(`[Code Beacon] Failed to start:`, err);
+        }
     }
     // 优雅关闭：进程退出时停止 watcher，防止上传截断
     const shutdown = () => { beacon?.stop(); process.exit(0); };

package/dist/storage/httpClient.js

@@ -517,7 +517,9 @@ export function initClient(apiUrl) {
 }
 export function getClient() {
     if (!client) {
-        throw new Error('API client not initialized. Call initClient(apiUrl) first.');
+        throw new Error('❌ 项目未初始化！请先调用 kg_init 工具绑定项目上下文。\n\n' +
+            '用法: kg_init({ projectPath: "项目根目录绝对路径" })\n' +
+            '该目录下需存在 .ppdocs 配置文件。');
     }
     return client;
 }

package/dist/tools/index.d.ts

@@ -1,11 +1,12 @@
 /**
  * MCP 工具注册入口
- * 精简后: 12 个工具, 5 个子模块
+ * 精简后: 13 个工具, 6 个子模块
  *
+ * 🔗 初始化:   kg_init                       (1个)
  * 📊 导航:     kg_status, kg_tree          (2个)
  * 📚 知识:     kg_doc, kg_projects, kg_rules (3个)
  * 📝 工作流:   kg_task, kg_files, kg_discuss (3个)
  * 🔬 代码分析: code_scan, code_query, code_impact, code_context (4个)
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function registerTools(server: McpServer, projectId: string, user: string): void;
+export declare function registerTools(server: McpServer, projectId: string, user: string, onProjectChange?: (newProjectId: string, newApiUrl: string) => void): void;

package/dist/tools/index.js

@@ -1,12 +1,14 @@
 /**
  * MCP 工具注册入口
- * 精简后: 12 个工具, 5 个子模块
+ * 精简后: 13 个工具, 6 个子模块
  *
+ * 🔗 初始化:   kg_init                       (1个)
  * 📊 导航:     kg_status, kg_tree          (2个)
  * 📚 知识:     kg_doc, kg_projects, kg_rules (3个)
  * 📝 工作流:   kg_task, kg_files, kg_discuss (3个)
  * 🔬 代码分析: code_scan, code_query, code_impact, code_context (4个)
  */
+import { registerInitTool } from './init.js';
 import { registerStatusTool } from './kg_status.js';
 import { registerDocTools } from './docs.js';
 import { registerProjectTools } from './projects.js';
@@ -15,7 +17,9 @@ import { registerTaskTools } from './tasks.js';
 import { registerFileTools } from './files.js';
 import { registerDiscussionTools } from './discussion.js';
 import { registerAnalyzerTools } from './analyzer.js';
-export function registerTools(server, projectId, user) {
+export function registerTools(server, projectId, user, onProjectChange) {
+    // 🔗 初始化 (kg_init — 运行时项目切换)
+    registerInitTool(server, projectId, onProjectChange || (() => { }));
     // 📊 导航 (kg_status + kg_tree在docs中)
     registerStatusTool(server, projectId);
     // 📚 知识 (kg_doc + kg_tree + kg_projects + kg_rules)

package/dist/tools/init.d.ts

@@ -0,0 +1,13 @@
+/**
+ * kg_init 工具 — 项目上下文初始化
+ *
+ * 解决全局共用 MCP 进程时的多项目隔离问题：
+ * - 智能体调用 kg_init 传入 projectPath
+ * - MCP 从该路径读取 .ppdocs 配置
+ * - 重新初始化 HTTP Client 指向正确项目
+ * - 后续所有工具调用自动使用新的项目上下文
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** 获取当前已初始化的 projectId */
+export declare function getActiveProjectId(): string | null;
+export declare function registerInitTool(server: McpServer, defaultProjectId: string, onProjectChange: (newProjectId: string, newApiUrl: string) => void): void;

package/dist/tools/init.js

@@ -0,0 +1,75 @@
+/**
+ * kg_init 工具 — 项目上下文初始化
+ *
+ * 解决全局共用 MCP 进程时的多项目隔离问题：
+ * - 智能体调用 kg_init 传入 projectPath
+ * - MCP 从该路径读取 .ppdocs 配置
+ * - 重新初始化 HTTP Client 指向正确项目
+ * - 后续所有工具调用自动使用新的项目上下文
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { z } from 'zod';
+import { initClient } from '../storage/httpClient.js';
+import { wrap, safeTool } from './shared.js';
+// 当前会话的项目上下文 (模块级单例)
+let currentProjectId = null;
+let currentApiUrl = null;
+/** 获取当前已初始化的 projectId */
+export function getActiveProjectId() {
+    return currentProjectId;
+}
+/** 尝试从指定目录读取 .ppdocs 配置 */
+function readPpdocsFrom(dir) {
+    const configPath = path.join(dir, '.ppdocs');
+    if (!fs.existsSync(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, defaultProjectId, 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);
+        currentProjectId = config.projectId;
+        currentApiUrl = config.apiUrl;
+        // 4. 通知主进程更新工具注册的 projectId
+        onProjectChange(config.projectId, config.apiUrl);
+        return wrap(`✅ 项目上下文已初始化\n\n` +
+            `📂 项目: ${config.projectId}\n` +
+            `📁 路径: ${targetDir}\n` +
+            `🔗 API: ${config.apiUrl.replace(/\/[^/]+$/, '/***')}\n` +
+            `👤 用户: ${config.user}\n\n` +
+            `所有后续工具调用将自动连接到此项目。`);
+    }));
+}

package/package.json

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