고성능 MCP 서버

TypeScript와 최신 MCP v2 SDK(@modelcontextprotocol/server)로 구축된 고성능·모듈형 Model Context Protocol(MCP) 서버입니다. 기본적으로 안전한 보안 프로필, 프로필 인지형 서버 지침, 모듈형 MCP 프롬프트, 검색 및 호스트 경로 프라이버시를 지원하는 읽기 전용 워크스페이스 액세스, Streamable HTTP, Stdio 전송, 재사용 가능한 워커 스레드 풀, 단일 비행(single-flight) 스탬피드 방지 기능을 갖춘 프로덕션 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에 바인딩되며 DNS 리바인딩 및 교차 사이트 요청 위조를 방지하기 위해 Host 및 Origin 헤더를 검증합니다.

• 경고: 인증 역방향 프록시 또는 게이트웨이 없이 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 전송은 JSON-RPC 메시지 전용으로 stdout을 예약하며, 모든 내부 디버그 및 텔레메트리 로그는 stderr로 라우팅됩니다.

• HTTP 전송은 엄격한 localhost 출처 및 호스트 헤더 검증을 적용합니다.

자세한 내용은 SECURITY.md를 검토하세요.

기여

기여는 환영합니다! 코드 스타일, 테스트 요구 사항 및 기여 지침에 대한 자세한 내용은 CONTRIBUTING.md를 읽어주세요.

라이선스

이 프로젝트는 MIT License에 따라 라이선스가 부여됩니다.