as-redis-mcp-server 1.0.0__tar.gz

as_redis_mcp_server-1.0.0/.env.example

@@ -0,0 +1,64 @@
+# Redis Connection
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_DB=0
+REDIS_USERNAME=default
+REDIS_PWD=
+REDIS_SSL=false
+REDIS_SSL_CA_CERTS=
+REDIS_CLUSTER_MODE=false
+
+# Connection Pool
+REDIS_MAX_CONNECTIONS=20
+REDIS_SOCKET_TIMEOUT=3
+REDIS_CONNECT_TIMEOUT=3
+
+# Security
+# Key prefix whitelist (glob patterns, comma-separated)
+# Example: cache:*,session:*,user:*,order:*
+# Leave empty to allow all keys (development only!)
+KEY_PREFIX_WHITELIST=
+
+# Limits
+MAX_SCAN_COUNT=100
+MAX_VALUE_LENGTH=2000
+RATE_LIMIT_QPS=20
+
+# Logging
+MCP_REDIS_LOG_LEVEL=INFO
+# ============================================================
+# Redis MCP Server Configuration
+# ============================================================
+# Copy this file to .env and edit values for your environment.
+# Environment variables take precedence over config file values.
+# ============================================================
+
+# --- Redis Connection ---
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_DB=0
+REDIS_USERNAME=default
+REDIS_PWD=
+REDIS_SSL=false
+REDIS_SSL_CA_CERTS=
+
+# --- Redis Cluster ---
+REDIS_CLUSTER_MODE=false
+
+# --- Connection Pool ---
+REDIS_MAX_CONNECTIONS=20
+REDIS_SOCKET_TIMEOUT=3
+REDIS_CONNECT_TIMEOUT=3
+
+# --- Security ---
+# Key prefix whitelist (comma-separated glob patterns)
+# Empty = allow all keys (development only)
+KEY_PREFIX_WHITELIST=
+
+# --- Limits ---
+MAX_SCAN_COUNT=100
+MAX_VALUE_LENGTH=2000
+RATE_LIMIT_QPS=20
+
+# --- Observability ---
+MCP_REDIS_LOG_LEVEL=INFO

as_redis_mcp_server-1.0.0/.idea/.gitignore

@@ -0,0 +1,8 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

as_redis_mcp_server-1.0.0/.idea/git_toolbox_blame.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="GitToolBoxBlameSettings">
+    <option name="version" value="2" />
+  </component>
+</project>

as_redis_mcp_server-1.0.0/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,5 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+  </profile>
+</component>

as_redis_mcp_server-1.0.0/.idea/misc.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.14" project-jdk-type="Python SDK">
+    <output url="file://$PROJECT_DIR$/out" />
+  </component>
+</project>

as_redis_mcp_server-1.0.0/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/redis-mcp.iml" filepath="$PROJECT_DIR$/.idea/redis-mcp.iml" />
+    </modules>
+  </component>
+</project>

as_redis_mcp_server-1.0.0/.idea/redis-mcp.iml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="JAVA_MODULE" version="4">
+  <component name="NewModuleRootManager" inherit-compiler-output="true">
+    <exclude-output />
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="jdk" jdkName="Python 3.14" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

as_redis_mcp_server-1.0.0/.idea/workspace.xml

