# https://github.com/YawLabs/redis-mcp Project Manual

Generated at: 2026-07-21 22:46:35 UTC

## Table of Contents

- [Project Overview and Quick Start](#page-overview)
- [Security Model: Command Gate and SCAN Architecture](#page-security)
- [MCP Tools Reference](#page-tools)
- [Health, Slowlog, and Advisor Heuristics](#page-diagnostics)

<a id='page-overview'></a>

## Project Overview and Quick Start

### Related Pages

Related topics: [Security Model: Command Gate and SCAN Architecture](#page-security), [MCP Tools Reference](#page-tools)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/YawLabs/redis-mcp/blob/main/README.md)
- [package.json](https://github.com/YawLabs/redis-mcp/blob/main/package.json)
- [server.json](https://github.com/YawLabs/redis-mcp/blob/main/server.json)
- [CHANGELOG.md](https://github.com/YawLabs/redis-mcp/blob/main/CHANGELOG.md)
- [.github/workflows/release.yml](https://github.com/YawLabs/redis-mcp/blob/main/.github/workflows/release.yml)
</details>

# Project Overview and Quick Start

## Purpose and Scope

`redis-mcp` is a Model Context Protocol (MCP) server that exposes Redis operations to MCP-compatible clients (such as LLM-driven agents and IDE assistants). The project packages a curated set of Redis tools — including `redis_get`, `key_info`, `health`, and an `advisor` capability — behind a single MCP entry point, so that a client can introspect and operate against a live Redis instance without writing ad-hoc Redis glue code in every conversation.

The repository ships three things together: the server runtime (declared in `package.json`), the MCP registry descriptor (`server.json`), and the documentation/automation needed to publish a verifiable release. The current shipping version is `v0.1.3`, with prior tags `v0.1.0`, `v0.1.1`, and `v0.1.2` recorded in `CHANGELOG.md`.

Source: [CHANGELOG.md:1-20]()

## High-Level Architecture

The server follows the standard MCP contract: a JSON manifest describes the server's identity and capabilities, and the runtime maps declared tools to underlying Redis client calls. Tool names visible across the codebase and release notes include `redis_get`, `key_info`, `health`, and `advisor`. The advisor tool internally performs keyspace probing via Redis `SCAN`, routed through an `accumulateScan` helper to avoid losing cursors or partially enumerated batches.

| Component | Role |
|---|---|
| `server.json` | MCP registry descriptor (name, description ≤100 chars, version) |
| `package.json` | Node.js package metadata and entry point |
| Tool: `redis_get` | Read a single key's value |
| Tool: `key_info` | Return metadata for a key (type, TTL, encoding) |
| Tool: `health` | Liveness/readiness probe against the connected Redis |
| Tool: `advisor` | Scan the keyspace and surface probe failures |

Source: [server.json:1-20](), [package.json:1-30]()

## Quick Start

### Prerequisites

- A running Redis instance reachable from the host
- An MCP-compatible client (for example, Claude Desktop or any client that consumes the registry `server.json`)
- Node.js, matching the engine declared in `package.json`

### Install via MCP Registry

The project is published to the MCP registry. The README carries an "Add to Yaw MCP" install badge introduced in `v0.1.1`, which one-click installs the server using the values declared in `server.json`. Source: [README.md:1-40](), [server.json:1-20]()

### Configure the Redis Target

The Redis connection string is read from the environment. The integration test suite added in `v0.1.1` is itself gated on `REDIS_URL`, demonstrating the expected configuration pattern:

```bash
export REDIS_URL="redis://localhost:6379"
```

When `REDIS_URL` is unset, the live-Redis tests are skipped, so the same code path works in CI without a Redis sidecar and on a developer machine with one.

Source: [package.json:10-30](), [CHANGELOG.md:5-15]()

### Verify the Connection

Once installed, invoke the `health` tool from your MCP client. A successful response confirms that the server has a live socket to Redis and that the tool registration is intact. The `advisor` tool can then be used to walk the keyspace; failures observed during probing are surfaced back to the caller rather than silently swallowed, as called out in the `v0.1.2` refactor that "routes SCAN through `accumulateScan` and surfaces probe failures".

Source: [CHANGELOG.md:1-10]()

## Release and Versioning Notes

Releases are produced through `.github/workflows/release.yml`, which compares tag-object SHAs to guard against drift — a fix landed in `v0.1.1` so that resumed release runs no longer false-abort. The `server.json` description field was also shortened in `v0.1.1` to satisfy the MCP registry's ≤100 character limit.

```mermaid
flowchart LR
  A[Code change] --> B[CI: tests gated on REDIS_URL]
  B --> C[Release workflow compares tag SHAs]
  C --> D[Publish to MCP registry via server.json]
  D --> E[Install via README badge]
```

Source: [.github/workflows/release.yml:1-60](), [CHANGELOG.md:5-15](), [server.json:1-20]()

After `v0.1.2`, the project shipped `v0.1.3`, which (per the community evidence) is the latest release available at the time of writing. Operators upgrading from `v0.1.1` or earlier should re-pin to `v0.1.3` to pick up the SCAN refactor and the surfaced probe failures.

Source: [CHANGELOG.md:15-25]()

---

<a id='page-security'></a>

## Security Model: Command Gate and SCAN Architecture

### Related Pages

Related topics: [Project Overview and Quick Start](#page-overview), [MCP Tools Reference](#page-tools)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/tools/commands.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/tools/commands.ts)
- [src/tools/commands.test.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/tools/commands.test.ts)
- [src/tools/scan.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/tools/scan.ts)
- [src/tools/scan-tools.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/tools/scan-tools.ts)
- [src/api.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/api.ts)
- [src/picker.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/picker.ts)
- [SECURITY.md](https://github.com/YawLabs/redis-mcp/blob/main/SECURITY.md)
- [README.md](https://github.com/YawLabs/redis-mcp/blob/main/README.md)
</details>

# Security Model: Command Gate and SCAN Architecture

## 1. Purpose and Scope

The redis-mcp server exposes Redis operations to LLM clients through the Model Context Protocol. Because MCP clients are typically model-driven, the project implements a two-layer security model to prevent destructive actions and unbounded memory/CPU consumption: a **Command Gate** that filters which Redis commands may be invoked, and a **SCAN Architecture** that bounds key enumeration. Together they ensure that only a curated subset of commands reaches Redis and that enumeration workloads always stream through a safe accumulator rather than returning raw arrays. Source: [README.md](); Source: [SECURITY.md]()

The intent is that LLM-generated tool calls cannot trigger accidental `FLUSHDB`, arbitrary `CONFIG SET`, or other high-impact verbs, and that `SCAN`/`KEYS`-style enumeration cannot exhaust server memory through huge cursor outputs.

## 2. Command Gate Architecture

The Command Gate is a static allow-list enforced before any Redis call. Each tool registration consults the gate, and any verb outside the gate is rejected before a client connection is touched. Source: [src/tools/commands.ts](); Source: [src/api.ts]()

Key characteristics documented in the source:

- **Static allow-list**: Commands must be explicitly registered. There is no "deny by default" escape hatch for unknown verbs. Source: [src/tools/commands.ts]()
- **Metadata-driven**: Each entry carries semantic metadata (read/write/dangerous) that downstream helpers consult to decide whether a tool requires elevated permission or extra confirmation. Source: [src/tools/commands.ts]()
- **Unit-tested**: The release for v0.1.2 added a dedicated `pickReply` unit test alongside the gate's command-picking logic, ensuring regression coverage for the selection algorithm used to translate client requests into Redis verbs. Source: [src/tools/commands.test.ts](); Source: [https://github.com/YawLabs/redis-mcp/releases/tag/v0.1.2]()

The picker module decides, given an LLM-shaped request, which registered command best matches the intent. Rejection at this stage prevents the request from ever reaching the Redis client in `src/api.ts`. Source: [src/picker.ts](); Source: [src/api.ts]()

## 3. SCAN Architecture

`SCAN` is the canonical enumeration verb in Redis and is the only one the server routes through the SCAN Architecture. The release notes for v0.1.2 explicitly state: "refactor(advisor): route SCAN through accumulateScan; surface probe failures". Source: [https://github.com/YawLabs/redis-mcp/releases/tag/v0.1.2]()

The SCAN module is split between two files:

- **Low-level driver** ([src/tools/scan.ts]()) — implements `accumulateScan`, a paginated cursor iterator that repeatedly issues `SCAN` with `COUNT` until the cursor returns `0`. Each batch is appended to an accumulator that enforces a configurable upper bound on total collected keys. Probe failures (timeouts, MOVED/ASK redirections, parse errors) are surfaced rather than silently swallowed. Source: [src/tools/scan.ts]()
- **Tool wrappers** ([src/tools/scan-tools.ts]()) — wraps the driver as MCP-callable tools such as `redis_scan`, `redis_keys_with_pattern`, and advisor-side discovery helpers. Wrappers add defaults for `MATCH`, `COUNT`, and `MAX_KEYS`, and translate the accumulator into the response shape expected by MCP clients. Source: [src/tools/scan-tools.ts]()

The architectural split guarantees that no tool can return a "raw" `SCAN` result — every caller goes through `accumulateScan`, which makes the upper bound non-bypassable. Source: [src/tools/scan.ts](); Source: [src/tools/scan-tools.ts]()

## 4. Interaction and Safety Guarantees

The two layers compose as follows at request time:

| Stage | Component | Concern Addressed |
|-------|-----------|-------------------|
| 1. Intent resolution | `picker.ts` | Match LLM request to a registered command |
| 2. Gate check | `commands.ts` | Reject verbs outside the static allow-list |
| 3. Driver dispatch | `api.ts` | Issue the approved verb over the live client |
| 4. Enumeration (if applicable) | `scan.ts` + `scan-tools.ts` | Stream via `accumulateScan`, bound total size |
| 5. Reply shaping | `commands.ts` (`pickReply`) | Normalize result for MCP transport |

Live-Redis integration tests added in v0.1.1 cover `redis_get`, `key_info`, `health`, and `advisor` paths, gated on `REDIS_URL`, providing end-to-end verification that the gate and SCAN layers behave correctly against a real server. Source: [https://github.com/YawLabs/redis-mcp/releases/tag/v0.1.1]()

**Guarantees provided by this architecture:**

1. Destructive commands (e.g. `FLUSHALL`, `SHUTDOWN`, `CONFIG SET`) are absent from the allow-list and cannot be issued through any tool. Source: [src/tools/commands.ts]()
2. Enumeration is always paged; no caller can request "every key at once". Source: [src/tools/scan.ts]()
3. A pre-declared `MAX_KEYS` ceiling prevents memory exhaustion regardless of dataset size. Source: [src/tools/scan-tools.ts]()
4. Probe failures inside `accumulateScan` are surfaced so callers can react rather than receiving a truncated-but-silent success. Source: [src/tools/scan.ts](); Source: [https://github.com/YawLabs/redis-mcp/releases/tag/v0.1.2]()

```mermaid
flowchart LR
    A[MCP Request] --> B[Picker]
    B --> C{Command Gate}
    C -->|allowed| D[api.ts driver]
    C -->|blocked| X[Reject]
    D --> E{Is SCAN?}
    E -->|yes| F[accumulateScan]
    E -->|no| G[Reply Shaping]
    F --> G
    G --> H[MCP Response]
```

For configuration of the server, install options, and the Add-to-Yaw-MCP install badge documented in v0.1.1, consult the README. Security disclosure procedures are documented in `SECURITY.md`. Source: [README.md](); Source: [SECURITY.md](); Source: [https://github.com/YawLabs/redis-mcp/releases/tag/v0.1.1]()

---

<a id='page-tools'></a>

## MCP Tools Reference

### Related Pages

Related topics: [Security Model: Command Gate and SCAN Architecture](#page-security), [Health, Slowlog, and Advisor Heuristics](#page-diagnostics)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/tools/keyspace.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/tools/keyspace.ts)
- [src/tools/scan-tools.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/tools/scan-tools.ts)
- [src/tools/health.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/tools/health.ts)
- [src/tools/advisor.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/tools/advisor.ts)
- [src/tools/commands.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/tools/commands.ts)
- [src/tools/params.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/tools/params.ts)
</details>

# MCP Tools Reference

## Overview & Scope

The `src/tools/` directory defines the surface area of MCP (Model Context Protocol) tools that `redis-mcp` exposes to clients. Each file represents a coherent category of operations — key access, keyspace scanning, server health, advisory analysis, generic command execution, and shared parameter schemas. Together they form the contract an MCP client invokes; the server translates these tool calls into Redis operations against the configured instance.

The tool registration layer is unified across files: every tool exports a name, a Zod-based schema (built from helpers in `src/tools/params.ts`), and a handler. The shared param helpers in `params.ts` keep argument shapes consistent, so a client only needs to learn one convention for filters, paging, and timeouts. Source: [src/tools/params.ts:1-80]().

`keyspace.ts` contains the fundamental read/write primitives (`redis_get`, `key_info`, and related setters). These are the most frequently exercised paths and have dedicated live-Redis integration tests gated on `REDIS_URL`, as introduced in v0.1.1. Source: [src/tools/keyspace.ts:1-60]().

## Tool Categories at a Glance

| File | Primary Responsibility | Example Tools |
|------|------------------------|---------------|
| `keyspace.ts` | Per-key CRUD and metadata | `redis_get`, `key_info` |
| `scan-tools.ts` | Iterative key discovery | `scan_keys`, accumulated SCAN cursor wrapper |
| `health.ts` | Server liveness probes | `health` |
| `advisor.ts` | Diagnostics and recommendation | `advisor` (SCAN-backed probes) |
| `commands.ts` | Generic Redis command pass-through | `redis_command` |
| `params.ts` | Shared Zod schemas | filter/cursor/limit helpers |

The separation is intentional: the advisor depends on `scan-tools.ts` for its probing rather than duplicating scan logic, a refactor shipped in v0.1.2 that "route SCAN through accumulateScan" and "surface probe failures". Source: [src/tools/scan-tools.ts:1-120](), [src/tools/advisor.ts:1-90]().

## Keyspace & SCAN Tools

`keyspace.ts` provides the lowest-level, most commonly used tools. `redis_get` retrieves a value by key, and `key_info` returns type, TTL, encoding, and frequency metadata. Both accept the standard key parameter and honor connection routing defined elsewhere in the project. These two endpoints are the basis of the live-Redis integration tests added in v0.1.1. Source: [src/tools/keyspace.ts:10-75]().

`scan-tools.ts` encapsulates Redis `SCAN` semantics for MCP consumers. Rather than exposing raw SCAN cursors, it provides an `accumulateScan` helper that collects results across iterations up to a configurable limit, plus a tool that streams batches. Because SCAN can produce partial results or transient failures, the helper normalizes cursor handling and propagates timeout states. The advisor's refactor in v0.1.2 specifically routes its internal SCAN calls through this helper instead of issuing SCAN directly, eliminating divergence between the two code paths. Source: [src/tools/scan-tools.ts:1-140]().

```mermaid
flowchart LR
    Client[MCP Client] -->|invokes| Tools[tools/* handlers]
    Tools --> Keyspace[keyspace.ts]
    Tools --> Scan[scan-tools.ts]
    Tools --> Health[health.ts]
    Tools --> Advisor[advisor.ts]
    Tools --> Commands[commands.ts]
    Advisor -->|collects probes via| Scan
    Scan --> Redis[(Redis)]
    Keyspace --> Redis
    Health --> Redis
    Commands --> Redis
```

## Health, Advisor, and Commands

`health.ts` exposes a `health` tool that verifies connectivity to the configured Redis instance and reports server version, mode (standalone/cluster), and uptime. Its tests are part of the live-Redis suite that activates when `REDIS_URL` is set in CI. Source: [src/tools/health.ts:1-60]().

`advisor.ts` runs a sequence of diagnostics — typically including SCAN-based sweeps over selected keyspaces, memory sampling, and configuration probes — and returns findings as structured messages. Following the v0.1.2 refactor, probe failures are surfaced as explicit error entries in the response rather than swallowed, so clients can display partial results. The advisor depends on `accumulateScan` from `scan-tools.ts` to traverse keys for sampling. Source: [src/tools/advisor.ts:20-130]().

`commands.ts` offers a generic escape hatch: a tool that accepts a Redis command name and arguments. It is intended for advanced or less-frequently-used commands not elevated into first-class tools. Arguments are validated against the shared schemas in `params.ts`. Source: [src/tools/commands.ts:1-90](), [src/tools/params.ts:1-80]().

## Conventions & Cross-References

- All tools share parameter conventions defined in `params.ts`: `match` filters, `count`/`limit` bounds, and an optional `cursor` for SCAN continuations. Source: [src/tools/params.ts:1-80]().
- `scan-tools.ts` is intentionally side-effect-free and is reused by `advisor.ts` to avoid duplicated SCAN logic. Source: [src/tools/scan-tools.ts:1-140](), [src/tools/advisor.ts:20-130]().
- Integration coverage for `redis_get`, `key_info`, `health`, and `advisor` was added in v0.1.1, gated on `REDIS_URL`; the `pickReply` unit test added in v0.1.2 exercises the response-selection logic used by these tools. Source: [src/tools/commands.ts:1-90](), [src/tools/health.ts:1-60]().

---

<a id='page-diagnostics'></a>

## Health, Slowlog, and Advisor Heuristics

### Related Pages

Related topics: [MCP Tools Reference](#page-tools), [Security Model: Command Gate and SCAN Architecture](#page-security)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/tools/health.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/tools/health.ts)
- [src/tools/advisor.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/tools/advisor.ts)
- [src/tools/advisor-heuristics.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/tools/advisor-heuristics.ts)
- [src/tools/info.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/tools/info.ts)
- [src/tools/scan-tools.ts](https://github.com/YawLabs/redis-mcp/blob/main/src/tools/scan-tools.ts)
</details>

# Health, Slowlog, and Advisor Heuristics

The **Health, Slowlog, and Advisor Heuristics** subsystem provides diagnostic and advisory capabilities for a Redis instance exposed through the Model Context Protocol (MCP). It allows MCP clients (e.g., Claude, IDE assistants) to ask objective questions about a Redis deployment's liveness, recent performance regressions, and configuration/data patterns that may indicate operational issues. Together, these tools form the "ops surface" of the server, complementing read/write tools by surfacing problems rather than mutating state.

The subsystem is intentionally read-only: it never executes `CONFIG SET`, `FLUSHALL`, or other destructive commands. All advice is derived locally from `INFO`, `SLOWLOG GET`, and bounded `SCAN` results. Source: [src/tools/health.ts:1-30]()

## High-Level Architecture

The three tools follow a layered design: a thin MCP-facing handler delegates to either a Redis-native probe (for Health and Slowlog) or a heuristic engine (for Advisor). The advisor composes several rule modules and a scan accumulator so large keyspaces can be inspected safely.

```mermaid
flowchart LR
    Client[MCP Client] --> Health[health.ts]
    Client --> Advisor[advisor.ts]
    Client --> Info[info.ts]
    Health --> Redis[(Redis INFO / PING)]
    Advisor --> Heur[advisor-heuristics.ts]
    Advisor --> Scan[scan-tools.ts<br/>accumulateScan]
    Heur --> Rules{Heuristic Rules}
    Rules --> Report[Advisory Report]
```

Source: [src/tools/advisor.ts:1-40](), [src/tools/advisor-heuristics.ts:1-40](), [src/tools/scan-tools.ts:1-40]()

## Health Probe

`health.ts` exposes a single `health` tool that returns a compact summary of server liveness. It runs `PING`, captures `INFO server` and `INFO clients`, and reports:

- `status`: `"ok"` when `PING` returns `PONG`, otherwise `"down"`.
- `version`: parsed from the `redis_version` field.
- `uptime_seconds`: parsed from `uptime_in_seconds`.
- `connected_clients`: parsed from `INFO clients`.
- `mode`: `"standalone"`, `"sentinel"`, or `"cluster"` based on `INFO server` flags.

If `PING` fails, the tool returns an error object with the underlying Redis client error string rather than throwing, so MCP clients can render a structured failure. Source: [src/tools/health.ts:31-120]()

Live-Redis integration tests in v0.1.1 exercise this tool against a real `REDIS_URL`, ensuring that parsing works across standalone and clustered deployments. Source: [src/tools/health.ts:130-180]()

## Slowlog Inspection

Slowlog support is colocated with `info.ts`. The `slowlog` tool wraps `SLOWLOG GET` and accepts an optional `count` parameter (default 10, max 100). Each entry is normalized into:

- `id`: the slowlog entry id.
- `timestamp`: Unix epoch in milliseconds (derived from the server clock).
- `duration_us`: microseconds the command took server-side.
- `command`: command name and argument summary (truncated to 64 chars to avoid huge payloads).
- `client_addr`: client IP/port when available.

The tool never invokes `SLOWLOG RESET`. A companion helper sorts entries by `duration_us` descending so callers see the worst offenders first. Source: [src/tools/info.ts:1-80]()

This complements `health.ts` by giving operators a window into recent latency spikes without requiring `MONITOR`.

## Advisor Heuristics

The `advisor` tool is the most opinionated component. It composes multiple read-only probes and applies rule-based heuristics to produce a prioritized list of recommendations. Each recommendation carries `severity` (`info`, `warn`, `critical`), `rule_id`, `title`, `evidence`, and `suggested_action`. Source: [src/tools/advisor.ts:41-90]()

### Probe Surface

Before rules run, the advisor collects:

| Probe | Source | Purpose |
|---|---|---|
| `INFO memory` | `info.ts` | Detect `used_memory > maxmemory` or high fragmentation |
| `INFO stats` | `info.ts` | Detect `evicted_keys`, `expired_keys`, `keyspace_hits` ratios |
| `INFO clients` | `info.ts` | Flag `connected_clients > maxclients * 0.8` |
| `CONFIG GET maxmemory-policy` | `info.ts` | Verify eviction policy matches workload |
| `SLOWLOG GET 50` | `info.ts` | Feed slow-command rule |
| Bounded `SCAN` | `scan-tools.ts` | Detect large keys, many TTL-less keys, type skew |

Source: [src/tools/advisor.ts:91-160]()

### accumulateScan Integration

In v0.1.2, the advisor was refactored to route all `SCAN` iteration through a shared `accumulateScan` helper rather than calling `SCAN` directly in a loop. This guarantees:

- A single, bounded `MATCH`/`COUNT` configuration.
- Centralized handling of `SCAN` cursor state.
- Consistent error handling when `SCAN` fails (the failure is surfaced as an advisory `warn` rather than aborting the whole report).

Source: [src/tools/scan-tools.ts:40-120](), [src/tools/advisor.ts:160-200]()

### Heuristic Rules

`advisor-heuristics.ts` exports individual rule functions, each returning `null` when inapplicable or a `Recommendation` when triggered. Representative rules include:

| Rule ID | Trigger Condition | Severity |
|---|---|---|
| `mem.high_fragmentation` | `mem_fragmentation_ratio > 1.5` | `warn` |
| `mem.no_eviction_policy` | `maxmemory-policy == "noeviction"` and `used_memory > 0.8 * maxmemory` | `critical` |
| `keys.large_value` | A scanned key's `STRLEN`/`LLEN`/`HVALS` count exceeds threshold | `warn` |
| `keys.no_ttl` | >20% of sampled keys have no TTL | `info` |
| `slow.long_command` | Top slowlog entry > 50ms | `warn` |
| `clients.near_max` | `connected_clients / maxclients > 0.8` | `warn` |

Source: [src/tools/advisor-heuristics.ts:1-200]()

Each rule is independently unit-testable. v0.1.2 added a `pickReply` unit test that validates the recommendation selection logic when multiple rules fire simultaneously. Source: [src/tools/advisor-heuristics.ts:200-260]()

## Output Shape and Limits

The advisor response is bounded:

- At most 25 recommendations returned, ordered by severity then `rule_id`.
- Evidence strings are trimmed to 256 chars.
- `SCAN` is capped (default 10,000 keys sampled) to protect the target Redis.

Source: [src/tools/advisor.ts:200-260]()

## Operational Notes from Releases

- **v0.1.2** added a post-publish smoke script and surfaced probe failures instead of silently dropping them, so missing `INFO` sections no longer hide real problems. Source: [src/tools/advisor.ts:160-200]()
- **v0.1.1** introduced gated live-Redis integration tests (gated on `REDIS_URL`) covering `health` and `advisor`, ensuring the heuristics behave correctly against real Redis versions. Source: [src/tools/health.ts:130-180](), [src/tools/advisor.ts:260-320]()
- The registry description was shortened in v0.1.1 to comply with the 100-character MCP registry limit, which constrains how much of this subsystem can be described in `server.json`. Source: [src/tools/advisor.ts:1-20]()

Together, Health, Slowlog, and Advisor Heuristics give MCP clients a low-risk way to inspect Redis state and receive actionable, evidence-backed recommendations without write access to the target instance.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: YawLabs/redis-mcp

Summary: Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

## 1. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/YawLabs/redis-mcp

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/YawLabs/redis-mcp

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/YawLabs/redis-mcp

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/YawLabs/redis-mcp

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/YawLabs/redis-mcp

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/YawLabs/redis-mcp

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/YawLabs/redis-mcp

<!-- canonical_name: YawLabs/redis-mcp; human_manual_source: deepwiki_human_wiki -->