pyscn-mcp

技能简介

pyscn-mcp 是 Ludo Technologies 官方维护的 Python 代码质量分析 MCP 服务器，把开源静态分析工具 pyscn 的能力通过 Model Context Protocol 暴露给 Claude Desktop、Claude Code、Cursor 等 AI 客户端。pyscn 本身是一个面向 Python 项目的代码结构分析器，能识别死代码、复杂函数、重复模式与架构异味；pyscn-mcp 让 AI 助手在不改文件的前提下直接调工具查询分析结果，把"找出这个仓库里复杂度最高的 10 个函数"、"这个文件哪些代码块没人调用"这种问题从"grep 猜"升级为"结构化分析结果"。安装方式上推荐使用 pipx/uvx 做隔离运行，避免污染全局 Python 环境。

核心能力

• 结构化代码查询：把 pyscn 的 AST 级分析结果通过 MCP tools 暴露给 AI，可查询函数圈复杂度、调用关系、依赖图、死代码与重复模式。
• 隔离运行：默认推荐 pipx / uvx 安装，每个项目独立虚拟环境，避免依赖冲突。
• 配置驱动：通过环境变量 PYSCN_CONFIG 指定项目级 .pyscn.toml 配置文件，无需修改源码即可调整分析阈值。
• 独立 CLI 模式：除作为 MCP server 启动外，也可以 pyscn-mcp 直接以命令行方式做一次性扫描，便于 CI 集成。
• MIT 开源许可：代码可自由用于商业项目，可二次封装进内部代码评审流程。
• 零侵入分析：只读扫描，不修改任何源代码，适合在 PR Review、refactor 规划阶段让 AI 调取。

安装配置

1. 使用 pipx 隔离安装（推荐）：pipx install pyscn-mcp，自动创建独立 venv 并注册可执行文件到 PATH。
2. 使用 uv 临时运行：uvx pyscn-mcp，无需安装即可一次性启动，适合临时调试。
3. 使用 pip 全局/虚拟环境安装：pip install pyscn-mcp，适合已激活项目 venv 的场景。
4. 准备配置文件：在 Python 项目根目录创建 .pyscn.toml，按需配置分析阈值（圈复杂度上限、扫描目录、忽略规则等）。
5. 配置 MCP 客户端：在 Claude Desktop / Claude Code / Cursor 的 MCP 配置中加入 pyscn-mcp server，命令为 uvx pyscn-mcp 或 pyscn-mcp，通过 env.PYSCN_CONFIG 指向项目 .pyscn.toml 绝对路径。
6. 重启 AI 客户端：保存 MCP 配置后重启 Claude Desktop 或在 Claude Code 中执行 /mcp 重连。

使用步骤

1. 在 Python 项目根目录创建或确认存在 .pyscn.toml，设置好需要扫描的源码目录与规则。
2. 用 pipx install pyscn-mcp 或 uvx pyscn-mcp 安装/运行服务。
3. 在 Claude Desktop / Claude Code / Cursor 的 MCP 配置中注册 server，命令为 uvx pyscn-mcp（或 pyscn-mcp），env 设置 PYSCN_CONFIG=/absolute/path/to/.pyscn.toml。
4. 重启 AI 客户端，确认 pyscn-mcp 出现在工具列表中。
5. 在对话中让 AI 调用相关分析，例如"分析 src/ 下所有函数的圈复杂度并列出 Top 10"、"找出 services/ 下从未被调用过的函数"、"对比 auth/ 模块和 payment/ 模块的耦合度"。
6. AI 助手读取 MCP 返回的结构化分析结果并给出可执行的改造建议。
7. CI 集成：在 pytest 之后加一步 pyscn-mcp --json > report.json，把结果作为 PR 评论的输入或在阈值超标时阻断合并。

适用场景

• 代码评审加速：让 Claude 在 PR Review 时直接拉结构化复杂度数据，而不是凭肉眼读代码判断"这个函数是不是太长了"。
• 重构优先级排序：在大型 Python monorepo 里快速识别复杂度/重复率最高的模块，优先投入重构工时。
• 死代码清理：扫描长期没人调用的函数与模块，配合 VCS blame 决定是否安全删除。
• 架构异味识别：让 AI 通过分析依赖图找到循环依赖、God Module、过深的调用链。
• CI/CD 质量门禁：把 pyscn-mcp 跑出的指标作为合并门槛，新代码圈复杂度超过阈值时拒绝合并。
• 新人 onboarding：让新成员通过对话快速了解项目代码质量地图，不必手工跑分析器读报告。

适用人群

• 维护中大型 Python 项目（特别是金融科技、SaaS 后端、数据平台）的资深 Python 工程师与 Tech Lead。
• 在 AI 编程助手（Claude Desktop / Cursor / Claude Code）中希望"让 AI 看懂项目代码质量"的 Python 开发者。
• 平台工程 / DevEx 团队，需要把代码质量分析无缝嵌入 Claude 工作流的工程师。
• 代码质量咨询顾问，给客户做技术债评估时用 MCP 工具快速产出数据。

工作原理

pyscn-mcp 内部使用 pyscn 作为分析引擎。pyscn 通过 Python AST 把源码解析为节点树，再依据一系列静态分析规则（圈复杂度、调用图、模块耦合度、复制粘贴检测等）输出结构化报告。pyscn-mcp 把这些分析能力通过 MCP 协议包装成 tools，每个 tool 接收查询条件（如目录、文件、阈值）并返回 JSON 格式结果。运行时通过 stdio 与 AI 客户端通信，加载 .pyscn.toml 配置文件控制分析范围与阈值。整个工具链是只读分析，不会修改任何源代码。

官方链接

• PyPI 包：https://pypi.org/project/pyscn-mcp/
• 完整文档：https://github.com/ludo-technologies/pyscn
• MCP 注册标识：io.github.ludo-technologies/pyscn
• GitHub 主页：https://github.com/ludo-technologies/pyscn
• 许可协议：MIT License