PyOverview

一个CLI工具和模型上下文协议（MCP）服务器，使您能够直接检查Python模块和类，提供全面的文档、方法、类和结构信息。

概述

PyOverview 是一个强大的工具，提供了对Python模块和类的全面概述。它既可以作为独立的CLI工具使用，也可以作为MCP服务器来弥合LLMs与Python代码库之间的差距。它允许动态检查和理解Python模块、类、函数及其关系，而无需静态分析或预生成文档。

为什么？

编码LLMs经常基于过时的半记忆中的文档做出决策，这些文档可能还在进行中（就像人类一样）。这个MCP直接从真实来源获取信息，并且经常揭示在文档中未提及的方法，让你能够在正确的级别上与库进行交互。

> 检查 fastmcp.client 模块并记录用于测试的函数

⏺ 我将检查 fastmcp.client 模块以识别用于测试的函数。让我使用
  pyoverview MCP服务器来检查此模块。

 McCartney: pyoverview - inspect_module (MCP)(目标: "fastmcp.client")
  ⎿  🔬 正在检查: fastmcp.client                                                            
     ├── 🏛️ 类
     │   ├── BearerAuth - 所有身份验证方案的基础类。
     … +128 行（按 ctrl+r 展开）

 McCartney: 现在我将获取关于 Client 类及其方法的更详细信息，因为这
  似乎是最主要的测试类：

 McCartney: pyoverview - inspect_module (MCP)(目标: "fastmcp.client.Client", 简短: false)
  ⎿  🔬 正在检查: fastmcp.client.Client                                                     
     ├── 📦 属性/属性
     │   ├── initialize_result: 属性
     … +300 行（按 ctrl+r 展开）

 McCartney: 现在我还将查看传输类，特别是 FastMCPTransport，它被提到
  对于测试很有用：

 McCartney: pyoverview - inspect_module (MCP)(目标: "fastmcp.client.FastMCPTransport")
  ⎿  🔬 正在检查: fastmcp.client.FastMCPTransport                                           
     ├── 📦 属性/属性
     │   └── _abc_impl: _abc_data
     … +21 行（按 ctrl+r 展开）

 McCartney: 我还将检查 auth 模块中可能可用的测试工具：

 McCartney: pyoverview - inspect_module (MCP)(目标: "fastmcp.client.auth")
  ⎿  🔬 正在检查: fastm
 mcp.client.auth                                                       
     ├── 🏛️ 类
     │   ├── BearerAuth - 所有身份验证方案的基础类。
     … +21 行（按 ctrl+r 展开）

 McCartney: 根据我对 fastmcp.client 模块的检查，这里是一些关键函数和类
  用于测试：

  核心测试类

  Client - 主要的MCP客户端类，具有广泛的测试能力：
  - 支持上下文管理器（async with client:）
  - 连接状态检查（is_connected()）
  - 使用引用计数的会话管理，适用于重新进入的上下文

  FastMCPTransport - 内存传输，非常适合单元测试：
  - 直接连接到同一Python进程中的FastMCP服务器实例
  - 没有网络开销，非常适合测试场景
  - 适用于FastMCP 2.x和1.0服务器

  关键测试方法

  工具测试

  - call_tool(name, arguments) - 高级工具调用，自动抛出错误
  - call_tool_mcp(name, arguments) - 原始MCP协议工具调用，返回完整的结果对象
  - list_tools() - 获取可用于验证的工具

  资源测试

  - read_resource(uri) - 读取资源内容
  - list_resources() - 列出可用资源
  - list_resource_templates() - 列出资源模板

  提示测试

  - get_prompt(name, arguments) - 获取渲染提示
  - list_prompts() - 列出可用提示

  连接测试

  - is_connected() - 检查连接状态
  - ping() - 测试服务器连通性
  - new() - 创建新的客户端实例，用于独立的测试会话

  协议测试

  所有方法都有_mcp变体（例如，call_tool_mcp()），它们返回原始MCP协议结果，
  有助于测试协议合规性和错误处理。

  认证测试

  - BearerAuth - 用于测试承载令牌认证
  - OAuth - 用于测试OAuth流程（尽管对于单元测试不太有用）

  测试工具

  重新进入的上下文管理器设计特别有利于测试并发场景，允许多个异步with client: 块安全地共享同一个会话。

特性

• 动态模块检查：运行时导入并分析任何Python模块
• 丰富的可视化：漂亮的树形结构输出，带有彩色分类
• 全面分析：提取方法、类、属性和文档
• 结构化数据：返回可读和机器解析的结果
• MCP集成：无缝集成到Claude和其他兼容MCP的AI助手

安全性

MCP中的S代表安全性。建议您始终在某种沙箱环境中运行MCP，并确保您的API和SSH密钥不暴露给其环境。就这个特定的MCP而言，您应该意识到它正在动态检查模块——即它们是由MCP执行的解释器加载的。如果模块编写得非常奇怪，可能会导致意外的代码执行和副作用。请自行调整。

