Suitable Loop

Local production engineering platform — semantic code analysis, git risk scoring, and log correlation via MCP.

What it does

Suitable Loop indexes your Python codebase and exposes deep analysis through MCP tools that AI assistants can call:

• Code Analysis — AST-based parsing, function/class extraction, call graph construction, cyclomatic complexity
• Git Risk Scoring — Weighted risk scores per commit (complexity delta × blast radius × churn × size)
• Log Correlation — Parse logs, group errors by signature, map stack frames to indexed code
• Dependency Graph — NetworkX-powered call graphs, import trees, blast radius analysis

Quick Start

1. Add MCP server to your project

Create .mcp.json in your project root:

{
  "mcpServers": {
    "suitable-loop": {
      "command": "uvx",
      "args": ["suitable-loop"]
    }
  }
}

That's it. uvx fetches the package from PyPI automatically — no manual install needed.

Local development? Point to a local checkout instead:

"args": ["--from", "/path/to/suitable-loop", "suitable-loop"]

2. Install slash commands (optional)

Clone the repo and copy the commands into your project:

git clone https://github.com/suitable-adventures/suitable-loop.git /tmp/suitable-loop
mkdir -p .claude/commands
cp /tmp/suitable-loop/.claude/commands/* .claude/commands/

3. Restart Claude Code and start using it

/onboard                          # Get a full codebase orientation
/risk-report                      # Analyze recent commits by risk
/impact-check models.py           # Check blast radius before changing a file
/debug-error "ConnectionResetError in db/pool.py"
/health-check                     # Full codebase health assessment
/trace-function my_function       # Map a function's callers and callees

Slash Commands

MCP Tools

Code Analysis

Git Analysis

Log Analysis

Utility

Architecture

suitable_loop/
├── __init__.py          # Package root
├── __main__.py          # Entry point (python -m suitable_loop)
├── server.py            # MCP server setup (FastMCP) + main() entry point
├── config.py            # Configuration dataclasses
├── models.py            # Data models (entities, edges)
├── db.py                # SQLite database layer
├── analyzers/
│   ├── code_analyzer.py # AST parsing, call resolution
│   ├── git_analyzer.py  # Commit analysis, risk scoring
│   └── log_analyzer.py  # Log parsing, error grouping
├── graph/
│   └── engine.py        # NetworkX graph engine
└── tools/
    ├── code_tools.py    # MCP code analysis tools
    ├── git_tools.py     # MCP git analysis tools
    ├── log_tools.py     # MCP log analysis tools
    └── util_tools.py    # MCP utility tools

Configuration

Environment variables:

Default exclude patterns (files skipped during indexing):

• .venv/, venv/, node_modules/, __pycache__/, migrations/, .git/

Development

For working on Suitable Loop itself:

cd suitable-loop
uv venv && uv pip install -e ".[dev]"
uv run pytest