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, allowlisted workspace inspection with opt-in guarded text mutation, SSRF-hardened network access, Streamable HTTP, Stdio transport, reusable worker thread pooling, production LRU caching with single-flight stampede protection, and structured telemetry.

---

Project Status: Public Preview (v0.5.0)

[!NOTE] Status: 0.5.0 Public Preview. This package provides safe-by-default MCP tools, read-only workspace inspection, opt-in guarded workspace mutation and network access, worker request cancellation, normalized progress reporting, and high-performance worker execution. Requires Node.js >= 22.0.0.

Compatibility: The new v0.5 options are additive. Existing callers that omit contextLines, maxDepth, createParents, and fetch_url.method retain their established default semantics. v0.5 also includes an intentional create-mode publication hardening: filesystems that cannot provide hard-link no-clobber publication now fail closed instead of using the previous check-then-rename fallback.

---

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, workspace_write, and all profiles.
• MCP-Native Workspace Completions: Autocompletes logical rootId values for every workspace prompt and the workspace resource template without enumerating files or exposing host paths.
• Safe-by-Default Tool Profiles: Default safe profile exposes zero filesystem, network, or hardware inspection. Filesystem mutation and outbound network access require explicit workspace_write/network (or all) opt-in.
• Workspace Security & Host Path Privacy: Secure allowlisted directory access with path traversal and symlink escape prevention, logical root mapping (root-1, root-2), bounded text operations, and binary file protection without exposing host absolute paths to clients or models. The workspace profile remains read-only; guarded mutation is isolated to workspace_write and all.
• Workspace Search & Exploration: Fast, bounded literal file and text search (search_files, search_text) with ignored directory defaults, bounded concurrency (SEARCH_CONCURRENCY = 8), coordinate mapping, optional bounded context lines (contextLines: 0..10), and client cancellation.
• Recursive Directory Listing: Bounded recursive subdirectory traversal (list_directory with maxDepth: 1..5) using breadth-first search and normalized relative paths up to a global 500-entry cap.
• Guarded Workspace Mutation & Safe Parent Creation: Transactional editing (edit_text_file) and atomic no-clobber creation (write_text_file) with optional safe segment-by-segment parent creation (createParents), optimistic SHA-256 concurrency control, and optional client confirmation.
• Safe Network Fetch & Metadata: Outbound HTTP/HTTPS fetching (fetch_url) protected by multi-layered SSRF defenses, DNS rebinding mitigation, port allowlists, conditional response caching, and lightweight HTTP HEAD metadata inspection.
• Worker Thread Pool with Cancellation: Offload CPU-heavy tasks from the Node.js event loop with automatic lifecycle recovery, AbortSignal cancellation support, and prompt hard termination for running synchronous compute.
• Normalized MCP Progress Reporting: High-performance progress notifications across workspace search and compute worker tools with guaranteed in-order delivery and zero overhead when omitted.
• 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"
      ]
    }
  }
}

MCP Inspector Testing

For local testing and interactive debugging with @modelcontextprotocol/inspector, refer to the configuration template in examples/inspector-workspace.example.json.

Local Development / Source Execution

# 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 Transport & Health Endpoint

The server can run over Streamable HTTP on loopback:

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

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

When running with HTTP transport (--transport=http or MCP_TRANSPORT=http):

• Protocol Endpoint: http://127.0.0.1:3000/mcp (Streamable HTTP protocol handler)
• Health Endpoint: http://127.0.0.1:3000/healthz (operational liveness probe)

Loopback Security & Health Contract

• Loopback-Only Binding: The HTTP server binds exclusively to 127.0.0.1. Remote binding, TLS termination, and external network exposures are not supported.
• Host & Origin Guards: DNS-rebinding (localhostHostValidation) and browser CSRF (localhostOriginValidation) protections remain active across all routes, including /healthz.
• Supported Methods:
  • GET /healthz: Returns 200 OK with {"status":"ok"} (Content-Type: application/json; charset=utf-8, Cache-Control: no-store).
  • HEAD /healthz: Returns 200 OK with identical headers and an empty body.
  • Unsupported methods (POST, PUT, DELETE, etc.) return 405 Method Not Allowed with Allow: GET, HEAD.
