redis-mcp 是由 YawLabs 维护的轻量级 Model Context Protocol (MCP) 服务器，它把 Redis 的常用操作以结构化工具的形式暴露给大模型客户端（如 Claude、Cursor、Yaw 等），使 LLM 能够在受控、可审计的前提下读写 Redis 实例。仓库遵循语义化版本控制，当前最新发布为 v0.1.3（基于 v0.1.2 的演进线） 资料来源：README.md:1-40。

项目定位与适用场景

redis-mcp 专注于解决"LLM 想要直接操作 Redis 但又缺少安全护栏"的痛点。它定位为只读优先、最小权限、按需写的 Redis 网关，而不是全功能的 Redis 代理。典型场景包括：

• 让 AI 助手在排障时安全地执行 GET、KEYS/SCAN、INFO 等只读操作
• 通过 key_info 工具查看键的元数据（类型、TTL、编码、内存占用等）
• 通过 health 工具探活并汇总 Redis 实例运行状态
• 通过 advisor 工具给出容量、热点键或配置层面的建议

这些工具名称在 v0.1.1 的发布说明中已明确列出 资料来源：package.json:10-25。

设计目标与核心原则

项目的设计目标可以从源码与发布说明中归纳为以下几条：

架构概览

redis-mcp 采用单进程、TypeScript 实现的 MCP 服务器架构。其核心组件关系如下：

flowchart LR
  Client[LLM 客户端 / MCP Host] -->|JSON-RPC| Server[redis-mcp 服务器]
  Server --> Router[工具路由层]
  Router --> ReadOps[redis_get / key_info]
  Router --> ScanOps[accumulateScan]
  Router --> Health[health / advisor]
  ReadOps --> Redis[(目标 Redis 实例)]
  ScanOps --> Redis
  Health --> Redis

所有工具最终都通过统一的 Redis 客户端连接下游实例，连接串由环境变量（参考 REDIS_URL）注入；与真实 Redis 的集成测试也以 REDIS_URL 作为门控开关，未设置时自动跳过 资料来源：README.md:60-120。

安全、可观测与发布治理

由于 LLM 直接触达数据面，安全边界是项目的首要约束：

• 最小暴露面：默认只注册经过审核的工具，未列入白名单的 Redis 命令不会被代理转发 资料来源：SECURITY.md:1-40。
• 可观测性：每次工具调用都会记录请求参数摘要与结果状态，便于事后审计；advisor 内的 probe 在失败时会被显式抛出而非吞掉，便于上游及时告警 资料来源：src/advisor.ts:40-90。
• 发布治理：版本号遵循 SemVer；server.json 作为 MCP Registry 的注册清单需满足字段长度与必填约束；CI 中的 drift guard 使用 tag-object SHA 比对，避免在断点续跑的发布流水线中误报冲突 资料来源：v0.1.1 release notes。
• 安装体验：README 中提供 "Add-to-Yaw-MCP" 徽章，方便用户一键接入 资料来源：v0.1.1 release notes。

小结

redis-mcp 的目标可以浓缩为一句话：把 Redis 变成 LLM 可以安全调用的结构化工具集。它通过工具语义化、SCAN 流式收敛、显式失败传播和严格的发布/注册表治理，在"让 AI 用上 Redis"与"不让 AI 滥用 Redis"之间取得平衡，这正是其后续版本（v0.1.x 系列）持续打磨的核心方向 资料来源：README.md:1-40。

redis-mcp 是一个面向 LLM 代理（agent）的 Redis 访问服务器，通过实现 Model Context Protocol（MCP） 将 Redis 的常用命令与诊断能力暴露为可被大模型调用的"工具（tool）"。自 v0.1.0 首发以来，仓库经历了 v0.1.1、v0.1.2 的迭代，重点完善了发布流程、注册元数据以及 advisor 模块中的 SCAN 聚合逻辑 资料来源：CHANGELOG / release notes。

设计目标与运行形态

服务器在运行时以 stdio 传输与 MCP 客户端（如 Claude Desktop、Yaw MCP）通信，避免对网络端口的依赖。src/index.ts 负责进程引导：装载环境变量、构造 Redis 客户端实例、注册工具并启动 MCP server。设计上强调：

• 只读/写分离的工具边界：每个工具的入参在 src/tools/params.ts 中以 Zod schema 描述，便于客户端校验。
• 错误与响应规范化：所有工具的返回值统一经过 src/mcp-response.ts 处理，确保错误文本不破坏 MCP 的结构化响应。
• 可发布的元数据：server.json 是注册中心描述文件，v0.1.1 修复了 description 长度不能超过 100 字符的注册限制 资料来源：v0.1.1 release notes。

整体架构

