@ppdocs/mcp 3.2.18 → 3.2.20

package/dist/cli.js

@@ -89,10 +89,12 @@ function showHelp() {
 ppdocs MCP CLI
 
 Commands:
-  init    Initialize ppdocs config + install workflow templates
+  init    Full setup: .ppdocs + templates + MCP registration
+  bind    Lightweight: only create .ppdocs (for adding projects to existing MCP)
 
 Usage:
   npx @ppdocs/mcp init -p <projectId> -k <key> [options]
+  npx @ppdocs/mcp bind -p <projectId> -k <key> [options]
 
 Options:
   -p, --project  Project ID (required)
@@ -105,51 +107,55 @@ Options:
   --sync <id>    Sync knowledge base docs from a source project to ./docs/ppdocs/
 
 Example:
-  npx @ppdocs/mcp init -p myproject -k abc123xyz
-  npx @ppdocs/mcp init -p myproject -k abc123xyz --codex
-  npx @ppdocs/mcp init -p myproject -k abc123xyz --from _templates
-  npx @ppdocs/mcp init -p myproject -k abc123xyz --sync shared-rules
+  npx @ppdocs/mcp init -p myproject -k abc123xyz --api 192.168.1.100
+  npx @ppdocs/mcp bind -p myproject -k abc123xyz --api 192.168.1.100
 `);
 }
 export async function runCli(args) {
     const cmd = args[0];
-    if (cmd === 'init') {
+    if (cmd === 'init' || cmd === 'bind') {
         const opts = parseArgs(args.slice(1));
         if (!opts) {
             console.error('Error: -p (project) and -k (key) are required\n');
             showHelp();
             process.exit(1);
         }
-        await initProject(opts);
+        if (cmd === 'bind') {
+            bindProject(opts);
+        }
+        else {
+            await initProject(opts);
+        }
         return true;
     }
     if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
         showHelp();
         return true;
     }
-    return false; // Not a CLI command, run as MCP server
+    return false;
 }
-async function initProject(opts) {
-    const cwd = process.cwd();
+/** 轻量绑定: 仅创建 .ppdocs, 不注册 MCP 不安装模板 */
+function bindProject(opts) {
+    writePpdocsConfig(process.cwd(), opts);
+    console.log(`\n🔗 Project bound: ${opts.project}\n   AI will auto-connect via kg_init when opening this directory.\n`);
+}
+/** 写入 .ppdocs 配置文件 (init + bind 复用) */
+function writePpdocsConfig(cwd, opts) {
     const apiUrl = `http://${opts.api}:${opts.port}/api/${opts.project}/${opts.key}`;
-    // Create .ppdocs config
-    const ppdocsConfig = {
-        api: `http://${opts.api}:${opts.port}`,
-        projectId: opts.project,
-        key: opts.key,
-        user: opts.user,
-    };
     const ppdocsPath = path.join(cwd, '.ppdocs');
-    // 检查是否存在同名目录，如果是则删除
-    if (fs.existsSync(ppdocsPath)) {
-        const stat = fs.statSync(ppdocsPath);
-        if (stat.isDirectory()) {
-            fs.rmSync(ppdocsPath, { recursive: true });
-            console.log(`⚠️  Removed existing .ppdocs directory`);
-        }
+    if (fs.existsSync(ppdocsPath) && fs.statSync(ppdocsPath).isDirectory()) {
+        fs.rmSync(ppdocsPath, { recursive: true });
+        console.log(`⚠️  Removed existing .ppdocs directory`);
     }
-    fs.writeFileSync(ppdocsPath, JSON.stringify(ppdocsConfig, null, 2));
+    fs.writeFileSync(ppdocsPath, JSON.stringify({
+        api: `http://${opts.api}:${opts.port}`, projectId: opts.project, key: opts.key, user: opts.user,
+    }, null, 2));
     console.log(`✅ Created ${ppdocsPath}`);
+    return apiUrl;
+}
+async function initProject(opts) {
+    const cwd = process.cwd();
+    const apiUrl = writePpdocsConfig(cwd, opts);
     // Install workflow templates based on IDE detection
     const detectedIdes = detectIDEs(cwd);
     let hasIdeDir = false;
@@ -179,7 +185,7 @@ async function initProject(opts) {
         }
     }
     // 自动检测并注册 MCP (如果已写入 Antigravity 配置，跳过 gemini CLI 注册避免冲突)
-    const registered = autoRegisterMcp(apiUrl, opts.user, detectedIdes.includes('antigravity'));
+    const registered = autoRegisterMcp(detectedIdes.includes('antigravity'));
     // 如果没有检测到任何 AI CLI，并且也没有检测到配置文件夹，创建 .mcp.json 作为备用
     if (!registered && !hasIdeDir) {
         createMcpJson(cwd, apiUrl, opts.user);
@@ -276,31 +282,39 @@ function execSilent(cmd) {
     }
     catch { /* ignore */ }
 }
-/** 自动检测 AI CLI 并注册 MCP (注入环境变量实现启动即就绪) */
-function autoRegisterMcp(apiUrl, user, skipGemini = false) {
+/** 自动检测 AI CLI 并注册全局 MCP (不注入 env，支持多项目通过 kg_init 切换) */
+function autoRegisterMcp(skipGemini = false) {
     const detected = [];
     const serverName = 'ppdocs-kg';
-    const envFlags = `-e PPDOCS_API_URL=${apiUrl} -e PPDOCS_USER=${user}`;
-    // Claude CLI
+    const addCmd = `-- npx -y @ppdocs/mcp@latest`;
+    // Claude CLI (幂等：已注册则跳过)
     if (commandExists('claude')) {
         detected.push('Claude');
         try {
-            console.log(`✅ Detected Claude CLI, registering MCP...`);
-            // 先移除旧配置(可能无 env)，再重新注册
-            execSilent(`claude mcp remove ${serverName}`);
-            execSync(`claude mcp add ${serverName} ${envFlags} -- npx -y @ppdocs/mcp@latest`, { stdio: 'inherit' });
+            const list = execSync(`claude mcp list`, { encoding: 'utf-8' });
+            if (list.includes(serverName)) {
+                console.log(`✅ Claude MCP already configured`);
+            }
+            else {
+                execSync(`claude mcp add ${serverName} ${addCmd}`, { stdio: 'inherit' });
+            }
         }
         catch {
-            console.log(`⚠️  Claude MCP registration failed`);
+            try {
+                execSilent(`claude mcp remove ${serverName}`);
+                execSync(`claude mcp add ${serverName} ${addCmd}`, { stdio: 'inherit' });
+            }
+            catch {
+                console.log(`⚠️  Claude MCP registration failed`);
+            }
         }
     }
-    // Codex CLI (OpenAI)
+    // Codex CLI
     if (commandExists('codex')) {
         detected.push('Codex');
         try {
-            console.log(`✅ Detected Codex CLI, registering MCP...`);
             execSilent(`codex mcp remove ${serverName}`);
-            execSync(`codex mcp add ${serverName} ${envFlags} -- npx -y @ppdocs/mcp@latest`, { stdio: 'inherit' });
+            execSync(`codex mcp add ${serverName} ${addCmd}`, { stdio: 'inherit' });
         }
         catch {
             console.log(`⚠️  Codex MCP registration failed`);
@@ -310,7 +324,6 @@ function autoRegisterMcp(apiUrl, user, skipGemini = false) {
     if (commandExists('gemini') && !skipGemini) {
         detected.push('Gemini');
         try {
-            console.log(`✅ Detected Gemini CLI, registering MCP...`);
             execSilent(`gemini mcp remove ${serverName}`);
             execSync(`gemini mcp add ${serverName} "npx -y @ppdocs/mcp@latest"`, { stdio: 'inherit' });
         }

package/dist/storage/httpClient.d.ts

@@ -104,6 +104,33 @@ export declare class PpdocsApiClient {
     analyzerImpactTree(projectPath: string, symbolName: string, depth?: number): Promise<unknown>;
     /** 获取文件 360° 上下文 */
     analyzerContext(projectPath: string, filePath: string): Promise<unknown>;
+    /** 智能上下文: 代码+文档+规则+任务全关联 */
+    analyzerSmartContext(projectPath: string, symbolName: string): Promise<unknown>;
+    /** 全关联路径: 两个符号之间的代码+文档路径 */
+    analyzerFullPath(projectPath: string, symbolA: string, symbolB: string, maxDepth?: number): Promise<unknown>;
+    private publicRequest;
+    /** 列出活跃讨论 (公开路由) */
+    discussionList(): Promise<unknown>;
+    /** 创建讨论 (公开路由) */
+    discussionCreate(title: string, initiator: string, participants: string[], content: string): Promise<{
+        id: string;
+    }>;
+    /** 批量读取讨论 (公开路由) */
+    discussionReadByIds(ids: string[]): Promise<unknown>;
+    /** 回复讨论 (公开路由) */
+    discussionReply(id: string, sender: string, content: string, newSummary?: string): Promise<boolean>;
+    /** 删除讨论 (公开路由) */
+    discussionDelete(id: string): Promise<boolean>;
+    /** 结案归档讨论 (认证路由) */
+    discussionClose(id: string, conclusion: string): Promise<{
+        archived_path: string;
+    }>;
+    meetingJoin(agentId: string, agentType: string): Promise<unknown>;
+    meetingLeave(agentId: string): Promise<unknown>;
+    meetingPost(agentId: string, content: string, msgType?: string): Promise<unknown>;
+    meetingClaim(agentId: string, filePath: string): Promise<unknown>;
+    meetingRelease(agentId: string, filePath: string): Promise<unknown>;
+    meetingStatus(): Promise<unknown>;
 }
 export declare function initClient(apiUrl: string): void;
 export declare function getClient(): PpdocsApiClient;

package/dist/storage/httpClient.js

@@ -509,6 +509,108 @@ export class PpdocsApiClient {
             body: JSON.stringify({ project_path: projectPath, file_path: filePath }),
         });
     }
+    /** 智能上下文: 代码+文档+规则+任务全关联 */
+    async analyzerSmartContext(projectPath, symbolName) {
+        return this.request('/analyzer/smart-context', {
+            method: 'POST',
+            body: JSON.stringify({ project_path: projectPath, symbol_name: symbolName }),
+        });
+    }
+    /** 全关联路径: 两个符号之间的代码+文档路径 */
+    async analyzerFullPath(projectPath, symbolA, symbolB, maxDepth = 3) {
+        return this.request('/analyzer/full-path', {
+            method: 'POST',
+            body: JSON.stringify({ project_path: projectPath, symbol_a: symbolA, symbol_b: symbolB, max_depth: maxDepth }),
+        });
+    }
+    // ============ 公开路由请求工具 (无需项目认证) ============
+    async publicRequest(path, options) {
+        const response = await fetch(`${this.serverUrl}${path}`, {
+            headers: { 'Content-Type': 'application/json' },
+            ...options,
+        });
+        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 discussionList() {
+        return this.publicRequest('/api/discussions');
+    }
+    /** 创建讨论 (公开路由) */
+    async discussionCreate(title, initiator, participants, content) {
+        return this.publicRequest('/api/discussions', {
+            method: 'POST',
+            body: JSON.stringify({ title, initiator, participants, content }),
+        });
+    }
+    /** 批量读取讨论 (公开路由) */
+    async discussionReadByIds(ids) {
+        return this.publicRequest('/api/discussions/read', {
+            method: 'POST',
+            body: JSON.stringify({ ids }),
+        });
+    }
+    /** 回复讨论 (公开路由) */
+    async discussionReply(id, sender, content, newSummary) {
+        return this.publicRequest(`/api/discussions/${encodeURIComponent(id)}/reply`, {
+            method: 'POST',
+            body: JSON.stringify({ sender, content, new_summary: newSummary }),
+        });
+    }
+    /** 删除讨论 (公开路由) */
+    async discussionDelete(id) {
+        return this.publicRequest(`/api/discussions/${encodeURIComponent(id)}`, {
+            method: 'DELETE',
+        });
+    }
+    /** 结案归档讨论 (认证路由) */
+    async discussionClose(id, conclusion) {
+        return this.request(`/discussions/${encodeURIComponent(id)}/close`, {
+            method: 'POST',
+            body: JSON.stringify({ conclusion }),
+        });
+    }
+    // ============ 多AI协作会议 ============
+    async meetingJoin(agentId, agentType) {
+        return this.request('/meeting/join', {
+            method: 'POST',
+            body: JSON.stringify({ agent_id: agentId, agent_type: agentType }),
+        });
+    }
+    async meetingLeave(agentId) {
+        return this.request('/meeting/leave', {
+            method: 'POST',
+            body: JSON.stringify({ agent_id: agentId }),
+        });
+    }
+    async meetingPost(agentId, content, msgType = 'status') {
+        return this.request('/meeting/post', {
+            method: 'POST',
+            body: JSON.stringify({ agent_id: agentId, content, msg_type: msgType }),
+        });
+    }
+    async meetingClaim(agentId, filePath) {
+        return this.request('/meeting/claim', {
+            method: 'POST',
+            body: JSON.stringify({ agent_id: agentId, file_path: filePath }),
+        });
+    }
+    async meetingRelease(agentId, filePath) {
+        return this.request('/meeting/release', {
+            method: 'POST',
+            body: JSON.stringify({ agent_id: agentId, file_path: filePath }),
+        });
+    }
+    async meetingStatus() {
+        return this.request('/meeting/status');
+    }
 }
 // ============ 模块级 API ============
 let client = null;

package/dist/tools/analyzer.d.ts

@@ -5,4 +5,5 @@
  * 让 AI Agent 通过 MCP 工具直接查询代码结构、依赖关系和影响范围
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function registerAnalyzerTools(server: McpServer, projectId: string): void;
+import { type McpContext } from './shared.js';
+export declare function registerAnalyzerTools(server: McpServer, ctx: McpContext): void;

package/dist/tools/analyzer.js

@@ -16,7 +16,7 @@ const SYMBOL_ICONS = {
 const SEVERITY_ICONS = {
     critical: '🔴', warning: '🟡', info: '🟢',
 };
-export function registerAnalyzerTools(server, projectId) {
+export function registerAnalyzerTools(server, ctx) {
     const client = () => getClient();
     // ===== code_scan: 扫描项目代码 =====
     server.tool('code_scan', '📡 扫描项目代码, 构建索引。返回文件数、符号数、语言统计。★首次使用 code_query/code_impact/code_context 前必须先执行★', {
@@ -94,19 +94,19 @@ export function registerAnalyzerTools(server, projectId) {
         projectPath: z.string().describe('项目源码的绝对路径'),
         filePath: z.string().describe('目标文件的相对路径(如"src/services/auth.ts")'),
     }, async (args) => safeTool(async () => {
-        const ctx = await client().analyzerContext(args.projectPath, args.filePath);
-        if (!ctx) {
+        const fileCtx = await client().analyzerContext(args.projectPath, args.filePath);
+        if (!fileCtx) {
             return wrap(`未找到文件 "${args.filePath}"。请确认路径正确, 路径格式为相对路径(如 src/main.ts)`);
         }
         const lines = [
-            `📄 ${ctx.filePath}`,
-            `语言: ${ctx.language} | ${ctx.linesTotal} 行`,
+            `📄 ${fileCtx.filePath}`,
+            `语言: ${fileCtx.language} | ${fileCtx.linesTotal} 行`,
             ``,
         ];
         // 定义的符号
-        if (ctx.symbolsDefined.length > 0) {
-            lines.push(`### 🔤 定义的符号 (${ctx.symbolsDefined.length})`);
-            for (const sym of ctx.symbolsDefined) {
+        if (fileCtx.symbolsDefined.length > 0) {
+            lines.push(`### 🔤 定义的符号 (${fileCtx.symbolsDefined.length})`);
+            for (const sym of fileCtx.symbolsDefined) {
                 const icon = SYMBOL_ICONS[sym.kind] || '?';
                 const exp = sym.exported ? ' [export]' : '';
                 lines.push(`  ${icon} ${sym.name}${exp}  L${sym.lineStart}-L${sym.lineEnd}`);
@@ -114,18 +114,18 @@ export function registerAnalyzerTools(server, projectId) {
             lines.push('');
         }
         // 导入
-        if (ctx.imports.length > 0) {
-            lines.push(`### 📥 导入 (${ctx.imports.length})`);
-            for (const imp of ctx.imports) {
+        if (fileCtx.imports.length > 0) {
+            lines.push(`### 📥 导入 (${fileCtx.imports.length})`);
+            for (const imp of fileCtx.imports) {
                 const specs = imp.specifiers.length > 0 ? `{ ${imp.specifiers.join(', ')} }` : '*';
                 lines.push(`  → ${imp.source}  ${specs}  L${imp.line}`);
             }
             lines.push('');
         }
         // 被谁引用
-        if (ctx.importedBy.length > 0) {
-            lines.push(`### 📤 被引用 (${ctx.importedBy.length})`);
-            for (const by of ctx.importedBy) {
+        if (fileCtx.importedBy.length > 0) {
+            lines.push(`### 📤 被引用 (${fileCtx.importedBy.length})`);
+            for (const by of fileCtx.importedBy) {
                 const specs = by.specifiers.length > 0 ? `{ ${by.specifiers.join(', ')} }` : '';
                 lines.push(`  ← ${by.filePath}  ${specs}`);
             }
@@ -260,4 +260,117 @@ export function registerAnalyzerTools(server, projectId) {
         }
         return wrap(lines.join('\n'));
     }));
+    // ===== code_smart_context: 代码+文档全关联上下文 =====
+    server.tool('code_smart_context', '🔍 代码+文档全关联上下文 — 输入一个函数名，一次调用返回：代码依赖、关联文档、匹配规则、活跃任务、影响范围摘要。需先运行 code_scan', {
+        projectPath: z.string().describe('项目源码的绝对路径'),
+        symbolName: z.string().describe('要查询的符号名称(如"handleLogin", "AuthService")'),
+    }, async (args) => safeTool(async () => {
+        const smartCtx = await client().analyzerSmartContext(args.projectPath, args.symbolName);
+        if (!smartCtx) {
+            return wrap(`未找到符号 "${args.symbolName}"。请确认名称正确且已运行 code_scan`);
+        }
+        const lines = [
+            `🔍 智能上下文: ${smartCtx.symbol.name}`,
+            ``,
+        ];
+        // 符号信息
+        const icon = SYMBOL_ICONS[smartCtx.symbol.kind] || '?';
+        const exp = smartCtx.symbol.exported ? ' [export]' : '';
+        lines.push(`### ${icon} 符号信息`);
+        lines.push(`  ${smartCtx.symbol.name}${exp} (${smartCtx.symbol.kind})`);
+        lines.push(`  📍 ${smartCtx.symbol.filePath}:${smartCtx.symbol.lineStart}-${smartCtx.symbol.lineEnd}`);
+        if (smartCtx.symbol.signature)
+            lines.push(`  📝 ${smartCtx.symbol.signature}`);
+        lines.push('');
+        // 文件上下文
+        lines.push(`### 📄 文件上下文: ${smartCtx.fileContext.filePath}`);
+        lines.push(`  语言: ${smartCtx.fileContext.language} | ${smartCtx.fileContext.linesTotal} 行`);
+        lines.push(`  定义: ${smartCtx.fileContext.symbolsDefined.length} 个符号 | 导入: ${smartCtx.fileContext.imports.length} | 被引用: ${smartCtx.fileContext.importedBy.length}`);
+        lines.push('');
+        // 影响范围
+        if (smartCtx.impactSummary.totalFiles > 0) {
+            lines.push(`### 💥 影响范围: ${smartCtx.impactSummary.totalFiles} 个文件`);
+            for (const f of smartCtx.impactSummary.l1Files.slice(0, 10)) {
+                lines.push(`  🔴 ${f}`);
+            }
+            lines.push('');
+        }
+        // 关联文档
+        if (smartCtx.relatedDocs.length > 0) {
+            lines.push(`### 📚 关联知识文档 (${smartCtx.relatedDocs.length})`);
+            for (const doc of smartCtx.relatedDocs) {
+                lines.push(`  📄 ${doc.path} — ${doc.summary}`);
+            }
+            lines.push('');
+        }
+        // 匹配规则
+        if (smartCtx.matchedRules.length > 0) {
+            lines.push(`### 📏 匹配规则 (${smartCtx.matchedRules.length})`);
+            for (const rule of smartCtx.matchedRules) {
+                lines.push(`  [${rule.ruleType}] ${rule.content.substring(0, 100)}`);
+            }
+            lines.push('');
+        }
+        // 活跃任务
+        if (smartCtx.activeTasks.length > 0) {
+            lines.push(`### 📝 活跃任务 (${smartCtx.activeTasks.length})`);
+            for (const task of smartCtx.activeTasks) {
+                lines.push(`  🔵 [${task.id}] ${task.title}`);
+            }
+        }
+        return wrap(lines.join('\n'));
+    }));
+    // ===== code_full_path: 全关联路径 =====
+    server.tool('code_full_path', '🔗 全关联路径 — 两个符号之间不仅返回代码引用链路，还返回共享的KG文档、共同导入、祖先模块。需先运行 code_scan', {
+        projectPath: z.string().describe('项目源码的绝对路径'),
+        symbolA: z.string().describe('起点符号名(如 "handleLogin")'),
+        symbolB: z.string().describe('终点符号名(如 "AuthService")'),
+        maxDepth: z.number().optional().describe('最大搜索深度(1-5, 默认3)'),
+    }, async (args) => safeTool(async () => {
+        const result = await client().analyzerFullPath(args.projectPath, args.symbolA, args.symbolB, args.maxDepth ?? 3);
+        if (!result) {
+            return wrap(`❌ 无法构建路径。请确认两个符号名称正确且已运行 code_scan`);
+        }
+        const lines = [
+            `🔗 全关联路径`,
+            ``,
+            `📍 ${result.symbolA.name} (${result.symbolA.kind}) → ${result.symbolA.filePath}:${result.symbolA.lineStart}`,
+            `📍 ${result.symbolB.name} (${result.symbolB.kind}) → ${result.symbolB.filePath}:${result.symbolB.lineStart}`,
+            ``,
+            `📊 ${result.pathSummary}`,
+            ``,
+        ];
+        // 代码路径
+        if (result.codePath.length > 0) {
+            lines.push(`### 🔗 代码引用链路 (${result.codePath.length} 步)`);
+            for (const step of result.codePath.slice(0, 20)) {
+                lines.push(`  L${step.depth} ${step.filePath} [${step.refKind}] ← ${step.symbolName}`);
+            }
+            lines.push('');
+        }
+        // 共享文档
+        if (result.sharedDocs.length > 0) {
+            lines.push(`### 📚 共享KG文档 (${result.sharedDocs.length})`);
+            for (const doc of result.sharedDocs) {
+                lines.push(`  📄 ${doc.path} — ${doc.summary}`);
+            }
+            lines.push('');
+        }
+        // 共同导入
+        if (result.commonImports.length > 0) {
+            lines.push(`### 📥 共同导入 (${result.commonImports.length})`);
+            for (const imp of result.commonImports) {
+                lines.push(`  → ${imp}`);
+            }
+            lines.push('');
+        }
+        // 共同祖先
+        if (result.commonAncestors.length > 0) {
+            lines.push(`### 📁 共同祖先目录`);
+            for (const anc of result.commonAncestors) {
+                lines.push(`  📂 ${anc}`);
+            }
+        }
+        return wrap(lines.join('\n'));
+    }));
 }

package/dist/tools/discussion.d.ts

@@ -1,7 +1,8 @@
 /**
  * 💬 kg_discuss (6→1)
- * 合并: kg_discussion_list, kg_discussion_read, kg_discussion_create,
- *       kg_discussion_reply, kg_discussion_close_and_archive, kg_discussion_delete
+ * 合并: list, read, create, reply, close, delete
+ * 统一走 HTTP → Rust 后端 (单一写入者)
+ * sender 格式: "projectId:user" (如 "p-ca3sgejg:张三")
  */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type McpContext } from './shared.js';