@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AutoImportSettings">
+    <option name="autoReloadType" value="SELECTIVE" />
+  </component>
+  <component name="ChangeListManager">
+    <list default="true" id="45c0c31a-69f6-49c5-9277-81663ff4069f" name="Changes" comment="" />
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="MavenImportPreferences">
+    <option name="generalSettings">
+      <MavenGeneralSettings>
+        <option name="localRepository" value="E:\soft\Maven\repository" />
+        <option name="useMavenConfig" value="false" />
+        <option name="userSettingsFile" value="E:\soft\Maven\apache-maven-3.6.3\conf\settings.xml" />
+      </MavenGeneralSettings>
+    </option>
+  </component>
+  <component name="ProjectColorInfo"><![CDATA[{
+  "associatedIndex": 1
+}]]></component>
+  <component name="ProjectId" id="3GUOFBDUh9hDtpzkffz1cr0Ucy8" />
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.typescript.service.memoryLimit.init": "true",
+    "com.intellij.ml.llm.matterhorn.ej.ui.settings.DefaultModelSelectionForGA.v1": "true",
+    "junie.onboarding.icon.badge.shown": "true",
+    "last_opened_file_path": "F:/ai/learn/redis-mcp",
+    "node.js.detected.package.eslint": "true",
+    "node.js.detected.package.tslint": "true",
+    "node.js.selected.package.eslint": "(autodetect)",
+    "node.js.selected.package.tslint": "(autodetect)",
+    "nodejs_package_manager_path": "npm",
+    "settings.editor.selected.configurable": "MavenSettings",
+    "to.speed.mode.migration.done": "true",
+    "vue.rearranger.settings.migration": "true"
+  }
+}]]></component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-js-predefined-d6986cc7102b-9b0f141eb926-JavaScript-PY-253.31033.139" />
+        <option value="bundled-python-sdk-2653e85de345-6d6dccd035ac-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-253.31033.139" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="45c0c31a-69f6-49c5-9277-81663ff4069f" name="Changes" comment="" />
+      <created>1784022574693</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1784022574693</updated>
+      <workItem from="1784022575999" duration="2590000" />
+    </task>
+    <servers />
+  </component>
+  <component name="TypeScriptGeneratedFilesManager">
+    <option name="version" value="3" />
+  </component>
+</project>

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/FastMCP - Third-party MCP Framework/FastMCP - Third-party MCP Framework.md

@@ -0,0 +1,19 @@
+---
+kind: external_dependency
+name: FastMCP - Third-party MCP Framework
+slug: fastmcp
+category: external_dependency
+category_hints:
+    - framework_behavior
+    - sdk_real_api
+scope:
+    - '**'
+---
+
+### FastMCP 框架
+- **角色**：作为 MCP 协议的第三方封装框架，提供装饰器风格的工具注册和生命周期管理
+- **关键行为**：
+  - v3.x 版本移除了 `description` 参数，改用 `instructions` 参数进行服务器描述
+  - 支持 lifespan 上下文管理器模式，用于资源初始化和清理
+- **API 修正**：FastMCP 3.x 的 Tool 定义使用 `instructions` 而非 `description`，需在升级时注意兼容性
+- **验证方式**：确认 FastMCP 版本与 MCP 协议 2025-06-18 规范的兼容性

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/Python /344/276/235/350/265/226/347/256/241/347/220/206/357/274/210pyproject + hatchling/357/274/211/Python /344/276/235/350/265/226/347/256/241/347/220/206/357/274/210pyproject + hatchling/357/274/211.md"

@@ -0,0 +1,17 @@
+---
+kind: dependency_management
+name: Python 依赖管理（pyproject + hatchling）
+category: dependency_management
+scope:
+    - '**'
+source_files:
+    - pyproject.toml
+---
+
+本项目采用基于 PEP 621 的 pyproject.toml 作为唯一依赖声明入口，构建后端使用 hatchling，未引入 lockfile、私有源或 vendoring。
+
+- 运行时依赖：通过 [project].dependencies 声明，全部使用 >=major.minor 的宽松下限约束，包括 fastmcp>=2.0、redis[hiredis]>=5.0、pydantic>=2.0、pydantic-settings>=2.0、structlog>=24.0；要求 Python >=3.12。
+- 可选/开发依赖：通过 [project.optional-dependencies] dev 提供测试与质量工具链（pytest、pytest-asyncio、fakeredis、ruff、mypy），安装时使用 pip install -e .[dev]。
+- 可执行脚本：[project.scripts] redis-mcp-server = "src.main:main" 将包安装后暴露 CLI 入口。
+- 构建系统：[build-system] requires = ["hatchling"]，[tool.hatch.build.targets.wheel] packages = ["src"] 指定源码位于 src/。
+- 缺失能力：仓库中不存在 requirements.txt、Pipfile、poetry.lock、uv.lock 等锁定文件，也未配置任何自定义 PyPI 镜像或私有源；依赖版本以宽松下限为主，无固定上限，升级时由解析器决定具体版本。

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/Python /345/214/205/346/236/204/345/273/272/344/270/216/345/256/271/345/231/250/345/214/226/357/274/210Hatchling + Docker/357/274/211/Python /345/214/205/346/236/204/345/273/272/344/270/216/345/256/271/345/231/250/345/214/226/357/274/210Hatchling + Docker/357/274/211.md"

