{
  "uri": "file:///home/user/projects/myproject",
  "name": "我的项目"
}

{
  "capabilities": {
    "roots": { "listChanged": true }
  }
}

mkdir project-stats-mcp && cd project-stats-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx
npx tsc --init

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts"
  }
}

import path from "path";

// 全局缓存：从客户端拉取并解析后的绝对路径
export let workspaceRoots: string[] = [];

export function setWorkspaceRoots(roots: string[]) {
  workspaceRoots = roots.map((p) => path.resolve(p));
}

// file:// URI → 本地绝对路径，拒绝非 file 协议
export function uriToPath(uri: string): string {
  const url = new URL(uri);
  if (url.protocol !== "file:") {
    throw new Error(`不支持的 root 协议 ${url.protocol}：当前规范仅允许 file://`);
  }
  return decodeURIComponent(url.pathname);
}

// 安全校验：目标路径必须严格落在某个 root 之内
export function assertWithinRoots(target: string): string {
  const resolved = path.resolve(target);
  const inside = workspaceRoots.some((root) => {
    const rel = path.relative(root, resolved);
    // rel 为空串表示恰好等于 root；不以 ".." 开头且非绝对路径表示在内部
    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
  });
  if (!inside) {
    throw new Error(`路径越界，不在任何 root 之内：${resolved}`);
  }
  return resolved;
}

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  RootsListChangedNotificationSchema,
} from "@modelcontextprotocol/sdk/types.js";
import fs from "fs/promises";
import path from "path";
import { uriToPath, assertWithinRoots, setWorkspaceRoots } from "./roots.js";

const server = new Server(
  { name: "project-stats", version: "0.1.0" },
  { capabilities: { tools: {} } }
);

// 从客户端拉取 roots，内置三级降级
async function refreshRoots() {
  const caps = server.getClientCapabilities();

  // 情况一：客户端未声明 roots 能力 → 降级到进程 cwd
  if (!caps?.roots) {
    setWorkspaceRoots([process.cwd()]);
    console.error("[roots] 客户端不支持 roots，降级到 cwd:", process.cwd());
    return;
  }

  try {
    const { roots } = await server.listRoots();
    const dirs = (roots ?? []).map((r) => uriToPath(r.uri));

    // 情况二：协商了 roots 但返回空 → 降级到 cwd
    if (dirs.length === 0) {
      setWorkspaceRoots([process.cwd()]);
      console.error("[roots] 客户端返回空 roots，降级到 cwd");
      return;
    }

    // 情况三：正常路径
    setWorkspaceRoots(dirs);
    console.error(`[roots] 已获取 ${dirs.length} 个 root:`, dirs.join(", "));
  } catch (err) {
    // 情况四：拉取抛错（如 -32601）→ 兜底降级
    setWorkspaceRoots([process.cwd()]);
    console.error("[roots] 拉取失败，降级到 cwd:", err);
  }
}

// 注册 roots 变更通知处理器（对应 listChanged: true）
server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
  console.error("[roots] 收到 list_changed，重新拉取...");
  await refreshRoots();
});

// 初始化完成后拉取第一次 roots
server.oninitialized = async () => {
  await refreshRoots();
};

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "count_lines",
      description: "统计指定路径下的代码总行数（仅限 root 边界内）",
      inputSchema: {
        type: "object",
        properties: {
          subdir: { type: "string", description: "相对某个 root 的子目录，默认为 root 本身" },
        },
      },
    },
    {
      name: "list_roots",
      description: "返回服务器当前感知到的项目 root 列表（用于调试）",
      inputSchema: { type: "object", properties: {} },
    },
  ],
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "list_roots") {
    const { workspaceRoots } = await import("./roots.js");
    return {
      content: [{ type: "text", text: JSON.stringify(workspaceRoots, null, 2) }],
    };
  }

  if (name === "count_lines") {
    // 注意：用户传的 subdir 必须拼接到某个真实 root 上再做校验
    const { workspaceRoots } = await import("./roots.js");
    if (workspaceRoots.length === 0) {
      return { content: [{ type: "text", text: "尚无可用 root" }] };
    }
    const base = workspaceRoots[0];
    const target = args?.subdir ? path.join(base, String(args.subdir)) : base;
    const safe = assertWithinRoots(target); // 越界直接抛错

    let total = 0;
    const walk = async (dir: string) => {
      for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
        const full = path.join(dir, entry.name);
        if (entry.isDirectory()) {
          if (entry.name === "node_modules" || entry.name === ".git") continue;
          await walk(full);
        } else {
          const content = await fs.readFile(full, "utf-8");
          total += content.split("\n").length;
        }
      }
    };
    await walk(safe);
    return { content: [{ type: "text", text: `${safe} 共 ${total} 行` }] };
  }

  throw new Error(`未知工具: ${name}`);
});

// 启动
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("project-stats MCP 服务器已启动（stdio）");

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

claude mcp add project-stats -- node /绝对路径/dist/index.js

claude --add-dir ~/repos/frontend ~/repos/backend

sequenceDiagram
    participant S as 服务器
    participant C as 客户端 (Claude Code / Inspector)
    participant U as 用户

    Note over S,C: 1. 握手与能力协商
    C->>S: initialize (capabilities.roots.listChanged=true)
    S-->>C: 返回服务器能力
    C->>S: initialized 通知

    Note over S,C: 2. 首次拉取
    S->>S: oninitialized 触发
    S->>C: roots/list 请求
    C-->>S: { roots: [{uri, name}] }
    S->>S: 解析+校验+缓存 workspaceRoots

    Note over U,C: 3. 运行时动态变更
    U->>C: /add-dir 新目录
    C->>S: notifications/roots/list_changed
    S->>C: roots/list (重新拉取)
    C-->>S: 更新后的 roots
    S->>S: 热更新缓存，无需重启

    Note over S,C: 4. 工具调用受边界约束
    C->>S: count_lines(subdir)
    S->>S: assertWithinRoots 越界校验
    S-->>C: 统计结果 / 越界错误

flowchart TD
    A[工具需要访问文件] --> B{客户端声明了 roots 能力?}
    B -- 否 --> C[降级: 使用进程 cwd]
    B -- 是 --> D[发送 roots/list]
    D --> E{返回有效 roots?}
    E -- 空或异常 --> F[降级: 使用进程 cwd]
    E -- 有效 --> G[解析 file:// URI 并缓存]
    C --> H[assertWithinRoots 越界校验]
    F --> H
    G --> H
    H --> I[执行文件操作]