pyoverview by closed-systems - MCP Server

PyOverview

A CLI tool and Model Context Protocol (MCP) server that enables you to directly inspect Python modules and classes, providing comprehensive documentation, methods, classes, and structural information.

Overview

PyOverview is a powerful tool that provides a comprehensive overview of Python modules and classes. It can be used both as a standalone CLI tool and as an MCP server to bridge the gap between LLMs and Python codebases. It allows dynamic inspection and understanding of Python modules, classes, functions, and their relationships without requiring static analysis or pre-generated documentation.

But Why?

Coding LLMs often base their decisions on outdated half remembered docs that might be work in progress (like humans do). This MCP cuts to the source of truth and often surfaces methods that aren't mentioned at all in docs that let you interface on the right level with the library.

> inspect the fastmcp.client module and note the functions useful for testing

⏺ I'll inspect the fastmcp.client module to identify functions useful for testing. Let me use
  the pyoverview MCP server to examine this module.

⏺ pyoverview - inspect_module (MCP)(target: "fastmcp.client")
  ⎿  🔬 Inspecting: fastmcp.client                                                            
     ├── 🏛️ Classes
     │   ├── BearerAuth - Base class for all authentication schemes.
     … +128 lines (ctrl+r to expand)

⏺ Now let me get more detailed information about the Client class and its methods, as this
  appears to be the main class for testing:

⏺ pyoverview - inspect_module (MCP)(target: "fastmcp.client.Client", short: false)
  ⎿  🔬 Inspecting: fastmcp.client.Client                                                     
     ├── 📦 Properties/Attributes
     │   ├── initialize_result: property
     … +300 lines (ctrl+r to expand)

⏺ Now let me also look at the transport classes, particularly FastMCPTransport which is
  mentioned as useful for testing:

⏺ pyoverview - inspect_module (MCP)(target: "fastmcp.client.FastMCPTransport")
  ⎿  🔬 Inspecting: fastmcp.client.FastMCPTransport                                           
     ├── 📦 Properties/Attributes
     │   └── _abc_impl: _abc_data
     … +21 lines (ctrl+r to expand)

⏺ Let me also check what testing utilities might be available in the auth module:

⏺ pyoverview - inspect_module (MCP)(target: "fastmcp.client.auth")
  ⎿  🔬 Inspecting: fastmcp.client.auth                                                       
     ├── 🏛️ Classes
     │   ├── BearerAuth - Base class for all authentication schemes.
     … +21 lines (ctrl+r to expand)

⏺ Based on my inspection of the fastmcp.client module, here are the key functions and classes
  useful for testing:

  Core Testing Classes

  Client - Main MCP client class with extensive testing capabilities:
  - Context manager support (async with client:)
  - Connection state checking (is_connected())
  - Session management with reference counting for reentrant contexts

  FastMCPTransport - In-memory transport ideal for unit tests:
  - Connects directly to FastMCP server instances in the same Python process
  - No network overhead, perfect for testing scenarios
  - Works with both FastMCP 2.x and 1.0 servers

  Key Testing Methods

  Tool Testing

  - call_tool(name, arguments) - High-level tool calling with automatic error raising
  - call_tool_mcp(name, arguments) - Raw MCP protocol tool calling, returns complete result
  object
  - list_tools() - Get available tools for validation

  Resource Testing

  - read_resource(uri) - Read resource contents
  - list_resources() - List available resources
  - list_resource_templates() - List resource templates

  Prompt Testing

  - get_prompt(name, arguments) - Retrieve rendered prompts
  - list_prompts() - List available prompts

  Connection Testing

  - is_connected() - Check connection state
  - ping() - Test server connectivity
  - new() - Create fresh client instances for independent test sessions

  Protocol Testing

  All methods have _mcp variants (e.g., call_tool_mcp()) that return raw MCP protocol results,
  useful for testing protocol compliance and error handling.

  Authentication Testing

  - BearerAuth - For testing bearer token authentication
  - OAuth - For testing OAuth flows (though less useful for unit tests)

  Testing Utilities

  The reentrant context manager design is particularly valuable for testing concurrent
  scenarios, allowing multiple async with client: blocks to share the same session safely.

  The FastMCPTransport is the most important class for testing as it enables in-process testing
   without network dependencies.

Features

Dynamic Module Inspection: Import and analyze any Python module at runtime
Rich Visualization: Beautiful tree-structured output with color-coded categories
Comprehensive Analysis: Extracts methods, classes, attributes, and documentation
Structured Data: Returns both human-readable and machine-parseable results
MCP Integration: Seamlessly integrates with Claude and other MCP-compatible AI assistants