• Zero Side Effects: Probing /healthz performs a constant-time local check. It creates no MCP sessions, incurs no worker thread allocations, touches no filesystem or network resources, and mutates no metrics.
• Orchestration / Supervisors: For local container or process supervisors (e.g. Docker HEALTHCHECK or Kubernetes probes), operators may point both liveness and readiness probes to /healthz (example command: curl -f -s http://127.0.0.1:3000/healthz). There is no separate /readyz endpoint because all server initialization is synchronous and in-memory upon successful port listen.

---

Programmatic Node.js Usage

The server can be embedded directly into Node.js applications (ESM-only, 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();

[!NOTE]

• Multiple server instances in the same Node.js process share process-global compute cache, worker pool, and metrics.
• Local WorkspaceConfig objects may contain canonical absolute filesystem paths for local host validation; physical host paths are never exposed over remote MCP client protocols.

---

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:

Profile	Included Categories	Exposed Tools	Prompts	Use Case
safe (Default)	safe	echo, ping	(none)	Zero host inspection, zero filesystem access, zero mutation. Safe for public exposure.
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	Read-only file and directory inspection strictly limited to allowlisted --root directories.
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	Guarded workspace text file creation, overwriting, and transactional editing with optimistic concurrency.
network	safe, network	echo, ping, fetch_url	(none)	SSRF-hardened, read-only HTTP/HTTPS web fetching for public resources.
diagnostics	safe, diagnostics	echo, ping, cache_stats, server_metrics, system_stats, worker_pool_stats	(none)	Process and system observability for monitoring health and event-loop lag.
benchmark	safe, benchmark	echo, ping, cached_prime_count, heavy_compute_main, heavy_compute_worker	(none)	CPU-intensive prime calculation benchmarks and worker pool tests.
admin	safe, diagnostics, admin	echo, ping, cache_stats, server_metrics, system_stats, worker_pool_stats, reset_cache, reset_metrics	(none)	Observability with administrative runtime state mutation (purging cache, resetting metrics).
all	safe, workspace, workspace_write, network, diagnostics, benchmark, admin	All 20 registered tools	All 4 workspace prompts	Complete tool and prompt catalog.

---

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, workspace_write, or all profile, the server exposes modular prompts that provide structured workflows for common engineering tasks:

Prompt	Arguments	Purpose
explore_workspace	rootId (required), goal (optional)	Guides the model through structured exploration of an allowlisted workspace root using search and file inspection.
find_and_explain	rootId (required), query (required)	Locates relevant code or configuration using literal text search and reads defining files to produce an explanation.
review_file	rootId (required), path (required), focus (optional)	Formulates a structured, read-only review of a specified text file within the workspace.
trace_symbol	rootId (required), symbol (required)	Traces declarations, references, and usage sites of a symbol across the workspace.

[!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.

Workspace Root Completions

Workspace-capable profiles advertise MCP's completions capability. Clients can request completion/complete suggestions for the rootId argument on all four workspace prompts and for the rootId variable in workspace:///{rootId}/{+path}. Suggestions contain only configured logical IDs such as root-1; they never enumerate files or reveal root names and absolute host paths. Profiles without workspace authority do not advertise completion support.

---

Read-Only Workspace Access

Filesystem access is disabled by default. To enable read-only workspace access, explicitly specify --profile=workspace and at least one allowlisted --root directory. The broader all profile also includes these tools but additionally enables mutation, network, diagnostics, benchmark, and admin capabilities.

# 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 returns logical root identifiers (id: "root-1", `name: "my-project"), and workspace resource URIs use those identifiers 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 Profile: The standard workspace profile exposes no mutation tools. Guarded text mutation is available only through the explicit workspace_write and all profiles; no MCP tools expose deletion, arbitrary rename, directory creation, permission changes, or command execution.
• 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 the canonical workspace:///{rootId}/{+path} (workspace_text_file) template. Discover logical roots with workspace_roots; resources/list does not recursively enumerate files.

Inspecting Directories & Files

The workspace profile provides bounded file and directory inspection tools:

1. list_directory:

   • Lists directory contents within an allowlisted workspace root up to a global 500-entry cap (truncated: true when exceeded).
   • Bounded Recursive Traversal: Optional maxDepth parameter (1..5, default: 1). When maxDepth > 1, directory trees are traversed breadth-first (BFS) up to the specified depth and returned as a flat list.
   • Relative Path Output: In recursive mode, entries include a normalized relativePath with forward-slash separators (/), while name preserves the entry's basename.
   • Deterministic Sorting: Existing comparator behavior is preserved across directory entries.

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

2. file_info: Retrieves size, timestamps, and file type attributes for a relative path within an allowlisted root.

3. read_text_file: Reads UTF-8 file contents up to the configured byte limit (default 256 KiB, max 1 MiB). Files containing NUL bytes are rejected.

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.
   • Streams native MCP progress notifications (notifications/progress) when a client progressToken is provided.

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.
   • Streams native MCP progress notifications (notifications/progress) when requested via progressToken. Zero progress overhead when unrequested.
   • Bounded Context Lines: Optional contextLines parameter (0..10, default: 0). When contextLines > 0, matching occurrences include contextBefore and contextAfter as bounded string arrays of surrounding lines. When omitted or 0, context fields are omitted. Unbounded context is not supported.

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

---

Guarded Workspace Text Write & Edit (workspace_write)

Workspace mutation is disabled by default. The standard workspace profile remains strictly read-only. To enable guarded text write and transactional editing capabilities, explicitly select the workspace_write profile (or all) along with at least one allowlisted --root:

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

Mutation Tools

[!WARNING] When running with --profile=all or --profile=workspace_write, connected clients and LLMs have guarded text write and edit capabilities within configured --root directories. The standard --profile=workspace remains strictly read-only.

1. write_text_file:

   • Create Mode (mode: "create"): Creates a new UTF-8 text file inside an allowlisted workspace root. Enforces atomic no-clobber semantics via fs.link; fails safely if the file already exists (already_exists) or if the parent directory does not exist (missing_parent). Providing expectedSha256 in create mode is forbidden.
   • Safe Parent Directory Creation: Optional createParents?: boolean (default: false). When true, missing parent directories within the workspace root are created segment-by-segment with strict canonical realpath containment validation. Only valid for mode: "create" (specifying createParents in mode: "overwrite" is rejected as schema-invalid). When write confirmation is enabled, confirmation occurs strictly before any directory creation or filesystem mutation. If final file publication fails, created parent directories may remain as partial side effects. Final file publication retains atomic no-clobber hard-link semantics on supported filesystems; parent-directory creation itself is not fully atomic.
   • No-Clobber Fail-Closed Hardening: Create-mode file publication no longer falls back to an unsafe check-then-rename path when hard-link publication is unavailable. fs.link is the create publication primitive; unsupported hard-link publication fails closed without overwriting existing files, and unexpected native filesystem errors are sanitized.
   • Overwrite Mode (mode: "overwrite"): Strictly requires expectedSha256 (64-character lowercase hex) matching the file's current SHA-256 hash. If the file was modified concurrently, throws content_conflict and aborts without touching the target file.
   • Exclusive Temp & Atomic Replacement: Creates an exclusive temporary file (.mcp-temp-<uuid>.tmp) in the target directory (O_CREAT | O_EXCL), flushes to disk (fsync), re-validates the target file type and hash, and atomically replaces the destination.

   {
     "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:

   • Exact Literal Replacement: Performs targeted, sequential in-memory text replacements without regex or special token expansion (e.g. $$, $1, $&, $\``, $'` are inserted verbatim).
   • Non-Overlapping Occurrence Guarantees: Evaluates expectedOccurrences (default: 1) using non-overlapping literal matching matching the exact replacement semantics.
   • Transactional Execution: Applies all edits sequentially in memory. If any edit fails its expectedOccurrences check or if the file hash mismatches expectedSha256, the operation aborts and the disk file remains 100% untouched.
   • Strict UTF-8 & BOM Preservation: Non-UTF-8 binary files are rejected (invalid_text_encoding). Existing UTF-8 BOM headers and CRLF line endings are preserved with byte-for-byte fidelity.

   {
     "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
         }
       ]
     }
   }
   

Operator-Configurable Write Limits

Server operators can set strict hard caps on the maximum allowed write or edit payload size in bytes:

• CLI flag: --workspace-max-write-bytes=<bytes> (1 to 5,242,880 bytes / 5 MiB, default: 1048576 / 1 MiB)
• Environment variable: MCP_WORKSPACE_MAX_WRITE_BYTES=<bytes>

Metadata & Concurrency Considerations