安装

先决条件

• Python 3.13 或更高版本
• uv 包管理器（推荐）

使用uvx安装（推荐）

直接从GitHub运行而不克隆：

uvx --from git+https://github.com/closed-systems/pyoverview pyoverview

使用uv安装

git clone https://github.com/closed-systems/pyoverview
cd pyoverview
uv sync

使用pip安装

git clone https://github.com/closed-systems/pyoverview
cd pyoverview
pip install -e .

使用

作为MCP服务器

运行服务器使其可供兼容MCP的客户端使用：

python pyoverview.py --mcp

支持的目标格式

inspect_module工具接受各种目标格式：

• 模块：src.sample_lib
• 类：src.sample_lib.MyClass
• 嵌套属性：module.submodule.ClassName

工具参考

inspect_module(target: str)

检查Python模块或类，并返回有关其结构的详细信息。

参数：

• target：模块或类的完整导入路径（例如，'src.sample_lib'或'src.sample_lib.MyClass'）

返回值：

• 富文本格式输出，带有树形结构
• 结构化数据包含：
  • modules：带有文档的子模块
  • classes：带有文档字符串的类
  • functions：带有签名和文档的方法/函数
  • attributes：带有类型信息的属性和变量

示例输出

当检查模块（pyoverview）时，你会看到（短输出开启）：

🔬 正在检查: pyoverview
├── 📦 属性/属性
│   ├── Dict: _SpecialGenericAlias
│   ├── List: _SpecialGenericAlias
│   └── server: FastMCP
├── 🔧 方法/函数
│   ├── inspect_module(target: str, short=False) -> fastmcp.tools.tool.ToolResult - 一个Python MCP（模块控制面板）用于检查模块和类。
│   ├── inspect_target(target_obj: Any) -> Dict[str, List[Dict]] - 检查对象，构建富树，并返回其成员的字典。
│   └── render_tree(structure: Dict[str, List[Dict]], target: str, short) - 
├── 🏛️ 类
│   ├── Any - 特殊类型，表示无约束类型。
│   ├── Console - 高级控制台接口。
│   ├── FastMCP - 泛型类型的抽象基类。
│   ├── Path - 可以调用系统命令的PurePath子类。
│   ├── TextContent - 消息的文本内容。
│   ├── ToolResult - 
│   └── Tree - 用于树形结构的可渲染项。
└── 📦 模块
    ├── importlib - 纯Python实现的导入。
    ├── inspect - 从实时Python对象中获取有用的信息。
    └── sys - 该模块提供了对一些由Python使用或维护的对象的访问。

一个LLM询问此模块时，将看到上述内容以及所请求模块/类的结构化JSON表示。我们不会迭代检查模块，以免造成混乱。

我在最终检查时发现，rich显示库实际上有自己的Python对象函数的漂亮表示。它提供了更多信息，并使用了更多的颜色，我不确定额外的数据是否会对LLMs有所帮助，还是会让它们的上下文混淆。

项目结构

pyoverview/
-  README.md              # 本文件
-  pyproject.toml         # 项目配置
-  pyoverview.py          # 主CLI和MCP服务器实现
-  uv.lock                # 依赖锁定文件

依赖项

• fastmcp：用于构建MCP服务器的FastMCP框架
• rich：富文本和美观格式

配置Claude Desktop

要将此MCP服务器与Claude Desktop一起使用，请在您的claude_desktop_config.json中添加以下内容：

{
  "mcpServers": {
    "pyoverview": {
      "命令": "uvx",
      "参数": ["--from", "git+https://github.com/closed-systems/pyoverview", "pyoverview", "--mcp"],
    }
  }
}

贡献

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 如适用，添加测试
5. 提交拉取请求

许可

该项目是开源的。请参阅存储库以获取许可详情。

示例

检查标准库模块

import asyncio
from pyoverview import inspect_module

async def inspect_datetime():
    # 检查 datetime 模块
    result = await inspect_module("datetime")
    print(result.content[0].text)

    
    # 检查特定类
    result = await inspect_module("datetime.datetime")
    print(result.content[0].text)


asyncio.run(inspect_datetime())

故障排除

常见问题

1. ModuleNotFoundError：确保目标模块在您的Python路径中
2. AttributeError：验证指定模块中的类或属性是否存在
3. 导入错误：检查目标模块的所有依赖项是否已安装

调试模式

为了获得详细的错误信息，请使用Python的verbose标志运行服务器：

python -v pyoverview.py --mcp

与开发工作流的集成

PyOverview 特别适用于：

• 代码文档：从实时代码自动生成文档
• API发现：探索不熟悉的代码库和库
• 重构：了解类层次结构和依赖关系
• 测试：验证模块结构和可用方法