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.4.0)

> [!NOTE]
> **Status**: `0.4.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**.

---

## 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 v1**: Fast, bounded literal file and text search (`search_files`, `search_text`) with ignored directory defaults, bounded concurrency (`SEARCH_CONCURRENCY = 8`), coordinate mapping, and client cancellation.
- **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)
```json
{
  "mcpServers": {
    "high-performance-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "high-performance-mcp-server"
      ]
    }
  }
}
```

#### Read-Only Workspace Profile
```json
{
  "mcpServers": {
    "workspace-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "high-performance-mcp-server",
        "--profile=workspace",
        "--root=/path/to/project"
      ]
    }
  }
}
```

### Local Development / Source Execution

```bash
# 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/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:

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

```bash
# 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