整体上由三层组成：传输层（stdio MCP）、工具适配层（src/api.ts + src/tools/*）、数据层（ioredis 客户端）。src/api.ts 将高层工具调用翻译为 Redis 命令，并把 SCAN 等游标命令的多次结果聚合成单次响应，这也是 v0.1.2 中 accumulateScan 重构的落点 资料来源：v0.1.2 release notes。src/mcp-response.ts 再把聚合结果包装成 MCP 的 content 数组。

flowchart LR
    A[MCP 客户端<br/>stdio] --> B[src/index.ts<br/>启动与注册]
    B --> C[工具列表<br/>tools/list]
    B --> D[工具调用<br/>tools/call]
    D --> E[src/api.ts<br/>命令适配]
    E -->|SCAN/GET/INFO...| F[(Redis)]
    E --> G[accumulateScan<br/>聚合]
    G --> H[src/mcp-response.ts<br/>响应规范化]
    H --> A

MCP 协议集成层

服务器遵循 MCP 的 JSON-RPC 风格消息契约，关键项目括：

• tools/list：枚举工具元数据（名称、描述、输入 schema），schema 来自 src/tools/params.ts 中各工具导出的 Zod 对象。
• tools/call：执行工具调用；src/api.ts 解析入参后调用对应 Redis 命令并捕获异常。
• health、redis_get、key_info、advisor 等工具在 v0.1.1 中加入了 live-Redis 集成测试，通过环境变量 REDIS_URL 门控，避免在没有真实实例时失败 资料来源：v0.1.1 release notes。
• 错误响应：当底层 Redis 报错（如 WRONGTYPE）时，src/mcp-response.ts 将其转为带 isError: true 的 MCP 内容块，使客户端可以区分软警告与硬失败。

advisor 工具在 v0.1.2 的重构中改由 accumulateScan 统一驱动 SCAN，并把探测失败显式上报，解决了原先 probe 异常被吞掉的问题 资料来源：v0.1.2 release notes。

发布、注册与可观测性

server.json 作为 MCP 注册中心的元数据清单，包含包名、版本、入口命令、传输方式等字段，必须满足注册中心的字段长度约束（v0.1.1 修复）。仓库使用基于 git tag 的 SHA 比对做发布漂移检测，v0.1.1 将其从"提交 SHA"改为"标签对象 SHA"，避免续跑（resume）任务误判为漂移而中止 资料来源：v0.1.1 release notes。v0.1.2 在发布后增加了"冒烟脚本"对 pickReply 等关键路径做最小化回归 资料来源：v0.1.2 release notes。

总体而言，redis-mcp 的架构以"MCP 适配薄壳 + 严格 schema + 统一响应"为支点，把 Redis 的高频运维与诊断能力封装为对 LLM 友好的工具集合，并通过 release 流水线持续收敛质量。

工具集总览

服务器在 src/server.ts 中注册并暴露工具，每个工具对应一项可由模型调用的能力。工具实现位于 src/tools/ 目录，按职责拆分为多个文件，每个文件聚焦一类操作。资料来源：src/server.ts:1-120。

工具按可观测性与变更风险大致分为四类：

v0.1.1 起加入了对 redis_get、key_info、health、advisor 的实时 Redis 集成测试（由 REDIS_URL 环境变量门控），表明这些都是服务器对外契约的核心能力。资料来源：CHANGELOG / v0.1.1 release notes。

键空间工具与 SCAN 行为

浏览键空间时一律走 SCAN 而不是 KEYS，避免在大键空间上阻塞 Redis。v0.1.2 重构了 advisor 工具，将 SCAN 路由到统一的 accumulateScan 助手，并显式地把探测失败暴露出来，使上层模型能够看到部分失败而不是静默吞掉。资料来源：src/tools/advisor.ts:1-200、accumulateScan 调用点。

scan-tools.ts 提供更细粒度的 SCAN 衍生能力，配合 keyspace.ts 输出键类型、TTL、编码等元数据。scan.ts 负责最基础的模式匹配入口。三个文件形成"扫描 → 聚合 → 元数据补全"的流水线。资料来源：src/tools/scan.ts:1-80、src/tools/scan-tools.ts:1-120、src/tools/keyspace.ts:1-150。

信息查询与健康检查

info.ts 提供基于 INFO/GET 的只读查询能力，是模型了解 Redis 实例状态与单键值的入口。health.ts 则封装 PING/连接校验，常用于会话开始时的连通性探测，也被注册到 MCP 列表中作为可调用工具而非仅内部预检。资料来源：src/tools/info.ts:1-100、src/tools/health.ts:1-80。

安全模型

安全模型围绕"最小权限 + 显式失败"两条原则构建，集中体现在以下几方面：

• 默认只读：默认暴露给模型的能力以只读查询为主，写操作不进入默认工具集，避免模型在缺乏审查时直接修改线上数据。资料来源：src/server.ts:1-120。
• 危险命令屏蔽：典型的破坏性命令（如 FLUSHALL、FLUSHDB、CONFIG、DEBUG、SHUTDOWN、KEYS * 等）不会被注册为工具；SCAN 替代 KEYS 是这一原则的体现。资料来源：src/tools/scan.ts:1-80。
• 环境变量门控：REDIS_URL 等敏感连接信息只通过环境变量注入，服务器不持久化凭据，也不通过工具参数回传连接串。资料来源：src/config.ts:1-120。
• 失败显式化：v0.1.2 起 advisor 的探测失败会被显式抛出，而不是被静默吞掉，确保模型与运维能看到真实状态。资料来源：src/tools/advisor.ts:1-200。
• 注册表约束：server.json 的 description 字段被压缩到 ≤100 字符以满足 MCP 注册表限制，避免在分发层面被截断导致安全提示丢失。资料来源：v0.1.1 release notes / fix(registry)。

演进与可靠性保障

工具集通过测试矩阵与发布流程逐步加固。pickReply 等单元测试覆盖回复解析路径，post-publish 冒烟脚本在每次发布后做一次实跑验证，drift guard 在 resume 模式下使用 tag-object SHA 比较，防止误判导致发布中止。资料来源：v0.1.2 release notes / test & post-publish smoke、v0.1.1 release notes / fix(release)。

对于运维与集成方而言，工具集与安全模型的整体契约可以归纳为一句话：所有工具默认安全、可观测、可在真实 Redis 上回归验证，任何写路径都必须显式开启而非隐式存在。

项目配置

package.json 是项目的核心清单文件，定义了入口脚本、依赖与 NPM scripts；tsconfig.json 提供 TypeScript 编译选项（目标版本、模块系统与严格模式）；sea-config.json 则用于声明 Node.js SEA 打包所需的入口与输出配置，使构建产物可被打包为单一可执行二进制。资料来源：package.json:1-40

// package.json scripts 片段示例
{
  "scripts": {
    "build": "node build.mjs",
    "build:binary": "node scripts/build-binary.mjs",
    "test": "vitest run",
    "release": "bash release.sh"
  }
}

构建流程

构建分为两个阶段：build.mjs 负责将 TypeScript 源码编译为符合 SEA 要求的 JavaScript 入口并产出 dist/；scripts/build-binary.mjs 进一步读取 sea-config.json，调用 node --experimental-sea-config 与 node --build-sea，最终生成跨平台可执行文件。资料来源：build.mjs:1-60 资料来源：scripts/build-binary.mjs:1-80

flowchart LR
  A[TypeScript 源码] --> B[build.mjs<br/>tsc + 拷贝资源]
  B --> C[dist/index.js]
  C --> D[scripts/build-binary.mjs<br/>node --build-sea]
  E[sea-config.json] --> D
  D --> F[单文件可执行二进制]

测试策略

测试覆盖两个层级：

• 单元测试：通过 vitest 运行，涵盖纯逻辑函数（如 pickReply 等无副作用模块）。资料来源：package.json:scripts.test
• 集成测试：针对真实 Redis 实例执行 redis_get、key_info、health、advisor 等端到端场景。该层通过 REDIS_URL 环境变量门控（gated），未设置时跳过，避免 CI 默认环境下产生误报。资料来源：v0.1.1 release notes
• 发布后冒烟脚本：post-publish smoke 在 NPM 发布成功后对线上注册表进行连通性验证，确保注册信息可被 MCP registry 正确读取。资料来源：v0.1.2 release notes

发布流程

release.sh 是项目的发布入口脚本，串联以下步骤：

1. drift guard：在打 tag 前对比 Git tag 对象指向的 SHA 与本地工作树 SHA，防止 resume 模式下历史运行误判为漂移并中止发布。资料来源：v0.1.1 release notes
2. 构建产物：调用 npm run build:binary 生成 SEA 可执行文件。
3. 写入注册表：将精简后的 server.json 推送到 MCP registry；description 字段被截断至 ≤100 字符以满足 registry 限制。资料来源：v0.1.1 release notes
4. 创建 GitHub Release：推送 vX.Y.Z tag 并附上构建产物。
5. 冒烟验证：执行 post-publish smoke 脚本，校验安装徽章（Add-to-Yaw-MCP badge）所指向的注册条目可被消费。资料来源：v0.1.1 release notes 资料来源：release.sh:1-120

下表汇总各发布版本在配置、测试与发布链路上的关键变更：

整体而言，redis-mcp 在配置层采用 SEA 单一可执行方案，测试层使用环境变量门控兼顾 CI 速度与覆盖率，发布层通过 drift guard、注册表字段约束与冒烟脚本构成三道防线。资料来源：package.json:1-40 资料来源：sea-config.json:1-30 资料来源：build.mjs:1-60 资料来源：scripts/build-binary.mjs:1-80 资料来源：release.sh:1-120

Pitfall Log / 踩坑日志

项目：YawLabs/redis-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/YawLabs/redis-mcp | host_targets=mcp_host, claude_code, claude, cursor

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/YawLabs/redis-mcp | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/YawLabs/redis-mcp | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/YawLabs/redis-mcp | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/YawLabs/redis-mcp | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/YawLabs/redis-mcp | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/YawLabs/redis-mcp | release_recency=unknown