Skip to main content
Glama
slamer59

MCP Python Refactoring

by slamer59
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

MCP Python Refactoring

License: MIT Python 3.13+ MCP Registry Docker

A Model Context Protocol (MCP) server that analyzes Python code and provides guided refactoring suggestions without automatically modifying your code.

Keywords

python refactoring code-analysis mcp-server ai-assistant claude rope radon vulture jedi educational mentoring code-quality static-analysis complexity-analysis

This tool integrates with AI coding assistants (Claude, ChatGPT, Cursor, etc.) to provide intelligent refactoring guidance. Instead of making automatic code changes, it gives you precise instructions on how to improve your Python code, acting as your refactoring mentor.

Related MCP server: MCP Refactoring

What This Tool Does

For AI Coding Assistants:

  • Provides structured JSON responses with refactoring opportunities

  • Identifies long functions, high complexity code, and dead code

  • Gives precise line numbers for extract method refactoring

  • Uses professional tools for comprehensive analysis

For Developers:

  • Get step-by-step refactoring instructions

  • Maintain full control over code changes

  • Learn refactoring patterns through guided practice

  • Improve code quality systematically

How It Differs

Approach

This Tool

Traditional Refactoring Tools

Integration

Works with any LLM/AI assistant

IDE-specific or standalone

Guidance

Step-by-step instructions with line numbers

Automatic changes only

Learning

Educational approach teaches patterns

No learning component

Control

Developer maintains full control

Tool makes all decisions

Registry Submissions

This MCP server is available across the entire MCP ecosystem:

Official MCP Registry

Published and Live: registry.modelcontextprotocol.io

  • Server name: io.github.slamer59/mcp-python-refactoring

  • Discoverable by all MCP-compatible clients

🟡 Docker MCP Registry

Pull Request Submitted: docker/mcp-registry #207

  • Will be available as mcp/mcp-python-refactoring on Docker Hub

  • Includes enhanced security: signatures, SBOM, provenance tracking

  • Integrated into Docker Desktop's MCP Toolkit

🟡 Awesome MCP Servers Lists

Community Curated Lists:

📦 Installation Options

Once all registries are live, users can discover via:

  • MCP catalog - Official registry search

  • Docker Desktop - MCP Toolkit integration

  • Community lists - GitHub awesome lists

  • Docker Hub - mcp/mcp-python-refactoring (with enhanced security)

Docker Support

Using with Docker MCP Catalog

# Pull from Docker Hub (after registry approval)
docker run -i mcp/mcp-python-refactoring

# Or build locally
docker build -t mcp-python-refactoring .
docker run -i mcp-python-refactoring

Dockerfile

