# cleanpy
> Python 3.12+ 最佳实践知识库 - MCP 服务器 + Claude Code 集成
为 AI 编程助手提供 33+ 个主题的中文文档，涵盖现代 Python 工具链（UV、Ruff、Basedpyright、Pytest）。通过 Rust 实现的零开销 MCP 服务器和专用 Claude Code 集成。
## 特性
- **MCP 服务器** - 通过工具查询 Python 最佳实践，支持 JSON-RPC 2.0
- **斜杠命令** - `/py` 命令实现自动化代码质量流程
- **专用 Agents** - python-implementer 和 python-checker 子代理
- **33+ 主题** - 涵盖 9 个类别的完整知识库
- **零运行时开销** - 编译时嵌入文档，类型安全的 Rust 实现
- **双范围安装** - 支持项目级 (.claude/) 和用户级 (~/.claude/) 安装
## 知识库主题
9 个类别，33+ 篇文档：
- **01_新特性** - PEP 695 泛型、PEP 701 f-string、@override、Linux Perf 支持
- **02_项目结构** - 扁平布局、命名约定、pyproject.toml、特殊文件
- **03_依赖管理** - UV 基础与高级功能、虚拟环境最佳实践
- **04_类型提示** - 基本/高级类型提示、Basedpyright 配置
- **05_代码质量** - Ruff Linter、Pre-commit 钩子
- **06_测试** - Pytest 基础、Fixtures、参数化、覆盖率
- **07_异步编程** - Asyncio 基础、上下文管理器、并发模式
- **08_性能优化** - 性能分析、数据结构、内存管理
- **09_安全** - OWASP Top 10、输入验证、加密最佳实践
## 快速开始
### 1. 安装
```bash
cargo build --release
cargo install --path .
```
### 2. 配置 MCP 服务器
```bash
# 使用 claude mcp 命令
claude mcp add -s project cleanpy cleanpy mcp
```
### 3. 安装斜杠命令和 Agents
```bash
cleanpy install # 项目级 (.claude/)
cleanpy install --scope local # 用户级 (~/.claude/)
```
安装内容：
- `commands/py.md` - `/py` 斜杠命令
- `agents/python-implementer.md` - Python 实现专家
- `agents/python-checker.md` - 代码质量检查器
### 4. 推荐配置
建议安装类 sequential-thinking 的思考链 MCP 服务器（如 sequential-thinking、reasoning 等）以增强复杂问题的推理能力。
## 使用
### MCP 工具
```python
# 列出所有主题
mcp__cleanpy__list_topics
# 获取特定主题文档
mcp__cleanpy__get_tips("asyncio_basics")
```
### 斜杠命令
```bash
/py 实现异步 HTTP 下载器，支持并发和进度显示
```
工作流程：查询最佳实践 → 实现代码 → Ruff 检查/格式化 → Basedpyright 类型检查
## 开发
### 添加新文档
1. 在 `src/python312_best_practices/XX_类别/` 创建 `.md` 文件
2. 添加 YAML Front Matter：
```yaml
---
topic: topic_id
title: 标题
when_to_use: 使用场景
keywords: [关键词1, 关键词2]
---
```
3. 重新构建：`cargo build`（`build.rs` 自动生成索引）