@@ -0,0 +1,19 @@
+---
+kind: build_system
+name: Python 包构建与容器化（Hatchling + Docker）
+category: build_system
+scope:
+    - '**'
+source_files:
+    - pyproject.toml
+    - Dockerfile
+---
+
+本项目采用基于 PEP 517/621 的现代化 Python 构建体系，核心由 Hatchling 驱动，并通过 Docker 完成镜像打包与部署。
+
+- 构建系统：pyproject.toml 声明 build-backend = "hatchling.build"，使用 Hatchling 作为后端，通过 [tool.hatch.build.targets.wheel] packages = ["src"] 指定源码目录为 src/。项目版本硬编码在 version = "1.0.0"，未引入动态版本或 Git 标签注入机制。
+- 依赖管理：运行时依赖集中在 [project].dependencies，开发依赖（pytest、ruff、mypy、fakeredis）放入 [project.optional-dependencies].dev。Docker 镜像内使用 uv pip install --system . 进行安装，借助 uv 加速依赖解析与安装。
+- 可执行入口：通过 [project.scripts] redis-mcp-server = "src.main:main" 暴露命令行工具，Dockerfile 以 ENTRYPOINT ["redis-mcp-server"] 启动服务。
+- 容器化：Dockerfile 基于 python:3.12-slim，先安装 uv，再复制 pyproject.toml 和 src/，最后用 uv pip install --system . 安装包；默认设置 MCP_REDIS_LOG_LEVEL=INFO 环境变量，并以 stdio 模式运行 MCP Server。
+- 测试与质量工具：pytest 配置于 [tool.pytest.ini_options]，启用 asyncio_mode = "auto"，测试路径为 tests/；代码风格检查使用 ruff（target-version=py312, line-length=100），类型检查使用 mypy（strict=true）。
+- 缺失项：仓库中不存在 Makefile、CI 流水线（如 .github/workflows）、tox.ini、setup.py/setup.cfg 等文件，也未发现自定义构建脚本（build*.sh）。发布流程未见 twine/publish 相关配置，版本管理为静态字符串。

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/Qoder IDE - MCP Host Client/Qoder IDE - MCP Host Client.md

@@ -0,0 +1,20 @@
+---
+kind: external_dependency
+name: Qoder IDE - MCP Host Client
+slug: qoder
+category: external_dependency
+category_hints:
+    - vendor_identity
+    - client_constraint
+scope:
+    - '**'
+---
+
+### Qoder IDE 集成
+- **角色**：MCP 协议的宿主客户端，通过 stdio 传输与 Redis MCP Server 通信
+- **集成约束**：
+  - 每个 Qoder 实例本地启动一个独立的 MCP Server 进程
+  - 要求每个 Tool 必须有标准的 `inputSchema` 和 `outputSchema`（JSON Schema 格式）
+  - 不支持运行时动态工具注册，Tool 设计需要在编译期确定 Schema
+- **配置文件**：Qoder 通过 `mcp.json` 或 IDE 设置中的 `mcpServers` 配置项来发现和管理 MCP Server
+- **传输协议**：默认使用 stdio 传输，stdout 被 MCP 协议占用，日志输出到 stderr

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/Redis - In-memory Data Store/Redis - In-memory Data Store.md

@@ -0,0 +1,24 @@
+---
+kind: external_dependency
+name: Redis - In-memory Data Store
+slug: redis
+category: external_dependency
+category_hints:
+    - vendor_identity
+    - client_constraint
+scope:
+    - '**'
+---
+
+### Redis 数据库
+- **角色**：核心数据存储后端，提供缓存、会话存储等能力
+- **集成点**：`src/redis_client/client.py` 中的 `RedisConnectionManager` 类管理连接池
+- **客户端约束**：
+  - 使用 `redis[hiredis]` 5.x 版本的异步客户端 (`redis.asyncio`) 
+  - 支持单机模式和 Cluster 模式，通过 `redis_cluster_mode` 配置切换
+  - 必须启用 `decode_responses=True` 以自动解码为字符串
+- **命令兼容性**：
+  - `MEMORY USAGE` 需要 Redis 4.0+，在 fakeredis 环境中不可用需优雅降级
+  - `INFO` 命令在某些受限环境中可能被禁用
+  - `SLOWLOG GET` 仅保留最近 128 条记录且重启后清空
+- **安全约束**：项目采用只读访问策略，通过白名单机制限制可执行命令

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/Redis MCP Server /351/241/271/347/233/256/346/240/271/Redis MCP Server /346/265/213/350/257/225/345/245/227/344/273/266/_module.yaml"

