高性能 MCP 服务器

一个高性能、模块化的模型上下文协议（MCP）服务器，使用 TypeScript 和现代 MCP v2 SDK（@modelcontextprotocol/server）构建。具有默认安全的安全配置文件、配置文件感知的服务器指令、模块化 MCP 提示词、只读工作区访问（支持搜索和主机路径隐私）、Streamable HTTP、Stdio 传输、可复用的工作线程池、带单飞击穿保护的生产级 LRU 缓存以及结构化遥测。

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

[!NOTE] 状态：0.1.0 公开预览。 此包提供默认安全的 MCP 工具、只读工作区检查和高效的工作线程执行。需要 Node.js >= 22.0.0。

Related MCP server: VSCode LSP MCP Server

特性

• 现代 MCP v2 架构：原生基于 @modelcontextprotocol/server，支持标准 JSON Schema draft 2020-12 验证和完整的 2026-07-28 协议支持。

• 双传输支持：可通过标准输入/输出（stdio）或现代 Streamable HTTP（node:http + /mcp）无缝运行。

• 配置文件感知的服务器指令：根据活动配置文件，向连接的 LLM 提供动态服务器指令，指导推荐工作流程、工具顺序和安全边界。

• 模块化 MCP 提示词：可复用的任务提示词（explore_workspace、find_and_explain、review_file、trace_symbol）仅在 workspace 和 all 配置文件中公开。

• 默认安全的工具配置文件：默认的 safe 配置文件不暴露任何文件系统或硬件检查。明确选择 workspace、diagnostics、benchmark、admin 或 all。

• 只读工作区与主机路径隐私：安全的允许列表目录访问，具有路径遍历和符号链接逃逸防护、逻辑根映射（root-1、root-2）、1 MiB 硬限制以及二进制文件保护，不会向客户端或模型暴露主机绝对路径。

• 工作区搜索 v1：快速、有界字面量文件与文本搜索（search_files、search_text），具有默认忽略目录、有界并发、坐标映射和客户端取消功能。

• 工作线程池：将 CPU 密集型任务从 Node.js 事件循环中卸载，具有自动生命周期恢复和零漂移不变量。

• 生产级 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"
      ]
    }
  }
}

本地开发 / 源码运行

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

# Run default safe profile
node dist/index.js

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

默认安全的配置文件

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

服务器指令与提示词

配置文件感知的服务器指令

当 MCP 客户端连接时，服务器通过 MCP 协议提供简洁、按配置文件定制的指令：

• safe：告知模型文件系统和硬件检查不可用。

• workspace：概述推荐的调查顺序（workspace_roots -> search_files / search_text -> file_info -> read_text_file），强调只读约束，并强调使用根相对路径。

• diagnostics 和 benchmark：指导观测指标的解读，并警告不要进行不必要的 CPU 密集型计算调用。

• admin：说明变更操作仅影响进程本地缓存和遥测状态。

模块化 MCP 提示词

在 workspace 或 all 配置文件下运行时，服务器公开模块化提示词，为常见工程任务提供结构化工作流程：

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

只读工作区访问

文件系统访问默认禁用。要启用只读工作区访问，请明确指定 --profile=workspace（或 --profile=all）以及至少一个允许列表 --root 目录：

# 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 工具和 workspace://roots 资源返回逻辑根标识符（id: "root-1"、name: "my-project"）而不是绝对主机路径：

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

• 严格允许列表：只能访问明确传递的 --root 目录。最多允许 16 个唯一根（去重前最多 64 个原始路径）。

• 只读：服务器代码库中不存在文件系统修改函数（writeFile、unlink、rm、mkdir、rename 等）。

• 遍历与符号链接保护：目标路径使用 fs.realpath 进行规范化处理，并严格验证永远不会逃逸根边界。

• 清理后的错误：错误响应仅引用逻辑根 ID、根名称和请求的相对路径，确保内部目录结构永远不会泄漏。

• 文件读取限制：默认文本读取限制为 256 KiB；硬上限为 1 MiB（MAX_TEXT_READ_BYTES）。

• 二进制文件检测：包含 NUL 字节（\0）的文件会被 read_text_file 拒绝，以防止上下文污染。

• MCP 资源：公开 workspace://roots（静态根列表）和 workspace://file/{rootId}{?path}（动态文本读取器）。

搜索工作区

workspace 配置文件提供有界、只读的搜索工具：

1. search_files：

   • 使用字面量子字符串匹配搜索文件和目录名称。

   • 按种类（file、directory、all）、大小写敏感性和起始路径进行过滤。

   • 默认跳过常见构建/供应商目录（.git、node_modules、.next、dist、build、target 等）。传入 includeIgnored: true 可搜索它们。

   • 从不进入符号链接/接合目录，以防止递归循环和逃逸。

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 完全取消。

命令行界面（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 read-only workspace root (repeatable, max 16)
  --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

# 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 启动时，服务器使用 Node.js 内置的 node:http 启动 Streamable HTTP 传输：

• 端点：http://127.0.0.1:<port>/mcp

• 安全：服务器严格绑定到 127.0.0.1，并验证 Host 和 Origin 标头，以防止 DNS 重绑定和跨站请求伪造。

• 警告：在没有身份验证反向代理或网关的情况下，请勿将 HTTP 传输直接暴露给不受信任的网络。

环境变量

开发

# 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 许可证 授权。