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, 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.7.0)

[!NOTE]

Status: 0.7.0 Public Preview.

This package provides safe-by-default MCP tools, read-only workspace inspection, opt-in guarded workspace mutation and network access, programmatic Node.js library embedding with operator policies, loopback HTTP health probes (/healthz) and opt-in observability dashboard (/dashboard), structured operational log levels, worker request cancellation, normalized progress reporting, and high-performance worker execution. Requires Node.js >= 22.0.0.

Compatibility: All v0.7 options (includeSha256 on file_info, extensions on search_files, excludeIgnored on list_directory) are additive. Existing callers that omit them retain their established default semantics.

---

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)
• Observability Dashboard *(opt-in via --dashboard or MCP_DASHBOARD=true)*: http://127.0.0.1:3000/dashboard (zero-dependency, read-only live telemetry UI and /dashboard/api/stats JSON snapshot)

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, createWorkspaceOperatorPolicy, createNetworkOperatorPolicy, createNetworkCachePolicy, } 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 write profile with canonicalized roots and operator policies const workspaceConfig = await resolveWorkspaceConfig(["/path/to/project"]); const workspaceServer = createServer({ profile: "workspace_write", workspaceConfig, workspacePolicy: createWorkspaceOperatorPolicy({ maxWriteBytes: 2 * 1024 * 1024, requireWriteConfirmation: true, }), networkPolicy: createNetworkOperatorPolicy({ allowedHostPatterns: ["example.com", "*.githubusercontent.com"], httpsOnly: true, }), networkCachePolicy: createNetworkCachePolicy({ enabled: true, }), });

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:

---

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 /