@ppdocs/mcp 3.12.0 → 3.13.1

package/README.md

@@ -64,12 +64,12 @@ npx @ppdocs/mcp init -p <项目ID> -k <密钥>
 **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
-{
-  "mcpServers": {
-    "ppdocs": {
-      "command": "npx",
-      "args": ["-y", "@ppdocs/mcp"],
-      "env": {
+{
+  "mcpServers": {
+    "ppdocs-kg": {
+      "command": "npx",
+      "args": ["-y", "@ppdocs/mcp"],
+      "env": {
         "PPDOCS_API_URL": "http://localhost:20001/api/项目ID/密码"
       }
     }
@@ -109,16 +109,13 @@ npx @ppdocs/mcp init -p <projectId> -k <key> --codex
 
 ### 核心工具
 
-| 工具 | 说明 |
-|------|------|
-| `kg_init` | 初始化项目连接与上下文 |
-| `kg_status` | 查看项目仪表盘与流程图概况 |
-| `kg_flowchart` | 统一的知识图谱入口，负责查询、更新、关系分析 |
-| `kg_workflow` | Markdown 文档工作流管理 |
+| 工具 | 说明 |
+|------|------|
+| `kg_status` | 查看项目仪表盘与流程图概况 |
+| `kg_flowchart` | 统一的知识图谱入口，负责查询、更新、关系分析 |
+| `kg_workflow` | Markdown 文档工作流管理 |
 | `kg_task` | 任务管理 |
-| `kg_files` | 项目文件读写/上传下载 |
-| `kg_discuss` | 讨论区 |
-| `kg_meeting` | 多 AI 协作会议 |
+| `kg_ref` | 外部参考资料（URL拉取、查看、删除） |
 | `code_scan` | 代码扫描 |
 | `code_smart_context` | 获取符号的智能上下文 |
 | `code_full_path` | 获取两个符号之间的全路径 |
@@ -207,6 +204,12 @@ kg_flowchart(action:"update_node", chartId:"main", nodeId:"n_storage",
 
 ## 更新日志
 
+### v3.3.0
+- 移除 6 个低使用率工具: `kg_doc`, `kg_discuss`, `kg_meeting`, `kg_files`, `kg_projects`, `kg_pitfall`
+- `kg_ref` 精简为 4 个 action: `list|get|fetch|delete`
+- 所有工具描述精简，减少 token 开销
+- 移除前端孤立组件: FloatingDiscussion, PitfallRecord, ImpactGraph
+
 ### v3.2.36
 - 统一为 `flowchart-first` MCP 接口模型
 - `kg_flowchart` 新增 `search` / `get_relations` / `find_path`

package/dist/cli.js

@@ -11,8 +11,26 @@ import { generateUser } from './config.js';
 import { PpdocsApiClient } from './storage/httpClient.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+const CANONICAL_MCP_SERVER_NAME = 'ppdocs-kg';
+const LEGACY_MCP_SERVER_PATTERNS = [
+    /^ppdocs$/,
+    /^ppdocs-mcp$/,
+    /^prodocs$/,
+    /^ppdocs-kg-.+$/,
+];
+function isLegacyPpdocsServerName(name) {
+    return name === CANONICAL_MCP_SERVER_NAME || LEGACY_MCP_SERVER_PATTERNS.some(pattern => pattern.test(name));
+}
+function stripLegacyPpdocsServers(mcpServers) {
+    return Object.fromEntries(Object.entries(mcpServers).filter(([name]) => !isLegacyPpdocsServerName(name)));
+}
+function removePpdocsServerAliases(cli) {
+    for (const name of [CANONICAL_MCP_SERVER_NAME, 'ppdocs', 'ppdocs-mcp', 'prodocs']) {
+        execSilent(`${cli} mcp remove ${name}`);
+    }
+}
 function parseArgs(args) {
-    const opts = { port: 20099, api: 'localhost', codex: false };
+    const opts = { port: 20000, api: 'localhost', codex: false };
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if (arg === '-p' || arg === '--project') {
@@ -101,7 +119,7 @@ Options:
   -p, --project  Project ID (required)
   -k, --key      API key (required)
   -u, --user     User name for logs (optional, auto-generated)
-  --port         API port (default: 20099)
+  --port         API port (default: 20000)
   --api          API host (default: localhost)
   --codex        Codex mode: generate AGENTS.md instead of .claude/
   --from <id>    Pull IDE configs from a template project
@@ -255,15 +273,12 @@ function execSilent(cmd) {
     }
     catch { /* ignore */ }
 }
-/** 自动检测 AI CLI 并注册全局 MCP，直接注入项目环境变量实现开箱即用 */
+/** 自动检测 AI CLI 并注册全局 MCP，仅注入项目根目录 hint 以便运行时定位 .ppdocs */
 function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
     const detected = [];
     const serverName = 'ppdocs-kg';
-    const envPairs = [
-        `PPDOCS_API_URL=${apiUrl}`,
-        `PPDOCS_USER=${user}`,
-        `PPDOCS_PROJECT_ROOT=${cwd}`,
-    ];
+    // 不再注入 PPDOCS_PROJECT_ROOT — 全局注册时依赖运行时 CWD 自动定位 .ppdocs
+    const envPairs = [];
     /** 用 spawnSync + args 数组注册 MCP，避免 Windows cmd.exe 引号解析问题 */
     function mcpAdd(cli, envFlag) {
         const args = ['mcp', 'add'];
@@ -273,8 +288,14 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
         // macOS/Linux: 必须注入 PATH，否则 Claude Code 启动 MCP 时可能找不到 npx/node
         // (Claude Code 进程的 PATH 通常不含 /opt/homebrew/bin 等 Homebrew/nvm 路径)
         if (process.platform !== 'win32') {
-            const macExtraPaths = '/usr/local/bin:/opt/homebrew/bin:/home/linuxbrew/.linuxbrew/bin';
-            const fullPath = `${process.env.PATH || '/usr/bin:/bin'}:${macExtraPaths}`;
+            const home = process.env.HOME || '';
+            const extraPaths = [
+                '/usr/local/bin', '/opt/homebrew/bin', '/home/linuxbrew/.linuxbrew/bin',
+                `${home}/.local/bin`, // pip/pipx (Linux)
+                `${home}/.nvm/versions/node`, // nvm hint (resolved via process.env.PATH)
+                `${home}/.fnm/aliases/default/bin`, // fnm
+            ].join(':');
+            const fullPath = `${process.env.PATH || '/usr/bin:/bin'}:${extraPaths}`;
             args.push(envFlag, `PATH=${fullPath}`);
         }
         args.push(serverName, '--', 'npx', '-y', '@ppdocs/mcp@latest');
@@ -286,12 +307,12 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
     if (commandExists('claude')) {
         detected.push('Claude');
         try {
-            execSilent(`claude mcp remove ${serverName}`);
+            removePpdocsServerAliases('claude');
             mcpAdd('claude', '-e');
         }
         catch {
             try {
-                execSilent(`claude mcp remove ${serverName}`);
+                removePpdocsServerAliases('claude');
                 mcpAdd('claude', '-e');
             }
             catch {
@@ -303,7 +324,7 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
     if (commandExists('codex')) {
         detected.push('Codex');
         try {
-            execSilent(`codex mcp remove ${serverName}`);
+            removePpdocsServerAliases('codex');
             mcpAdd('codex', '--env');
         }
         catch {
@@ -314,7 +335,7 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
     if (commandExists('opencode')) {
         detected.push('OpenCode');
         try {
-            execSilent(`opencode mcp remove ${serverName}`);
+            removePpdocsServerAliases('opencode');
             mcpAdd('opencode', '-e');
         }
         catch {
@@ -346,7 +367,7 @@ function autoRegisterMcp(cwd, apiUrl, user, skipGemini = false) {
     console.log(`✅ Registered MCP for: ${detected.join(', ')}`);
     return true;
 }
-/** 在指定路径创建或更新 mcp.json 配置，注入 PPDOCS_* 环境变量实现启动即就绪 */
+/** 在指定路径创建或更新 mcp.json 配置，仅保留 PATH + 可选项目根目录 hint */
 function createMcpConfigAt(mcpPath, apiUrl, options) {
     let mcpConfig = {};
     if (fs.existsSync(mcpPath)) {
@@ -359,25 +380,30 @@ function createMcpConfigAt(mcpPath, apiUrl, options) {
         }
     }
     const isWindows = process.platform === 'win32';
-    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 home = process.env.HOME || '';
+    const extraPaths = [
+        '/usr/local/bin', '/opt/homebrew/bin', '/home/linuxbrew/.linuxbrew/bin',
+        `${home}/.local/bin`, // pip/pipx (Linux)
+        `${home}/.nvm/versions/node`, // nvm hint
+        `${home}/.fnm/aliases/default/bin`, // fnm
+    ].join(':');
+    const actualPath = `${process.env.PATH || '/usr/bin:/bin'}:${extraPaths}`;
+    // 构建 env: 非 Windows 补 PATH + 注入项目根目录 hint（如有）
     const env = {};
     if (!isWindows)
         env.PATH = actualPath;
-    if (!options?.noEnv) {
-        env.PPDOCS_API_URL = apiUrl;
-        if (options?.user)
-            env.PPDOCS_USER = options.user;
-        if (options?.projectRoot)
-            env.PPDOCS_PROJECT_ROOT = options.projectRoot;
+    if (!options?.noEnv && options?.projectRoot) {
+        env.PPDOCS_PROJECT_ROOT = options.projectRoot;
     }
     const ppdocsServer = isWindows
         ? { command: 'cmd', args: ['/c', 'npx', '-y', '@ppdocs/mcp@latest'], ...(Object.keys(env).length > 0 && { env }) }
         : { command: 'npx', args: ['-y', '@ppdocs/mcp@latest'], env };
+    const existingServers = (mcpConfig.mcpServers && typeof mcpConfig.mcpServers === 'object'
+        ? mcpConfig.mcpServers
+        : {});
     mcpConfig.mcpServers = {
-        ...(mcpConfig.mcpServers || {}),
-        "ppdocs-kg": ppdocsServer,
+        ...stripLegacyPpdocsServers(existingServers),
+        [CANONICAL_MCP_SERVER_NAME]: ppdocsServer,
     };
     // 确保父目录存在
     const parentDir = path.dirname(mcpPath);
@@ -411,7 +437,9 @@ function copyDirRecursive(src, dest) {
 function generateHooksConfig(cwd) {
     // 使用绝对路径，避免 CWD 不一致导致找不到脚本
     const hookPath = path.join(cwd, '.claude', 'hooks', 'hook.py').replace(/\\/g, '/');
-    const command = `python ${hookPath}`;
+    // Linux/macOS 优先使用 python3 (Ubuntu 20.04+ 默认无 python 命令)
+    const pythonCmd = process.platform === 'win32' ? 'python' : 'python3';
+    const command = `${pythonCmd} ${hookPath}`;
     return {
         hooks: {
             UserPromptSubmit: [
@@ -425,29 +453,16 @@ function generateHooksConfig(cwd) {
 /** 生成 MCP 权限配置 (允许全部 ppdocs-kg 工具) */
 function generateMcpPermissions() {
     const mcpMethods = [
-        // 初始化 + 导航
-        'kg_init',
         'kg_status',
-        // 知识管理
-        'kg_projects',
         'kg_workflow',
-        // 工作流
         'kg_task',
-        'kg_files',
-        'kg_discuss',
         'kg_ref',
-        // 流程图
         'kg_flowchart',
-        // 文档查询
-        'kg_doc',
-        // 协作
-        'kg_meeting',
-        // 代码分析
         'code_scan',
         'code_smart_context',
         'code_full_path',
     ];
-    return mcpMethods.map(m => `mcp__ppdocs-kg__${m}`);
+    return mcpMethods.map(m => `mcp__${CANONICAL_MCP_SERVER_NAME}__${m}`);
 }
 /** 安装 Claude Code 模板 */
 function installClaudeTemplates(cwd) {

package/dist/config.d.ts

@@ -1,16 +1,36 @@
 /**
  * ppdocs MCP Config
- * 读取配置: 环境变量 > .ppdocs 文件 > 提示去 Agent WebUI 绑定
+ * 读取配置: 项目根目录 .ppdocs 是唯一正式绑定源
  */
 export interface PpdocsConfig {
     apiUrl: string;
     projectId: string;
     user: string;
     agentId: string;
-    source: 'env' | 'file';
+    source: 'file';
+    configPath: string;
+    projectRoot: string;
+    searchRoot: string;
+    warnings: string[];
 }
 export declare const PPDOCS_CONFIG_FILE = ".ppdocs";
+declare const REQUIRED_BINDING_FIELDS: readonly ["api", "projectId", "key"];
+type RequiredBindingField = typeof REQUIRED_BINDING_FIELDS[number];
+export interface PpdocsBindingDiagnostic {
+    reason: 'not_found' | 'invalid_json' | 'missing_fields';
+    searchRoot: string;
+    hintedProjectRoot?: string;
+    configPath?: string;
+    missingFields?: RequiredBindingField[];
+    warnings: string[];
+}
+export declare class PpdocsBindingError extends Error {
+    diagnostic: PpdocsBindingDiagnostic;
+    constructor(diagnostic: PpdocsBindingDiagnostic);
+}
 /** 生成随机用户名 */
 export declare function generateUser(): string;
 export declare function generateAgentId(): string;
-export declare function loadConfig(): Promise<PpdocsConfig | null>;
+export declare function findPpdocsFile(startDir?: string): string | null;
+export declare function loadConfig(startDir?: string): Promise<PpdocsConfig>;
+export {};

package/dist/config.js

@@ -1,10 +1,19 @@
 /**
  * ppdocs MCP Config
- * 读取配置: 环境变量 > .ppdocs 文件 > 提示去 Agent WebUI 绑定
+ * 读取配置: 项目根目录 .ppdocs 是唯一正式绑定源
  */
 import * as fs from 'fs';
 import * as path from 'path';
 export const PPDOCS_CONFIG_FILE = '.ppdocs';
+const REQUIRED_BINDING_FIELDS = ['api', 'projectId', 'key'];
+export class PpdocsBindingError extends Error {
+    diagnostic;
+    constructor(diagnostic) {
+        super(createBindingErrorMessage(diagnostic));
+        this.name = 'PpdocsBindingError';
+        this.diagnostic = diagnostic;
+    }
+}
 /** 生成随机用户名 */
 export function generateUser() {
     const chars = 'abcdefghjkmnpqrstuvwxyz23456789';
@@ -25,20 +34,44 @@ export function generateAgentId() {
     return _cachedAgentId;
 }
 // ============ 配置读取 ============
-function readEnvConfig() {
-    const apiUrl = process.env.PPDOCS_API_URL;
-    if (!apiUrl)
-        return null;
-    const match = apiUrl.match(/\/api\/([^/]+)\/[^/]+\/?$/);
+function buildWarnings() {
+    const warnings = [];
+    if (process.env.PPDOCS_API_URL) {
+        warnings.push('PPDOCS_API_URL is ignored at runtime; .ppdocs is the canonical binding source.');
+    }
+    return warnings;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function normalizeApiBase(api) {
+    return api.replace(/\/+$/, '');
+}
+function createBindingErrorMessage(diagnostic) {
+    switch (diagnostic.reason) {
+        case 'not_found':
+            return `No ${PPDOCS_CONFIG_FILE} binding found from ${diagnostic.searchRoot}`;
+        case 'invalid_json':
+            return `${PPDOCS_CONFIG_FILE} is not valid JSON at ${diagnostic.configPath}`;
+        case 'missing_fields':
+            return `${PPDOCS_CONFIG_FILE} is missing required fields: ${(diagnostic.missingFields || []).join(', ')}`;
+    }
+}
+function resolveSearchRoot(startDir = process.cwd()) {
+    const hintedProjectRoot = process.env.PPDOCS_PROJECT_ROOT?.trim();
+    const candidate = path.resolve(hintedProjectRoot || startDir);
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+        return {
+            searchRoot: path.dirname(candidate),
+            hintedProjectRoot: hintedProjectRoot ? candidate : undefined,
+        };
+    }
     return {
-        apiUrl,
-        projectId: match?.[1] || 'unknown',
-        user: process.env.PPDOCS_USER || generateUser(),
-        agentId: process.env.PPDOCS_AGENT_ID || generateAgentId(),
-        source: 'env',
+        searchRoot: candidate,
+        hintedProjectRoot: hintedProjectRoot ? candidate : undefined,
     };
 }
-function findPpdocsFile(startDir = process.cwd()) {
+export function findPpdocsFile(startDir = process.cwd()) {
     let currentDir = path.resolve(startDir);
     while (true) {
         const configPath = path.join(currentDir, PPDOCS_CONFIG_FILE);
@@ -52,33 +85,58 @@ function findPpdocsFile(startDir = process.cwd()) {
         currentDir = parentDir;
     }
 }
-function readPpdocsFile() {
-    const hintedRoot = process.env.PPDOCS_PROJECT_ROOT;
-    const configPath = hintedRoot
-        ? path.join(path.resolve(hintedRoot), PPDOCS_CONFIG_FILE)
-        : findPpdocsFile();
-    if (!configPath || !fs.existsSync(configPath))
-        return null;
+function parsePpdocsFile(configPath, searchRoot, warnings) {
     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 || generateUser(), agentId: c.agentId || process.env.PPDOCS_AGENT_ID || generateAgentId(), source: 'file' };
+        const raw = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        const missingFields = REQUIRED_BINDING_FIELDS.filter((field) => !isNonEmptyString(raw[field]));
+        if (missingFields.length > 0) {
+            throw new PpdocsBindingError({
+                reason: 'missing_fields',
+                searchRoot,
+                configPath,
+                missingFields,
+                warnings,
+            });
+        }
+        const projectRoot = path.dirname(configPath);
+        return {
+            apiUrl: `${normalizeApiBase(raw.api)}/api/${raw.projectId}/${raw.key}`,
+            projectId: raw.projectId,
+            user: isNonEmptyString(raw.user) ? raw.user : generateUser(),
+            agentId: isNonEmptyString(raw.agentId)
+                ? raw.agentId
+                : (process.env.PPDOCS_AGENT_ID || generateAgentId()),
+            source: 'file',
+            configPath,
+            projectRoot,
+            searchRoot,
+            warnings,
+        };
     }
-    catch {
-        return null;
+    catch (error) {
+        if (error instanceof PpdocsBindingError) {
+            throw error;
+        }
+        throw new PpdocsBindingError({
+            reason: 'invalid_json',
+            searchRoot,
+            configPath,
+            warnings,
+        });
     }
 }
 // ============ 入口 ============
-export async function loadConfig() {
-    // 1. 环境变量
-    const envConfig = readEnvConfig();
-    if (envConfig)
-        return envConfig;
-    // 2. .ppdocs 文件 (由 init 命令生成)
-    const fileConfig = readPpdocsFile();
-    if (fileConfig)
-        return fileConfig;
-    // 无配置 → 返回 null，由调用方决定行为 (MCP 模式下等待 kg_init)
-    return null;
+export async function loadConfig(startDir = process.cwd()) {
+    const warnings = buildWarnings();
+    const { searchRoot, hintedProjectRoot } = resolveSearchRoot(startDir);
+    const configPath = findPpdocsFile(searchRoot);
+    if (!configPath) {
+        throw new PpdocsBindingError({
+            reason: 'not_found',
+            searchRoot,
+            hintedProjectRoot,
+            warnings,
+        });
+    }
+    return parsePpdocsFile(configPath, searchRoot, warnings);
 }

package/dist/index.d.ts

@@ -4,6 +4,6 @@
  *
  * 使用方式:
  * 1. CLI 初始化: npx @ppdocs/mcp init -p <projectId> -k <key>
- * 2. MCP 服务: 自动读取 .ppdocs 配置或 PPDOCS_API_URL 环境变量
+ * 2. MCP 服务: 启动时自动读取项目根目录 .ppdocs
  */
 export {};

package/dist/index.js

@@ -4,7 +4,7 @@
  *
  * 使用方式:
  * 1. CLI 初始化: npx @ppdocs/mcp init -p <projectId> -k <key>
- * 2. MCP 服务: 自动读取 .ppdocs 配置或 PPDOCS_API_URL 环境变量
+ * 2. MCP 服务: 启动时自动读取项目根目录 .ppdocs
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -14,7 +14,7 @@ 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, generateAgentId } from './config.js';
+import { loadConfig, PpdocsBindingError } 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'));
@@ -64,6 +64,32 @@ async function checkConnectivity(apiUrl) {
         clearTimeout(timer);
     }
 }
+function logBindingSuccess(config) {
+    console.error(`ppdocs MCP v${VERSION} | project: ${config.projectId} | user: ${config.user} | source: ${config.source}`);
+    console.error(`[binding] search root: ${config.searchRoot}`);
+    console.error(`[binding] config file: ${config.configPath}`);
+    console.error(`[binding] project root: ${config.projectRoot}`);
+    for (const warning of config.warnings) {
+        console.error(`[binding] warning: ${warning}`);
+    }
+}
+function logBindingFailure(error) {
+    console.error(`ppdocs MCP v${VERSION} | ❌ startup aborted: ${error.message}`);
+    console.error(`[binding] search root: ${error.diagnostic.searchRoot}`);
+    if (error.diagnostic.hintedProjectRoot) {
+        console.error(`[binding] PPDOCS_PROJECT_ROOT hint: ${error.diagnostic.hintedProjectRoot}`);
+    }
+    if (error.diagnostic.configPath) {
+        console.error(`[binding] config file: ${error.diagnostic.configPath}`);
+    }
+    if (error.diagnostic.missingFields?.length) {
+        console.error(`[binding] missing fields: ${error.diagnostic.missingFields.join(', ')}`);
+    }
+    for (const warning of error.diagnostic.warnings) {
+        console.error(`[binding] warning: ${warning}`);
+    }
+    console.error(`[binding] fix: create a project-root .ppdocs file before starting the MCP server.`);
+}
 // 检查是否为 CLI 命令
 const args = process.argv.slice(2);
 if (args.length > 0) {
@@ -73,24 +99,26 @@ if (args.length > 0) {
 }
 // 运行 MCP 服务
 async function main() {
-    const config = await loadConfig();
-    // 有配置 → 自动初始化 (环境变量 / .ppdocs)
-    if (config) {
-        initClient(config.apiUrl);
-        console.error(`ppdocs MCP v${VERSION} | project: ${config.projectId} | user: ${config.user} | source: ${config.source}`);
-        // 启动时连通性检查 (非阻塞, 3秒超时)
-        checkConnectivity(config.apiUrl).catch(() => { });
+    let config;
+    try {
+        config = await loadConfig();
     }
-    else {
-        console.error(`ppdocs MCP v${VERSION} | ⏳ 等待 kg_init 初始化项目上下文...`);
+    catch (error) {
+        if (error instanceof PpdocsBindingError) {
+            logBindingFailure(error);
+            process.exit(1);
+        }
+        throw error;
     }
-    const projectId = config?.projectId || 'pending';
-    const user = config?.user || 'agent';
-    const agentId = config?.agentId || process.env.PPDOCS_AGENT_ID || generateAgentId();
+    initClient(config.apiUrl);
+    logBindingSuccess(config);
+    // 启动时连通性检查 (非阻塞, 3秒超时)
+    checkConnectivity(config.apiUrl).catch(() => { });
+    const projectId = config.projectId;
+    const user = config.user;
+    const agentId = config.agentId;
     const server = new McpServer({ name: `ppdocs [${projectId}]`, version: VERSION }, { capabilities: { tools: {} } });
-    registerTools(server, projectId, user, agentId, (newProjectId, newApiUrl) => {
-        console.error(`[kg_init] 项目已切换: ${newProjectId}`);
-    });
+    registerTools(server, projectId, user, agentId);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     const shutdown = () => { process.exit(0); };

package/dist/retainedCoreMatrix.d.ts

@@ -0,0 +1,19 @@
+export declare const RETAINED_CORE_MATRIX: {
+    readonly retainedTools: {
+        readonly kg_status: true;
+        readonly kg_flowchart: readonly ["list", "get", "search", "get_relations", "find_path", "get_node", "update_node", "delete_node", "batch_add", "bind", "unbind", "orphans", "health", "create_chart", "delete_chart"];
+        readonly kg_workflow: readonly ["list", "get", "save", "delete"];
+        readonly kg_task: readonly ["create", "get", "update", "archive", "delete"];
+        readonly kg_ref: readonly ["list", "get", "fetch", "delete"];
+        readonly code_tools: readonly ["code_scan", "code_smart_context", "code_full_path"];
+    };
+    readonly removed: {
+        readonly tools: readonly ["kg_init", "kg_discuss", "kg_meeting", "kg_files", "kg_projects"];
+        readonly referenceActions: readonly ["save", "read_file", "import_file", "reimport", "refetch-copyin", "copy-in"];
+        readonly clientSurfaces: readonly ["pitfalls"];
+    };
+};
+export type RetainedToolName = keyof typeof RETAINED_CORE_MATRIX.retainedTools;
+export declare function getRetainedActions(tool: Exclude<RetainedToolName, 'kg_status'>): readonly string[];
+export declare function isRemovedTool(tool: string): boolean;
+export declare function isRemovedReferenceAction(action: string): boolean;

package/dist/retainedCoreMatrix.js

@@ -0,0 +1,40 @@
+export const RETAINED_CORE_MATRIX = {
+    retainedTools: {
+        kg_status: true,
+        kg_flowchart: [
+            'list',
+            'get',
+            'search',
+            'get_relations',
+            'find_path',
+            'get_node',
+            'update_node',
+            'delete_node',
+            'batch_add',
+            'bind',
+            'unbind',
+            'orphans',
+            'health',
+            'create_chart',
+            'delete_chart',
+        ],
+        kg_workflow: ['list', 'get', 'save', 'delete'],
+        kg_task: ['create', 'get', 'update', 'archive', 'delete'],
+        kg_ref: ['list', 'get', 'fetch', 'delete'],
+        code_tools: ['code_scan', 'code_smart_context', 'code_full_path'],
+    },
+    removed: {
+        tools: ['kg_init', 'kg_discuss', 'kg_meeting', 'kg_files', 'kg_projects'],
+        referenceActions: ['save', 'read_file', 'import_file', 'reimport', 'refetch-copyin', 'copy-in'],
+        clientSurfaces: ['pitfalls'],
+    },
+};
+export function getRetainedActions(tool) {
+    return RETAINED_CORE_MATRIX.retainedTools[tool];
+}
+export function isRemovedTool(tool) {
+    return RETAINED_CORE_MATRIX.removed.tools.includes(tool);
+}
+export function isRemovedReferenceAction(action) {
+    return RETAINED_CORE_MATRIX.removed.referenceActions.includes(action);
+}