Loop Engineering MCP Server

Stop typing prompts. Start designing systems that prompt.

Automate repetitive coding tasks with AI agents. Set up once, run forever.

What is This?

An MCP server that brings loop engineering to your AI coding workflow. Instead of manually prompting your AI agent for every task, you design loops that prompt the agent for you. Each loop implements the canonical loop-engineering control system:

• 🔄 Run automatically on a schedule (the heartbeat)
• 🔁 Iterate until the goal is verifiably met — act → verify → decide → repeat
• 🧑‍🔧 Maker/checker separation — the agent makes changes; an independent checker gate decides whether the goal is met (the agent never grades its own homework)
• 🛑 Stop rules — escalate to a human after N attempts or on a repeated failure (no Ralph-Wiggum runaway loops)
• 🌳 Worktree isolation — each run gets its own git worktree so parallel loops never collide
• 💸 Budget caps — daily run limits and a cumulative cost ceiling
• 🧠 Durable memory — state file with run history and lessons learned that survives restarts
• 🧪 Suitability test — a 4-condition pre-flight check so you only automate loop-shaped work

Think of it as: GitHub Actions + AI Agents + an Intelligent, Self-Verifying Control Loop

Why is This Powerful?

Before Loop Engineering

You: "Check CI failures"          [5 minutes]
AI:  [reports failures]

You: "What caused the auth test failure?"  [3 minutes]
AI:  [investigates]

You: "Fix it"                     [10 minutes]
AI:  [writes fix]

You: "Open a PR"                  [2 minutes]
AI:  [creates PR]

Total: 20 minutes × 4 times/day = 80 minutes/day

After Loop Engineering

[You set up once: "Create a CI triage loop, run every 6 hours"]

Loop automatically:
✅ Detects failures
✅ Classifies (flake vs bug vs env issue)
✅ Drafts fixes for deterministic bugs
✅ Runs tests
✅ Opens PRs
✅ Escalates complex issues
✅ Records lessons learned

Total: 0 minutes/day (runs while you sleep)

Real Impact:

• ⚡ 80% faster - Loops run in parallel, don't need your attention
• 🎯 Higher quality - Consistent checks, learns from past mistakes
• 💰 Cost effective - Only runs when needed, tracks ROI
• 😴 Works 24/7 - Runs while you sleep, on weekends

What Can You Automate?

✅ Perfect for Loops

• CI Triage - Classify failures, draft fixes, escalate blockers
• Dependency Updates - Check for updates, test compatibility, create PRs
• Lint & Format - Apply automated fixes on every PR
• Documentation Sync - Keep docs updated with code changes
• Flaky Test Detection - Identify and track intermittent failures
• Security Patches - Auto-apply safe security updates

❌ Don't Automate These

• Architecture decisions (requires judgment)
• Auth/payment code (too risky)
• Production deployments (needs human oversight)
• Vague product work (unclear success criteria)

Installation

Pick one of the following. Both work with the MCP config templates in Setup below.

Option 1: uv (Recommended)

Install uv, then run the server from PyPI — no separate pip install needed:

uvx loop-mcp

Use the uv MCP template (command: uvx) in Step 1.

Option 2: pip

pip install loop-mcp

Verify it is on your PATH:

loop-mcp

Use the pip MCP template (command: loop-mcp) in Step 1.

Option 3: From Source (Local Development)

Clone and install:

# Clone repository
git clone https://github.com/yourusername/loop-engineering
cd loop-engineering

# Install Python package
cd python
pip install -e ".[dev]"

Setup (2 minutes)

Step 1: Add to Your AI Agent Config

For Cursor

Create or edit .cursor/mcp.json in your project.

uv (Option 1 — uvx fetches loop-mcp from PyPI automatically):

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

pip (Option 2 — after pip install loop-mcp):

{
  "mcpServers": {
    "loop-engineering": {
      "command": "loop-mcp"
    }
  }
}

For Kiro

Create or edit .kiro/settings/mcp.json — same templates as Cursor above (uv or pip).

For Claude Desktop

Mac: Edit ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: Edit %APPDATA%\Claude\claude_desktop_config.json

Use the same uv or pip template as Cursor above.

Local development? Use:

{
  "command": "python",
  "args": ["-m", "loop_engineering_mcp"]
}

Step 2: Restart Your AI Agent

• Cursor: Reload window (Cmd/Ctrl + R)
• Kiro: Reconnects automatically
• Claude Desktop: Restart application

Step 3: Create Your First Loop

Open your AI agent and say:

Create a CI triage loop that runs every 6 hours

The AI will set up everything automatically.

Quick Example

Creating a Loop

You: "Create a CI triage loop"

AI: ✅ Loop 'ci-triage' created!
    Schedule: Every 6 hours
    Verification: npm test
    Goal: All CI failures classified
    
    Files created:
    - .loop/loops.json (configuration)
    - .loop/skills/ci-triage.md (instructions)
    - .loop/state/ci-triage.json (state tracking)

You: "Start it"

AI: ✅ Loop started and will run automatically

Checking Status

You: "What loops are running?"

AI: 📊 Active loops:
    
    ci-triage
    - Last run: 2 hours ago
    - PRs today: 3 (2 merged)
    - Acceptance rate: 67%
    - Token cost today: $4.20

Viewing History

You: "Show me ci-triage state"

AI: 📊 State for ci-triage:
    
    Last 5 runs:
    - 2h ago: Classified 3 failures, opened 2 PRs
    - 8h ago: All tests passing, no action needed
    - 14h ago: Fixed flaky auth test, escalated DB issue
    
    Lessons learned:
    - Auth tests need AUTH_SECRET env var
    - E2E tests require Stripe webhook config

Available Tools

Once installed, your AI agent gets these tools:

Your AI agent uses these automatically when you ask for loop-related tasks.

How a run actually loops

run_loop_now ──► brief (goal, working dir, stop rule)
      │
      ▼
  agent makes the smallest change
      │
      ▼
complete_loop_run ──► maker self-check ──► independent checker gate
      │                                          │
      │                              ┌───────────┴───────────┐
      │                          goal met?                 not yet
      │                              │                       │
      ▼                              ▼                       ▼
   open PR & stop              open PR & stop      attempts left? ── yes ─► iterate (same run_id)
                                                          │
                                                          no / repeated failure
                                                          ▼
                                                   escalate to human

Local Development Setup

Python

# Navigate to python package
cd python

# Install in development mode
pip install -e ".[dev]"

# Run MCP server
loop

# Run background worker (optional - for scheduled execution)
loop-worker

# Run tests
pytest

# Run tests with coverage
pytest --cov

Testing the MCP Server

1. Install locally (commands above)
2. Configure in your AI agent (see Setup section)
3. Test with your AI agent:
   hljs language-arduino

   Copy

   "Do you have loop-engineering tools?"
   "Create a test loop"
   "List all loops"
   

Project Structure

loop-engineering/
├── python/                  # Python MCP server
│   ├── src/
│   │   └── loop_engineering_mcp/
│   │       ├── server.py            # MCP server
│   │       ├── loop_manager.py      # Loop CRUD
│   │       ├── skill_manager.py     # Skill templates
│   │       ├── state_manager.py     # State tracking
│   │       ├── loop_executor.py     # Control loop: isolation, checker gate, stop rules
│   │       ├── scheduler.py         # Cron scheduler (the heartbeat)
│   │       ├── suitability.py       # 4-condition loop suitability test
│   │       ├── verification_runner.py  # Maker/checker gate runner
│   │       ├── github_client.py     # GitHub integration
│   │       └── worker.py            # Background worker
│   └── tests/
│
├── shared/                  # Shared skill templates
│   └── skills/
│       ├── ci-triage.md
│       ├── dependency-updates.md
│       └── lint-fixes.md
│
└── references/              # Documentation
    ├── README.md            # Full loop engineering guide
    ├── FRAMEWORK.md         # Complete implementation guide
    └── QUICKSTART.md        # 5-minute setup

Is This True Loop Engineering?

