High Performance MCP Server

高性能 MCP 服务

一个使用 TypeScript 和现代 MCP v2 SDK（@modelcontextprotocol/server）构建的高性能模块化 Model Context Protocol（MCP）服务。具备默认安全的安全配置、支持配置文件的服务说明、模块化 MCP 提示词、带显式启用的防护文本修改功能的允许列表工作区检查、强化 SSRF 防护的网络访问、Streamable HTTP、Stdio 传输、可复用的工作线程池、具备单次请求保护的生产级 LRU 缓存，以及结构化遥测。

---

项目状态：公开预览版（v0.5.0）

说明

状态：0.5.0 公开预览版。 此软件包提供默认安全的 MCP 工具、只读工作区检查、显式启用的受保护工作区修改和网络访问、工作线程请求取消、规范化进度报告，以及高性能工作线程执行。需要 Node.js >= 22.0.0。

兼容性：新增的 v0.5 选项均为增量添加。现有调用方若省略 contextLines、maxDepth、createParents 和 fetch_url.method，则保留既有默认语义。v0.5 还包含一项有意实施的创建模式发布强化：无法提供硬链接防覆盖发布的文件系统现在会直接失败，而不再使用先检查后重命名的回退方式。

---

功能

• 现代 MCP v2 架构：原生基于 @modelcontextprotocol/server 构建，采用标准 JSON Schema draft 2020-12 验证，并完整支持 2026-07-28 协议。
• 双传输方式支持：可通过标准输入/输出（stdio）或现代 Streamable HTTP（node:http + /mcp）无缝运行。
• 感知配置的服务说明：动态服务说明会根据当前启用的配置，引导已连接的大模型了解推荐工作流、工具调用顺序和安全边界。
• 模块化 MCP 提示词：可复用的任务提示词（explore_workspace、find_and_explain、review_file、trace_symbol）仅在 workspace、workspace_write 和 all 配置中提供。
• 原生 MCP 工作区补全：为每个工作区提示词和工作区资源模板自动补全逻辑 rootId 值，无需枚举文件或暴露主机路径。
• 默认安全的工具配置：默认的 safe 配置不开放任何文件系统、网络或硬件检查功能。文件系统修改和出站网络访问必须明确选择启用 workspace_write/network（或 all）。
• 工作区安全与主机路径隐私：通过安全的允许列表目录访问，防止路径遍历和符号链接逃逸；支持逻辑根映射（root-1、root-2）、有界文本操作和二进制文件保护，不向客户端或模型暴露主机绝对路径。workspace 配置保持只读；受保护的修改功能仅在 workspace_write 和 all 中提供。
• 工作区搜索与探索：快速、有界的字面文件和文本搜索（search_files、search_text），支持默认忽略目录、有界并发（SEARCH_CONCURRENCY = 8）、坐标映射、可选的有界上下文行（contextLines: 0..10）以及客户端取消。
• 递归目录列表：通过广度优先搜索进行有界的递归子目录遍历（list_directory 的 maxDepth: 1..5），使用规范化相对路径，最多返回全局上限 500 个条目。
• 受保护的工作区修改与安全的父目录创建：支持事务式编辑（edit_text_file）和原子式防覆盖创建（write_text_file），可选安全地逐级创建父目录（createParents），并支持乐观 SHA-256 并发控制和可选的客户端确认。
• 安全的网络抓取与元数据：通过多层 SSRF 防护、DNS 重绑定缓解、端口允许列表、条件响应缓存以及轻量级 HTTP HEAD 元数据检查，保护出站 HTTP/HTTPS 抓取（fetch_url）。
• 支持取消的工作线程池：将 CPU 密集型任务从 Node.js 事件循环中卸载，支持自动生命周期恢复和 AbortSignal 取消，并可快速强制终止正在运行的同步计算。
• 规范化的 MCP 进度报告：工作区搜索和计算工作线程工具提供高性能进度通知，保证按序送达；未启用时不产生任何开销。
• 生产级 LRU 缓存：支持 TTL 的内存有界缓存，并通过单次请求合并消除缓存击穿。
• 内部结构化日志：仅通过 stderr 输出适用于 Stdio 的 JSON 日志。

---

快速开始

MCP 客户端配置（Claude Desktop、Cursor 等）

将以下内容添加到 MCP 配置中（例如 claude_desktop_config.json）：

默认安全配置（Stdio）

{
  "mcpServers": {
    "high-performance-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "high-performance-mcp-server"
      ]
    }
  }
}

只读工作区配置

{
  "mcpServers": {
    "workspace-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "high-performance-mcp-server",
        "--profile=workspace",
        "--root=/path/to/project"
      ]
    }
  }
}

MCP Inspector 测试

如需使用 @modelcontextprotocol/inspector 进行本地测试和交互式调试，请参阅 examples/inspector-workspace.example.json 中的配置模板。

本地开发 / 源码执行

# Clone and build
git clone https://github.com/AnIayana/high-performance-mcp-server.git
cd high-performance-mcp-server
npm install
npm run build

# Run default safe profile
node dist/cli.js

# Run workspace profile with allowlisted root
node dist/cli.js --profile=workspace --root=.

# Run with Streamable HTTP transport
node dist/cli.js --transport=http --port=3000

---

Streamable HTTP 传输与健康端点

服务器可通过 loopback 上的 Streamable HTTP 运行：

# Using CLI flag
node dist/cli.js --transport=http --port=3000

# Or using environment variable
MCP_TRANSPORT=http PORT=3000 node dist/cli.js