@@ -0,0 +1,8 @@
+schema_version: 1
+module_path: tests
+title: Redis MCP Server 测试套件
+scope:
+    - tests/
+source_files: []
+depends_on: []
+related_to: []

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/Redis MCP Server /351/241/271/347/233/256/346/240/271/Redis MCP Server /346/265/213/350/257/225/345/245/227/344/273/266//346/212/200/346/234/257/346/240/210.md"

@@ -0,0 +1 @@
+pytest + pytest-asyncio 驱动异步测试；fakeredis.aioredis.FakeRedis 作为无外部依赖的 Redis 替代；通过 `@pytest_asyncio.fixture` 声明 async fixture。

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/Redis MCP Server /351/241/271/347/233/256/346/240/271/Redis MCP Server /346/265/213/350/257/225/345/245/227/344/273/266//346/236/266/346/236/204/350/256/276/350/256/241.md"

@@ -0,0 +1,4 @@
+- 以 `conftest.py` 集中提供共享 fixture：`fake_redis`（空 FakeRedis）、`seeded_redis`（预置 hash/string/list/set/sorted set 等数据）以及 `key_filter_allow_all` / `key_filter_restricted` 两个 KeyFilter 实例，供各 `test_*.py` 复用。
+- 按被测模块划分测试文件：`test_security.py` 对应 `src.security.*`（whitelist/keyfilter/masker/limiter），`test_advisor_tool.py` 对应 `src.tools.advisor_tool`，其余 `test_*_tool.py` 分别对应一个 tool handler；`test_server.py` 校验 `create_server()` 返回的 MCP 服务名称及 `list_tools()` 注册的完整工具集。
+- 通过 `from src.mcp.server import create_server` 和 `from src import server as server_module; mcp = server_module.mcp` 直接访问应用层入口，不启动真实进程，属于单元/轻量集成测试而非端到端。
+- 依赖方向单向指向 `src/` 源码，测试包自身不包含业务逻辑，仅消费 `src.models.schema`、`src.errors`、`src.config.Settings` 等公共类型。

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/Redis MCP Server /351/241/271/347/233/256/346/240/271/Redis MCP Server /346/265/213/350/257/225/345/245/227/344/273/266//346/246/202/350/277/260.md"

@@ -0,0 +1 @@
+基于 pytest/pytest-asyncio 的 Redis MCP Server 集成与单元测试，使用 fakeredis 模拟 Redis 并覆盖安全、工具函数与服务注册。

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/Redis MCP Server /351/241/271/347/233/256/346/240/271/Redis MCP Server /346/265/213/350/257/225/345/245/227/344/273/266//347/274/226/347/240/201/350/247/204/350/214/203.md"

@@ -0,0 +1,4 @@
+- 每个被测源模块对应一个 `test_<module>.py` 文件，文件名与被测子包一一对应。
+- 对纯函数/类方法采用 `class TestXxx:` 组织用例，对需要异步 Redis 客户端的用例使用 `@pytest.mark.asyncio` 装饰器。
+- 共享资源统一在 `conftest.py` 中以 `@pytest_asyncio.fixture` 暴露，测试函数通过参数名注入，fixture 末尾显式 `await r.aclose()` 释放连接。
+- 断言失败时附带集合差集信息（如 `f"Missing tools: {EXPECTED_TOOLS - registered_tools}"`），便于快速定位缺失项。

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/Redis MCP Server /351/241/271/347/233/256/346/240/271/_module.yaml"

@@ -0,0 +1,12 @@
+schema_version: 1
+module_path: ""
+title: Redis MCP Server 项目根
+scope:
+    - README.md
+    - Dockerfile
+    - pyproject.toml
+    - spec/spec.md
+    - .env.example
+source_files: []
+depends_on: []
+related_to: []

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/Redis MCP Server /351/241/271/347/233/256/346/240/271//346/212/200/346/234/257/346/240/210.md"

@@ -0,0 +1 @@
+Python 3.12+ / hatchling 构建 / FastMCP ≥ 2.0 / redis-py[hiredis] ≥ 5.0 / Pydantic v2 + pydantic-settings / structlog / pytest + pytest-asyncio + fakeredis（dev extras）。

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/Redis MCP Server /351/241/271/347/233/256/346/240/271//346/236/266/346/236/204/350/256/276/350/256/241.md"

