Flutter-Skill MCP 安装与配置踩坑深度复盘指南

#!/usr/bin/env node
/**
 * flutter_skill MCP 协议透明补丁代理
 * 
 * 核心特性与加固：
 * 1. 【实例环境隔离】：为每个 MCP 客户端实例创建独立运行沙箱（独立隔离 HOME 目录），
 *    彻底解决原生 flutter_skill 的 ~/.flutter_skill.lock 单例锁冲突，
 *    允许多个 Language Server（全局实例 + Workspace 实例）并发拉起而不发生抢锁崩溃。
 * 2. 【严禁跨进程滥杀】：移除所有全局 pkill 命令，每个 wrapper 实例严格仅管理和销毁自身的 child 进程。
 * 3. 【协议兼容兜底】：
 *    - 拦截 resources/list, resources/templates/list, prompts/list, ping, roots/list, server/discover 等
 *    - 剥离 capabilities 中的 resources 声明，避免客户端拉取无效资源
 *    - 未知请求自动返回 JSON-RPC 2.0 Method not found 错误，防止 IDE 握手阶段挂起
 * 4. 【生命周期守卫与优雅回收】：
 *    - 监听 process exit, SIGINT, SIGTERM, SIGHUP, stdin close 等事件
 *    - 进程销毁时同步终止子进程并递归清理专属沙箱目录
 * 5. 【日志隔离】：子进程 stderr 与调试信息写入 /tmp/flutter_skill_mcp.log，保持 stdio 管道纯净
 */

const { spawn } = require("child_process");
const readline = require("readline");
const fs = require("fs");
const path = require("path");
const os = require("os");

const realHome = os.homedir();
const logFile = "/tmp/flutter_skill_mcp.log";

function debugLog(msg) {
  try {
    fs.appendFileSync(logFile, `[${new Date().toISOString()}][PID ${process.pid}] ${msg}\n`);
  } catch (e) {}
}

// 捕获未处理异常，防止无声崩溃
process.on("uncaughtException", (err) => {
  debugLog(`Uncaught exception: ${err ? err.stack || err : ""}`);
});
process.on("unhandledRejection", (reason) => {
  debugLog(`Unhandled rejection: ${reason}`);
});

// 清理已消亡进程遗留的全局锁文件（如有）
try {
  const staleLock = path.join(realHome, ".flutter_skill.lock");
  if (fs.existsSync(staleLock)) {
    const content = fs.readFileSync(staleLock, "utf8");
    const oldPid = parseInt(content.split("\n")[0].trim(), 10);
    let isAlive = false;
    if (oldPid) {
      try {
        process.kill(oldPid, 0);
        isAlive = true;
      } catch (e) {
        isAlive = false;
      }
    }
    if (!isAlive) {
      fs.unlinkSync(staleLock);
      debugLog(`Cleaned stale ~/.flutter_skill.lock for dead PID ${oldPid}`);
    }
  }
} catch (e) {}

// 1. 创建属于当前实例的沙箱 HOME 目录，隔离 .flutter_skill.lock
const instanceHome = path.join(os.tmpdir(), `flutter_skill_mcp_${process.pid}`);
try {
  if (!fs.existsSync(instanceHome)) {
    fs.mkdirSync(instanceHome, { recursive: true });
  }
  // 软链接用户主目录下的重要配置，保证 flutter_skill 工具能力完备
  const dirsToLink = [".pub-cache", ".flutter-skill", ".fvm", ".android", "Library", "allRepos"];
  for (const dir of dirsToLink) {
    const target = path.join(realHome, dir);
    const link = path.join(instanceHome, dir);
    if (fs.existsSync(target) && !fs.existsSync(link)) {
      try {
        fs.symlinkSync(target, link);
      } catch (e) {}
    }
  }
  debugLog(`Initialized sandbox HOME at ${instanceHome}`);
} catch (e) {
  debugLog(`Sandbox init error: ${e.message}`);
}

const dartBin = "/Users/mingo/fvm/versions/3.38.10/bin/cache/dart-sdk/bin/dart";
const snapshot = "/Users/mingo/.pub-cache/global_packages/flutter_skill/bin/flutter_skill.dart-3.10.9.snapshot";

// 2. 拉起原生 Dart MCP 进程
const child = spawn(dartBin, [snapshot, "server"], {
  stdio: ["pipe", "pipe", "pipe"],
  env: {
    ...process.env,
    HOME: instanceHome,
    USERPROFILE: instanceHome,
    PATH: "/Users/mingo/fvm/versions/3.38.10/bin/cache/dart-sdk/bin:/Users/mingo/fvm/versions/3.38.10/bin:/Users/mingo/Library/Android/sdk/platform-tools:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:" + (process.env.PATH || "")
  }
});

