@caixm/api-check-mcp 1.0.0

package/README.md

@@ -0,0 +1,146 @@
+# api-check-mcp
+
+一个用于扫描前端项目中接口实际使用情况的 MCP Server。
+
+它会读取项目根目录下的 `api-exclude.md`，分析接口是否仍被业务代码使用，并输出一份扫描结果文件。
+
+## 功能
+
+- 扫描指定项目中的接口使用情况
+- 支持扫描当前代码
+- 支持根据 commit 列表逐版本扫描
+- 输出 Markdown 格式结果，方便查看和整理
+
+## 安装
+
+```bash
+npm install -g api-check-mcp
+```
+
+或者直接通过 `npx` 使用：
+
+```bash
+npx api-check-mcp
+```
+
+## MCP 配置示例
+
+在 MCP 客户端配置中添加：
+
+```json
+{
+  "mcpServers": {
+    "api-check": {
+      "command": "npx",
+      "args": ["-y", "api-check-mcp"]
+    }
+  }
+}
+```
+
+## 可用工具
+
+### `check_api_usage`
+
+扫描指定项目中的接口使用情况。
+
+参数：
+
+- `rootDir`: 需要扫描的项目根目录
+
+示例：
+
+```json
+{
+  "rootDir": "/Users/yourname/project"
+}
+```
+
+## 项目中需要提供的文件
+
+在被扫描项目根目录下创建 `api-exclude.md`。
+
+### 仅扫描当前代码
+
+````md
+# 接口排查
+
+## 条件
+
+需要排查的接口列表
+
+```
+expense/report
+expense/page
+secure/expense/page
+```
+````
+
+### 按版本扫描
+
+````md
+# 接口排查
+
+## 条件
+
+commit列表:
+
+```json
+[
+  { "version": "1.22.1", "build": 5221 },
+  { "version": "1.22.2", "build": 5224 }
+]
+```
+
+需要排查的接口列表
+
+```
+expense/report
+expense/page
+secure/expense/page
+```
+````
+
+## 输出结果
+
+扫描完成后，会在项目根目录生成一个结果文件，例如：
+
+```bash
+api-1700000000000.md
+```
+
+内容示例：
+
+```md
+| 版本 | 接口 | 是否使用 | 引用位置 | 备注 |
+|------|------|----------|----------|------|
+| 1.22.1 | secure/expense/page | ✅ | src/screens/finance/expense/index.tsx:106 | - |
+| 1.22.1 | expense/page | ❌ | - | - |
+```
+
+如果没有版本列表，则输出格式为：
+
+```md
+| 接口 | 是否使用 | 引用位置 | 备注 |
+|------|----------|----------|------|
+| secure/expense/info | ❌ | src/services/expense.ts:9 | 未发现页面引用该方法 |
+```
+
+## 使用说明
+
+扫描逻辑大致如下：
+
+- 优先扫描 `src/services/` 下的 service 文件
+- 优先识别 `src/common/network/` 等约定目录
+- 通过 import 关系和字符串匹配查找接口引用
+- 如果接口仅存在于 service 方法中，但没有业务调用，会标记为未实际使用
+
+## 注意事项
+
+- 被扫描项目通常需要包含 `src` 目录
+- 如果配置了 commit 列表，项目必须是 Git 仓库
+- 扫描结果依赖项目中的接口写法和目录约定，特殊封装场景可能需要人工复核
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@caixm/api-check-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for scanning API usage in frontend projects",
+  "type": "module",
+  "bin": {
+    "api-check-mcp": "server.js"
+  },
+  "files": [
+    "server.js"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "api-check"
+  ],
+  "license": "MIT",
+  "author": "jinkai123",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/server.js