@@ -0,0 +1 @@
+根目录作为单一 hatchling 构建单元，将 src/ 下的分层模块（mcp/server、tools/*、redis_client/*、security/*、observability/*）打包为可安装包，并通过 pyproject.toml 的 [project.scripts] 暴露 redis-mcp-server CLI 入口；Dockerfile 基于 python:3.12-slim 用 uv pip install --system 安装该包并以 ENTRYPOINT 直接运行该脚本，实现容器内进程级隔离的 stdio MCP 传输；spec/spec.md 作为跨子模块的契约文档，统一约束所有 Tool 的 inputSchema/outputSchema、错误码与安全策略，tests/ 则按同一分层镜像编写 pytest-asyncio + fakeredis 用例，确保工具层、安全层与 Redis 适配层的变更在测试中联动验证。

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/Redis MCP Server /351/241/271/347/233/256/346/240/271//346/246/202/350/277/260.md"

@@ -0,0 +1 @@
+以 Python 包形式聚合 FastMCP Tool、安全守卫、Redis 适配与可观测层，通过 stdio 为 Qoder IDE 提供只读 Redis AI 助手。

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/Redis MCP Server /351/241/271/347/233/256/346/240/271//347/211/271/346/256/212/351/205/215/347/275/256/344/270/216/345/221/275/344/273/244.md"

@@ -0,0 +1 @@
+本地开发：`pip install -e ".[dev]"` 后直接执行 `redis-mcp-server` 启动 stdio MCP 服务；容器化：`docker build -t redis-mcp-server .` 后镜像默认以 ENTRYPOINT 运行同一 CLI。

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/Redis MCP Server /351/241/271/347/233/256/346/240/271//347/274/226/347/240/201/350/247/204/350/214/203.md"

@@ -0,0 +1,4 @@
+- 每个 Tool 必须配套 Pydantic BaseModel 定义输入参数，并由 FastMCP 自动推导 MCP inputSchema
+- 所有对外返回值经 security/masker 脱敏与截断后再输出，禁止直接透传原始数据
+- Redis 访问统一走 redis_client 连接池，禁止在 Tool 中直接 new 连接
+- 日志使用 structlog JSON 格式输出到 stderr，审计日志独立写入 redis_mcp_audit.log

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh/_index.yaml

@@ -0,0 +1,30 @@
+# 知识卡导出索引文件
+schema_version: 1
+locale: zh-CN
+branch: Q0DeR-MaG1C-BrAnCh-Fo2-NoN-GiT-Or-No-C0MmIt
+nodes_managed: true
+exported_at: "2026-07-14T10:50:03Z"
+modules:
+    "":
+        dir_name: Redis MCP Server 项目根
+        title: Redis MCP Server 项目根
+        scope:
+            - README.md
+            - Dockerfile
+            - pyproject.toml
+            - spec/spec.md
+            - .env.example
+        source_files: []
+        children:
+            - tests
+        depends_on: []
+        related_to: []
+    tests:
+        dir_name: Redis MCP Server 测试套件
+        title: Redis MCP Server 测试套件
+        scope:
+            - tests/
+        source_files: []
+        children: []
+        depends_on: []
+        related_to: []

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh//344/270/232/345/212/241/346/234/257/350/257/255/350/241/250//344/270/232/345/212/241/346/234/257/350/257/255/350/241/250.md

@@ -0,0 +1,39 @@
+---
+kind: business_term
+name: 业务术语表
+category: business_term
+scope:
+    - '**'
+---
+
+### MCP Server
+- 定义：Model Context Protocol 服务器，是本项目实现的核心组件。作为 MCP 协议的 Python 服务端实现，通过 stdio 传输与 Qoder IDE 通信，暴露一组语义化的 Redis 操作工具供 LLM 调用。每个工具都有明确的输入输出 Schema 定义，确保类型安全和参数校验。
+- 别名：mcp server、MCP服务
+
+### Tool
+- 定义：MCP 协议中的工具概念，指代 MCP Server 暴露给客户端的可调用功能单元。在本项目中，每个 Tool 对应一个具体的 Redis 操作场景（如键检查、模式分析、健康检查等），具有明确的名称、描述、输入参数 Schema 和输出结果格式。Tool 是 LLM 与 Redis 交互的唯一入口。
+- 别名：tool、工具
+
+### Command Whitelist
+- 定义：命令白名单机制，是本项目安全设计的核心组件。通过显式允许列表控制哪些 Redis 命令可以被执行，所有未明确允许的命令都被拒绝。当前白名单包含 GET、HGET、LRANGE 等只读命令，严格禁止 SET、DEL、CONFIG 等写操作和管理命令。
+- 别名：whitelist、命令白名单
+
+### Key Prefix Whitelist
+- 定义：Key 前缀白名单，是数据访问隔离的安全机制。通过配置允许访问的 Key 前缀模式（如 cache:*、session:*），防止 LLM 查询其他业务域或敏感数据的 Key。该机制与命令白名单配合，形成纵深防御体系。
+- 别名：key whitelist、前缀白名单
+
+### Rate Limiting
+- 定义：速率限制机制，用于保护 Redis 免受过度请求的影响。本项目实现了两种限流器：通用令牌桶限流器（RateLimiter）针对普通工具调用，以及专门的 SCAN 操作限流器（ScanRateLimiter）。限流失败会返回 RateLimitError 并记录审计日志。
+- 别名：rate limiter、限流器
+
+### Audit Logging
+- 定义：审计日志系统，用于记录所有工具调用的完整信息。每条审计日志包含时间戳、工具名称、参数（已脱敏）、执行的 Redis 命令、耗时、成功状态、错误码和结果大小等字段。审计日志文件独立于应用日志，便于安全合规审查。
+- 别名：audit log、审计日志
+
+### Readonly Query
+- 定义：受限只读查询工具，是项目中唯一允许执行非白名单命令的特殊接口。通过枚举类型严格限定可执行的命令集合（HLEN、LLEN、SCARD、ZCARD、STRLEN、ZSCORE、HEXISTS、SISMEMBER），并提供 field 参数的可选支持。这是为了兼容特定查询场景而设计的兜底接口。
+- 别名：readonly query、只读查询
+
+### Sampling Analysis
+- 定义：采样分析策略，是本项目的性能优化设计。对于可能匹配大量 Key 的操作（如模式分析、内存分析），不遍历所有匹配的 Key，而是随机采样固定数量的 Key 进行分析，并在结果中标注 sampled 字段说明数据来源。这避免了全量扫描对 Redis 造成的性能影响。
+- 别名：sampling、采样分析

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh//345/211/215/347/253/257/346/240/267/345/274/217/347/263/273/347/273/237/357/274/232/346/234/254/351/241/271/347/233/256/344/270/215/346/266/211/345/217/212/345/211/215/347/253/257 UI//345/211/215/347/253/257/346/240/267/345/274/217/347/263/273/347/273/237/357/274/232/346/234/254/351/241/271/347/233/256/344/270/215/346/266/211/345/217/212/345/211/215/347/253/257 UI.md"

@@ -0,0 +1,9 @@
+---
+kind: frontend_style
+name: 前端样式系统：本项目不涉及前端 UI
+category: frontend_style
+scope:
+    - '**'
+---
+
+经检索，该仓库为纯 Python 后端服务（Redis MCP Server），通过 stdio 协议向 Qoder IDE 暴露只读 Redis 工具函数。代码库中不存在任何 CSS、SCSS、HTML、模板文件或前端构建配置（如 tailwind.config、postcss.config、vite.config 等），也未发现与主题、设计令牌或组件库相关的资源。因此 `frontend_style` 类别不适用于本仓库。

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh//345/237/272/344/272/216 pydantic-settings /347/232/204/347/216/257/345/242/203/345/217/230/351/207/217/351/205/215/347/275/256/347/263/273/347/273/237//345/237/272/344/272/216 pydantic-settings /347/232/204/347/216/257/345/242/203/345/217/230/351/207/217/351/205/215/347/275/256/347/263/273/347/273/237.md"

@@ -0,0 +1,36 @@
+---
+kind: configuration_system
+name: 基于 pydantic-settings 的环境变量配置系统
+category: configuration_system
+scope:
+    - '**'
+source_files:
+    - src/config.py
+    - .env.example
+    - src/main.py
+    - pyproject.toml
+---
+
+本项目采用 **pydantic-settings** 作为统一的配置加载与校验层，所有运行时参数通过环境变量注入，并以 `.env` 文件提供默认值。核心设计如下：
+
+### 1. 配置模型定义
+- 唯一入口 `src/config.py` 中的 `Settings(BaseSettings)` 类集中声明全部配置项，使用 `Field(alias=...)` 将 Python 属性映射到 `REDIS_*`、`KEY_PREFIX_WHITELIST`、`MAX_SCAN_COUNT` 等环境变量。
+- 每个字段都附带合理默认值（如 `redis_host="127.0.0.1"`、`log_level="INFO"`），使服务可在无显式配置时启动。
+- 通过 `model_config = {"env_file": ".env", "env_file_encoding": "utf-8", "extra": "ignore"}` 自动从项目根目录的 `.env` 加载，并忽略未声明的环境变量。
+
+### 2. 配置分层与优先级
+- 优先级：**进程环境变量 > .env 文件 > 代码默认值**。
+- 示例模板 `.env.example` 列出全部可配置项及注释说明，部署时复制为 `.env` 并覆盖所需项。
+
+### 3. 类型校验与派生属性
+- 借助 pydantic 的类型注解（`int`、`bool`、`str | None`）在实例化时完成强类型校验，非法值直接抛出异常，避免运行时隐式错误。
+- 提供派生属性 `key_prefix_patterns`，将逗号分隔的 glob 字符串解析为列表，供安全模块消费。
+
+### 4. 使用方式
+- 入口 `src/main.py` 在启动时构造 `Settings()`，读取 `log_level` 初始化日志，并将完整配置对象传入后续组件（Redis 客户端、安全策略等）。
+- 通过 `pyproject.toml` 的 `[project.scripts]` 暴露 `redis-mcp-server` CLI 命令，统一由 `main()` 引导配置加载与服务启动。
+
+### 5. 约定与约束
+- 新增配置项必须在 `Settings` 中声明对应字段 + `alias`，并在 `.env.example` 补充条目。
+- 敏感信息（密码、证书路径）仅通过环境变量或 `.env` 注入，不硬编码；`.env` 不应提交至版本库。
+- 配置变更需同步更新测试夹具（`tests/conftest.py` 中使用 `fakeredis` 时通常通过环境变量覆盖连接参数）。

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh//345/237/272/344/272/216 structlog /347/232/204/347/273/223/346/236/204/345/214/226/346/227/245/345/277/227/347/263/273/347/273/237//345/237/272/344/272/216 structlog /347/232/204/347/273/223/346/236/204/345/214/226/346/227/245/345/277/227/347/263/273/347/273/237.md"

@@ -0,0 +1,28 @@
+---
+kind: logging_system
+name: 基于 structlog 的结构化日志系统
+category: logging_system
+scope:
+    - '**'
+source_files:
+    - src/observability/logger.py
+    - src/config.py
+    - src/main.py
+    - src/mcp/server.py
+    - src/redis_client/client.py
+    - src/observability/audit.py
+---
+
+本项目使用 `structlog` 作为结构化日志框架，通过 `src/observability/logger.py` 集中配置并对外暴露 `setup_logging` 和 `get_logger` 两个入口。日志输出到 `stderr`（因为 stdout 被 MCP stdio 传输独占），采用 `ConsoleRenderer` 以人类可读的键值对形式打印，同时启用 `merge_contextvars`、`add_log_level`、`TimeStamper(fmt="iso")`、`StackInfoRenderer` 等处理器，实现带 ISO 时间戳、调用栈信息和上下文变量的结构化输出。
+
+**初始化流程**：应用启动时 `main()` 先加载 `Settings`（含 `MCP_REDIS_LOG_LEVEL` 环境变量），调用 `setup_logging(config.log_level)` 完成全局配置，随后各模块通过 `get_logger(name)` 获取 `BoundLogger` 实例进行记录。
+
+**日志级别策略**：支持 DEBUG/INFO/WARNING(WARN)/ERROR/CRITICAL(FATAL)，默认 INFO；通过 `_resolve_level` 映射到 Python `logging` 标准级别，并使用 `make_filtering_bound_logger` 在 structlog 层做过滤。
+
+**使用约定**：所有业务模块统一从 `src.observability.logger import get_logger` 获取 logger，并以关键字参数传递结构化字段（如 `redis_host`、`redis_port`、`error=str(e)` 等），避免拼接字符串。审计日志通过独立的 `AuditLogger` 组件记录写入操作失败等安全相关事件。
+
+**关键文件**：
+- `src/observability/logger.py` — 日志框架初始化与工厂函数
+- `src/config.py` — `MCP_REDIS_LOG_LEVEL` 配置项
+- `src/main.py` — 应用启动时调用 `setup_logging`
+- `src/mcp/server.py`、`src/redis_client/client.py`、`src/observability/audit.py` — 典型的使用方

as_redis_mcp_server-1.0.0/.qoder/repowiki/knowledge/zh//347/273/237/344/270/200/351/224/231/350/257/257/346/250/241/345/236/213/344/270/216/345/267/245/345/205/267/345/261/202/345/274/202/345/270/270/345/244/204/347/220/206//347/273/237/344/270/200/351/224/231/350/257/257/346/250/241/345/236/213/344/270/216/345/267/245/345/205/267/345/261/202/345/274/202/345/270/270/345/244/204/347/220/206.md

@@ -0,0 +1,51 @@
+---
+kind: error_handling
+name: 统一错误模型与工具层异常处理
+category: error_handling
+scope:
+    - '**'
+source_files:
+    - src/errors.py
+    - src/server.py
+    - src/security/keyfilter.py
+    - src/security/limiter.py
+    - src/mcp/server.py
+---
+
+本仓库采用「领域异常 + 统一错误响应」的两层错误处理架构：各安全/业务组件抛出细粒度异常，在 MCP Tool 注册层统一捕获并转换为结构化的 MCPError JSON 返回给客户端。
+
+## 1. 错误分类与编码体系
+- src/errors.py 定义 ErrorCode（如 INVALID_INPUT、KEY_FORBIDDEN、RATE_LIMITED、REDIS_TIMEOUT、INTERNAL_ERROR）和 ErrorCategory（client_error / server_error）。
+- ERROR_META 将每个 code 映射到类别与是否可重试；ERROR_MESSAGES 提供人类可读的默认消息。
+- MCPError dataclass 作为最终响应体，包含 code、message、tool、category、retryable，并提供 to_json()。
+- create_error(code, tool_name, detail) 是构造响应的唯一入口，detail 会拼接到 message 末尾。
+
+## 2. 领域异常类型
+- KeyForbiddenError（src/security/keyfilter.py）：key 不在白名单时抛出。
+- RateLimitError（src/security/limiter.py）：QPS/SCAN 限流触发时抛出，支持区分 operation。
+- 其他 Redis 连接/超时等异常由上层 Exception 兜底归入 INTERNAL_ERROR。
+
+## 3. 统一捕获与响应格式
+- src/server.py 中每个 @mcp.tool() 装饰的异步函数遵循固定模式：
+  1) 记录 t0；2) 从 ctx.request_context.lifespan_context 取共享资源；3) try 调用具体 handler；4) 分别 catch KeyForbiddenError、RateLimitError、ValueError、Exception；5) 通过 _handle_error 生成结构化错误。
+- _handle_error(code, tool_name, detail, resources, args, t0) 内部调用 create_error，写入结构化日志并通过 _audit 记录审计日志（含 success=false、error_code），最后返回 error.to_json()。
+- 成功路径同样走 _audit，携带 duration_ms、success=true、result_size。
+
+## 4. 设计决策与约定
+- 不向上冒泡：Tool 层不向外抛异常，所有异常都被转换为 JSON 字符串返回，保证 MCP 协议侧只看到文本结果。
+- 按职责分层：安全/限流组件只负责「抛什么错」，错误呈现集中在 errors.py，避免在各处散落格式化逻辑。
+- 可重试语义：通过 ERROR_META 标注 retryable，客户端可据此实现退避策略（如 RATE_LIMITED、REDIS_TIMEOUT）。
+- 审计联动：每次调用无论成败都经 _audit 落盘，错误码直接关联审计事件，便于事后排查。
+
+## 5. 开发者应遵守的规则
+- 新增业务错误时，先在 ErrorCode 枚举补充 code，并在 ERROR_META、ERROR_MESSAGES 补齐元数据，再使用 create_error 构造响应。
+- 在对应 Tool 函数的 except 分支显式捕获领域异常（如 KeyForbiddenError、RateLimitError），不要依赖最外层 Exception 兜底。
+- 不要在工具实现中直接 print/raise 原始异常堆栈，必须经 _handle_error 包装后再返回。
+- 若需要新的可重试场景，更新 ERROR_META[code] 的第三个元素为 True。
+
+## 关键文件
+- src/errors.py — 错误码、分类、MCPError 结构与工厂
+- src/server.py — Tool 注册层统一异常捕获与审计
+- src/security/keyfilter.py — KeyForbiddenError 定义
+- src/security/limiter.py — RateLimitError 定义
+- src/mcp/server.py — FastMCP 生命周期（无全局中间件，错误处理下沉至 Tool 层）