使用 HTTP 传输运行时（--transport=http 或 MCP_TRANSPORT=http）：

• 协议端点：http://127.0.0.1:3000/mcp（Streamable HTTP 协议处理程序）
• 健康端点：http://127.0.0.1:3000/healthz（运行状态探测）

Loopback 安全与健康契约

• 仅绑定 Loopback：HTTP 服务器仅绑定到 127.0.0.1。不支持远程绑定、TLS 终止和对外部网络开放。
• Host 与 Origin 防护：DNS 重绑定（localhostHostValidation）和浏览器 CSRF（localhostOriginValidation）防护在所有路由（包括 /healthz）上均保持启用。
• 支持的方法：
  • GET /healthz：返回 200 OK，响应内容为 {"status":"ok"}（Content-Type: application/json; charset=utf-8，Cache-Control: no-store）。
  • HEAD /healthz：返回 200 OK，响应头相同，响应体为空。
  • 不支持的方法（POST、PUT、DELETE 等）返回 405 Method Not Allowed，并带有 Allow: GET, HEAD。
• 零副作用：探测 /healthz 会执行一个固定时间的本地检查。它不会创建 MCP 会话、分配工作线程、访问文件系统或网络资源，也不会修改任何指标。
• 编排器 / 监督程序：对于本地容器或进程监督程序（例如 Docker HEALTHCHECK 或 Kubernetes 探测），运维人员可将存活和就绪探测都指向 /healthz（示例命令：curl -f -s http://127.0.0.1:3000/healthz）。没有单独的 /readyz 端点，因为服务器成功监听端口后，所有初始化都是同步且在内存中完成的。

---

以编程方式使用 Node.js

服务器可直接嵌入 Node.js 应用（仅 ESM，Node >=22）：

import {
  createServer,
  resolveWorkspaceConfig,
} from "high-performance-mcp-server";

// 1. Safe default server (only 'echo' and 'ping' enabled)
const safeServer = createServer();

// Connect to transport or execute within application...

// Gracefully close protocol sessions when done
await safeServer.close();

// 2. Workspace profile with canonicalized roots
const workspaceConfig = await resolveWorkspaceConfig(["/path/to/project"]);
const workspaceServer = createServer({
  profile: "workspace",
  workspaceConfig,
});

await workspaceServer.close();

说明

• 同一 Node.js 进程中的多个服务器实例共享进程级全局计算缓存、工作线程池和指标。
• 本地 WorkspaceConfig 对象可包含用于本地主机验证的规范绝对文件系统路径；物理主机路径绝不会通过远程 MCP 客户端协议暴露。

---

默认安全配置文件

为保护主机并防止意外消耗资源或泄露元数据，工具、资源、指令和提示词按安全配置文件分类：

配置文件	包含的类别	暴露的工具	提示词	使用场景
safe (默认)	safe	echo、ping	(无)	不检查主机、不访问文件系统、不进行修改。适合公开暴露。
workspace	safe、workspace	echo、ping、workspace_roots、list_directory、file_info、read_text_file、search_files、search_text	explore_workspace、find_and_explain、review_file、trace_symbol	只读检查文件和目录，严格限制在允许列表中的 --root 目录内。
workspace_write	safe、workspace、workspace_write	echo、ping、workspace_roots、list_directory、file_info、read_text_file、search_files、search_text、write_text_file、edit_text_file	explore_workspace、find_and_explain、review_file、trace_symbol	受保护的工作区文本文件创建、覆盖和事务性编辑，并采用乐观并发控制。
network	safe、network	echo、ping、fetch_url	(无)	经过 SSRF 防护、只读的 HTTP/HTTPS 公共资源获取。
diagnostics	safe、diagnostics	echo、ping、cache_stats、server_metrics、system_stats、worker_pool_stats	(无)	进程和系统可观测性，用于监控运行状况和事件循环延迟。
benchmark	safe、benchmark	echo、ping、cached_prime_count、heavy_compute_main、heavy_compute_worker	(无)	CPU 密集型素数计算基准测试和工作池测试。
admin	safe、diagnostics、admin	echo、ping、cache_stats、server_metrics、system_stats、worker_pool_stats、reset_cache、reset_metrics	(无)	可观测性及管理性运行时状态修改（清除缓存、重置指标）。
all	safe、workspace、workspace_write、network、diagnostics、benchmark、admin	全部 20 个已注册工具	全部 4 个工作区提示词	完整的工具和提示词目录。

---

服务指令与提示词

按配置文件定制的服务指令

MCP 客户端连接时，服务会通过 MCP 协议发送简洁且针对相应配置文件定制的指令：

• safe：告知模型无法检查文件系统和硬件。
• workspace：概述推荐的调查顺序（workspace_roots -> search_files / search_text -> file_info -> read_text_file），强调只读限制，并提醒使用相对于根目录的路径。
• diagnostics & benchmark：指导如何解读观测指标，并提醒不要进行不必要的 CPU 密集型计算。
• admin：说明修改操作仅影响进程本地的缓存和遥测状态。

模块化 MCP 提示词

在 workspace、workspace_write 或 all 配置中运行时，服务会提供模块化提示词，为常见工程任务提供结构化工作流：

提示词	参数	用途
explore_workspace	rootId (必填)，goal (可选)	引导模型使用搜索和文件检查，对允许列表中的工作区根目录进行结构化探索。
find_and_explain	rootId (必填)，query (必填)	使用字面文本搜索定位相关代码或配置，并读取定义文件以生成说明。
review_file	rootId (必填)，path (必填)，focus (可选)	针对工作区中的指定文本文件进行结构化的只读审查。
trace_symbol	rootId (必填)，symbol (必填)	跨工作区追踪某个符号的声明、引用和使用位置。