@@ -0,0 +1,785 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+const JSONRPC_VERSION = "2.0";
+const PROTOCOL_VERSION = "2024-11-05";
+const CODE_EXTENSIONS = new Set([".js", ".ts", ".jsx", ".tsx"]);
+
+function log(...args) {
+  process.stderr.write(`[${new Date().toISOString()}] ${args.join(" ")}\n`);
+}
+
+function send(message) {
+  const body = Buffer.from(JSON.stringify(message), "utf-8");
+  process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
+  process.stdout.write(body);
+}
+
+function sendResult(id, result) {
+  if (id === undefined) return;
+  send({ jsonrpc: JSONRPC_VERSION, id, result });
+}
+
+function sendError(id, code, message, data) {
+  if (id === undefined) return;
+  const error = { code, message };
+  if (data !== undefined) error.data = data;
+  send({ jsonrpc: JSONRPC_VERSION, id, error });
+}
+
+function isGitRepo(root) {
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: root, stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getCommitByBuild(root, build) {
+  const list = execFileSync("git", ["rev-list", "--reverse", "HEAD"], { cwd: root, stdio: "pipe" })
+    .toString()
+    .trim()
+    .split("\n")
+    .filter(Boolean);
+
+  if (build < 1 || build > list.length) {
+    throw new Error(`build ${build} 超出 commit 范围`);
+  }
+  return list[build - 1];
+}
+
+function createTempWorktree(root, hash) {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "api-check-"));
+  execFileSync("git", ["worktree", "add", "--detach", tempRoot, hash], { cwd: root, stdio: "pipe" });
+  return tempRoot;
+}
+
+function removeTempWorktree(root, worktreePath) {
+  try {
+    execFileSync("git", ["worktree", "remove", "--force", worktreePath], { cwd: root, stdio: "pipe" });
+  } catch {
+    // Ignore cleanup errors so the tool can still return the scan result.
+  }
+
+  try {
+    fs.rmSync(worktreePath, { recursive: true, force: true });
+  } catch {
+    // Ignore cleanup errors for temporary directories.
+  }
+}
+
+function walk(dir) {
+  let results = [];
+  const list = fs.readdirSync(dir);
+
+  for (const file of list) {
+    const full = path.join(dir, file);
+    if (full.includes("node_modules")) continue;
+
+    const stat = fs.statSync(full);
+    if (stat.isDirectory()) {
+      results = results.concat(walk(full));
+      continue;
+    }
+
+    if (CODE_EXTENSIONS.has(path.extname(full))) {
+      results.push(full);
+    }
+  }
+
+  return results;
+}
+
+function normalizePath(filePath) {
+  return filePath.replace(/\\/g, "/");
+}
+
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function escapeTableCell(text) {
+  return text.replace(/\|/g, "\\|");
+}
+
+function stripCommentsPreserveStrings(content) {
+  let result = "";
+  let state = "code";
+
+  // 用简单状态机剥离注释，但保留字符串内容与换行位置，
+  // 这样后续做正则搜索时既能避开注释误判，又不会破坏行号映射。
+  for (let i = 0; i < content.length; i += 1) {
+    const char = content[i];
+    const next = content[i + 1];
+
+    if (state === "lineComment") {
+      if (char === "\n") {
+        state = "code";
+        result += "\n";
+      } else {
+        result += " ";
+      }
+      continue;
+    }
+
+    if (state === "blockComment") {
+      if (char === "*" && next === "/") {
+        result += "  ";
+        i += 1;
+        state = "code";
+      } else {
+        result += char === "\n" ? "\n" : " ";
+      }
+      continue;
+    }
+
+    if (state === "singleQuote") {
+      result += char;
+      if (char === "\\") {
+        result += content[i + 1] || "";
+        i += 1;
+      } else if (char === "'") {
+        state = "code";
+      }
+      continue;
+    }
+
+    if (state === "doubleQuote") {
+      result += char;
+      if (char === "\\") {
+        result += content[i + 1] || "";
+        i += 1;
+      } else if (char === "\"") {
+        state = "code";
+      }
+      continue;
+    }
+
+    if (state === "template") {
+      result += char;
+      if (char === "\\") {
+        result += content[i + 1] || "";
+        i += 1;
+      } else if (char === "`") {
+        state = "code";
+      }
+      continue;
+    }
+
+    if (char === "/" && next === "/") {
+      result += "  ";
+      i += 1;
+      state = "lineComment";
+      continue;
+    }
+
+    if (char === "/" && next === "*") {
+      result += "  ";
+      i += 1;
+      state = "blockComment";
+      continue;
+    }
+
+    if (char === "'") {
+      state = "singleQuote";
+      result += char;
+      continue;
+    }
+
+    if (char === "\"") {
+      state = "doubleQuote";
+      result += char;
+      continue;
+    }
+
+    if (char === "`") {
+      state = "template";
+      result += char;
+      continue;
+    }
+
+    result += char;
+  }
+
+  return result;
+}
+
+function getRelativePath(root, filePath) {
+  return normalizePath(path.relative(root, filePath));
+}
+
+function isPreferredServiceFile(root, filePath) {
+  return getRelativePath(root, filePath).startsWith("src/services/");
+}
+
+function isPreferredCommonNetworkFile(root, filePath) {
+  return getRelativePath(root, filePath).startsWith("src/common/network/");
+}
+
+function getLineMatches(content, sanitizedContent, api) {
+  const rawLines = content.split(/\r?\n/);
+  const cleanLines = sanitizedContent.split(/\r?\n/);
+  const pattern = new RegExp(`(["'\`])${escapeRegExp(api)}(?=["'\`?])`);
+  const matches = [];
+
+  cleanLines.forEach((line, index) => {
+    if (!pattern.test(line)) return;
+    matches.push({
+      lineNumber: index + 1,
+      lineText: rawLines[index].trim()
+    });
+  });
+
+  return matches;
+}
+
+function formatRef(relativePath, lineNumber) {
+  return escapeTableCell(`${relativePath}:${lineNumber}`);
+}
+
+function findNearestExportName(lines, lineNumber) {
+  for (let index = lineNumber - 1; index >= 0; index -= 1) {
+    const line = lines[index];
+    let match = line.match(/^\s*export\s+const\s+([A-Za-z0-9_$]+)/);
+    if (match) return { name: match[1], lineNumber: index + 1 };
+
+    match = line.match(/^\s*export\s+async\s+function\s+([A-Za-z0-9_$]+)/);
+    if (match) return { name: match[1], lineNumber: index + 1 };
+
+    match = line.match(/^\s*export\s+function\s+([A-Za-z0-9_$]+)/);
+    if (match) return { name: match[1], lineNumber: index + 1 };
+  }
+
+  return null;
+}
+
+function resolveImportPath(root, fromFile, importSource) {
+  let candidateBase = null;
+
+  // 这里只处理项目内可静态解析的导入。
+  // 第三方包导入直接跳过，因为它们不可能指向业务 service 文件。
+  if (importSource.startsWith("@src/")) {
+    candidateBase = path.join(root, "src", importSource.slice("@src/".length));
+  } else if (importSource.startsWith("@/")) {
+    candidateBase = path.join(root, "src", importSource.slice(2));
+  } else if (importSource.startsWith(".")) {
+    candidateBase = path.resolve(path.dirname(fromFile), importSource);
+  } else {
+    return null;
+  }
+
+  const candidates = [
+    candidateBase,
+    `${candidateBase}.ts`,
+    `${candidateBase}.tsx`,
+    `${candidateBase}.js`,
+    `${candidateBase}.jsx`,
+    path.join(candidateBase, "index.ts"),
+    path.join(candidateBase, "index.tsx"),
+    path.join(candidateBase, "index.js"),
+    path.join(candidateBase, "index.jsx")
+  ];
+
+  return candidates.find(candidate => fs.existsSync(candidate)) || null;
+}
+
+function parseImportBindings(specifier) {
+  const info = {
+    defaultImport: null,
+    namespaceImport: null,
+    namedImports: new Map()
+  };
+
+  const trimmed = specifier.trim();
+  const braceStart = trimmed.indexOf("{");
+  const braceEnd = trimmed.lastIndexOf("}");
+
+  if (trimmed.startsWith("* as ")) {
+    info.namespaceImport = trimmed.slice(5).trim();
+    return info;
+  }
+
+  if (braceStart >= 0 && braceEnd >= braceStart) {
+    const beforeBrace = trimmed.slice(0, braceStart).replace(/,$/, "").trim();
+    if (beforeBrace) {
+      info.defaultImport = beforeBrace.replace(/^type\s+/, "").trim();
+    }
+
+    const namedBlock = trimmed.slice(braceStart + 1, braceEnd);
+    namedBlock
+      .split(",")
+      .map(part => part.trim())
+      .filter(Boolean)
+      .forEach(part => {
+        const cleaned = part.replace(/^type\s+/, "");
+        const [imported, local] = cleaned.split(/\s+as\s+/);
+        info.namedImports.set(imported.trim(), (local || imported).trim());
+      });
+
+    return info;
+  }
+
+  if (trimmed) {
+    info.defaultImport = trimmed.replace(/^type\s+/, "").trim();
+  }
+
+  return info;
+}
+
+function parseImports(root, filePath, sanitizedContent) {
+  const imports = [];
+  const importPattern = /import\s+([\s\S]*?)\s+from\s+["']([^"']+)["']/g;
+  let match;
+
+  // 先把 import 关系建索引，后面追踪“业务文件是否调用某个 service 导出”时
+  // 就不需要全量做 AST 分析，靠 import + 文本匹配即可覆盖当前场景。
+  while ((match = importPattern.exec(sanitizedContent))) {
+    const importSource = match[2];
+    const resolvedPath = resolveImportPath(root, filePath, importSource);
+    if (!resolvedPath) continue;
+
+    imports.push({
+      source: importSource,
+      resolvedPath: normalizePath(resolvedPath),
+      ...parseImportBindings(match[1])
+    });
+  }
+
+  return imports;
+}
+
+function uniqueRefs(refs) {
+  return [...new Set(refs)].sort();
+}
+
+function getScanFileGroups(root, files) {
+  // 扫描时优先收敛到约定目录，减少无关文件带来的误报；
+  // 若项目不符合该目录约定，再退化为扫描全部代码文件。
+  const preferredCommonFiles = files.filter(file => isPreferredCommonNetworkFile(root, file.filePath));
+  const nonCommonFiles = preferredCommonFiles.length
+    ? files.filter(file => !isPreferredCommonNetworkFile(root, file.filePath))
+    : files;
+  const preferredServiceFiles = nonCommonFiles.filter(file => isPreferredServiceFile(root, file.filePath));
+
+  return {
+    serviceFiles: preferredServiceFiles.length ? preferredServiceFiles : nonCommonFiles,
+    businessFiles: preferredServiceFiles.length
+      ? nonCommonFiles.filter(file => !isPreferredServiceFile(root, file.filePath))
+      : nonCommonFiles,
+    usedServiceFallback: preferredServiceFiles.length === 0,
+    usedCommonFallback: preferredCommonFiles.length === 0
+  };
+}
+
+function buildFileIndex(root) {
+  const srcDir = path.join(root, "src");
+  if (!fs.existsSync(srcDir)) throw new Error("未找到 src 目录");
+
+  const files = walk(srcDir);
+  return files.map(filePath => {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const sanitizedContent = stripCommentsPreserveStrings(content);
+
+    return {
+      filePath,
+      relativePath: getRelativePath(root, filePath),
+      content,
+      sanitizedContent,
+      lines: content.split(/\r?\n/),
+      // 预先缓存 import 信息，避免每次扫描接口时重复解析文件。
+      imports: parseImports(root, filePath, sanitizedContent)
+    };
+  });
+}
+
+function findServiceSymbols(api, serviceFiles) {
+  const symbols = [];
+
+  serviceFiles.forEach(file => {
+    const matches = getLineMatches(file.content, file.sanitizedContent, api);
+    matches.forEach(match => {
+      const nearestExport = findNearestExportName(file.lines, match.lineNumber);
+      if (!nearestExport) return;
+
+      symbols.push({
+        serviceFilePath: file.filePath,
+        serviceRelativePath: file.relativePath,
+        exportName: nearestExport.name,
+        definitionLineNumber: nearestExport.lineNumber,
+        apiLineNumber: match.lineNumber
+      });
+    });
+  });
+
+  const deduped = new Map();
+  symbols.forEach(symbol => {
+    const key = `${symbol.serviceFilePath}::${symbol.exportName}`;
+    deduped.set(key, symbol);
+  });
+  return [...deduped.values()];
+}
+
+function findDirectBusinessRefs(api, businessFiles) {
+  const refs = [];
+
+  businessFiles.forEach(file => {
+    const matches = getLineMatches(file.content, file.sanitizedContent, api);
+    matches.forEach(match => {
+      refs.push(formatRef(file.relativePath, match.lineNumber));
+    });
+  });
+
+  return refs;
+}
+
+function findBusinessCallsForSymbol(symbol, businessFiles) {
+  const refs = [];
+
+  businessFiles.forEach(file => {
+    const relatedImports = file.imports.filter(item => item.resolvedPath === normalizePath(symbol.serviceFilePath));
+    if (!relatedImports.length) return;
+
+    const cleanLines = file.sanitizedContent.split(/\r?\n/);
+
+    relatedImports.forEach(item => {
+      const localName = item.namedImports.get(symbol.exportName);
+      if (localName) {
+        const callPattern = new RegExp(`\\b${escapeRegExp(localName)}\\s*\\(`);
+        cleanLines.forEach((line, index) => {
+          if (!callPattern.test(line)) return;
+          refs.push(formatRef(file.relativePath, index + 1));
+        });
+      }
+
+      if (item.namespaceImport) {
+        const namespacedPattern = new RegExp(`\\b${escapeRegExp(item.namespaceImport)}\\s*\\.\\s*${escapeRegExp(symbol.exportName)}\\s*\\(`);
+        cleanLines.forEach((line, index) => {
+          if (!namespacedPattern.test(line)) return;
+          refs.push(formatRef(file.relativePath, index + 1));
+        });
+      }
+    });
+  });
+
+  return refs;
+}
+
+function findServiceDefinitionRefs(symbols) {
+  return symbols.map(symbol => formatRef(symbol.serviceRelativePath, symbol.apiLineNumber));
+}
+
+function scanApis(root, apis) {
+  const fileIndex = buildFileIndex(root);
+  const {
+    serviceFiles,
+    businessFiles,
+    usedServiceFallback,
+    usedCommonFallback
+  } = getScanFileGroups(root, fileIndex);
+  const result = {};
+
+  if (usedServiceFallback) {
+    log("未发现 src/services 目录，回退到全 src 非通用文件推断接口定义");
+  }
+
+  if (usedCommonFallback) {
+    log("未发现 src/common/network 目录，回退到全 src 文件中查找业务调用");
+  }
+
+  apis.forEach(api => {
+    const refs = [];
+    const businessRefs = findDirectBusinessRefs(api, businessFiles);
+    refs.push(...businessRefs);
+
+    const symbols = findServiceSymbols(api, serviceFiles);
+    let serviceCallRefs = [];
+    symbols.forEach(symbol => {
+      serviceCallRefs = serviceCallRefs.concat(findBusinessCallsForSymbol(symbol, businessFiles));
+    });
+    refs.push(...serviceCallRefs);
+
+    let note = "";
+    const actualUsageRefs = uniqueRefs([...businessRefs, ...serviceCallRefs]);
+    if (!refs.length) {
+      refs.push(...findServiceDefinitionRefs(symbols));
+      if (symbols.length) {
+        note = "未发现页面引用该方法";
+      }
+    }
+
+    const unique = uniqueRefs(refs);
+    result[api] = {
+      used: actualUsageRefs.length > 0,
+      refs: unique,
+      note
+    };
+  });
+
+  return result;
+}
+
+function parseConfig(root) {
+  const file = path.join(root, "api-exclude.md");
+  if (!fs.existsSync(file)) throw new Error("未找到 api-exclude.md");
+
+  const content = fs.readFileSync(file, "utf-8");
+  const blocks = [...content.matchAll(/```([a-zA-Z0-9_-]+)?\n([\s\S]*?)```/g)].map(match => ({
+    lang: (match[1] || "").trim().toLowerCase(),
+    body: match[2].trim()
+  }));
+
+  if (!blocks.length) throw new Error("未找到接口列表");
+
+  let commits = [];
+  let apiBlock = null;
+
+  blocks.forEach(block => {
+    if (apiBlock) return;
+
+    // 约定第一个满足结构的 json 代码块为版本列表；
+    // 剩余的首个非空代码块视为接口列表，兼容文档里同时放示例和说明文本。
+    if (block.lang === "json") {
+      try {
+        const parsed = JSON.parse(block.body);
+        const isCommitList = Array.isArray(parsed) && parsed.every(item =>
+          item &&
+          typeof item === "object" &&
+          typeof item.version === "string" &&
+          typeof item.build === "number"
+        );
+
+        if (isCommitList) {
+          commits = parsed;
+          return;
+        }
+      } catch {
+        // Ignore invalid json block here and continue finding API list.
+      }
+    }
+
+    apiBlock = block.body;
+  });
+
+  if (!apiBlock) {
+    const apiCandidate = blocks.find(block => block.body);
+    apiBlock = apiCandidate ? apiCandidate.body : "";
+  }
+
+  const apis = apiBlock
+    .split("\n")
+    .map(item => item.trim())
+    .filter(Boolean);
+
+  if (!apis.length) throw new Error("未找到接口列表");
+
+  return { commits, apis, hasCommitList: commits.length > 0 };
+}
+
+function generateMarkdown(results, root, options = {}) {
+  const ts = Date.now();
+  const file = path.join(root, `api-${ts}.md`);
+  const includeVersion = options.includeVersion ?? true;
+
+  let md = includeVersion
+    ? "| 版本 | 接口 | 是否使用 | 引用位置 | 备注 |\n|------|------|----------|----------|------|\n"
+    : "| 接口 | 是否使用 | 引用位置 | 备注 |\n|------|----------|----------|------|\n";
+
+  results.forEach(item => {
+    const refs = item.refs.length ? item.refs.join("<br/>") : "-";
+    const note = item.note || "-";
+    md += includeVersion
+      ? `| ${item.version} | ${item.api} | ${item.used ? "✅" : "❌"} | ${refs} | ${note} |\n`
+      : `| ${item.api} | ${item.used ? "✅" : "❌"} | ${refs} | ${note} |\n`;
+  });
+
+  fs.writeFileSync(file, md, "utf-8");
+  return file;
+}
+
+async function runCheck(root) {
+  log("解析 api-exclude.md");
+  const { commits, apis, hasCommitList } = parseConfig(root);
+  log(`找到 ${commits.length} 个 commit, ${apis.length} 个接口`);
+
+  const finalResults = [];
+
+  if (hasCommitList) {
+    if (!isGitRepo(root)) {
+      throw new Error("api-exclude.md 中存在 commit 列表，但当前项目不是 git 项目，无法按版本扫描");
+    }
+
+    log("是 git 项目，基于当前分支历史检查");
+
+    // 每个版本通过临时 worktree 回到对应 commit 扫描，
+    // 避免直接切换当前工作区，减少对开发环境的干扰。
+    for (const commitInfo of commits) {
+      const hash = getCommitByBuild(root, commitInfo.build);
+      log(`在临时 worktree 检查 commit ${commitInfo.version} (${hash})`);
+      const worktreePath = createTempWorktree(root, hash);
+
+      try {
+        const scan = scanApis(worktreePath, apis);
+        apis.forEach(api => {
+          log(`接口 ${api} 使用状态: ${scan[api].used ? "✅" : "❌"}`);
+          finalResults.push({
+            version: commitInfo.version,
+            api,
+            used: scan[api].used,
+            refs: scan[api].refs,
+            note: scan[api].note
+          });
+        });
+      } finally {
+        removeTempWorktree(root, worktreePath);
+      }
+    }
+  } else {
+    log("未提供 commit 列表，按当前项目代码直接扫描");
+    const scan = scanApis(root, apis);
+    apis.forEach(api => {
+      finalResults.push({
+        api,
+        used: scan[api].used,
+        refs: scan[api].refs,
+        note: scan[api].note
+      });
+    });
+  }
+
+  const file = generateMarkdown(finalResults, root, { includeVersion: hasCommitList });
+  log(`输出结果文件: ${file}`);
+  return file;
+}
+
+async function handleRequest(message) {
+  if (!message || typeof message !== "object") return;
+
+  // 兼容不同客户端的 initialized 通知写法；这类通知无需响应。
+  if (message.method === "notifications/initialized" || message.method === "initialized") {
+    return;
+  }
+
+  if (message.method === "ping") {
+    sendResult(message.id, {});
+    return;
+  }
+
+  if (message.method === "initialize") {
+    sendResult(message.id, {
+      protocolVersion: PROTOCOL_VERSION,
+      serverInfo: { name: "api-check-mcp", version: "1.0.0" },
+      capabilities: { tools: {} }
+    });
+    return;
+  }
+
+  if (message.method === "tools/list") {
+    sendResult(message.id, {
+      tools: [
+        {
+          name: "check_api_usage",
+          description: "扫描指定项目中接口在业务逻辑里的实际调用位置",
+          inputSchema: {
+            type: "object",
+            properties: {
+              rootDir: { type: "string", description: "需要扫描的项目根目录" }
+            },
+            required: ["rootDir"]
+          }
+        }
+      ]
+    });
+    return;
+  }
+
+  if (message.method === "tools/call") {
+    const params = message.params || {};
+    if (params.name !== "check_api_usage") {
+      sendError(message.id, -32601, `未知工具: ${params.name || "undefined"}`);
+      return;
+    }
+
+    if (!params.arguments || typeof params.arguments.rootDir !== "string" || !params.arguments.rootDir.trim()) {
+      sendError(message.id, -32602, "rootDir 必须是非空字符串");
+      return;
+    }
+
+    try {
+      const file = await runCheck(params.arguments.rootDir);
+      sendResult(message.id, {
+        content: [{ type: "text", text: `✅ 完成，结果文件：${file}` }]
+      });
+    } catch (error) {
+      sendResult(message.id, {
+        isError: true,
+        content: [{ type: "text", text: `❌ 扫描失败: ${error.message}` }]
+      });
+    }
+    return;
+  }
+
+  if (message.id !== undefined) {
+    sendError(message.id, -32601, `不支持的方法: ${message.method || "undefined"}`);
+  }
+}
+
+function parseHeaders(headerText) {
+  const headers = {};
+  headerText.split("\r\n").forEach(line => {
+    const separator = line.indexOf(":");
+    if (separator === -1) return;
+    const key = line.slice(0, separator).trim().toLowerCase();
+    const value = line.slice(separator + 1).trim();
+    headers[key] = value;
+  });
+  return headers;
+}
+
+let buffer = Buffer.alloc(0);
+
+async function processBuffer() {
+  while (true) {
+    const headerEnd = buffer.indexOf("\r\n\r\n");
+    if (headerEnd === -1) return;
+
+    const headerText = buffer.slice(0, headerEnd).toString("utf-8");
+    const headers = parseHeaders(headerText);
+    const contentLength = Number(headers["content-length"]);
+
+    if (!Number.isInteger(contentLength) || contentLength < 0) {
+      throw new Error("缺少合法的 Content-Length");
+    }
+
+    const totalLength = headerEnd + 4 + contentLength;
+    if (buffer.length < totalLength) return;
+
+    // stdin 是流式输入，一次 data 事件可能带来半包、整包或多包，
+    // 所以这里按 Content-Length 手动拆包，并把剩余字节留给下一轮继续处理。
+    const body = buffer.slice(headerEnd + 4, totalLength).toString("utf-8");
+    buffer = buffer.slice(totalLength);
+
+    let message;
+    try {
+      message = JSON.parse(body);
+    } catch {
+      log("收到无法解析的 JSON 请求");
+      continue;
+    }
+
+    await handleRequest(message);
+  }
+}
+
+process.stdin.on("data", async chunk => {
+  buffer = Buffer.concat([buffer, chunk]);
+  try {
+    await processBuffer();
+  } catch (error) {
+    log(`处理请求失败: ${error.message}`);
+  }
+});