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: