python-clean-code

name	python-clean-code
description	Review Python code in the gsc-mcp codebase for clean code violations. Checks function size, single responsibility, type hints, naming, error handling patterns, and adherence to the project's module contracts. Use when refactoring a module or before code review.
allowed-tools	Read, Grep, Glob

Python Clean Code Review

Reviews Python code in gsc-mcp for quality issues. Read-only analysis: produces a findings report, applies no fixes.

When to use

Invoke before opening a PR, after adding a new tool, or when a module feels hard to read. Pass a file path or module name as the argument.

Review Dimensions

1. Function Size and Focus

Flag any function exceeding 30 lines (excluding docstring and blank lines). A function that does more than one thing usually has a name with "and" in it, or a docstring that lists multiple behaviors. Each tool function in tools/ should do exactly one thing: call the API, transform the response, and return the JSON string.

2. Type Hints

Every function signature must be fully annotated. Check for:

• Missing return type (-> str:, -> None:)
• Missing parameter types
• Use of Any without justification
• list and dict without subscripts where the shape is known (e.g. list[dict] not just list)

3. Naming

Private helpers must start with _. Constants at module level must be in _SCREAMING_SNAKE_CASE. Tool functions exposed to MCP must be lowercase with underscores. No abbreviations that require context to decode (r for rows; svc is acceptable because it appears consistently across the codebase).

4. Error Handling

Tool functions must not silently swallow exceptions. They may catch specific exceptions to convert them into user-friendly error messages, but they must not use bare except: or except Exception: without re-raising or returning a structured error response. Transient Google API errors belong in retry.py, not in tool functions.

5. Duplication

Check for logic duplicated across modules. Common candidates: date range calculation (already in analytics._date_range), URL normalization (already in cross._normalize_url), dimension filter construction (already in ga4._build_dimension_filter). If a function re-implements one of these, flag it.

6. Output Contract Compliance

Every public tool function must return json.dumps(with_meta(...)). Flag any function that:

• Returns raw json.dumps({...}) without with_meta
• Returns a plain string or dict
• Nests the main data under a "data" key inside with_meta

7. Docstrings

MCP uses the function docstring as the tool description visible to the user. The docstring must be present, must describe what the tool does (not how), and must mention key parameters and any data lag (GSC has a 3-day lag by default).

Output Format

## Clean Code Review: <file>

### Critical
- [function:line] [issue]: [why it matters]

### Improvement
- [function:line] [issue]: [suggested fix]

### Minor
- [function:line] [issue]

### Passed
- Type hints: complete on all public functions
- Output contract: all tools use with_meta

Evidence Rule

Every finding must cite the exact function name and line number. Do not flag something as a violation without reading the code to confirm it.