Metadata-Version: 2.4
Name: as-redis-mcp-server
Version: 1.0.2
Summary: A secure, read-only Redis MCP Server — empowers AI coding agents to inspect keys, analyze memory, diagnose slow queries, and advise on cache design through 8 semantic tools with defense-in-depth security.
Project-URL: Homepage, https://github.com/zicheng-ai/redis-mcp-server
Project-URL: Documentation, https://github.com/zicheng-ai/redis-mcp-server#readme
Project-URL: Repository, https://github.com/zicheng-ai/redis-mcp-server
Project-URL: Issues, https://github.com/zicheng-ai/redis-mcp-server/issues
Author: Redis MCP Team
License-Expression: MIT
Keywords: ai,assistant,cache,llm,mcp,mcp-server,qoder,redis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Requires-Dist: fastmcp>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: redis[hiredis]>=5.0
Requires-Dist: structlog>=24.0
Provides-Extra: dev
Requires-Dist: fakeredis>=2.20; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# Redis MCP Server

**Read-only Redis AI Assistant for Qoder IDE** — 面向研发团队的 Redis AI 助手

[![PyPI version](https://img.shields.io/pypi/v/as-redis-mcp-server)](https://pypi.org/project/as-redis-mcp-server/)
[![Python](https://img.shields.io/pypi/pyversions/as-redis-mcp-server)](https://pypi.org/project/as-redis-mcp-server/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 项目简介

Redis MCP Server 是基于 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 协议构建的 **只读** Redis AI 助手，专为 [Qoder IDE](https://qoder.ai/) 设计。它通过 stdio 传输层为 AI Agent 提供安全、可控、语义化的 Redis 访问能力。

### 核心价值

- **降低 Redis 排障成本** — AI 辅助分析 Key 分布、内存热点、慢查询
- **提升 AI 理解基础设施能力** — 语义化工具替代手工 redis-cli
- **建立安全可控的 AI-Redis 交互入口** — 只读 + 命令白名单 + Key 前缀过滤 + 数据脱敏 + 审计日志

### 适用场景

| 场景 | 示例对话 |
|------|---------|
| 排查缓存问题 | "帮我分析一下 `order:*` 这批 Key 的 TTL 分布" |
| 定位大 Key | "Redis 内存占用太高，帮我找出 Top 10 大 Key" |
| 慢查询分析 | "最近 Redis 响应慢，帮我看看慢查询日志" |
| Key 设计评审 | "分析一下 `session:*` 的内存和过期策略" |
| 缓存方案设计 | "我要设计一个用户画像缓存，给个方案建议" |

---

## 8 个语义化工具

| 工具名 | 功能 | 说明 |
|--------|------|------|
| `redis_inspect_key` | Key 检查 | 查看 Key 的类型、TTL、内存占用、大小、值预览 |
| `redis_search_keys` | Key 搜索 | 基于 SCAN 的 Key 名称搜索（禁止 KEYS） |
| `redis_analyze_key_pattern` | Pattern 分析 | 采样分析某类 Key 的 TTL/大小分布，识别风险 |
| `redis_health_check` | 健康检查 | Redis 实例状态：内存、连接数、QPS、命中率 |
| `redis_memory_analysis` | 内存分析 | 采样识别大 Key 和内存热点，Top 10 排行 |
| `redis_slowlog_analysis` | 慢查询分析 | 分析 SLOWLOG，自动生成优化建议 |
| `redis_cache_advisor` | 缓存建议 | 基于场景描述的缓存设计方案（不访问 Redis） |
| `redis_readonly_query` | 只读查询 | 有限枚举命令（HLEN/LLEN/SCARD/ZCARD/STRLEN 等） |

---

## 安全设计

本项目采用**纵深防御**策略，确保生产 Redis 安全：

| 安全层 | 机制 | 说明 |
|--------|------|------|
| 只读访问 | 命令白名单 | 仅允许 GET/TYPE/TTL/SCAN/INFO 等只读命令 |
| Key 前缀白名单 | 环境变量配置 | 限制可访问的 Key 前缀（如 `cache:*,user:*`） |
| 数据脱敏 | 自动脱敏 | 手机号/邮箱/身份证/密码字段自动脱敏 |
| 返回大小限制 | 自动截断 | 大 Value 自动截断（默认 2000 字符） |
| 速率限制 | 令牌桶 | 单实例 20 QPS，SCAN 操作 5 QPS |
| 审计日志 | 全链路追踪 | 每次 Tool 调用记录完整审计信息 |

> **注意**：V1.0 仅支持只读操作，所有写命令（SET/DEL/EXPIRE 等）均被拒绝。

---

## 架构

```
Qoder IDE (MCP Host)
    │
    │ stdio (stdin/stdout JSON-RPC 2.0)
    ▼
Redis MCP Server (Python)
    ├── Tool Layer        — 8 个语义化 MCP Tool
    ├── Security Guard    — 白名单 + 脱敏 + 截断 + 限流
    ├── Redis Adapter     — 连接池 + 超时 + 健康检查
    └── Observability     — structlog 日志 + 审计日志
            │
            │ redis-py (async)
            ▼
    Redis (单机/Cluster >= 6.0)
```

---

## 安装

### 通过 pip（推荐）

```bash
pip install as-redis-mcp-server
```

### 通过 uvx（零安装）

```bash
uvx --from as-redis-mcp-server@latest as-redis-mcp-server
```

### 从源码安装

```bash
git clone <repository-url>
cd redis-mcp
pip install -e ".[dev]"
```

---

## 配置

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `REDIS_HOST` | Redis 主机地址 | `127.0.0.1` |
| `REDIS_PORT` | Redis 端口 | `6379` |
| `REDIS_DB` | Redis 数据库编号 | `0` |
| `REDIS_USERNAME` | Redis 用户名（ACL） | `default` |
| `REDIS_PWD` | Redis 密码 | （空） |
| `REDIS_SSL` | 是否启用 SSL/TLS | `false` |
| `REDIS_SSL_CA_CERTS` | CA 证书路径 | （空） |
| `REDIS_CLUSTER_MODE` | 是否集群模式 | `false` |
| `REDIS_MAX_CONNECTIONS` | 连接池上限 | `20` |
| `REDIS_SOCKET_TIMEOUT` | 命令超时（秒） | `3` |
| `REDIS_CONNECT_TIMEOUT` | 连接超时（秒） | `3` |
| `KEY_PREFIX_WHITELIST` | Key 前缀白名单（逗号分隔 glob） | （空=全部允许） |
| `MAX_SCAN_COUNT` | SCAN 单次迭代 COUNT | `100` |
| `MAX_VALUE_LENGTH` | 返回值最大字符数 | `2000` |
| `RATE_LIMIT_QPS` | 全局 QPS 限制 | `20` |
| `MCP_REDIS_LOG_LEVEL` | 日志级别 | `INFO` |

### Redis ACL 配置（推荐）

生产环境建议使用只读账号：

```redis
ACL SETUSER mcp_reader on ><your-password> ~* +@read -@write -@admin -@dangerous
```

---

## Qoder IDE 配置

### 方式一：uvx 零安装（推荐）

在 Qoder 的 MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "redis-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "as-redis-mcp-server@latest",
        "as-redis-mcp-server"
      ],
      "env": {
        "REDIS_HOST": "127.0.0.1",
        "REDIS_PORT": "6379",
        "REDIS_PWD": "<your-redis-password>",
        "KEY_PREFIX_WHITELIST": "cache:*,session:*,user:*,order:*",
        "MCP_REDIS_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

> **说明**：uvx 方式会自动从 PyPI 下载最新版本并运行，无需手动安装。需先安装 [uv](https://docs.astral.sh/uv/)。

### 方式二：pip 全局安装

```bash
pip install as-redis-mcp-server
```

然后在 Qoder MCP 配置中添加：

```json
{
  "mcpServers": {
    "redis-mcp": {
      "type": "stdio",
      "command": "as-redis-mcp-server",
      "env": {
        "REDIS_HOST": "127.0.0.1",
        "REDIS_PORT": "6379",
        "REDIS_PWD": "<your-redis-password>",
        "KEY_PREFIX_WHITELIST": "cache:*,session:*,user:*,order:*",
        "MCP_REDIS_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

### 方式三：本地开发（pip install -e）

```bash
git clone <repository-url>
cd redis-mcp
pip install -e ".[dev]"
```

Qoder MCP 配置：

```json
{
  "mcpServers": {
    "redis-mcp": {
      "type": "stdio",
      "command": "as-redis-mcp-server",
      "cwd": "/path/to/redis-mcp",
      "env": {
        "REDIS_HOST": "127.0.0.1",
        "REDIS_PORT": "6379",
        "REDIS_PWD": "<your-redis-password>",
        "KEY_PREFIX_WHITELIST": "cache:*,session:*,user:*,order:*"
      }
    }
  }
}
```

### 方式四：Docker

```dockerfile
FROM python:3.12-slim
WORKDIR /app
RUN pip install --no-cache-dir as-redis-mcp-server
ENTRYPOINT ["as-redis-mcp-server"]
```

### Key 前缀白名单配置说明

`KEY_PREFIX_WHITELIST` 控制 AI 可访问的 Key 前缀，使用 glob 模式，逗号分隔：

| 配置值 | 效果 |
|--------|------|
| （空/不设置） | 允许所有 Key（**仅开发环境**） |
| `cache:*,session:*` | 仅允许 `cache:` 和 `session:` 开头的 Key |
| `user:*,order:*,product:*` | 允许三类业务 Key |

> **安全建议**：生产环境**必须**配置 Key 前缀白名单，避免 AI 访问不相关的 Key 空间。

---

## 快速验证

### 启动 MCP Server

```bash
# 直接启动（需先设置环境变量或 .env 文件）
export REDIS_HOST=127.0.0.1
export REDIS_PORT=6379
as-redis-mcp-server
```

### 使用 MCP Inspector 调试

```bash
npx @modelcontextprotocol/inspector as-redis-mcp-server
```

### 运行测试

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

---

## 技术栈

| 组件 | 版本 | 说明 |
|------|------|------|
| Python | >= 3.12 | 运行时 |
| FastMCP | >= 2.0 | MCP 框架 |
| redis-py | >= 5.0 (含 hiredis) | Redis 异步客户端 |
| Pydantic | >= 2.0 | Schema 验证 |
| pydantic-settings | >= 2.0 | 环境变量配置管理 |
| structlog | >= 24.0 | 结构化日志 |

---

## 项目结构

```
redis-mcp-server/
├── pyproject.toml          # 项目元数据与依赖
├── Dockerfile              # 容器化部署
├── README.md               # 本文档
├── src/
│   ├── main.py             # 入口点
│   ├── server.py           # Tool 注册（@mcp.tool()）
│   ├── config.py           # 配置管理（pydantic-settings）
│   ├── errors.py           # 统一错误模型
│   ├── mcp/server.py       # FastMCP 实例 + 生命周期
│   ├── tools/              # 8 个 MCP Tool 实现
│   ├── redis_client/       # 连接池 + SCAN + 分析器
│   ├── security/           # 白名单 + 脱敏 + 截断 + 限流
│   ├── models/schema.py    # Pydantic 模型
│   └── observability/      # structlog + 审计日志
└── tests/                  # pytest 测试套件
```

---

## License

MIT