debugLog(`Spawned child process PID ${child.pid}`);

let isCleanedUp = false;
function cleanup() {
  if (isCleanedUp) return;
  isCleanedUp = true;
  debugLog("Cleaning up child process and sandbox...");
  try {
    if (child && !child.killed) {
      child.kill("SIGTERM");
      setTimeout(() => {
        try { if (!child.killed) child.kill("SIGKILL"); } catch (e) {}
      }, 500);
    }
  } catch (e) {}

  try {
    if (fs.existsSync(instanceHome)) {
      fs.rmSync(instanceHome, { recursive: true, force: true });
    }
  } catch (e) {}
}

process.on("exit", cleanup);
process.on("SIGINT", () => { cleanup(); process.exit(0); });
process.on("SIGTERM", () => { cleanup(); process.exit(0); });
process.on("SIGHUP", () => { cleanup(); process.exit(0); });
process.stdin.on("end", () => { cleanup(); process.exit(0); });
process.stdin.on("close", () => { cleanup(); process.exit(0); });

child.on("error", (err) => {
  debugLog(`Child process error: ${err.message}`);
  cleanup();
  process.exit(1);
});

child.on("exit", (code, signal) => {
  debugLog(`Child exited with code ${code}, signal ${signal}`);
  cleanup();
  process.exit(code || 0);
});

child.stderr.on("data", (chunk) => {
  debugLog(`[child stderr] ${chunk.toString().trim()}`);
});

// 支持的原生方法集合
const SUPPORTED_NATIVE_METHODS = new Set([
  "initialize",
  "notifications/initialized",
  "tools/list",
  "tools/call"
]);

// 处理从 IDE 客户端发来的请求
const rlStdin = readline.createInterface({ input: process.stdin, terminal: false });

rlStdin.on("line", (line) => {
  const trimmed = line.trim();
  if (!trimmed) return;
  try {
    const req = JSON.parse(trimmed);
    const method = req.method;
    const id = req.id;

    // 1. 特殊已知方法主动应答
    if (method === "server/discover") {
      const resp = { jsonrpc: "2.0", id: id, error: { code: -32601, message: "Method not found" } };
      process.stdout.write(JSON.stringify(resp) + "\n");
      return;
    }

    if (method === "resources/list") {
      const resp = { jsonrpc: "2.0", id: id, result: { resources: [] } };
      process.stdout.write(JSON.stringify(resp) + "\n");
      return;
    }

    if (method === "resources/templates/list") {
      const resp = { jsonrpc: "2.0", id: id, result: { resourceTemplates: [] } };
      process.stdout.write(JSON.stringify(resp) + "\n");
      return;
    }

    if (method === "prompts/list") {
      const resp = { jsonrpc: "2.0", id: id, result: { prompts: [] } };
      process.stdout.write(JSON.stringify(resp) + "\n");
      return;
    }

    if (method === "ping") {
      const resp = { jsonrpc: "2.0", id: id, result: {} };
      process.stdout.write(JSON.stringify(resp) + "\n");
      return;
    }

    if (method === "roots/list") {
      const resp = { jsonrpc: "2.0", id: id, result: { roots: [] } };
      process.stdout.write(JSON.stringify(resp) + "\n");
      return;
    }

    // 2. 如果是底层明确支持的方法，透传给底层 flutter_skill
    if (SUPPORTED_NATIVE_METHODS.has(method)) {
      child.stdin.write(line + "\n");
      return;
    }

    // 3. 对其他带有 id 的未知方法，主动返回标准 JSON-RPC 2.0 Method not found
    if (id !== undefined && id !== null) {
      const resp = { jsonrpc: "2.0", id: id, error: { code: -32601, message: `Method not found: ${method}` } };
      process.stdout.write(JSON.stringify(resp) + "\n");
      return;
    }

    // 无 id 的通知类消息，安全透传
    child.stdin.write(line + "\n");
  } catch (e) {
    child.stdin.write(line + "\n");
  }
});

rlStdin.on("close", () => {
  cleanup();
  process.exit(0);
});

// 处理底层 flutter_skill 发出的响应
const rlStdout = readline.createInterface({ input: child.stdout, terminal: false });

rlStdout.on("line", (line) => {
  const trimmed = line.trim();
  if (!trimmed) return;
  try {
    const msg = JSON.parse(trimmed);
    // 移除 initialize 中的 resources 声明，避免 IDE 去请求 resources/list
    if (msg.result && msg.result.capabilities && msg.result.capabilities.resources) {
      delete msg.result.capabilities.resources;
      process.stdout.write(JSON.stringify(msg) + "\n");
      return;
    }
    process.stdout.write(line + "\n");
  } catch (e) {
    process.stdout.write(line + "\n");
  }
});