@ppdocs/mcp 3.1.9 → 3.1.10

package/dist/cli.d.ts

@@ -3,3 +3,5 @@
  * 命令: init - 初始化项目配置 + 安装工作流模板 + 自动注册 MCP
  */
 export declare function runCli(args: string[]): boolean;
+/** 安装项目模板文件 (供授权后自动配置调用) */
+export declare function setupProjectFiles(cwd: string, apiUrl: string): void;

package/dist/cli.js

@@ -181,8 +181,8 @@ async function initProject(opts) {
             installClaudeTemplates(cwd); // Default to Claude templates
         }
     }
-    // 自动检测并注册 MCP
-    const registered = autoRegisterMcp(apiUrl, opts.user);
+    // 自动检测并注册 MCP (如果已写入 Antigravity 配置，跳过 gemini CLI 注册避免冲突)
+    const registered = autoRegisterMcp(apiUrl, opts.user, detectedIdes.includes('antigravity'));
     // 如果没有检测到任何 AI CLI，并且也没有检测到配置文件夹，创建 .mcp.json 作为备用
     if (!registered && !hasIdeDir) {
         createMcpJson(cwd, apiUrl);
@@ -280,7 +280,7 @@ function execSilent(cmd) {
     catch { /* ignore */ }
 }
 /** 自动检测 AI CLI 并注册 MCP */
-function autoRegisterMcp(apiUrl, user) {
+function autoRegisterMcp(apiUrl, user, skipGemini = false) {
     const detected = [];
     const serverName = 'ppdocs-kg';
     // 检测 Claude CLI (不传环境变量，MCP启动时读取.ppdocs)
@@ -324,7 +324,7 @@ function autoRegisterMcp(apiUrl, user) {
         }
     }
     // 检测 Gemini CLI
-    if (commandExists('gemini')) {
+    if (commandExists('gemini') && !skipGemini) {
         detected.push('Gemini');
         try {
             console.log(`✅ Detected Gemini CLI, registering MCP...`);
@@ -344,33 +344,39 @@ function autoRegisterMcp(apiUrl, user) {
     return true;
 }
 /** 在指定路径创建或更新 mcp.json 配置 */
-function createMcpConfigAt(mcpPath, apiUrl) {
+function createMcpConfigAt(mcpPath, apiUrl, options) {
     let mcpConfig = {};
     if (fs.existsSync(mcpPath)) {
         try {
             mcpConfig = JSON.parse(fs.readFileSync(mcpPath, 'utf-8'));
         }
         catch {
-            // ignore parse error
+            // 解析失败时中止，避免清空已有配置
+            console.log(`⚠️  ${mcpPath} JSON格式无效，跳过MCP配置写入（请手动修复后重试）`);
+            return;
         }
     }
     // Windows 需要 cmd /c 包装才能执行 npx
     const isWindows = process.platform === 'win32';
     // 对于 Mac/Linux，IDE 可能没有用户的完整 PATH，导致找不到 npx
+    // 使用实际 PATH 值拼接，JSON 中的 $PATH 不会被展开
+    const macExtraPaths = '/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin';
+    const actualPath = `${process.env.PATH || '/usr/bin:/bin'}:${macExtraPaths}`;
     const ppdocsServer = isWindows
         ? {
             command: 'cmd',
             args: ['/c', 'npx', '-y', '@ppdocs/mcp@latest'],
-            env: { "PPDOCS_API_URL": apiUrl }
+            ...(options?.noEnv ? {} : { env: { "PPDOCS_API_URL": apiUrl } })
         }
         : {
             command: 'npx',
             args: ['-y', '@ppdocs/mcp@latest'],
-            env: {
-                "PPDOCS_API_URL": apiUrl,
-                // 强行注入常见路径，防止找不到 node/npx
-                "PATH": "$PATH:/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin:$HOME/.nvm/versions/node/current/bin:$HOME/.local/share/fnm/aliases/default/bin"
-            }
+            ...(options?.noEnv ? { env: { "PATH": actualPath } } : {
+                env: {
+                    "PPDOCS_API_URL": apiUrl,
+                    "PATH": actualPath
+                }
+            })
         };
     mcpConfig.mcpServers = {
         ...(mcpConfig.mcpServers || {}),
@@ -522,8 +528,8 @@ function installCursorTemplates(cwd, apiUrl) {
 }
 /** 安装 Antigravity (Gemini IDE) 模板 */
 function installAntigravityTemplates(cwd, apiUrl) {
-    // 1. 填充 .gemini/settings.json
-    createMcpConfigAt(path.join(cwd, '.gemini', 'settings.json'), apiUrl);
+    // 1. 填充 .gemini/settings.json (noEnv: 依赖 .ppdocs 文件，不传 PPDOCS_API_URL 避免覆盖)
+    createMcpConfigAt(path.join(cwd, '.gemini', 'settings.json'), apiUrl, { noEnv: true });
     // 2. 生成 AGENTS.md
     generateAgentsMd(cwd);
     // 3. 安装斜杠命令 → .agents/workflows/ (Antigravity 的 slash command 机制)
@@ -587,3 +593,23 @@ function detectIDEs(cwd) {
         ides.push('kiro');
     return ides;
 }
+/** 安装项目模板文件 (供授权后自动配置调用) */
+export function setupProjectFiles(cwd, apiUrl) {
+    const detectedIdes = detectIDEs(cwd);
+    if (detectedIdes.includes('antigravity')) {
+        installAntigravityTemplates(cwd, apiUrl);
+    }
+    if (detectedIdes.includes('cursor')) {
+        installCursorTemplates(cwd, apiUrl);
+    }
+    if (detectedIdes.includes('kiro')) {
+        installKiroTemplates(cwd, apiUrl);
+    }
+    if (detectedIdes.includes('claude')) {
+        installClaudeTemplates(cwd);
+    }
+    // 如果没检测到任何 IDE，默认安装 Claude 模板
+    if (detectedIdes.length === 0) {
+        installClaudeTemplates(cwd);
+    }
+}

package/dist/config.d.ts

@@ -1,16 +1,22 @@
 /**
  * ppdocs MCP Config
- * 读取配置: 环境变量 > .ppdocs 文件
+ * 读取配置: 环境变量 > .ppdocs 文件 > 自动发现 > 授权请求
  */
 export interface PpdocsConfig {
     apiUrl: string;
     projectId: string;
     user: string;
+    source: 'env' | 'file' | 'discover' | 'auth';
+    /** 原始连接参数 (discover/auth 填充, 供持久化使用) */
+    connection?: {
+        host: string;
+        port: number;
+        password: string;
+    };
 }
 export declare const PPDOCS_CONFIG_FILE = ".ppdocs";
-/** 生成随机用户名 (8位字母数字) */
+/** 生成随机用户名 */
 export declare function generateUser(): string;
-/**
- * 加载配置 (优先级: 环境变量 > .ppdocs 文件)
- */
-export declare function loadConfig(): PpdocsConfig;
+/** 写入 .ppdocs 文件 (需 config.connection 存在) */
+export declare function writePpdocsFile(config: PpdocsConfig): void;
+export declare function loadConfig(): Promise<PpdocsConfig>;

package/dist/config.js

@@ -1,72 +1,172 @@
 /**
  * ppdocs MCP Config
- * 读取配置: 环境变量 > .ppdocs 文件
+ * 读取配置: 环境变量 > .ppdocs 文件 > 自动发现 > 授权请求
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 export const PPDOCS_CONFIG_FILE = '.ppdocs';
-/** 生成随机用户名 (8位字母数字) */
+/** 生成随机用户名 */
 export function generateUser() {
     const chars = 'abcdefghjkmnpqrstuvwxyz23456789';
     return Array.from({ length: 8 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');
 }
-/**
- * 从 .ppdocs 文件读取配置
- */
+// ============ 静态配置读取 ============
+function readEnvConfig() {
+    const apiUrl = process.env.PPDOCS_API_URL;
+    if (!apiUrl)
+        return null;
+    const match = apiUrl.match(/\/api\/([^/]+)\/[^/]+\/?$/);
+    return { apiUrl, projectId: match?.[1] || 'unknown', user: process.env.PPDOCS_USER || generateUser(), source: 'env' };
+}
 function readPpdocsFile() {
-    const cwd = process.cwd();
-    const configPath = path.join(cwd, '.ppdocs');
-    if (!fs.existsSync(configPath)) {
+    const configPath = path.join(process.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) {
+        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 || generateUser(), source: 'file' };
+    }
+    catch {
+        return null;
+    }
+}
+async function findLocalServer() {
+    for (const host of ['localhost', '127.0.0.1', '10.0.0.176']) {
+        for (const port of [20001]) {
+            try {
+                const res = await fetch(`http://${host}:${port}/health`, { signal: AbortSignal.timeout(2000) });
+                if (res.ok)
+                    return { host, port, base: `http://${host}:${port}` };
+            }
+            catch {
+                continue;
+            }
         }
+    }
+    return null;
+}
+// ============ 自动发现 ============
+async function autoDiscoverConfig(server) {
+    const cwd = process.cwd().replace(/\\/g, '/').toLowerCase();
+    try {
+        const res = await fetch(`${server.base}/api/projects`, { signal: AbortSignal.timeout(2000) });
+        if (!res.ok)
+            return null;
+        const { data: projects } = await res.json();
+        if (!Array.isArray(projects))
+            return null;
+        const match = projects.find((p) => p.projectPath && cwd.startsWith(p.projectPath.replace(/\\/g, '/').toLowerCase()));
+        if (!match)
+            return null;
+        const metaRes = await fetch(`${server.base}/api/projects/${match.id}/meta`, { signal: AbortSignal.timeout(2000) });
+        if (!metaRes.ok)
+            return null;
+        const { data: meta } = await metaRes.json();
+        if (!meta?.password)
+            return null;
+        console.error(`[AutoDiscovery] 匹配项目: ${match.name} (${match.id})`);
         return {
-            apiUrl: `${config.api}/api/${config.projectId}/${config.key}`,
-            projectId: config.projectId,
-            user: config.user || generateUser(),
+            apiUrl: `${server.base}/api/${match.id}/${meta.password}`,
+            projectId: match.id,
+            user: `auto-${generateUser().slice(0, 4)}`,
+            source: 'discover',
+            connection: { host: server.host, port: server.port, password: meta.password },
         };
     }
     catch {
         return null;
     }
 }
-/**
- * 从环境变量读取配置
- */
-function readEnvConfig() {
-    const apiUrl = process.env.PPDOCS_API_URL;
-    if (!apiUrl)
+// ============ 授权请求 ============
+async function requestAuthConfig(server) {
+    try {
+        const reqRes = await fetch(`${server.base}/api/auth/request`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ cwd: process.cwd(), hostname: os.hostname() }),
+        });
+        if (!reqRes.ok)
+            return null;
+        const { data } = await reqRes.json();
+        if (!data?.requestId)
+            return null;
+        console.error(`[Auth] 等待桌面端授权... (请在 ppdocs 桌面端确认)`);
+        for (let i = 0; i < 150; i++) {
+            await new Promise(r => setTimeout(r, 2000));
+            const pollRes = await fetch(`${server.base}/api/auth/poll/${data.requestId}`, { signal: AbortSignal.timeout(3000) });
+            if (!pollRes.ok)
+                continue;
+            const { data: poll } = await pollRes.json();
+            if (poll?.status === 'approved' && poll.result) {
+                const r = poll.result;
+                console.error(`[Auth] 已授权: ${r.project_name} (${r.project_id})`);
+                return {
+                    apiUrl: `http://${r.api_host}:${r.api_port}/api/${r.project_id}/${r.password}`,
+                    projectId: r.project_id,
+                    user: `auto-${generateUser().slice(0, 4)}`,
+                    source: 'auth',
+                    connection: { host: r.api_host, port: r.api_port, password: r.password },
+                };
+            }
+            if (poll?.status === 'rejected') {
+                console.error('[Auth] 授权被拒绝');
+                return null;
+            }
+            if (poll?.status === 'expired') {
+                console.error('[Auth] 授权超时');
+                return null;
+            }
+        }
+        console.error('[Auth] 轮询超时');
         return null;
-    // URL 格式: http://localhost:20001/api/{projectId}/{password}
-    const match = apiUrl.match(/\/api\/([^/]+)\/[^/]+\/?$/);
-    const projectId = match?.[1] || 'unknown';
-    const user = process.env.PPDOCS_USER || generateUser();
-    return { apiUrl, projectId, user };
+    }
+    catch {
+        return null;
+    }
 }
-/**
- * 加载配置 (优先级: 环境变量 > .ppdocs 文件)
- */
-export function loadConfig() {
-    // 1. 尝试环境变量
+// ============ 持久化 ============
+/** 写入 .ppdocs 文件 (需 config.connection 存在) */
+export function writePpdocsFile(config) {
+    if (!config.connection)
+        return;
+    const configPath = path.join(process.cwd(), '.ppdocs');
+    if (fs.existsSync(configPath))
+        return;
+    const { host, port, password } = config.connection;
+    fs.writeFileSync(configPath, JSON.stringify({
+        api: `http://${host}:${port}`,
+        projectId: config.projectId,
+        key: password,
+        user: config.user,
+    }, null, 2), 'utf-8');
+    console.error(`[Config] 已保存 .ppdocs`);
+}
+// ============ 入口 ============
+export async function loadConfig() {
+    // 1. 环境变量
     const envConfig = readEnvConfig();
     if (envConfig)
         return envConfig;
-    // 2. 尝试 .ppdocs 文件
+    // 2. .ppdocs 文件
     const fileConfig = readPpdocsFile();
     if (fileConfig)
         return fileConfig;
-    // 3. 报错
+    // 3-4. 需要服务器 → 只扫一次
+    const server = await findLocalServer();
+    if (server) {
+        const discoverConfig = await autoDiscoverConfig(server);
+        if (discoverConfig)
+            return discoverConfig;
+        const authConfig = await requestAuthConfig(server);
+        if (authConfig)
+            return authConfig;
+    }
+    // 5. 全部失败
     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}');
+    console.error('  Option 1: npx @ppdocs/mcp init -p <projectId> -k <key>');
+    console.error('  Option 2: Ensure ppdocs desktop app is running');
     process.exit(1);
 }

package/dist/index.js

@@ -13,8 +13,8 @@ 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';
+import { runCli, setupProjectFiles } from './cli.js';
+import { loadConfig, writePpdocsFile } from './config.js';
 // 从 package.json 读取版本号
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -26,7 +26,17 @@ if (args.length > 0 && runCli(args)) {
 }
 // 运行 MCP 服务
 async function main() {
-    const config = loadConfig();
+    const config = await loadConfig();
+    // 自动持久化: 发现/授权后写入 .ppdocs + 安装模板
+    if ((config.source === 'discover' || config.source === 'auth') && config.connection) {
+        try {
+            writePpdocsFile(config);
+            setupProjectFiles(process.cwd(), config.apiUrl);
+        }
+        catch (e) {
+            console.error('[AutoSetup] 自动配置失败:', e);
+        }
+    }
     initClient(config.apiUrl);
     const server = new McpServer({ name: `ppdocs [${config.projectId}]`, version: VERSION }, { capabilities: { tools: {} } });
     registerTools(server, config.projectId, config.user);

package/dist/tools/projects.js

@@ -21,12 +21,16 @@ export function registerProjectTools(server, projectId) {
     }));
     // 创建项目
     server.tool('kg_create_project', '创建新项目。返回项目ID和密码(密码用于MCP连接)', {
-        id: z.string().describe('项目ID(英文/数字/中文，如"my-app")'),
+        id: z.string().optional().describe('项目ID(可选，不填则自动生成随机ID)'),
         name: z.string().describe('项目名称'),
         description: z.string().optional().describe('项目简介'),
         projectPath: z.string().optional().describe('项目源码路径(本地绝对路径)'),
     }, async (args) => safeTool(async () => {
-        const result = await client().createProject(args.id, args.name, args.description, args.projectPath || process.cwd());
+        // 如果未提供 ID，自动生成随机ID
+        const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+        const randomPart = Array.from({ length: 8 }, () => chars[Math.floor(Math.random() * chars.length)]).join('');
+        const id = args.id || `p-${randomPart}`;
+        const result = await client().createProject(id, args.name, args.description, args.projectPath || process.cwd());
         return wrap(`✅ 项目创建成功\n\n- 项目ID: ${result.project.id}\n- 项目名: ${result.project.name}\n- 密码: ${result.password}\n\nMCP 连接地址: http://<服务器IP>:20001/api/${result.project.id}/${result.password}`);
     }));
     // 更新根文档 (项目介绍)

package/package.json

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