{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["notes-mcp-server.js"],
      "env": {
        "NOTES_ROOT": "F:\\2. ObsidianNotes"
      }
    },
    "browser": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

// JsonRpcMessage = MCP 底层 JSON-RPC 消息。
type JsonRpcMessage = {
  jsonrpc: "2.0";       // 协议版本。
  id?: string | number; // request/response 关联 ID。
  method?: string;      // 请求方法，例如 tools/list。
  params?: unknown;     // 请求参数。
  result?: unknown;     // 成功响应结果。
  error?: {
    code: number;       // 错误码。
    message: string;    // 错误信息。
    data?: unknown;     // 可选错误详情。
  };
};

// Transport = MCP client 依赖的传输接口。
// stdio/http/websocket 都可以实现它。
interface Transport {
  start(): Promise<void>; // 启动连接。
  send(message: JsonRpcMessage): Promise<void>; // 发送消息。
  onMessage(handler: (message: JsonRpcMessage) => void): void; // 注册接收回调。
  close(): Promise<void>; // 关闭连接。
}

// StdioTransport = 本地子进程 MCP server 的传输实现。
class StdioTransport implements Transport {
  // MCP server 子进程。
  private child?: ChildProcess;

  // 收到完整 JSON-RPC 消息后要调用的 handler。
  private handlers: Array<(message: JsonRpcMessage) => void> = [];

  // stdout 可能分包，所以需要 buffer 拼行。
  private buffer = "";

  constructor(
    private command: string, // 启动命令。
    private args: string[],  // 参数。
    private env: Record<string, string | undefined> // 环境变量。
  ) {}

  async start() {
    // 启动子进程。
    this.child = spawn(this.command, this.args, {
      stdio: ["pipe", "pipe", "pipe"],
      env: { ...process.env, ...this.env }
    });

    // stdout 收 MCP JSON-RPC 消息。
    this.child.stdout?.on("data", chunk => {
      // 先追加到 buffer，不直接 JSON.parse。
      this.buffer += chunk.toString("utf8");
      this.drainLines();
    });

    // stderr 当日志，不当协议消息。
    this.child.stderr?.on("data", chunk => {
      appendMcpLog("stderr", chunk.toString("utf8"));
    });
  }

  // drainLines = 从 buffer 中取出完整行。
  private drainLines() {
    while (this.buffer.includes("\n")) {
      const index = this.buffer.indexOf("\n");
      // 取出一行并 trim。
      const line = this.buffer.slice(0, index).trim();
      // 剩余内容留在 buffer，等待下一次 data。
      this.buffer = this.buffer.slice(index + 1);

      if (!line) continue;

      // 一行是一个 JSON-RPC 消息。
      const message = JSON.parse(line);
      for (const handler of this.handlers) {
        handler(message);
      }
    }
  }

  async send(message: JsonRpcMessage) {
    // 发送时也是一行一个 JSON。
    this.child?.stdin?.write(JSON.stringify(message) + "\n");
  }

  onMessage(handler: (message: JsonRpcMessage) => void) {
    // 注册回调。
    this.handlers.push(handler);
  }

  async close() {
    // 关闭子进程。
    this.child?.kill();
  }
}

// McpClient = MCP client，负责请求/响应配对和工具调用。
class McpClient {
  // 下一个 request id。
  private nextId = 1;

  // pending 保存等待响应的请求。
  private pending = new Map<number, {
    resolve(value: JsonRpcMessage): void;
    reject(error: Error): void;
    // 每个请求都有 timeout，避免永远挂着。
    timeout: NodeJS.Timeout;
  }>();

  constructor(
    public readonly name: string, // server 名。
    private transport: Transport  // 底层传输。
  ) {}

  async connect() {
    // 先注册消息处理，避免 start 后马上有消息但没人接。
    this.transport.onMessage(message => this.handleMessage(message));
    await this.transport.start();

    // 初始化握手。
    await this.request("initialize", {
      protocolVersion: "2026-03-26",
      clientInfo: {
        name: "learning-agent-cli",
        version: "0.1.0"
      }
    });
  }

  async listTools(): Promise<McpTool[]> {
    // 请求远端工具列表。
    const response = await this.request("tools/list", {});
    return (response.result as any).tools;
  }

