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

Command	What it does
/onboard	Index the codebase and produce a full orientation: structure, hotspots, complexity, blast radius
/risk-report	Score recent commits by risk, find hotspots, recommend where to focus review
/impact-check <file>	Before changing a file: blast radius, who calls what, what could break
/debug-error <error or log path>	Correlate an error/traceback to source code paths
/health-check	Full assessment: complexity, coupling, churn trends, actionable recommendations
/trace-function <name>	Map a function's callers, callees, complexity, and role in the system
/release [patch|minor|major]	Bump version, tag, and publish a new release to PyPI

MCP Tools

Code Analysis

Tool	Description
index_codebase	Index a Python project — parse AST, extract entities, build call graph
query_entity	Look up a function/class/file by name with all relationships
find_callers	Find all functions that call a given function
find_callees	Find all functions called by a given function
dependency_tree	Get import dependency tree for a file
search_code	Full-text search across indexed functions and classes
complexity_report	Top N most complex functions
codebase_summary	High-level stats and most-connected modules

Git Analysis

Tool	Description
analyze_recent_changes	Score recent commits by risk
analyze_commit	Deep-dive a single commit
hotspot_report	Files with high churn × high dependency count
blast_radius	Transitive impact of changing a file

Log Analysis

Tool	Description
ingest_logs	Parse log files, extract errors, group by signature
get_error_groups	List distinct error groups by frequency
error_detail	Full detail on an error group with code links
correlate_error	Map raw error text to code paths
error_timeline	Error frequency over time

Utility

Tool	Description
status	Server status and entity counts
reindex	Incremental re-index (only changed files)

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:

Variable	Default	Description
SUITABLE_LOOP_DB_PATH	~/.suitable-loop/suitable-loop.db	SQLite database path
SUITABLE_LOOP_LOG_LEVEL	INFO	Logging level

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