Security

The S in MCP stands for Security. I'd recommend you always run MCPs in some sort of sandbox and keep your API and SSH keys out of their environment. In terms of this particular MCP you should be aware it is doing dynamic inspection of modules - i.e. they are loaded by the interpreter the MCP executes. This could lead to unexpected code execution and side effects if modules are written weirdly. Govern yourself accordingly.

Installation

Prerequisites

Python 3.13 or higher
uv package manager (recommended)

Install with uvx (recommended)

Run directly from GitHub without cloning:

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

Install with uv

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

Install with pip

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

Usage

As an MCP Server

Run the server to make it available to MCP-compatible clients:

python pyoverview.py --mcp

Supported Target Formats

The inspect_module tool accepts various target formats:

Module: src.sample_lib
Class: src.sample_lib.MyClass
Nested attributes: module.submodule.ClassName

Tool Reference

`inspect_module(target: str)`

Inspects a Python module or class and returns detailed information about its structure.

Parameters:

target: The full import path to the module or class (e.g., 'src.sample_lib' or 'src.sample_lib.MyClass')

Returns:

Rich formatted text output with tree structure
Structured data containing:
- modules: Submodules with documentation
- classes: Classes with docstrings
- functions: Functions/methods with signatures and documentation
- attributes: Properties and variables with type information

Example Output

When inspecting the module (pyoverview), you'll see (with short output on):

🔬 Inspecting: pyoverview
├── 📦 Properties/Attributes
│   ├── Dict: _SpecialGenericAlias
│   ├── List: _SpecialGenericAlias
│   └── server: FastMCP
├── 🔧 Methods/Functions
│   ├── inspect_module(target: str, short=False) -> fastmcp.tools.tool.ToolResult - A Python MCP (Module Control Panel) to inspect modules and classes.
│   ├── inspect_target(target_obj: Any) -> Dict[str, List[Dict]] - Inspects an object, builds a rich Tree, and returns a dictionary of its members.
│   └── render_tree(structure: Dict[str, List[Dict]], target: str, short) - 
├── 🏛️ Classes
│   ├── Any - Special type indicating an unconstrained type.
│   ├── Console - A high level console interface.
│   ├── FastMCP - Abstract base class for generic types.
│   ├── Path - PurePath subclass that can make system calls.
│   ├── TextContent - Text content for a message.
│   ├── ToolResult - 
│   └── Tree - A renderable for a tree structure.
└── 📦 Modules
    ├── importlib - A pure Python implementation of import.
    ├── inspect - Get useful information from live Python objects.
    └── sys - This module provides access to some objects used or maintained by the

An LLM asking about this module will see the above and also a structured JSON representation of the module/class requested. We don't iteratively examine modules due to the likely resulting madness.

I found out when doing final checks that the rich display library actually has its own fancy representation of a Python object function. It provides more information and uses more colors, I'm not sure if the extra data would help LLMs or confuse their context.

Project Structure

pyoverview/
-  README.md              # This file
-  pyproject.toml         # Project configuration
-  pyoverview.py          # Main CLI and MCP server implementation
-  uv.lock                # Dependency lock file

Dependencies

fastmcp: FastMCP framework for building MCP servers
rich: Rich text and beautiful formatting

Configuration for Claude Desktop

To use this MCP server with Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "pyoverview": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/closed-systems/pyoverview", "pyoverview", "--mcp"],
    }
  }
}

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

This project is open source. Please check the repository for license details.

Examples

Inspecting Standard Library Modules

import asyncio
from pyoverview import inspect_module

async def inspect_datetime():
    # Inspect the datetime module
    result = await inspect_module("datetime")
    print(result.content[0].text)

    
    # Inspect a specific class
    result = await inspect_module("datetime.datetime")
    print(result.content[0].text)


asyncio.run(inspect_datetime())

Troubleshooting

Common Issues

ModuleNotFoundError: Ensure the target module is in your Python path
AttributeError: Verify the class or attribute exists in the specified module
Import Errors: Check that all dependencies of the target module are installed

Debug Mode

For detailed error information, run the server with Python's verbose flag:

python -v pyoverview.py --mcp

Integration with Development Workflows

PyOverview is particularly useful for:

Code Documentation: Automatically generate documentation from live code
API Discovery: Explore unfamiliar codebases and libraries
Refactoring: Understand class hierarchies and dependencies
Testing: Verify module structure and available methods