Loop engineering (Addy Osmani / Codez / O'Reilly, 2026) defines a loop as a small control system with six parts. This server maps to all six:

Plus the safety rules that separate a real loop from a cron job: an iterate-until-goal cycle, stop rules (max attempts + no-progress detection), budget caps, and a 4-condition suitability test before you build at all.

Pre-built Skill Templates

CI Triage

Automatically classifies CI failures and drafts fixes:

• Flakes - Retry once, file issue if persists
• Bugs - Draft fix PR immediately
• Env issues - Escalate with clear instructions
• Dependency issues - Draft rollback PR

Dependency Updates

Keeps packages up-to-date safely:

• Checks for outdated packages
• Tests compatibility
• Creates PRs for safe updates
• Flags breaking changes for review

Lint & Format Fixes

Maintains code quality automatically:

• Applies automated formatting
• Verifies no logic changes
• Runs tests before committing
• Opens clean-up PRs

Configuration Options

Loop Schedule (Cron Format)

"0 */6 * * *"    # Every 6 hours
"0 9 * * 1"      # Mondays at 9am
"0 0 * * *"      # Daily at midnight
"*/30 * * * *"   # Every 30 minutes

Verification & the Maker/Checker Gate

A loop has two gates. The maker self-check (verification_command) is the fast check the agent runs after its changes. The independent checker (goal_check_command) is a separate, objective command that decides whether the goal is actually met — so the agent that wrote the code is not the one grading it. A PR is opened only when both pass.

{
  "verification_command": "npm test",
  "goal_check_command": "npm run test:integration && npm run lint"
}

Stop Rules & Budgets

{
  "max_attempts": 3,        // escalate to a human after 3 failed attempts
  "max_runs_per_day": 24,   // daily run cap (heartbeat budget)
  "cost_budget": 5.00,      // cumulative USD token-cost ceiling (0 = unlimited)
  "isolation": "worktree"   // "worktree" (isolated, parallel-safe) or "branch"
}

The loop also performs no-progress detection: if the same failure occurs twice in a row it escalates immediately rather than burning tokens on a dead end.

Environment Variables

# Optional: GitHub integration
export GITHUB_TOKEN="ghp_..."

# Optional: Custom workspace
export LOOP_WORKSPACE="/path/to/project"

Documentation

• QUICKSTART.md - 5-minute setup guide
• FRAMEWORK.md - Complete implementation guide with examples
• references/README.md - Loop engineering concepts and theory
• CONTRIBUTING.md - How to contribute
• PROJECT_STRUCTURE.md - Architecture details

Troubleshooting

MCP Server Not Found

# Check if installed
loop-mcp --version

Tools Not Available in AI Agent

1. Verify MCP config is valid JSON
2. Check command path is correct
3. Restart your AI agent
4. Check AI agent logs for errors

Permission Errors

# Unix/Mac
chmod -R u+w .loop/

# Windows
icacls .loop /grant Users:F /T

FAQ

Q: Do I need an API key?
A: No! Your AI agent (Cursor/Kiro/Claude) already has its own API key. This MCP server just provides tools.

Q: Does it work offline?
A: The MCP server works offline, but loop execution needs internet (to call AI APIs, create PRs, etc.)

Q: What about security?
A: Loops never auto-merge to main. Human review required. Verification gates prevent bad code.

Q: Can I use my own AI model?
A: Yes! Works with any AI agent that supports MCP (Cursor, Kiro, Claude Desktop, etc.)

Q: How much does it cost?
A: The MCP server is free. You only pay for AI API usage (same as manual prompting, but more efficient).

Credits & License

Loop Engineering Concept

• Author: Codez (@0xCodez)
• Article: 14-Step Roadmap
• Based on: Anthropic engineering docs, Addy Osmani's research

MCP Server Implementation

• License: MIT
• Repository: GitHub

Model Context Protocol

• Developed by: Anthropic
• Docs: modelcontextprotocol.io

Support

• 📖 Documentation: FRAMEWORK.md
• 🐛 Report Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 🚀 Quick Start: QUICKSTART.md

What's Next?

1. Install the MCP server (1 command)
2. Configure your AI agent (add JSON config)
3. Create your first loop ("Create a CI triage loop")
4. Monitor performance (acceptance rates, time saved)
5. Iterate based on learnings

Build the loop. Stay the engineer. 🚀

Star History

⭐ If this saves you time, give us a star on GitHub!

Made with ❤️ by the Loop Engineering community