  async callTool(name: string, input: unknown): Promise<ToolResult> {
    // 请求远端执行工具。
    const response = await this.request("tools/call", {
      name,
      arguments: input
    });

    // 转成本地统一 ToolResult。
    return normalizeMcpToolResult(response.result);
  }

  // request = 发送 JSON-RPC 请求并等待响应。
  private async request(method: string, params: unknown): Promise<JsonRpcMessage> {
    // 分配 ID。
    const id = this.nextId++;

    const promise = new Promise<JsonRpcMessage>((resolve, reject) => {
      // 超时后清理 pending 并 reject。
      const timeout = setTimeout(() => {
        this.pending.delete(id);
        reject(new Error(`MCP request timeout: ${method}`));
      }, 30_000);

      this.pending.set(id, { resolve, reject, timeout });
    });

    // 发出请求。
    await this.transport.send({
      jsonrpc: "2.0",
      id,
      method,
      params
    });

    // 等待 handleMessage resolve/reject。
    return promise;
  }

  // handleMessage = 收到 JSON-RPC response 后按 id 找回 pending。
  private handleMessage(message: JsonRpcMessage) {
    // 没有数字 id 的消息先忽略，例如 notification。
    if (typeof message.id !== "number") return;

    // 找对应请求。
    const pending = this.pending.get(message.id);
    if (!pending) return;

    // 清理 timeout 和 pending。
    clearTimeout(pending.timeout);
    this.pending.delete(message.id);

    // JSON-RPC error 转 reject，否则 resolve。
    if (message.error) {
      pending.reject(new Error(message.error.message));
    } else {
      pending.resolve(message);
    }
  }
}

// wrapMcpTool = 把远程 MCP tool 包装成本地 Tool。
// 包装后进入 Tool Registry，走和本地工具一样的权限/审计/超时。
function wrapMcpTool(client: McpClient, remoteTool: McpTool): Tool<any, any> {
  return {
    // namespace 防止不同 server 的 search/read 等工具重名。
    name: `mcp__${client.name}__${remoteTool.name}`,
    // 描述里标明来源。
    description: `[MCP:${client.name}] ${remoteTool.description}`,
    // 远程 schema 作为本地 inputSchema。
    inputSchema: remoteTool.inputSchema,
    // 根据名字和描述推断默认风险。
    risk: inferMcpRisk(remoteTool),
    // MCP 工具也必须有超时。
    timeoutMs: 30_000,
    // 返回内容也要限制大小。
    maxOutputBytes: 64_000,
    async run(input) {
      // 本地工具执行时，转发到远端 MCP server。
      return client.callTool(remoteTool.name, input);
    }
  };
}

// inferMcpRisk = MCP 工具默认风险推断。
// 真实项目应允许用户在配置里覆盖。
function inferMcpRisk(tool: McpTool): ToolRisk {
  // 拼接名称和描述，用关键词粗略判断。
  const text = `${tool.name} ${tool.description}`.toLowerCase();

  // 写/删/更新类工具。
  if (text.includes("delete") || text.includes("write") || text.includes("update")) {
    return "write";
  }

  // 执行命令类工具。
  if (text.includes("run") || text.includes("exec") || text.includes("shell")) {
    return "execute";
  }

  // 网络/浏览器类工具。
  if (text.includes("fetch") || text.includes("browser") || text.includes("http")) {
    return "network";
  }

  // 默认只读。
  return "read";
}

// loadMcpTools = 加载所有 MCP server 的工具。
// 单个 server 失败不应该导致整个 Agent CLI 启动失败。
export async function loadMcpTools(config: McpConfig) {
  const tools: Tool<any, any>[] = [];
  const errors: McpLoadError[] = [];

  for (const server of config.servers) {
    try {
      // 连接 server。
      const client = await connectServer(server);

      // 获取远程工具。
      const remoteTools = await client.listTools();

      // 包装成本地工具。
      tools.push(...remoteTools.map(tool => wrapMcpTool(client, tool)));
    } catch (error) {
      // 记录失败，继续下一个 server。
      errors.push({
        server: server.name,
        message: error instanceof Error ? error.message : String(error)
      });
    }
  }

  // 返回成功工具和失败列表，UI 可提示但不中断。
  return { tools, errors };
}

MCP server notes failed to connect: timeout.
Continuing without notes tools.

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

{"type":"tool_start","name":"read_file"}