说明

提示词参数会被视为有界任务数据，并在插入可复用的 MCP 提示词模板前进行转义。提示词不会自行执行直接文件系统 I/O；实际的文件读取和搜索由模型在严格的根目录允许列表控制下，使用标准 MCP 工具和资源执行。

工作区根目录补全

支持工作区的配置会声明 MCP 的 completions 能力。客户端可以针对全部四个工作区提示词的 rootId 参数，以及 workspace:///{rootId}/{+path} 中的 rootId 变量，请求 completion/complete 建议。建议仅包含已配置的逻辑 ID，例如 root-1；绝不会枚举文件或泄露根目录名称和主机绝对路径。不具备工作区访问权限的配置不会声明补全支持。

---

只读工作区访问

默认情况下，文件系统访问处于禁用状态。要启用只读工作区访问，请明确指定 --profile=workspace 和至少一个列入允许列表的 --root 目录。范围更广的 all 配置也包含这些工具，但还会启用修改、网络、诊断、基准测试和管理功能。

# POSIX / macOS / Linux
npx high-performance-mcp-server --profile=workspace --root=/home/user/my-project

# Windows
npx high-performance-mcp-server --profile=workspace --root="C:\Projects\app"

# Multiple roots
npx high-performance-mcp-server --profile=workspace --root=./packages/core --root=./packages/cli

安全保障与限制

• 主机路径隐私：已配置的文件系统绝对路径仅在服务内部使用。workspace_roots 工具会返回逻辑根目录标识符（id: "root-1"，name: "my-project"），工作区资源 URI 也会使用这些标识符，而非主机绝对路径：

  {
    "roots": [
      {
        "id": "root-1",
        "name": "my-project"
      }
    ]
  }
  

• 严格允许列表：只能访问通过 --root 明确指定的目录。最多允许 16 个不重复的根目录（去重前最多 64 个原始路径）。
• 只读配置：标准 workspace 配置不提供任何修改工具。受保护的文本修改仅在明确使用 workspace_write 和 all 配置时可用；没有任何 MCP 工具可执行删除、任意重命名、创建目录、更改权限或执行命令。
• 路径遍历与符号链接保护：目标路径会使用 fs.realpath 进行规范化，并经过严格验证，确保绝不会越出根目录边界。
• 错误信息清理：错误响应只包含逻辑根目录 ID、根目录名称和请求的相对路径，确保不会泄露内部目录结构。
• 文件读取限制：默认文本读取上限为 256 KiB；硬性上限为 1 MiB（MAX_TEXT_READ_BYTES）。
• 二进制文件检测：read_text_file 会拒绝包含 NUL 字节（\0）的文件，以防止污染上下文。
• MCP 资源：提供规范的 workspace:///{rootId}/{+path}（workspace_text_file）模板。使用 workspace_roots 发现逻辑根目录；resources/list 不会递归枚举文件。

检查目录和文件

workspace 配置提供受限的文件和目录检查工具：

1. list_directory：

   • 列出允许访问的工作区根目录中的目录内容，总条目数上限为 500 条（超出时为 truncated: true）。
   • 受限递归遍历：可选参数 maxDepth（1..5，默认值：1）。当 maxDepth > 1 时，按广度优先搜索（BFS）遍历目录树，最多达到指定深度，并以扁平列表形式返回。
   • 相对路径输出：在递归模式下，条目包含使用正斜杠分隔符（/）的规范化 relativePath，而 name 保留条目的基本名称。
   • 确定性排序：保留现有的比较器行为，对目录条目进行排序。

   {
     "name": "list_directory",
     "arguments": {
       "rootId": "root-1",
       "path": "src",
       "maxDepth": 2
     }
   }
   

2. file_info：获取允许访问的根目录中某个相对路径的大小、时间戳和文件类型属性。

3. read_text_file：读取 UTF-8 文件内容，读取量不超过配置的字节数上限（默认值为 256 KiB，最大为 1 MiB）。包含 NUL 字节的文件将被拒绝。

搜索工作区

workspace 配置提供受限的只读搜索工具：

1. search_files：

   • 使用字面子字符串匹配搜索文件和目录名称。
   • 可按类型（file、directory、all）、是否区分大小写以及起始路径进行筛选。
   • 默认跳过常见的构建和供应商目录（.git、node_modules、.next、dist、build、target 等）。传入 includeIgnored: true 可搜索这些目录。
   • 不会遍历符号链接或联接目录，以防止递归循环和路径逃逸。
   • 当客户端提供 progressToken 时，流式发送原生 MCP 进度通知（notifications/progress）。

2. search_text：

   • 使用固定并发数（8 个工作线程）对 UTF-8 文本文件进行受限的字面匹配搜索。
   • 返回从 1 开始计数的行号和列号，以及经过截断的预览片段（最多 300 个字符）。
   • 支持文件扩展名筛选（例如 extensions: [".ts", ".md"] 或 extensions: ["ts", "md"]）。
   • 自动跳过二进制文件（包含 NUL 字节）和大于 1 MiB 的文件（MAX_SEARCH_FILE_BYTES）。
   • 限制：硬性默认值（maxResults: 100 [最大 500]、maxFiles: 5000 [最大 50000]、timeoutMs: 10000 [最大 30000]）。
   • 可通过客户端的 AbortSignal 完全取消。
   • 通过 progressToken 请求时，流式发送原生 MCP 进度通知（notifications/progress）。未请求时，进度开销为零。
   • 受限上下文行：可选参数 contextLines（0..10，默认值：0）。当 contextLines > 0 时，匹配项包含 contextBefore 和 contextAfter，它们是包含周围行的受限字符串数组。省略该参数或设为 0 时，不会包含上下文字段。不支持不受限的上下文。

   {
     "name": "search_text",
     "arguments": {
       "rootId": "root-1",
       "query": "SEARCH_CONCURRENCY",
       "path": "src",
       "contextLines": 2
     }
   }
   

