@ppdocs/mcp 3.2.17 → 3.2.19

package/dist/cli.d.ts

@@ -4,4 +4,4 @@
  */
 export declare function runCli(args: string[]): Promise<boolean>;
 /** 安装项目模板文件 (供授权后自动配置调用) */
-export declare function setupProjectFiles(cwd: string, apiUrl: string): void;
+export declare function setupProjectFiles(cwd: string, apiUrl: string, user?: string): void;

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;
@@ -158,15 +164,15 @@ async function initProject(opts) {
         hasIdeDir = true;
     }
     if (detectedIdes.includes('cursor')) {
-        installCursorTemplates(cwd, apiUrl);
+        installCursorTemplates(cwd, apiUrl, opts.user);
         hasIdeDir = true;
     }
     if (detectedIdes.includes('antigravity')) {
-        installAntigravityTemplates(cwd, apiUrl);
+        installAntigravityTemplates(cwd, apiUrl, opts.user);
         hasIdeDir = true;
     }
     if (detectedIdes.includes('kiro')) {
-        installKiroTemplates(cwd, apiUrl);
+        installKiroTemplates(cwd, apiUrl, opts.user);
         hasIdeDir = true;
     }
     // Fallback behavior: if no specific IDE config directories found
@@ -179,10 +185,10 @@ 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);
+        createMcpJson(cwd, apiUrl, opts.user);
     }
     // --from: 从模板项目拉取 IDE 配置文件
     if (opts.from) {
@@ -276,61 +282,53 @@ 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';
-    // 检测 Claude CLI (不传环境变量，MCP启动时读取.ppdocs)
+    const addCmd = `-- npx -y @ppdocs/mcp@latest`;
+    // Claude CLI (幂等：已注册则跳过)
     if (commandExists('claude')) {
         detected.push('Claude');
         try {
-            console.log(`✅ Detected Claude CLI, registering MCP...`);
-            // 先检查是否已存在
-            const checkResult = execSync(`claude mcp list`, { encoding: 'utf-8' });
-            if (checkResult.includes(serverName)) {
+            const list = execSync(`claude mcp list`, { encoding: 'utf-8' });
+            if (list.includes(serverName)) {
                 console.log(`✅ Claude MCP already configured`);
             }
             else {
-                const cmd = `claude mcp add ${serverName} -- npx -y @ppdocs/mcp@latest`;
-                execSync(cmd, { stdio: 'inherit' });
+                execSync(`claude mcp add ${serverName} ${addCmd}`, { stdio: 'inherit' });
             }
         }
-        catch (e) {
-            // 如果 list 失败，尝试添加
+        catch {
             try {
                 execSilent(`claude mcp remove ${serverName}`);
-                const cmd = `claude mcp add ${serverName} -- npx -y @ppdocs/mcp@latest`;
-                execSync(cmd, { stdio: 'inherit' });
+                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}`);
-            const cmd = `codex mcp add ${serverName} -- npx -y @ppdocs/mcp@latest`;
-            execSync(cmd, { stdio: 'inherit' });
+            execSync(`codex mcp add ${serverName} ${addCmd}`, { stdio: 'inherit' });
         }
-        catch (e) {
-            console.log(`⚠️  Codex MCP registration failed: ${e}`);
+        catch {
+            console.log(`⚠️  Codex MCP registration failed`);
         }
     }
-    // 检测 Gemini CLI
+    // Gemini CLI
     if (commandExists('gemini') && !skipGemini) {
         detected.push('Gemini');
         try {
-            console.log(`✅ Detected Gemini CLI, registering MCP...`);
             execSilent(`gemini mcp remove ${serverName}`);
-            const cmd = `gemini mcp add ${serverName} "npx -y @ppdocs/mcp@latest"`;
-            execSync(cmd, { stdio: 'inherit' });
+            execSync(`gemini mcp add ${serverName} "npx -y @ppdocs/mcp@latest"`, { stdio: 'inherit' });
         }
-        catch (e) {
-            console.log(`⚠️  Gemini MCP registration failed: ${e}`);
+        catch {
+            console.log(`⚠️  Gemini MCP registration failed`);
         }
     }
     if (detected.length === 0) {
@@ -340,34 +338,33 @@ function autoRegisterMcp(apiUrl, user, skipGemini = false) {
     console.log(`✅ Registered MCP for: ${detected.join(', ')}`);
     return true;
 }
-/** 在指定路径创建或更新 mcp.json 配置 (不传 PPDOCS_API_URL，依赖 cwd/.ppdocs 文件) */
-function createMcpConfigAt(mcpPath, _apiUrl, _options) {
+/** 在指定路径创建或更新 mcp.json 配置，注入 PPDOCS_API_URL 环境变量实现启动即就绪 */
+function createMcpConfigAt(mcpPath, apiUrl, options) {
     let mcpConfig = {};
     if (fs.existsSync(mcpPath)) {
         try {
             mcpConfig = JSON.parse(fs.readFileSync(mcpPath, 'utf-8'));
         }
         catch {
-            // 解析失败时中止，避免清空已有配置
             console.log(`⚠️  ${mcpPath} JSON格式无效，跳过MCP配置写入（请手动修复后重试）`);
             return;
         }
     }
-    // Windows 需要 cmd /c 包装才能执行 npx
     const isWindows = process.platform === 'win32';
-    // 对于 Mac/Linux，IDE 可能没有用户的完整 PATH，导致找不到 npx
     const macExtraPaths = '/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin';
     const actualPath = `${process.env.PATH || '/usr/bin:/bin'}:${macExtraPaths}`;
+    // 构建 env: 非 Windows 补 PATH + 注入项目绑定变量
+    const env = {};
+    if (!isWindows)
+        env.PATH = actualPath;
+    if (!options?.noEnv) {
+        env.PPDOCS_API_URL = apiUrl;
+        if (options?.user)
+            env.PPDOCS_USER = options.user;
+    }
     const ppdocsServer = isWindows
-        ? {
-            command: 'cmd',
-            args: ['/c', 'npx', '-y', '@ppdocs/mcp@latest'],
-        }
-        : {
-            command: 'npx',
-            args: ['-y', '@ppdocs/mcp@latest'],
-            env: { "PATH": actualPath }
-        };
+        ? { command: 'cmd', args: ['/c', 'npx', '-y', '@ppdocs/mcp@latest'], ...(Object.keys(env).length > 0 && { env }) }
+        : { command: 'npx', args: ['-y', '@ppdocs/mcp@latest'], env };
     mcpConfig.mcpServers = {
         ...(mcpConfig.mcpServers || {}),
         "ppdocs-kg": ppdocsServer,
@@ -381,8 +378,8 @@ function createMcpConfigAt(mcpPath, _apiUrl, _options) {
     console.log(`✅ Configured MCP in ${mcpPath}`);
 }
 /** 创建 .mcp.json (手动配置备用) */
-function createMcpJson(cwd, apiUrl) {
-    createMcpConfigAt(path.join(cwd, '.mcp.json'), apiUrl);
+function createMcpJson(cwd, apiUrl, user) {
+    createMcpConfigAt(path.join(cwd, '.mcp.json'), apiUrl, { user });
 }
 /** 递归复制目录 */
 function copyDirRecursive(src, dest) {
@@ -505,9 +502,8 @@ function generateAgentsMd(cwd) {
     }
 }
 /** 安装 Cursor 模板 */
-function installCursorTemplates(cwd, apiUrl) {
-    // 1. 生成 Cursor MCP 配置
-    createMcpConfigAt(path.join(cwd, '.cursor', 'mcp.json'), apiUrl);
+function installCursorTemplates(cwd, apiUrl, user) {
+    createMcpConfigAt(path.join(cwd, '.cursor', 'mcp.json'), apiUrl, { user });
     // 2. 生成 .cursorrules 提示词
     const srcRules = path.join(TEMPLATES_DIR, 'cursorrules.md');
     const destRules = path.join(cwd, '.cursorrules');
@@ -517,9 +513,9 @@ function installCursorTemplates(cwd, apiUrl) {
     }
 }
 /** 安装 Antigravity (Gemini IDE) 模板 */
-function installAntigravityTemplates(cwd, apiUrl) {
-    // 1. 填充 .gemini/settings.json (noEnv: 依赖 .ppdocs 文件，不传 PPDOCS_API_URL 避免覆盖)
-    createMcpConfigAt(path.join(cwd, '.gemini', 'settings.json'), apiUrl, { noEnv: true });
+function installAntigravityTemplates(cwd, apiUrl, user) {
+    // Antigravity 由 gemini CLI 注册 env，文件配置不注入避免冲突
+    createMcpConfigAt(path.join(cwd, '.gemini', 'settings.json'), apiUrl, { noEnv: true, user });
     // 2. 生成 AGENTS.md
     generateAgentsMd(cwd);
     // 3. 安装斜杠命令 → 全局目录 ~/.gemini/antigravity/global_workflows/
@@ -575,9 +571,8 @@ function installAntigravityTemplates(cwd, apiUrl) {
     }
 }
 /** 安装 Kiro 模板 */
-function installKiroTemplates(cwd, apiUrl) {
-    // 1. 生成 Kiro MCP 配置
-    createMcpConfigAt(path.join(cwd, '.kiro', 'settings', 'mcp.json'), apiUrl);
+function installKiroTemplates(cwd, apiUrl, user) {
+    createMcpConfigAt(path.join(cwd, '.kiro', 'settings', 'mcp.json'), apiUrl, { user });
     // 2. 生成 Kiro Agent 规则
     const kiroRulesDir = path.join(cwd, '.kiro', 'rules');
     if (!fs.existsSync(kiroRulesDir)) {
@@ -604,21 +599,20 @@ function detectIDEs(cwd) {
     return ides;
 }
 /** 安装项目模板文件 (供授权后自动配置调用) */
-export function setupProjectFiles(cwd, apiUrl) {
+export function setupProjectFiles(cwd, apiUrl, user) {
     const detectedIdes = detectIDEs(cwd);
     if (detectedIdes.includes('antigravity')) {
-        installAntigravityTemplates(cwd, apiUrl);
+        installAntigravityTemplates(cwd, apiUrl, user);
     }
     if (detectedIdes.includes('cursor')) {
-        installCursorTemplates(cwd, apiUrl);
+        installCursorTemplates(cwd, apiUrl, user);
     }
     if (detectedIdes.includes('kiro')) {
-        installKiroTemplates(cwd, apiUrl);
+        installKiroTemplates(cwd, apiUrl, user);
     }
     if (detectedIdes.includes('claude')) {
         installClaudeTemplates(cwd);
     }
-    // 如果没检测到任何 IDE，默认安装 Claude 模板
     if (detectedIdes.length === 0) {
         installClaudeTemplates(cwd);
     }

package/package.json

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