An MCP server that analyzes Python code for design patterns and architecture signals, proposes prioritized refactors, and can scaffold safe boilerplate intros with guarded headers.
Caution
Disclaimer — Experimental / Early Stage: This project uses third‑party libraries and optional integrations (Radon, Ruff, ast-grep, rope) that evolve quickly. Treat outputs as recommendations and verify against official docs and your tests before production use. Scaffolds are boilerplate helpers, not automatic refactors. Optional features are gated by env/CLI toggles and should be enabled deliberately.
- MCP Architecton for Python 🏛️🐍
Architecton focuses on pattern/architecture guidance with actionable prompts and minimal diffs. It unifies detectors, metrics, and ranked enforcement so you can move from “what’s wrong” to “what to do next” quickly.
- Pattern and architecture detection with tailored advice from a curated catalog
- Unified proposals: Radon metrics (CC/MI/LOC), Ruff-only rule counts, and ranked enforcement prompts
- Safe scaffolding: guarded module header with contract, validation gauntlet (ast/parso/libcst/astroid/RedBaron/tree-sitter/py_compile), complexity hint, and cross-refs
- Optional integrations (gated):
- ast-grep-py heuristics (top-level defs, long parameter lists, repeated literals)
- rope dry-run rename validator in enforcement (hits scope) and sanity parse
- FastMCP-based server; minimal tool surface; catalog-driven prompt hints
Requires Python 3.10+ and uses uv.
Install (editable):
uv sync --devRun the server:
uv run mcp-architectonAdd this to User Settings (JSON) or .vscode/mcp.json:
{
"mcp": {
"servers": {
"architecton": {
"command": "uvx",
"args": ["mcp-architecton"]
}
}
}
}User Settings (JSON) example using uvx (same as above). Alternatively, add .vscode/mcp.json with the same block to share in a workspace.
Runtime features are gated by environment variables and mirrored flags:
- ARCHITECTON_ENABLE_ASTGREP: enables ast-grep heuristics (default: enabled)
- ARCHITECTON_ENABLE_ROPE: enables rope checks and dry-run validator (default: enabled)
Flags (equivalent to setting env vars):
uv run mcp-architecton --enable-astgrep
uv run mcp-architecton --disable-astgrep
uv run mcp-architecton --enable-rope
uv run mcp-architecton --disable-ropeFish shell env example:
set -x ARCHITECTON_ENABLE_ASTGREP 0
set -x ARCHITECTON_ENABLE_ROPE 1
uv run mcp-architectonRun a quick indicator summary and ranked suggestions across a repo:
uv run python scripts/scan_repo.py --dir .Toggles also apply here:
uv run python scripts/scan_repo.py --enable-astgrep --disable-rope --dir .- propose-architecture: unified proposal using detectors, Radon, Ruff, and ranked enforcement prompts
- propose-patterns: pattern-focused filtering of the unified proposal
- analyze-metrics: Radon (CC/MI/LOC) and Ruff rule counts (Ruff-only; Vulture removed)
- thresholded-enforcement: anti-pattern indicators + ranked prompts with reasons
- analyze-patterns: detect design patterns
- analyze-architectures: detect architecture styles
- suggest-refactor-patterns: advice for detected patterns
- suggest-architecture-refactor: advice for detected architectures
- introduce-pattern / introduce-architecture: transformation-first; scaffold fallback; return unified diff (supports {dry_run, out_path})
- analyze-paths: scan files/dirs/globs with optional per-file metrics
# Unified proposal for file(s)
uv run mcp-architecton # call propose_architecture with {"files": ["path/to/file.py"]}
# Metrics + Ruff counts
uv run mcp-architecton # call analyze_metrics with {"files": ["src/**/*.py"]}
# Pattern-only proposal
uv run mcp-architecton # call propose_patterns with {"files": ["module.py"]}
# Introduce Strategy (dry-run)
uv run mcp-architecton # call introduce_pattern with {"name": "strategy", "module_path": "demo/demo_file_large.py", "dry_run": true}
# Refactor-as-new path
uv run mcp-architecton # call introduce_pattern with {"name": "strategy", "module_path": "demo/demo_file_large.py", "out_path": "demo/refactored_demo_file_large.py"}- Header scaffold preview: examples/preview-header.md
- ast-grep indicators: examples/preview-astgrep.md
- rope preview rename: examples/preview-rope.md
Generated scaffolds prepend a compact module docstring to enforce safe integration:
- Steps 1–5: role mapping → interface extraction → implementation → seam wiring → validate and commit minimal diffs
- Contract: inputs/outputs invariants (behavior unchanged)
- Validation: ast, parso, libcst, astroid, RedBaron, tree-sitter, py_compile
- Complexity: low/medium/high via LOC/top-level defs, with Strangler Fig/Branch-by-Abstraction cues
- Cross-refs: links for pattern/architecture and refactoring techniques (catalog-driven)
- Prompt: one-line hint from the catalog when available
This header is guidance only—the generator emits safe boilerplate, not automatic refactors.
If you use the bundled presets tool:
uv run architecton-presets list prompts
uv run architecton-presets list subruns
uv run architecton-presets show prompts minimal-seam-integration# Install
uv sync --dev
# Lint
uv run ruff check .
# Test
uv run -q pytest -q
# Run comprehensive pipeline
python scripts/run_pipeline.py --verbose
# Run specific pipeline stage
python scripts/run_pipeline.py --stage security --verboseInstall pre-commit hooks for automatic quality checks:
# Install pre-commit hooks
uv run pre-commit install
# Run manually
uv run pre-commit run --all-filesThe project includes a comprehensive pipeline for code quality, security, and analysis:
- Security Stage: Bandit security scanning, dependency vulnerability checks
- Quality Stage: Ruff linting/formatting, MyPy type checking, complexity analysis
- Testing Stage: Comprehensive test execution with coverage reporting
- Analysis Stage: Architecture and design pattern detection
See docs/pipeline.md and docs/pre-commit.md for detailed documentation.
- MCP Specification: https://modelcontextprotocol.io/
- FastMCP Framework: https://gofastmcp.com/
- Design Patterns (overview): https://refactoring.guru/design-patterns
- Python patterns (examples): https://github.com/faif/python-patterns
- Presentation/Domain/Data layering: https://martinfowler.com/bliki/PresentationDomainDataLayering.html
- Hexagonal Architecture: https://alistair.cockburn.us/hexagonal-architecture/
- Clean Architecture: https://8thlight.com/blog/uncle-bob/2012/08/13/the-clean-architecture.html
- Microservices: https://martinfowler.com/articles/microservices.html
- Event-Driven Architecture: https://martinfowler.com/articles/201701-event-driven.html
- CQRS: https://martinfowler.com/bliki/CQRS.html
Full curated catalog used by the server: data/patterns/catalog.json
Contributions welcome. Please keep changes typed, linted (Ruff), and include tests for behavior changes.
By contributing, you agree your contributions are licensed under the project’s MIT License. No Contributor License Agreement (CLA) is required at this time.