---

受保护的工作区文本写入和编辑（workspace_write）

默认情况下禁用工作区修改。标准的 workspace 配置仍严格为只读。若要启用受保护的文本写入和事务性编辑功能，请显式选择 workspace_write 配置（或 all），并至少指定一个允许访问的 --root：

# Start server with workspace write capabilities
npx high-performance-mcp-server --profile=workspace_write --root=./project --workspace-max-write-bytes=2097152

修改工具

警告

使用 --profile=all 或 --profile=workspace_write 运行时，已连接的客户端和大模型可在配置的 --root 目录中，以受保护的方式写入和编辑文本。标准的 --profile=workspace 仍严格保持只读。

1. write_text_file：

   • 创建模式（mode: "create"）：在列入允许列表的工作区根目录中创建新的 UTF-8 文本文件。通过 fs.link 强制执行原子防覆盖语义；如果文件已存在（already_exists）或父目录不存在（missing_parent），则安全失败。在创建模式下禁止提供 expectedSha256。
   • 安全创建父目录：可选参数 createParents?: boolean（默认值：false）。设为 true 时，会在工作区根目录内逐级创建缺失的父目录，并严格验证规范化的真实路径是否位于允许范围内。仅适用于 mode: "create"（在 mode: "overwrite" 中指定 createParents 会被拒绝，并视为架构无效）。启用写入确认时，必须先完成确认，之后才能创建任何目录或进行任何文件系统更改。如果最终文件发布失败，已创建的父目录可能会作为部分副作用而保留。在受支持的文件系统上，最终文件发布仍采用原子防覆盖硬链接语义；父目录的创建本身并非完全原子。
   • 防覆盖失败关闭加固：创建模式下的文件发布不再在硬链接发布不可用时，回退到不安全的先检查后重命名路径。fs.link 是创建文件的发布原语；不支持硬链接发布时会安全失败，不覆盖现有文件，并对意外的原生文件系统错误进行清理。
   • 覆盖模式（mode: "overwrite"）：必须提供 expectedSha256（64 个字符的小写十六进制字符串），且其值必须与文件当前的 SHA-256 哈希匹配。如果文件被并发修改，则抛出 content_conflict 并中止操作，不会触碰目标文件。
   • 独占临时文件与原子替换：在目标目录中创建独占临时文件（.mcp-temp-<uuid>.tmp，使用 O_CREAT | O_EXCL），将数据刷新到磁盘（fsync），重新验证目标文件类型和哈希，然后原子替换目标文件。

   {
     "name": "write_text_file",
     "arguments": {
       "rootId": "root-1",
       "path": "src/nested/components/Button.tsx",
       "mode": "create",
       "content": "export function Button() { return <button>Click</button>; }\n",
       "createParents": true
     }
   }
   

2. edit_text_file：

   • 精确字面替换：在内存中按顺序执行针对性的文本替换，不使用正则表达式或特殊标记展开（例如，$$、$1、$&、$\``、$'` 均会按原样插入）。
   • 非重叠匹配次数保证：使用与精确替换语义一致的非重叠字面匹配来评估 expectedOccurrences（默认值：1）。
   • 事务式执行：在内存中按顺序应用所有编辑。如果任何编辑未通过 expectedOccurrences 检查，或文件哈希与 expectedSha256 不匹配，则操作会中止，磁盘文件保持完全未更改。
   • 严格 UTF-8 与 BOM 保留：拒绝非 UTF-8 二进制文件（invalid_text_encoding）。现有 UTF-8 BOM 标头和 CRLF 换行符会逐字节保留。

   {
     "name": "edit_text_file",
     "arguments": {
       "rootId": "root-1",
       "path": "src/index.ts",
       "expectedSha256": "4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a",
       "edits": [
         {
           "oldText": "const PORT = 3000;",
           "newText": "const PORT = 8080;",
           "expectedOccurrences": 1
         }
       ]
     }
   }
   

操作员可配置的写入限制

服务操作员可以设置允许的写入或编辑负载大小上限（以字节为单位）：

• CLI 标志：--workspace-max-write-bytes=<bytes>（1 至 5,242,880 字节 / 5 MiB，默认值：1048576 / 1 MiB）
• 环境变量：MCP_WORKSPACE_MAX_WRITE_BYTES=<bytes>

元数据与并发注意事项

• 原子替换元数据：原子替换会创建新的文件系统条目，并在支持的情况下保留 POSIX 权限位（0755、0644）。其他特定于操作系统的元数据（例如 inode 编号、创建时间戳 ctime、ACL 继承）可能无法跨平台保留。
• 残余并发边界：替换前重新验证可最大程度减少与不可信 MCP 调用方之间的 TOCTOU 竞态条件。不过，具有相同文件系统权限的恶意本地操作系统进程，若在最终验证后的几微秒内执行并发写入，仍可能与基于路径的操作发生竞态。具有相同权限的本地文件系统竞态仍属于残余威胁模型。
• 路径间接引用与边界检查：路径包含性依赖于 fs.realpath 在已配置根目录边界内进行规范解析。
• 失败即关闭的硬链接发布：如果文件系统或运行环境不支持通过原子 fs.link 硬链接发布，则创建模式的写入会失败关闭，且不会覆盖现有文件。

