High Performance MCP Server

High-Performance MCP Server

A high-performance, modular Model Context Protocol (MCP) server built with TypeScript and the modern MCP v2 SDK (@modelcontextprotocol/server). Features safe-by-default security profiles, profile-aware server instructions, modular MCP prompts, read-only workspace access with search and host path privacy, Streamable HTTP, Stdio transport, reusable worker thread pooling, production LRU caching with single-flight stampede protection, and structured telemetry.

---

Project Status: Public Preview (v0.1.0)

[!NOTE] Status: 0.1.0 Public Preview. This package provides safe-by-default MCP tools, read-only workspace inspection, and high-performance worker execution. Requires Node.js >= 22.0.0.

---

Features

• Modern MCP v2 Architecture: Built natively on @modelcontextprotocol/server with standard JSON Schema draft 2020-12 validation and full 2026-07-28 protocol support.
• Dual Transport Support: Run seamlessly over standard input/output (stdio) or modern Streamable HTTP (node:http + /mcp).
• Profile-Aware Server Instructions: Dynamic server instructions that guide connected LLMs on recommended workflows, tool sequencing, and safety boundaries based on the active profile.
• Modular MCP Prompts: Reusable task prompts (explore_workspace, find_and_explain, review_file, trace_symbol) exposed exclusively in workspace and all profiles.
• Safe-by-Default Tool Profiles: Default safe profile exposes zero filesystem or hardware inspection. Explicit opt-in for workspace, diagnostics, benchmark, admin, or all.
• Read-Only Workspace & Host Path Privacy: Secure allowlisted directory access with path traversal and symlink escape prevention, logical root mapping (root-1, root-2), 1 MiB hard limits, and binary file protection without exposing host absolute paths to clients or models.
• Workspace Search v1: Fast, bounded literal file and text search (search_files, search_text) with ignored directory defaults, bounded concurrency, coordinate mapping, and client cancellation.
• Worker Thread Pool: Offload CPU-heavy tasks from the Node.js event loop with automatic lifecycle recovery and zero-drift invariants.
• Production LRU Cache: Memory-bounded cache with TTL support and single-flight request coalescing to eliminate cache stampedes.
• Internal Structured Logging: Stdio-safe JSON logging exclusively on stderr.

---

Quick Start

MCP Client Configuration (Claude Desktop, Cursor, etc.)

Add to your MCP configuration (e.g. claude_desktop_config.json):

Default Safe Profile (Stdio)

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

Read-Only Workspace Profile

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

Local Development / Source Execution

# 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=.

---

Safe-by-Default Profiles

To protect host machines and prevent unintended resource consumption or metadata leakage, tools, resources, instructions, and prompts are categorized into security profiles:

---

Server Instructions & Prompts

Profile-Aware Server Instructions

When an MCP client connects, the server delivers concise, profile-tailored instructions via the MCP protocol:

• safe: Instructs the model that filesystem and hardware inspection are not available.
• workspace: Outlines the recommended investigation sequence (workspace_roots -> search_files / search_text -> file_info -> read_text_file), reinforces read-only constraints, and emphasizes root-relative path usage.
• diagnostics & benchmark: Guides observational metrics interpretation and warns against unnecessary CPU-intensive compute invocations.
• admin: Notes that mutation operations affect only process-local caches and telemetry state.

Modular MCP Prompts

When running in workspace or all profile, the server exposes modular prompts that provide structured workflows for common engineering tasks:

[!NOTE] Prompt arguments are treated as bounded task data and escaped before being inserted into reusable MCP prompt templates. Prompts do not execute direct filesystem I/O themselves; actual file reading and searching is performed by the model using standard MCP tools and resources under strict root allowlist controls.

---

Read-Only Workspace Access

Filesystem access is disabled by default. To enable read-only workspace access, explicitly specify --profile=workspace (or --profile=all) and at least one allowlisted --root directory:

# 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

Security Guarantees & Constraints

• Host Path Privacy: Configured absolute filesystem paths remain internal to the server. The workspace_roots tool and workspace://roots resource return logical root identifiers (id: "root-1", name: "my-project") rather than absolute host paths:

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

• Strict Allowlist: Only explicitly passed --root directories can be accessed. Maximum 16 unique roots allowed (and max 64 raw paths before deduplication).
• Read-Only: No filesystem mutation functions (writeFile, unlink, rm, mkdir, rename, etc.) exist in the server codebase.
• Traversal & Symlink Protection: Target paths are canonicalized using fs.realpath and strictly verified to never escape root boundaries.
• Sanitized Errors: Error responses reference only logical root IDs, root names, and requested relative paths, ensuring internal directory structures are never leaked.
• File Read Limits: Default text read limit is 256 KiB; hard upper limit is 1 MiB (MAX_TEXT_READ_BYTES).
• Binary File Detection: Files containing NUL bytes (\0) are rejected by read_text_file to prevent context pollution.
• MCP Resources: Exposes workspace://roots (static list of roots) and workspace://file/{rootId}{?path} (dynamic text reader).

Searching the Workspace

The workspace profile provides bounded, read-only search tools:

1. search_files:

   • Searches file and directory names using literal substring matching.
   • Filters by kind (file, directory, all), case sensitivity, and start path.
   • Skips common build/vendor directories (.git, node_modules, .next, dist, build, target, etc.) by default. Pass includeIgnored: true to search them.
   • Never traverses into symlink/junction directories to prevent recursion cycles and escapes.

2. search_text:

   • Searches UTF-8 text files using bounded literal matching with fixed concurrency (8 workers).
   • Returns 1-based line, column, and trimmed preview snippets (up to 300 characters).
   • Supports file extension filters (e.g. extensions: [".ts", ".md"] or extensions: ["ts", "md"]).
   • Automatically skips binary files (NUL bytes) and files larger than 1 MiB (MAX_SEARCH_FILE_BYTES).
   • Limits: Hard defaults (maxResults: 100 [max 500], maxFiles: 5000 [max 50000], timeoutMs: 10000 [max 30000]).
   • Fully cancellable via client AbortSignal.

---

Command Line Interface (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

Examples

# 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 Details

When started with --transport=http, the server launches a Streamable HTTP transport using Node.js built-in node:http:

• Endpoint: http://127.0.0.1:<port>/mcp
• Security: The server binds strictly to 127.0.0.1 and validates Host and Origin headers to protect against DNS rebinding and cross-site request forgery.
• Warning: Do not expose the HTTP transport directly to untrusted networks without an authenticating reverse proxy or gateway.

---

Environment Variables

---

Development

# 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

---

Architecture

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)

---

Security

• Default security profile (safe) ensures no filesystem or hardware inspection is exposed without explicit opt-in.
• Read-only workspace access strictly isolates file access to configured --root directories without revealing host filesystem absolute paths.
• Server instructions and prompts reinforce safe tool sequencing and explicit task boundaries with character escaping.
• Stdio transport reserves stdout exclusively for JSON-RPC messages; all internal debug and telemetry logs route to stderr.
• HTTP transport enforces strict localhost origin and host header validation.

For details, review SECURITY.md.

---

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on our code style, test requirements, and contribution guidelines.

---

License

This project is licensed under the MIT License.