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)

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();

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

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:
  json

  {
    "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.
   json

   {
     "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.
   json

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

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.
   json

   {
     "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.
   json

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

• Atomic Replacement Metadata: Atomic replacement creates a new filesystem entry, preserving POSIX permission bits (0755, 0644) where supported. Other OS-specific metadata (e.g. inode number, creation timestamp ctime, ACL inheritance) may not be portably preserved.
• Residual Concurrency Boundaries: Pre-replace revalidation minimizes TOCTOU race conditions against untrusted MCP callers. However, a hostile local OS process with equivalent filesystem privileges executing concurrent writes in the microseconds after final validation may still race path-based operations. Equal-privilege local filesystem races remain a residual threat model.
• Path Indirection & Boundary Checks: Path containment relies on canonical fs.realpath resolution within configured root boundaries.
• Fail-Closed Hard-Link Publication: Where filesystems or operating environments do not support atomic fs.link hard-link publication, create-mode writes fail closed without clobbering existing files.

Optional Client-Mediated Write Confirmation

Confirmation is off by default. Enable it for both mutation tools with the operator-only --workspace-write-confirmation flag, or MCP_WORKSPACE_WRITE_CONFIRMATION=true (true/1/false/0). The CLI flag enables confirmation even if the environment says false; tool arguments cannot disable it. No tools are added and profile access stays unchanged.

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

The server validates the target, then asks the client to show a form containing a confirm boolean. Only an accepted response with confirm: true proceeds. Decline, cancel, false, and malformed accepted content leave the file unchanged. No temporary file is created while approval is pending. The normal root, size, exact-edit, and SHA-256 checks still run after approval, including when a file changes during the prompt.

The prompt identifies the operation and canonical logical rootId/relative path; it does not display file content, expected hashes, root names, or absolute host paths. Control and bidirectional formatting characters are escaped. Targets over 4,096 characters are refused instead of silently truncated. Response keys include the proposed arguments and resolved logical target so a changed proposal asks again.

With confirmation disabled, existing modern and legacy calls behave as before. Use a client that actually presents the form to a human: elicitation is a client-mediated safeguard, not authentication or a security boundary against a malicious client. The server cannot prove that a human approved a client-supplied response. Direct service-level embedding is also outside this MCP handler gate. For protocol details, see the official SDK input-required guide.

MCP Workspace Resources

In addition to workspace inspection tools, this server natively exposes allowlisted workspace text files as standard MCP Resources using the official URI Template:

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

Canonical Resource URI Format

Workspace resources use a stable, portable URI scheme based on logical root IDs rather than host filesystem paths:

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

Host absolute paths (such as file:///C:/... or /home/...) are never exposed in resource URIs, titles, or error messages.

Resource Invariants & Security Guarantees

• Profile Gated: Workspace resources are exposed exclusively in workspace-capable profiles (workspace, workspace_write, all). In non-workspace profiles (safe, network, diagnostics, benchmark, admin), resource endpoints return Method not found and zero workspace existence is advertised.
• Strict Read-Only: Resources are strictly read-only. Possessing a resource URI never grants mutation rights or filesystem write capabilities.
• Root & Symlink Confinement: Resource reads reuse the central workspace security resolver, enforcing strict containment inside configured --root directories and blocking symlink/junction escapes.
• Complete-or-Error Semantics: Resources are never silently truncated. If a file exceeds the operator byte limit, the read is rejected with resource_too_large.
• Strict UTF-8 & Text Only: All resource content is decoded strictly as UTF-8 text (fatal: true). Files containing NUL bytes (0x00) or non-UTF-8 sequences are rejected as unsupported binary files (invalid_text_encoding).
• No Recursive Enumeration: resources/templates/list advertises the resource template (workspace_text_file). The server does not recursively crawl repository directories for resources/list, preventing latency, memory spikes, and information disclosure on large repositories.
• Operator-Configurable Resource Size Limits:
  • CLI flag: --workspace-max-resource-bytes=<bytes> (1 to 5,242,880 bytes / 5 MiB, default: 1048576 / 1 MiB)
  • Environment variable: MCP_WORKSPACE_MAX_RESOURCE_BYTES=<bytes>

Recommended Client Workflow

1. Discovery: Discover available root IDs and paths using workspace_roots, list_directory, or search_files.
2. Read Resource: Consume text files directly via standard MCP resources/read using workspace:///<rootId>/<path>.
3. Guarded Mutation: When mutations are needed, use read_text_file to obtain the authoritative sha256 hash and perform concurrency-controlled edits via write_text_file or edit_text_file in the workspace_write profile.

Network Access & fetch_url

Network access is disabled by default. To enable SSRF-hardened read-only web fetching, run with --profile=network (or --profile=all):

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

fetch_url Tool Details

The fetch_url tool performs strictly bounded, read-only HTTP/HTTPS requests to public web resources.

• Supported Methods: Optional method parameter accepts "GET" (default) or "HEAD". Arbitrary HTTP verbs (POST, PUT, DELETE, PATCH, OPTIONS) are rejected at the schema boundary.
• HEAD Metadata Support: When method: "HEAD" is specified, the server issues a native HEAD request reusing the exact same SSRF, DNS multi-answer validation, socket pinning, and redirect policy as GET. Representation bodies are not consumed (bytesRead: 0, truncated: false, body: undefined). Content-Length is reported as server-declared representation length metadata, not downloaded bytes. Bypasses text-body decoding constraints, enabling metadata retrieval for binary assets (image/png, application/pdf, application/octet-stream) and compressed content (Content-Encoding: gzip).
• Redirect Method Preservation: Retains the requested HTTP method (GET or HEAD) across all redirect hops (301, 302, 303, 307, 308). Specifically, HEAD with 303 See Other remains HEAD at the destination.
• Conditional Cache Isolation: GET and HEAD cache entries are strictly isolated using separate preimages; neither method can satisfy or pollute the other. Existing GET cache key identity is preserved (network-fetch-v1\0<canonicalUrl>). Conditional 304 Not Modified revalidation on HEAD returns cached original status and statusText with omitted body and revalidationStatus: 304.

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

Security Guarantees & Constraints

• Multi-Layered SSRF Defense: All resolved IP addresses are evaluated against standard IPv4/IPv6 private and special-use subnets (net.BlockList). Loopback (127.0.0.0/8, ::1), private RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), link-local (169.254.0.0/16, fe80::/10), carrier-grade NAT (100.64.0.0/10), cloud metadata (169.254.169.254, metadata.google.internal), unique-local IPv6 (fc00::/7), multicast, and IPv4-mapped IPv6 (::ffff:x.x.x.x) destinations are strictly blocked.
• Authoritative Socket Lookup (DNS Rebinding Prevention): Connection sockets use a dedicated, security-aware lookup hook ensuring TCP sockets connect only to verified public IP addresses, eliminating time-of-check to time-of-use (TOCTOU) DNS rebinding.
• Allowed Port Allowlist: Strictly limited to standard public web ports: 80, 443, 8080, and 8443.
• Manual Redirect Re-validation: Up to 5 redirects (301, 302, 303, 307, 308) are manually followed. Every intermediate target is re-validated against full URL, port, and IP security policies. HTTPS-to-HTTP downgrade redirects are rejected.
• Zero IP Disclosure: Error messages returned to clients never leak internal IP addresses, local socket details, or DNS topologies.
• Bounded Resource Usage: Streaming response reader buffers only up to requested maxBytes (default 1 MiB, hard maximum 5 MiB). If payload exceeds limit, truncated: true is returned and the stream is immediately destroyed.
• Strict Textual Decoding (GET): For GET requests, decodes exclusively textual MIME types (text/*, application/json, application/xml, application/javascript, application/xhtml+xml, application/yaml) with fatal UTF-8 decoding (new TextDecoder("utf-8", { fatal: true })). Binary bodies and explicit non-UTF-8 encodings are rejected. HEAD requests bypass body decoding restrictions and allow metadata inspection of binary content types.

Operator-Configurable Egress Policy

Server operators can enforce additional deployment-level egress policies to restrict outbound network capabilities:

1. Allowed Hostname Patterns (--network-allow-host, MCP_NETWORK_ALLOW_HOSTS_JSON):

   • Limits network egress exclusively to specified exact hostnames (example.com) or subdomain wildcards (*.githubusercontent.com).
   • Repeatable on CLI or specified as a JSON string array in environment variables.
   • If configured, any unlisted host is rejected with host_not_allowed ("Destination hostname is not allowed by server network policy.").

2. Denied Hostname Patterns (--network-deny-host, MCP_NETWORK_DENY_HOSTS_JSON):

   • Explicitly blocks specified hostnames or subdomain wildcards.
   • Deny takes strict precedence over allow: If a destination matches both allow and deny patterns, it is rejected with host_denied ("Destination hostname is denied by server network policy.").

3. HTTPS-Only Mode (--network-https-only, MCP_NETWORK_HTTPS_ONLY):

   • Enforces encrypted HTTPS for all outbound requests. Any http:// initial target or redirect destination is rejected with https_required ("HTTPS is required by server network policy.").

4. Operator Resource Caps:

   • --network-max-response-bytes (MCP_NETWORK_MAX_RESPONSE_BYTES): Clamps the maximum response size (1 to 5,242,880 bytes).
   • --network-max-timeout-ms (MCP_NETWORK_MAX_TIMEOUT_MS): Clamps the maximum request timeout (1,000 to 30,000 ms).

Conditional HTTP Response Cache

An optional, bounded, in-memory conditional cache can be enabled for fetch_url to reduce upstream bandwidth and latency for frequently accessed public HTTPS documents:

• Flag: --network-cache (MCP_NETWORK_CACHE_ENABLED=true)
• Retention & Sizing Caps:
  • --network-cache-max-size-bytes=<n> (MCP_NETWORK_CACHE_MAX_SIZE_BYTES): Logical max cache payload size (1 KiB to 64 MiB, default 16 MiB).
  • --network-cache-max-entries=<n> (MCP_NETWORK_CACHE_MAX_ENTRIES): Maximum cached entries (1 to 512, default 128).
  • --network-cache-ttl-ms=<n> (MCP_NETWORK_CACHE_TTL_MS): Retention TTL in ms (1,000 to 3,600,000 ms, default 300,000 ms / 5 minutes).
• Mandatory Revalidation Invariant: Cached entries are never served offline without revalidation. Every reuse sends conditional headers (If-None-Match, If-Modified-Since) to the origin over the full secure network transport (SSRF checks, DNS rebinding lookup, operator policy, and timeout deadline).
• Zero Stale Fallback: If the origin is unreachable, times out, or changes to a private IP, the error is immediately returned; stale cached content is never served.
• Privacy-Preserving Keys: Cache keys are opaque SHA-256 hashes of canonical HTTPS URLs. Plaintext URLs and authorization credentials are never stored.

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

Examples

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

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

• Precedence: --transport > MCP_TRANSPORT > default (stdio).
• Endpoint: http://127.0.0.1:<port>/mcp
• Scope: The transport configuration applies exclusively to the CLI executable and does not alter the programmatic createServer API.
• Security: The server binds strictly to loopback (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.

Operational Logging & Levels

The server emits structured JSON Lines operational logs exclusively to stderr:

• Log Levels: debug, info, warn, error, off (default: info).
• Configuration: Configurable via the --log-level=<level> CLI flag or MCP_LOG_LEVEL environment variable.
• Timing-Aware Precedence:
  • Import-Time / Static Initialization: MCP_LOG_LEVEL > default (info).
  • Post-CLI-Parse: --log-level > MCP_LOG_LEVEL > default (info).
• Initialization Note: The CLI --log-level flag cannot retroactively suppress warnings emitted during static module loading prior to CLI option parsing; use MCP_LOG_LEVEL when suppression of import-time warnings is required.
• Stdio Protocol Purity: In stdio transport mode, stdout is 100% reserved for MCP JSON-RPC protocol framing; zero operational logs enter stdout.
• User Diagnostics: CLI argument validation errors, usage help, and fatal process crashes remain formatted human-readable text on stderr and are not suppressed by off.
• Privacy Policy: Operational logs never intentionally record tool argument payloads, tool results, file bodies, authentication headers, raw request bodies, or full network URLs. Error stack traces are only included when the active log threshold is explicitly configured to debug.

Environment Variables

See .env.example for a ready-to-use template containing all supported 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 & Releases

Contributions and feedback are welcome! Please read CONTRIBUTING.md for details on code style, tool development conventions, testing requirements, and the maintainer release workflow.

License

This project is licensed under the MIT License.