可选的客户端介导写入确认

确认功能默认关闭。使用仅供操作员使用的 --workspace-write-confirmation 标志，或设置 MCP_WORKSPACE_WRITE_CONFIRMATION=true（true/1/false/0），即可为这两种变更工具启用该功能。即使环境变量值为 false，CLI 标志仍会启用确认；工具参数无法将其关闭。不会添加任何工具，配置文件访问权限也保持不变。

high-performance-mcp-server --profile=workspace_write --root=./project --workspace-write-confirmation

服务端会验证目标，然后请求客户端显示一个包含 confirm 布尔值的表单。只有接受且响应中包含 confirm: true 时，操作才会继续。拒绝、取消、值为 false，以及格式错误的接受内容，都会使文件保持不变。等待批准期间不会创建临时文件。批准后仍会执行常规的根目录、大小、精确编辑和 SHA-256 检查，包括文件在提示期间发生变化的情况。

提示会标明操作以及规范化的逻辑 rootId/相对路径；不会显示文件内容、预期哈希值、根目录名称或主机绝对路径。控制字符和双向格式字符会进行转义。超过 4,096 个字符的目标会被拒绝，而不会静默截断。响应键包含提议的参数和解析后的逻辑目标，因此提议发生变化时会再次请求确认。

连接	已启用确认
MCP 2026-07-28，stdio 或 HTTP	原生 input_required 表单引导
旧版 MCP，stdio	SDK 兼容性垫片使用 elicitation/create
旧版 MCP，无状态 HTTP	拒绝：没有用于批准的反向请求通道
不支持表单引导的客户端	拒绝，不执行变更

关闭确认功能时，现有的新旧版本调用行为保持不变。请使用确实会向人类展示表单的客户端：引导是由客户端介导的防护措施，并非身份验证，也不是针对恶意客户端的安全边界。服务端无法证明客户端提供的响应确实获得了人类批准。直接在服务级嵌入也不受此 MCP 处理程序门控的保护。协议详情请参阅官方 SDK 输入必需指南。

---

MCP 工作区资源

除了工作区检查工具之外，此服务还会原生地将列入允许列表的工作区文本文件公开为标准 MCP 资源，并使用官方 URI 模板：

workspace:///{rootId}/{+path}

规范资源 URI 格式

工作区资源使用一种稳定且可移植的 URI 方案，以逻辑根目录 ID 而非主机文件系统路径为基础：

• workspace:///root-1/README.md
• workspace:///root-1/src/index.ts
• workspace:///root-2/docs/architecture.md

资源 URI、标题或错误消息中绝不会公开主机绝对路径（例如 file:///C:/... 或 /home/...）。

资源不变量与安全保障

• 配置文件门控：仅在支持工作区的配置文件（workspace、workspace_write、all）中公开工作区资源。在非工作区配置文件（safe、network、diagnostics、benchmark、admin）中，资源端点会返回 Method not found，且不会公开任何工作区是否存在的信息。
• 严格只读：资源严格只读。持有资源 URI 绝不会授予修改权限或文件系统写入能力。
• 根目录与符号链接限制：资源读取复用中央工作区安全解析器，严格限制在配置的 --root 目录内，并阻止通过符号链接或 junction 逃逸。
• 完整读取或报错语义：资源绝不会被静默截断。如果文件超过运算符设置的字节数限制，读取将以 resource_too_large 错误拒绝。
• 严格 UTF-8 与纯文本：所有资源内容都会严格解码为 UTF-8 文本（fatal: true）。包含 NUL 字节（0x00）或非 UTF-8 序列的文件会被拒绝，并作为不支持的二进制文件处理（invalid_text_encoding）。
• 不递归枚举：resources/templates/list 会公开资源模板（workspace_text_file）。服务器不会为 resources/list 递归遍历仓库目录，以避免大型仓库中的延迟、内存激增和信息泄露。
• 可由运算符配置的资源大小限制：
  • CLI 标志：--workspace-max-resource-bytes=<bytes>（1 至 5,242,880 字节 / 5 MiB，默认值：1048576 / 1 MiB）
  • 环境变量：MCP_WORKSPACE_MAX_RESOURCE_BYTES=<bytes>

推荐的客户端工作流

1. 发现：使用 workspace_roots、list_directory 或 search_files 发现可用的根目录 ID 和路径。
2. 读取资源：通过标准 MCP resources/read 使用 workspace:///<rootId>/<path> 直接读取文本文件。
3. 受保护的修改：需要修改时，使用 read_text_file 获取权威的 sha256 哈希，并在 workspace_write 配置文件中通过 write_text_file 或 edit_text_file 执行并发控制下的编辑。

---

网络访问与 fetch_url

网络访问默认禁用。要启用经过 SSRF 强化的只读网页抓取，请使用 --profile=network（或 --profile=all）运行：

# Start server with opt-in network profile
npx high-performance-mcp-server --profile=network

fetch_url 工具详情

fetch_url 工具会对公开网页资源执行严格受限的只读 HTTP/HTTPS 请求。

