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. 安装

cargo build --release
cargo install --path .

2. 配置 MCP 服务器

# 使用 claude mcp 命令
claude mcp add -s project cleanpy cleanpy mcp

3. 安装斜杠命令和 Agents

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 工具

# 列出所有主题
mcp__cleanpy__list_topics

# 获取特定主题文档
mcp__cleanpy__get_tips("asyncio_basics")

斜杠命令

/py 实现异步 HTTP 下载器，支持并发和进度显示

工作流程：查询最佳实践 → 实现代码 → Ruff 检查/格式化 → Basedpyright 类型检查

开发

添加新文档

1. 在 src/python312_best_practices/XX_类别/ 创建 .md 文件
2. 添加 YAML Front Matter：

   ---
   topic: topic_id
   title: 标题
   when_to_use: 使用场景
   keywords: [关键词1, 关键词2]
   ---

3. 重新构建：cargo build（build.rs 自动生成索引）