@ppdocs/mcp 3.2.6 → 3.2.8

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,15 @@
 /**
  * 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 { createContext } from './shared.js';
+import { registerInitTool } from './init.js';
 import { registerStatusTool } from './kg_status.js';
 import { registerDocTools } from './docs.js';
 import { registerProjectTools } from './projects.js';
@@ -15,17 +18,21 @@ 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) {
+    // 创建共享可变上下文 — 所有工具捕获此对象引用
+    const ctx = createContext(projectId, user);
+    // 🔗 初始化 (kg_init — 运行时项目切换，更新 ctx)
+    registerInitTool(server, ctx, onProjectChange || (() => { }));
     // 📊 导航 (kg_status + kg_tree在docs中)
-    registerStatusTool(server, projectId);
+    registerStatusTool(server, ctx);
     // 📚 知识 (kg_doc + kg_tree + kg_projects + kg_rules)
-    registerDocTools(server, projectId);
-    registerProjectTools(server, projectId);
-    registerRuleTools(server, projectId);
+    registerDocTools(server, ctx.projectId);
+    registerProjectTools(server, ctx.projectId);
+    registerRuleTools(server, ctx.projectId);
     // 📝 工作流 (kg_task + kg_files + kg_discuss)
-    registerTaskTools(server, projectId, user);
+    registerTaskTools(server, ctx.projectId, ctx.user);
     registerFileTools(server);
-    registerDiscussionTools(server, projectId);
+    registerDiscussionTools(server, ctx.projectId);
     // 🔬 代码分析 (不变)
-    registerAnalyzerTools(server, projectId);
+    registerAnalyzerTools(server, ctx.projectId);
 }

package/dist/tools/init.d.ts

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

package/dist/tools/init.js

@@ -0,0 +1,72 @@
+/**
+ * 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 { wrap, safeTool } from './shared.js';
+// 当前会话的 API URL (用于幂等检查)
+let currentApiUrl = null;
+/** 尝试从指定目录读取 .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, 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;
+        // 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/kg_status.d.ts

@@ -2,4 +2,5 @@
  * 📊 kg_status — 项目速览仪表盘 (新增)
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function registerStatusTool(server: McpServer, projectId: string): void;
+import { type McpContext } from './shared.js';
+export declare function registerStatusTool(server: McpServer, ctx: McpContext): void;

package/dist/tools/kg_status.js

@@ -3,7 +3,7 @@
  */
 import { getClient } from '../storage/httpClient.js';
 import { wrap, safeTool } from './shared.js';
-export function registerStatusTool(server, projectId) {
+export function registerStatusTool(server, ctx) {
     const client = () => getClient();
     server.tool('kg_status', '📊 项目速览仪表盘 — 一键了解项目健康。返回: 文档总数、目录数、活跃任务数、最近变更。每次对话开始建议首先调用', {}, async () => safeTool(async () => {
         const [docs, activeTasks] = await Promise.all([
@@ -20,7 +20,7 @@ export function registerStatusTool(server, projectId) {
             statusMap.set(s, (statusMap.get(s) || 0) + 1);
         }
         const lines = [
-            `📊 项目速览 [${projectId}]`,
+            `📊 项目速览 [${ctx.projectId}]`,
             ``,
             `📄 文档: ${docCount} 个 | 📁 目录: ${dirCount} 个`,
             `📝 活跃任务: ${activeTasks.length} 个`,

package/dist/tools/shared.d.ts

@@ -3,6 +3,13 @@
  * 合并原 helpers.ts + 新增 safeTool / withCross 模式
  */
 import type { DocData } from '../storage/types.js';
+/** 运行时可变上下文 — 所有工具通过引用获取最新值 */
+export interface McpContext {
+    projectId: string;
+    user: string;
+}
+/** 创建可变上下文对象 (工具闭包捕获此对象的引用，kg_init 更新其属性) */
+export declare function createContext(projectId: string, user: string): McpContext;
 export declare function wrap(text: string): {
     content: {
         type: "text";

package/dist/tools/shared.js

@@ -2,6 +2,10 @@
  * MCP 工具共享模块
  * 合并原 helpers.ts + 新增 safeTool / withCross 模式
  */
+/** 创建可变上下文对象 (工具闭包捕获此对象的引用，kg_init 更新其属性) */
+export function createContext(projectId, user) {
+    return { projectId, user };
+}
 // ==================== MCP 返回包装 ====================
 export function wrap(text) {
     return { content: [{ type: 'text', text }] };

package/package.json

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