• 支持的方法：可选的 method 参数接受 "GET"（默认值）或 "HEAD"。任意 HTTP 动词（POST、PUT、DELETE、PATCH、OPTIONS）都会在架构边界处被拒绝。
• HEAD 元数据支持：指定 method: "HEAD" 时，服务器会发起原生 HEAD 请求，并复用与 GET 完全相同的 SSRF、DNS 多应答验证、套接字固定和重定向策略。不会读取表示正文（bytesRead: 0、truncated: false、body: undefined）。Content-Length 报告的是服务器声明的表示长度元数据，而非已下载字节数。此方式不受正文文本解码限制，因此可检索二进制资源（image/png、application/pdf、application/octet-stream）和压缩内容（Content-Encoding: gzip）的元数据。
• 重定向时保留方法：在所有重定向跳转（301、302、303、307、308）中保留请求的 HTTP 方法（GET 或 HEAD）。具体而言，带有 303 See Other 的 HEAD 请求到达目标地址时仍为 HEAD。
• 条件缓存隔离：GET 和 HEAD 缓存条目通过独立的前像严格隔离；两种方法都不能满足或污染另一种方法的缓存。现有 GET 缓存键标识保持不变（network-fetch-v1\0<canonicalUrl>）。HEAD 请求通过条件式 304 Not Modified 重新验证时，会返回缓存的原始状态码和 statusText，省略正文，并附带 revalidationStatus: 304。

{
  "name": "fetch_url",
  "arguments": {
    "url": "https://raw.githubusercontent.com/modelcontextprotocol/specification/main/LICENSE",
    "method": "HEAD"
  }
}

安全保障与约束