FROM python:3.13-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    && rm -rf /var/lib/apt/lists/*

# Copy project files
COPY pyproject.toml README.md ./
COPY src/ ./src/

# Install the package
RUN pip install --no-cache-dir -e .

# Expose MCP server port (optional, for documentation)
EXPOSE 3000

# Run the MCP server
ENTRYPOINT ["python-refactor", "server"]

Installation

Quick Start with uvx (Recommended)

# Install and run MCP server directly from GitHub
uvx --from git+https://github.com/slamer59/mcp-python-refactoring.git python-refactor server

Add to Claude Code (One Command)

# Add to Claude Code MCP configuration
claude-code mcp add mcp-python-refactoring uvx --from git+https://github.com/slamer59/mcp-python-refactoring.git python-refactor server

After running this command, restart Claude Desktop and the Python refactoring tools will be available in your Claude conversations!

Development Installation

# Clone and setup for development
git clone https://github.com/slamer59/mcp-python-refactoring.git
cd mcp-python-refactoring
uv sync

# Run MCP server locally
python -m mcp_refactoring_assistant server

# Or use the entry point after installation
pip install -e .
python-refactor server

CLI Usage

The python-refactor-cli entry point (installed via uv sync or pip install -e .) runs every analysis standalone, without an MCP client — useful for scripts, CI, or driving the tool directly from an agent's shell:

uv run python-refactor-cli --help

In addition to analyze, analyze-package, package-metrics, package-issues, and package-dependencies, the CLI covers every MCP tool 1:1:

find-long-functions <file_path>

Find functions at or above a line-count threshold.

uv run python-refactor-cli find-long-functions src/app.py --line-threshold 30 --format json

extraction-guidance <file_path>

Step-by-step guidance for extracting a specific function.

uv run python-refactor-cli extraction-guidance src/app.py --function-name process_order

test-coverage <source_path>

Analyze test coverage and suggest what needs tests.

uv run python-refactor-cli test-coverage src/ --test-path tests/ --target-coverage 80

tdd-guidance <file_path>

Red-Green-Refactor guidance for a function.

uv run python-refactor-cli tdd-guidance src/app.py --function-name process_order

security-scan <file_path>

Security vulnerabilities, dependency scanning, and modernization suggestions (bandit, pip-audit, refurb).

uv run python-refactor-cli security-scan src/app.py --format table

Every command supports --format json for machine-readable output.

Working with Agents

This project ships a SKILL.md describing how an agent should call it — which command to use for which situation, and the JSON output contract.

uv run python-refactor-cli skill path

Point your coding agent (e.g. Claude Code) at the path this prints and ask it to load the skill file before refactoring Python code in this repo. A good generic prompt:

Run uv run python-refactor-cli skill path and load that skill for this session.

Available MCP Tools

Unified Server

Single Server: Both guide-only and apply-changes modes in one server

Connection Options:

  • stdin/stdout: python-refactor server (default)

  • Module execution: python -m mcp_refactoring_assistant server

Tools

1. analyze_python_code

Comprehensive analysis with optional automatic refactoring.

Parameters:

  • content (required): Python file content as string

  • mode (optional): "guide_only" (default) or "apply_changes"

  • file_path (optional): Path to the file for context

  • line_threshold (optional): Minimum lines for long functions (default: 20)

Mode: guide_only - Returns instructions only Mode: apply_changes - Returns modified code

2. analyze_security_and_patterns 🔒 NEW!

Comprehensive security scanning and modern Python patterns analysis.

Parameters:

  • content (required): Python file content as string

  • file_path (optional): Path to the file for context

  • include_security_scan (optional): Enable security vulnerability scanning (default: true)

  • include_dependency_scan (optional): Enable dependency vulnerability scanning (default: true)

  • include_modernization (optional): Enable modern Python pattern suggestions (default: true)

Features:

  • Security Analysis: Detects 20+ vulnerability types (hardcoded secrets, SQL injection, weak crypto, etc.)

  • Dependency Scanning: Scans project dependencies for known CVEs using pip-audit

  • Modernization: Suggests modern Python patterns (f-strings, pathlib, enumerate, etc.)

  • Intelligent Prioritization: Issues ranked by severity and impact

  • Configurable Analysis: Enable/disable specific scanning types as needed

3. extract_function

Extract specific functions with guide or apply mode.

Parameters:

  • content (required): Python file content

  • mode (optional): "guide_only" or "apply_changes"

  • function_name (optional): Specific function to target

  • start_line, end_line (for apply_changes): Exact extraction range

  • new_function_name (for apply_changes): Name for extracted function

4. quick_analyze

Fast analysis for immediate refactoring opportunities.

Parameters:

  • content (required): Python file content

Returns: Quick summary of long functions and parameter issues

4. check_types_with_pyrefly

Advanced type checking and quality analysis using pyrefly.

Parameters:

  • content (required): Python code content to type check

Returns: Detailed type errors, quality issues, and improvement suggestions

5. get_server_capabilities (Internal)

Returns server capabilities and available analysis tools.

Returns: List of available tools: rope, radon, vulture, jedi, libcst, pyrefly, mccabe, complexipy

Analysis Capabilities

Code Quality Issues Detected:

  • Functions over 20 lines (extract method opportunities)

  • High cyclomatic complexity (>10) using McCabe analysis

  • High cognitive complexity (>15) using Complexipy analysis

  • Functions with too many parameters (>5)

  • Dead/unused code (consolidated suggestions) via Vulture

  • Low maintainability index (<20) using Radon metrics

  • Type annotation problems detected by Pyrefly

  • Large files (>500 lines) with module splitting recommendations

  • Files with too many imports (>20) suggesting restructuring

🔒 Security & Modernization Features (NEW!):

  • Security Vulnerability Detection: Comprehensive security scanning using Bandit

  • Dependency Security Analysis: CVE detection in project dependencies with pip-audit

  • Modern Python Patterns: Code modernization suggestions using Refurb

  • Unified Analysis: Intelligent prioritization combining security and modernization

  • Configurable Scanning: Enable/disable specific analysis types via MCP endpoint

Additional Analysis Tools:

  • Performance Analysis: Bottleneck identification and optimization suggestions

  • Type Hints: Missing type annotation detection

  • Documentation: Docstring coverage and quality assessment

Professional Tools Used:

🔧 Core Refactoring Analysis:

  • Rope: Professional refactoring analysis and extract method detection

  • Radon: Code complexity metrics (cyclomatic, maintainability index)

  • Vulture: Dead code detection and unused import analysis

  • Jedi: Semantic code analysis and variable tracking

  • LibCST: Syntax tree manipulation for precise code analysis

  • Pyrefly: Advanced type checking and quality analysis

  • McCabe: Cyclomatic complexity measurement

  • Complexipy: Advanced complexity analysis and cognitive complexity

🔒 Security & Modernization Tools (NEW!):

  • Bandit: AST-based security vulnerability scanner (20+ vulnerability types)

  • pip-audit: Dependency vulnerability scanner with CVE database

  • Refurb: Modern Python pattern suggestions and code modernization

📁 Built-in Analysis:

  • File Analysis: File size analysis and module splitting recommendations

  • Package Analysis: Comprehensive package structure and dependency analysis

Testing and Debugging

Test with MCP Inspector

# Launch MCP Inspector
bunx @modelcontextprotocol/inspector

# In the web interface:
# Command: python
# Args: -m mcp_refactoring_assistant server
# Working Directory: /path/to/your/project

Test Both Modes in Inspector:

Guide Mode Test:

{
  "content": "def long_function():\n    print('line1')\n    # ... 20+ lines",
  "mode": "guide_only"
}

Apply Mode Test:

{
  "content": "def long_function():\n    print('line1')\n    # ... 20+ lines", 
  "mode": "apply_changes"
}

Test with Bun (Fastest)

# Install Bun if not available
curl -fsSL https://bun.sh/install | bash

# Install MCP SDK
bun install -g @modelcontextprotocol/sdk

# Run tests
export PATH=.venv/bin:$PATH && bun run test_unified.js

Test Standalone (No MCP)

# Simple Python test
python test_tool.py

# Test with example file
python -m mcp_refactoring_assistant --help

Debug Server Issues

# Check dependencies
uv sync

# Verify MCP imports
python -c "import mcp; print('MCP available')"

# Test individual tools
python -c "
from src.mcp_refactoring_assistant.server import EnhancedRefactoringAnalyzer
analyzer = EnhancedRefactoringAnalyzer()
print('Analyzer working')
"

Example Usage

Educational Workflow

  1. AI assistant calls analyze_python_code with guide_only mode

  2. Tool returns structured suggestions with precise steps

  3. Developer follows step-by-step instructions

  4. Developer learns refactoring patterns through practice

Productivity Workflow

  1. AI assistant calls analyze_python_code with apply_changes mode

  2. Tool returns modified code with applied refactorings

  3. Developer reviews changes and applies as needed

  4. Faster refactoring for experienced developers

Sample MCP Response (Guide Mode)

{
  "analysis_summary": {
    "total_issues_found": 2,
    "medium_priority": 1,
    "low_priority": 1
  },
  "refactoring_guidance": [
    {
      "issue_type": "extract_function",
      "location": "Function 'process_data' lines 45-78",
      "description": "Long function (34 lines) with extractable blocks",
      "precise_steps": [
        "SELECT lines 45-52 (validation block)",
        "CREATE function: validate_input(data)",
        "REPLACE with: is_valid = validate_input(data)"
      ]
    },
    {
      "issue_type": "dead_code", 
      "location": "Multiple locations (6 items)",
      "description": "6 unused items found",
      "precise_steps": [
        "Review all unused items listed below:",
        "• Line 11: Unused import 're'",
        "• Line 12: Unused import 'Optional'",
        "Verify each item is truly unused",
        "Remove confirmed unused code"
      ]
    }
  ]
}

Integration with Coding Assistants

Claude Code/CLI

Add to your MCP configuration:

{
  "servers": {
    "python-refactoring": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/slamer59/mcp-python-refactoring.git", "python-refactor", "server"]
    }
  }
}

Or for local installation:

{
  "servers": {
    "python-refactoring": {
      "command": "python",
      "args": ["-m", "mcp_refactoring_assistant", "server"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "python-refactoring": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/slamer59/mcp-python-refactoring.git", "python-refactor", "server"]
    }
  }
}

Or for local installation:

{
  "mcpServers": {
    "python-refactoring": {
      "command": "python",
      "args": ["-m", "mcp_refactoring_assistant", "server"]
    }
  }
}

Cline (VSCode Extension)

In VSCode settings or .vscode/settings.json:

{
  "cline.mcpServers": {
    "python-refactoring": {
      "command": "python",
      "args": ["-m", "mcp_refactoring_assistant", "server"]
    }
  }
}

Cursor

Add to Cursor's MCP configuration:

{
  "mcpServers": {
    "python-refactoring": {
      "command": "python",
      "args": ["-m", "mcp_refactoring_assistant", "server"]
    }
  }
}

Continue (VSCode Extension)

In ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "python-refactoring",
      "command": "python",
      "args": ["-m", "mcp_refactoring_assistant", "server"]
    }
  ]
}

Windsurf

Add to Windsurf MCP configuration:

{
  "servers": {
    "python-refactoring": {
      "command": "python",
      "args": ["-m", "mcp_refactoring_assistant", "server"]
    }
  }
}

Aider

Use with MCP bridge or direct integration:

aider --mcp-server "python -m mcp_refactoring_assistant server"

OpenHands (formerly OpenDevin)

In OpenHands configuration:

mcp_servers:
  python-refactoring:
    command: python
    args: ["-m", "mcp_refactoring_assistant", "server"]

Roo-Code

Add to Roo-Code's MCP settings:

{
  "mcpServers": {
    "python-refactoring": {
      "command": "python",
      "args": ["-m", "mcp_refactoring_assistant", "server"]
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.python-refactoring]
command = "python"
args = ["-m", "mcp_refactoring_assistant", "server"]

Terminal-based clients

For most terminal-based MCP clients:

# With uvx
client-name --mcp-server "uvx --from git+https://github.com/slamer59/mcp-python-refactoring.git python-refactor server"

# With local installation  
client-name --mcp-server "python -m mcp_refactoring_assistant server"

SSE Mode (Web-based clients)

For web-based clients that support SSE connections:

  1. Start the server in SSE mode:

# SSE mode is not currently supported
# Use stdin/stdout mode instead
python-refactor server

  1. Use stdin/stdout connection instead of SSE

Using with mcpo (ChatGPT and others)

For clients without native MCP support:

# Install mcpo
pip install mcpo

# Bridge MCP to OpenAI-compatible API
mcpo --mcp-server "python -m mcp_refactoring_assistant server" --port 8080

Then configure your client to use http://localhost:8080 as API endpoint.

Notes

  • Use python -m mcp_refactoring_assistant server for local installations

  • For uvx installation, use the full uvx command instead of local paths

  • Some clients may require additional configuration or have different syntax

  • Always use absolute paths when specifying python executable

  • Test the connection with the client's MCP debugging tools if available

How It Works

  1. Analysis: Server analyzes Python code using multiple professional tools

  2. Detection: Identifies specific refactoring opportunities with metrics

  3. Guidance: Provides precise line numbers and step-by-step instructions

  4. Integration: AI assistant interprets results and guides developer

  5. Control: Developer maintains full control over all code changes

User Feedback

Users report significant improvements in code quality understanding and refactoring skills when using this tool with AI assistants. The guided approach helps developers learn refactoring patterns while maintaining control over code changes.

"Finally, a tool that teaches me refactoring instead of doing it for me"
"The precise line numbers make it easy to follow the suggestions"
"Game changer for working with legacy code"

Troubleshooting

MCP Connection Issues:

  • Ensure all dependencies installed: uv sync

  • Check Python path: which python

  • Verify MCP import: python -c "import mcp"

Analysis Not Working:

  • Test analyzer directly: python test_tool.py

  • Check file permissions

  • Verify example file exists: ls examples/

Tool Responses Empty:

  • Check if code has functions to analyze (minimum complexity threshold)

  • Increase line threshold for testing: "line_threshold": 10

  • Verify file syntax is valid Python

  • Ensure virtual environment is activated

SSE Connection Issues:

  • Verify port is not in use: netstat -an | grep 3001

  • Check firewall settings for local connections

  • Ensure FastAPI and Uvicorn are installed: uv add fastapi uvicorn

Performance Issues:

  • For large codebases (>100 files), consider using file-specific analysis

  • Increase timeout settings in MCP client configuration

  • Use quick_analyze for immediate feedback on specific functions

Community Registries

Submit to awesome lists and community catalogs:

🆕 Recent Major Updates

Version 2.0: Security & Modernization Features

🎉 What's New:

  • 🔒 Security Scanning: Professional-grade vulnerability detection using Bandit

    • Detects 20+ security issue types (SQL injection, hardcoded secrets, weak crypto)

    • Integrates seamlessly with existing refactoring analysis

  • 📦 Dependency Security: CVE scanning with pip-audit

    • Scans project dependencies for known vulnerabilities

    • Provides specific version upgrade recommendations

  • ⚡ Code Modernization: Python pattern suggestions using Refurb

    • Suggests modern Python features (f-strings, pathlib, enumerate)

    • Helps upgrade legacy code to contemporary best practices

  • 🎯 Unified Analysis: Intelligent prioritization system

    • Combines security, modernization, and refactoring analysis

    • Smart priority ordering by severity and impact

    • Configurable scanning options via new MCP endpoint

  • ✅ Production Ready:

    • 177+ comprehensive tests (100% passing)

    • Extensive error handling and edge case coverage

    • Performance tested on large codebases

    • Full backward compatibility maintained

📊 Proven Results:

  • Successfully analyzed and improved itself through iterative refinement

  • Reduced code complexity while adding powerful new features

  • Enhanced type safety and maintainability throughout the codebase

License

MIT License - Free for personal and commercial use.

Available Tools

9 tools
analyze_python_fileB

Analyze Python file for refactoring opportunities with precise guidance

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYesPython file content to analyze
file_pathNoPath to Python file to analyze

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states it gives 'precise guidance' but doesn't clarify whether it modifies files, requires authentication, or has side effects. It implies a read operation but is not explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no unnecessary words. It is front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 2 parameters and no output schema, the description is minimal. It does not explain how to choose between 'content' and 'file_path', nor what the output looks like. More context would improve usability.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema's parameter descriptions, which are already clear. No additional constraints or usage hints are provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool analyzes Python files for refactoring opportunities, using a specific verb and resource. This distinguishes it from siblings like analyze_python_package or find_long_functions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like analyze_security_and_patterns or tdd_refactoring_guidance. The description lacks context on prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

analyze_python_packageC

Comprehensive package/folder analysis for refactoring opportunities

ParametersJSON Schema
NameRequiredDescriptionDefault
package_nameNoName of the package (optional, will be inferred from path)
package_pathYesPath to Python package/folder to analyze

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It does not disclose whether the tool modifies anything, requires dependencies, or what its output is. The word 'analysis' suggests a read-only operation, but this is not explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that conveys the core purpose. It is well front-loaded, though slightly generic and not structured with bullet points or examples.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool performing 'comprehensive analysis', the description lacks essential details: what the tool returns, any prerequisites, or limitations. Without an output schema, the agent has no idea what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the description does not add any additional meaning beyond what the schema already provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it performs 'comprehensive package/folder analysis for refactoring opportunities', specifying the verb and resource. However, it does not distinguish itself from sibling tools like 'find_package_issues' or 'analyze_security_and_patterns'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, nor are there any exclusions or prerequisites mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

analyze_security_and_patternsC

Comprehensive security scanning and modern Python patterns analysis

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYesPython file content to analyze
file_pathNoPath to Python file to analyze
include_modernizationNoInclude modern Python pattern suggestions (default: true)
include_security_scanNoInclude code security vulnerability scanning (default: true)
include_dependency_scanNoInclude dependency vulnerability scanning (default: true)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full disclosure burden. It only states 'scanning and analysis' without detailing behavioral traits like whether it modifies files, requires authentication, has rate limits, or output format. The vague term 'comprehensive' lacks specifics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient sentence. It is front-loaded with the key action. However, it is too brief and could benefit from elaboration without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters, no output schema, and no annotations, the description is incomplete. It does not explain return values, failure modes, or the scope of 'comprehensive'. A more detailed description is needed for adequate agent comprehension.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema; parameters are self-explanatory from their names and descriptions. No compensation needed for low coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Comprehensive security scanning and modern Python patterns analysis' clearly states the tool's purpose with specific verbs and resources. However, it does not differentiate from sibling tools like 'analyze_python_file' or 'find_package_issues', which may overlap.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives, such as 'analyze_python_file' for general analysis or 'find_package_issues' for dependency issues. No exclusions or context scenarios are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

analyze_test_coverageC

Analyze Python test coverage and suggest improvements

ParametersJSON Schema
NameRequiredDescriptionDefault
test_pathNoPath to test directory (optional)
source_pathYesPath to source code directory or file
target_coverageNoTarget coverage percentage (default: 80)

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavior, but it only states a generic analysis task. It does not clarify whether the tool runs tests, requires a coverage report, modifies files, or is read-only. The phrase 'suggest improvements' hints at output but lacks detail on side effects or requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise but arguably too minimal. It quickly states the purpose but omits critical context. It is front-loaded but could benefit from a second sentence clarifying behavior or usage without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and annotations, the description provides insufficient context. It does not explain the output format, what 'improvements' means, or how the tool interacts with the codebase. The agent has no way to assess prerequisites, side effects, or result structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents all 3 parameters (source_path, test_path, target_coverage). The description adds no additional meaning beyond the word 'coverage', which is already inferred from the tool name. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'analyze' and resource 'Python test coverage', with the added behavior 'suggest improvements'. It is specific and distinguishable from sibling tools like find_package_issues or analyze_security_and_patterns, though it could be more explicit about the unique focus on coverage.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings (e.g., find_package_issues or analyze_python_file). There are no prerequisites, context hints, or exclusions, leaving the agent to infer usage purely from the tool name and schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_long_functionsB

Find functions that are candidates for extraction

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYesPython file content to analyze
line_thresholdNoMinimum lines to consider a function long (default: 20)

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description bears full responsibility for behavioral disclosure. It only says 'find functions' but does not explain whether the tool performs analysis, modifies files, requires permissions, or what output format is expected. The lack of detail on behavioral traits is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single clear sentence with no unnecessary words. It is efficient, but could benefit from slightly more structure or context while remaining concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description should explain what the tool returns (e.g., list of functions with line numbers). It also does not differentiate from siblings. The description is too minimal for the complexity indicated by the parameter count and sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters have descriptions in the input schema, so the description does not need to add much. The tool name and description hint at the purpose, but no additional meaning beyond the schema is provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifically states 'Find functions that are candidates for extraction', clearly identifying the verb (find), resource (functions), and context (candidates for extraction). This distinguishes it from sibling tools like find_package_issues or analyze_python_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, nor does it mention when not to use it. Given siblings like get_extraction_guidance and analyze_python_file, the lack of differentiation is a significant gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_package_issuesB

Identify package-level refactoring opportunities and structural issues

ParametersJSON Schema
NameRequiredDescriptionDefault
issue_typesNoSpecific types of issues to look for (optional): scattered_functionality, god_package, circular_dependency, etc.
package_pathYesPath to Python package/folder

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose all behavioral traits. It only states the purpose without detailing return format, side effects, or required permissions. This is insufficient for an agent to fully understand the tool's behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence front-loaded with the main action. Every word earns its place with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description could hint at the result format (e.g., list of issues). It adequately conveys the purpose but lacks completeness about what the agent can expect in the response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters. The description does not add extra meaning beyond the schema, providing no additional context for parameter usage. Baseline is 3, and no additional value is provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool identifies package-level refactoring opportunities and structural issues. It uses a specific verb-noun pair and distinguishes from sibling tools like analyze_python_package (broader analysis) and get_package_metrics (metrics-focused).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives like analyze_python_package or find_long_functions. The usage context is implied but not articulated, and no warnings or prerequisites are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_extraction_guidanceC

Get detailed step-by-step guidance for extracting functions

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYesPython file content
file_pathNoPath to Python file
function_nameNoName of function to analyze for extraction

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must disclose behavioral traits. It only states the tool gives guidance, but does not clarify if it modifies anything, requires authentication, or the implications of missing parameters. It fails to inform the agent about side effects or safety.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that is appropriately concise. It is front-loaded and contains no superfluous information. However, it could benefit from slightly more detail without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (3 parameters, no output schema, no annotations) and sibling tools, the description is insufficient. It doesn't mention return value format, what happens if the function is not found, or the scope of the guidance. The agent lacks critical context to use the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for its three parameters, so the schema already explains each parameter. The description adds no extra meaning beyond what is in the schema, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get detailed step-by-step guidance for extracting functions' clearly indicates the tool provides guidance on function extraction, which is a specific verb+resource. However, it could be more precise, e.g., clarifying that it analyzes Python files, and doesn't distinguish from siblings that offer similar guidance (e.g., tdd_refactoring_guidance).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like analyze_python_file or tdd_refactoring_guidance. No when-to-use, when-not-to-use, or prerequisite information is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_package_metricsC

Get aggregated metrics for a Python package

ParametersJSON Schema
NameRequiredDescriptionDefault
package_nameNoName of the package (optional)
package_pathYesPath to Python package/folder

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description bears full responsibility for behavioral disclosure. It only implies a read operation ('get'), but fails to specify permissions, rate limits, or side effects. The description is insufficient for safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is concise and front-loaded. However, it could be more informative without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is incomplete; it does not explain what 'aggregated metrics' entails. There is no output schema to clarify the return value, leaving the agent uncertain about the tool's output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, as both parameters have descriptions in the schema. The tool description adds no extra meaning beyond the schema, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get aggregated metrics for a Python package' clearly states the action (get) and resource (package metrics). However, it does not differentiate from sibling tools like analyze_python_package, which could also return metrics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidance is provided. The description does not indicate when to use this tool vs alternatives like find_package_issues or analyze_test_coverage, leaving the agent without decision context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tdd_refactoring_guidanceA

Generate TDD-based refactoring guidance: test first, refactor, test again

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYesPython code content to refactor
test_pathNoPath to test directory (optional)
function_nameNoSpecific function/class to refactor (optional)

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It does not mention whether the tool is read-only, requires authentication, or has side effects. While 'generate guidance' suggests no destruction, the lack of explicit disclosure is a gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the core purpose and method. There is no redundancy or wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple guidance tool, the description is adequate but lacks detail on return values or output format, especially given no output schema. The description could clarify what the guidance contains (e.g., step-by-step suggestions, code diff).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage with descriptions for each parameter. The tool description adds no additional meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it generates TDD-based refactoring guidance with the specific cycle 'test first, refactor, test again'. It distinguishes well from sibling tools focused on analysis, security, and metrics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the name and description: use when you want TDD refactoring guidance for Python code. It does not explicitly state when not to use or list alternatives, but the sibling tools are unrelated, so no confusion arises.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 9 tool updatesv1.0.0
    • First observedanalyze_python_file
    • First observedanalyze_python_package
    • First observedanalyze_security_and_patterns
    • First observedanalyze_test_coverage
    • First observedfind_long_functions
    • First observedfind_package_issues
    • First observedget_extraction_guidance
    • First observedget_package_metrics
    • First observedtdd_refactoring_guidance
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0
Disambiguation4/5

Most tools have distinct purposes (file vs package analysis, metrics vs guidance, security vs tests). However, 'find_package_issues' and 'analyze_python_package' may have some overlap in identifying structural issues.

Naming Consistency5/5

All tools use consistent snake_case and follow a verb_noun pattern (find_, analyze_, get_, etc.), with no mixing of conventions.

Tool Count5/5

9 tools is well-scoped for a refactoring analysis server, covering files, packages, functions, tests, security, and patterns without being excessive.

Completeness3/5

The server covers analysis and guidance well but lacks any tool for applying refactoring (e.g., rename, extract). Users get recommendations but cannot execute changes via the server.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • OHM-MCP

    Murugarajr
    A
    license
    Not graded
    quality
    D
    maintenance
    AI-powered Python refactoring assistant that provides AST-based code analysis, SOLID violation detection, dead code elimination, type safety analysis, performance optimization, and automated refactoring with rollback capabilities.
    2
    MIT

  • MCP Refactoring

    marshally
    A
    license
    A
    quality
    C
    maintenance
    Enables LLMs to apply Martin Fowler's 71+ refactoring patterns to codebases through a pluggable, language-agnostic architecture. Supports previewing and applying refactorings, analyzing code smells, and inspecting code structure with safe-by-default operations.
    5
    5
    MIT

  • ropey

    andrewesweet
    A
    license
    A
    quality
    D
    maintenance
    Enables coding agents to perform safe, project-wide Python refactoring (rename, move, extract, inline, change signature, organize imports, etc.) with a dry-run safety contract and LSP-coordinate addressing.
    15
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/slamer59/mcp-python-refactoring'

If you have feedback or need assistance with the MCP directory API, please join our Discord server