• 多层 SSRF 防护：根据标准 IPv4/IPv6 私有和特殊用途子网（net.BlockList）检查所有解析出的 IP 地址。严格阻止环回地址（127.0.0.0/8、::1）、RFC 1918 私有地址（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16）、链路本地地址（169.254.0.0/16、fe80::/10）、运营商级 NAT（100.64.0.0/10）、云元数据地址（169.254.169.254、metadata.google.internal）、IPv6 唯一本地地址（fc00::/7）、多播地址和 IPv4 映射的 IPv6 地址（::ffff:x.x.x.x）。
• 权威套接字查询（防止 DNS 重绑定）：连接套接字使用专用的安全感知查询钩子，确保 TCP 套接字只连接到已验证的公网 IP 地址，从而杜绝 DNS 重绑定中的检查时与使用时之间（TOCTOU）问题。
• 允许端口白名单：严格限制为标准公网 Web 端口：80、443、8080 和 8443。
• 手动重新验证重定向：手动跟随最多 5 次重定向（301、302、303、307、`308）。每个中间目标都会根据完整 URL、端口和 IP 安全策略重新验证。拒绝从 HTTPS 降级到 HTTP 的重定向。
• 不泄露 IP：返回给客户端的错误消息绝不会泄露内部 IP 地址、本地套接字详情或 DNS 拓扑。
• 限制资源使用：流式响应读取器只缓冲请求的 maxBytes 大小（默认 1 MiB，硬上限为 5 MiB）。如果负载超过限制，则返回 truncated: true 并立即销毁流。
• 严格的文本解码（GET）：对于 GET 请求，仅解码文本 MIME 类型（text/*、application/json、application/xml、application/javascript、application/xhtml+xml、application/yaml），并使用严格 UTF-8 解码（new TextDecoder("utf-8", { fatal: true })）。拒绝二进制正文和明确指定的非 UTF-8 编码。HEAD 请求不受正文解码限制，可检查二进制内容类型的元数据。

运维人员可配置的出站策略

服务运维人员可以执行额外的部署级出站策略，以限制出站网络能力：

1. 允许的主机名模式（--network-allow-host、MCP_NETWORK_ALLOW_HOSTS_JSON）：

   • 将出站网络限制为指定的精确主机名（example.com）或子域名通配符（*.githubusercontent.com）。
   • 可在命令行中重复指定，或在环境变量中指定为 JSON 字符串数组。
   • 如果已配置，则拒绝任何未列出的主机，并返回 host_not_allowed（“服务器网络策略不允许目标主机名。”）。

2. 禁止的主机名模式（--network-deny-host、MCP_NETWORK_DENY_HOSTS_JSON）：

   • 明确阻止指定的主机名或子域名通配符。
   • 禁止规则严格优先于允许规则：如果目标同时匹配允许和禁止模式，则拒绝该目标，并返回 host_denied（“服务器网络策略禁止目标主机名。”）。

3. 仅 HTTPS 模式（--network-https-only、MCP_NETWORK_HTTPS_ONLY）：

   • 强制所有出站请求使用加密 HTTPS。任何初始 http:// 目标或重定向目标都会被拒绝，并返回 https_required（“服务器网络策略要求使用 HTTPS。”）。

4. 运维人员资源上限：

   • --network-max-response-bytes（MCP_NETWORK_MAX_RESPONSE_BYTES）：限制最大响应大小（1 至 5,242,880 字节）。
   • --network-max-timeout-ms（MCP_NETWORK_MAX_TIMEOUT_MS）：限制最大请求超时时间（1,000 至 30,000 毫秒）。

重要

运维限制只能收紧策略：运维人员的配置绝不能削弱或覆盖内置的 SSRF 防护。即使列在 --network-allow-host 中，私有 IP、环回地址、链路本地地址、运营商级 NAT 和云元数据目标仍会被严格阻止。

条件 HTTP 响应缓存

可以为 fetch_url 启用可选的有界内存条件缓存，以减少频繁访问的公开 HTTPS 文档所产生的上游带宽消耗和延迟：

• 标志：--network-cache（MCP_NETWORK_CACHE_ENABLED=true）
• 保留期限与大小上限：
  • --network-cache-max-size-bytes=<n>（MCP_NETWORK_CACHE_MAX_SIZE_BYTES）：缓存负载的逻辑最大大小（1 KiB 至 64 MiB，默认 16 MiB）。
  • --network-cache-max-entries=<n>（MCP_NETWORK_CACHE_MAX_ENTRIES）：缓存条目的最大数量（1 至 512，默认 128）。
  • --network-cache-ttl-ms=<n>（MCP_NETWORK_CACHE_TTL_MS）：保留 TTL，以毫秒为单位（1,000 至 3,600,000 毫秒，默认 300,000 毫秒 / 5 分钟）。
• 强制重新验证不变量：缓存条目绝不会在未经重新验证的情况下离线提供。每次复用都会通过完整的安全网络传输流程向源站发送条件请求标头（If-None-Match、If-Modified-Since），该流程包括 SSRF 检查、DNS 重绑定查询、操作者策略和超时期限。
• 绝不回退到过期内容：如果源站无法访问、请求超时，或其 IP 地址变为私有 IP，则立即返回错误；绝不提供过期的缓存内容。
• 保护隐私的键：缓存键是规范化 HTTPS URL 的不透明 SHA-256 哈希值。不会存储明文 URL 和授权凭据。

---

命令行界面（CLI）

Usage:
  high-performance-mcp-server [options]

Options:
  --transport=<stdio|http>       Transport protocol to run (default: stdio)
  --port=<number>                HTTP server port (default: 3000, only for http transport)
  --profile=<profile>            Security tool profile (default: safe)
  --root=<path>                  Allowlisted workspace root (repeatable, max 16)
  --workspace-max-write-bytes=<n> Operator hard cap for text write/edit size in bytes (1-5242880, default: 1048576)
  --workspace-max-resource-bytes=<n> Operator hard cap for resource read size in bytes (1-5242880, default: 1048576)
  --workspace-write-confirmation Require client-mediated confirmation before text write/edit operations
  --network-allow-host=<pattern> Allowlisted public hostname or *.domain pattern (repeatable, operator restriction)
  --network-deny-host=<pattern>  Denylisted hostname or *.domain pattern (repeatable, operator restriction)
  --network-https-only           Enforce HTTPS-only mode for all network requests (operator restriction)
  --network-max-response-bytes=<n> Operator hard cap for response size in bytes (1-5242880, default: 5242880)
  --network-max-timeout-ms=<n>   Operator hard cap for request timeout in ms (1000-30000, default: 30000)
  --network-cache                Enable conditional in-memory response cache for fetch_url (operator restriction)
  --network-cache-max-size-bytes=<n> Logical max cache payload size in bytes (1024-67108864, default: 16777216)
  --network-cache-max-entries=<n> Max cache entry count (1-512, default: 128)
  --network-cache-ttl-ms=<n>     Max cache retention TTL in ms (1000-3600000, default: 300000)
  --log-level=<level>            Operational log level (debug|info|warn|error|off, default: info)
  --list-tools                   Display available tools for the active profile and exit
  --help, -h                     Show this help message and exit
  --version, -v                  Show version and exit

示例

# Start default safe server on stdio
high-performance-mcp-server

# Start with network profile, operator egress restrictions, and conditional cache
high-performance-mcp-server --profile=network \
  --network-allow-host=example.com \
  --network-allow-host="*.githubusercontent.com" \
  --network-https-only \
  --network-max-response-bytes=262144 \
  --network-max-timeout-ms=5000 \
  --network-cache \
  --network-cache-max-entries=256

# List tools available under the workspace profile
high-performance-mcp-server --profile=workspace --list-tools

# Run Streamable HTTP transport on port 8080 with workspace profile
high-performance-mcp-server --transport=http --port=8080 --profile=workspace --root=./project

---

HTTP 传输详情

使用 --transport=http 或 MCP_TRANSPORT=http 启动时，服务会使用 Node.js 内置的 node:http 启动 Streamable HTTP 传输：

• 优先级：--transport > MCP_TRANSPORT > 默认值（stdio）。
• 端点：http://127.0.0.1:<port>/mcp
• 适用范围：此传输配置仅适用于 CLI 可执行文件，不会更改程序化的 createServer API。
• 安全性：服务严格绑定到回环地址（127.0.0.1），并验证 Host 和 Origin 标头，以防范 DNS 重绑定和跨站请求伪造。
• 警告：如果没有身份验证反向代理或网关，请勿将 HTTP 传输直接暴露给不受信任的网络。

---

运行日志与级别

服务仅向 stderr 输出结构化 JSON Lines 运行日志：

• 日志级别：debug、info、warn、error、off（默认值：info）。
• 配置：可通过 --log-level=<level> CLI 标志或 MCP_LOG_LEVEL 环境变量进行配置。
• 根据时机确定优先级：
  • 导入时 / 静态初始化期间：MCP_LOG_LEVEL > 默认值（info）。
  • CLI 解析后：--log-level > MCP_LOG_LEVEL > 默认值（info）。
• 初始化说明：CLI 的 --log-level 标志无法追溯性地抑制 CLI 选项解析前静态模块加载期间发出的警告；如需抑制导入时的警告，请使用 MCP_LOG_LEVEL。
• Stdio 协议纯净性：在 stdio 传输模式下，stdout 完全保留给 MCP JSON-RPC 协议帧使用；运行日志不会输出到 stdout。
• 用户诊断信息：CLI 参数验证错误、用法帮助和致命进程崩溃仍会以易读的人类可读文本格式输出到 stderr，不会被 off 抑制。
• 隐私政策：运行日志不会主动记录工具参数负载、工具结果、文件正文、身份验证标头、原始请求正文或完整网络 URL。只有在明确将活动日志阈值配置为 debug 时，才会包含错误堆栈跟踪。

---

环境变量

请参阅 .env.example，其中包含所有受支持环境变量的即用型模板。

变量	类型	默认值	描述
MCP_PROFILE	string	safe	覆盖默认工具配置（safe、workspace、workspace_write、network、diagnostics、benchmark、admin、all）
MCP_TRANSPORT	string	stdio	覆盖传输协议（stdio、http）。CLI --transport 会覆盖此变量。
PORT	number	3000	覆盖默认 HTTP 端口（严格限制为 1–65535 的整数）
MCP_LOG_LEVEL	string	info	覆盖运行日志级别（debug、info、warn、error、off）
MCP_ROOTS_JSON	string	(无)	工作区根目录的 JSON 数组（例如 ["/home/user/project", "/home/user/docs"]）
MCP_WORKSPACE_MAX_WRITE_BYTES	number	1048576	覆盖运维人员设置的工作区写入大小上限（字节，1 至 5242880）
MCP_WORKSPACE_MAX_RESOURCE_BYTES	number	1048576	覆盖运维人员设置的工作区资源读取大小上限（字节，1 至 5242880）
MCP_WORKSPACE_WRITE_CONFIRMATION	boolean	false	要求客户端介导的写入/编辑审批（true/1/false/0）
MCP_NETWORK_ALLOW_HOSTS_JSON	string	(无)	允许的公共主机模式的 JSON 数组（例如 ["example.com","*.githubusercontent.com"]）
MCP_NETWORK_DENY_HOSTS_JSON	string	(无)	拒绝的主机模式的 JSON 数组（例如 ["ads.example.com"]）
MCP_NETWORK_HTTPS_ONLY	boolean	false	对所有网络请求强制启用仅 HTTPS 模式（true/1/false/0）
MCP_NETWORK_MAX_RESPONSE_BYTES	number	5242880	覆盖运维人员设置的响应字节数上限（1 至 5242880）
MCP_NETWORK_MAX_TIMEOUT_MS	number	30000	覆盖运维人员设置的请求超时上限（毫秒，1000 至 30000）
MCP_NETWORK_CACHE_ENABLED	boolean	false	启用条件式内存响应缓存（true/1/false/0）
MCP_NETWORK_CACHE_MAX_SIZE_BYTES	number	16777216	覆盖逻辑缓存负载大小上限（字节，1024 至 67108864）
MCP_NETWORK_CACHE_MAX_ENTRIES	number	128	覆盖缓存条目数上限（1 至 512）
MCP_NETWORK_CACHE_TTL_MS	number	300000	覆盖缓存保留时间 TTL 上限（毫秒，1000 至 3600000）
MCP_WORKER_COUNT	number	4	在线程池中创建的工作线程数（1 至 16）
MCP_CACHE_MAX_ENTRIES	number	256	LRU 计算缓存中的最大条目数（1 至 10000）
MCP_CACHE_TTL_MS	number	300000	LRU 计算缓存条目的生存时间（毫秒，5 分钟）

---

开发

# Install dependencies
npm install

# Run code generator and TypeScript typecheck
npm run typecheck

# Execute unit, security, search, and modern protocol integration test suites
npm test

# Build production bundle
npm run build

# Validate npm package payload without publishing
npm run pack:check

# Run package payload security & privacy scan
npm run security:package

# Run end-to-end tarball installation smoke test
npm run smoke:package

---

架构

MCP Clients (Claude Desktop, Cursor, Custom SDK Clients)
                       │
       ┌───────────────┴───────────────┐
       ▼                               ▼
  Stdio Transport             Streamable HTTP Transport
(process.stdin / stdout)         (127.0.0.1:3000/mcp)
       │                               │
       └───────────────┬───────────────┘
                       ▼
                McpServer Instance
      (Profile-Aware Server Instructions)
                       │
       ┌───────────────┴───────────────┐
       ▼                               ▼
  Tool & Prompt Profiles       Internal Telemetry
(safe, workspace, diag, ...)    (Metrics & Stderr Logger)
       │                               │
       ├──────► Read-Only Workspace, Search, Resources & Prompts (Allowlisted Roots, Host Privacy)
       │
       ├──────► In-Memory LRU Cache (Single-Flight Stampede Protection)
       │
       └──────► Reusable Worker Thread Pool (CPU Offloading)

---

安全

• 默认安全配置（safe）确保未经明确授权，不会暴露文件系统或硬件检查功能。
• 只读工作区访问会严格将文件访问限制在已配置的 --root 目录内，且不会泄露主机文件系统的绝对路径。
• 服务端说明和提示词通过字符转义，强化安全的工具调用顺序和明确的任务边界。
• Stdio 传输专门将 stdout 用于 JSON-RPC 消息；所有内部调试和遥测日志均写入 stderr。
• HTTP 传输会严格验证 localhost 来源和主机标头。

详情请参阅 SECURITY.md。

---

贡献与发布

欢迎贡献和反馈！有关代码风格、工具开发规范、测试要求和维护者发布工作流的详情，请阅读 CONTRIBUTING.md。

---

许可证

本项目采用 MIT License 授权。