Skip to main content
Glama
looplens-mcp

looplens-mcp

by musaceylan

LoopLens MCP ๐Ÿ”๐Ÿ”

See the loop. Break the loop.

LoopLens MCP is an iteration observability and loop-detection MCP server for Claude Code and agentic coding workflows.

It is built for a very specific pain point:

You ask the model to fix something. It tries. The fix fails. You ask again. It retries. Same issue. More edits. More noise. ๐Ÿ˜ตโ€๐Ÿ’ซ

LoopLens turns that messy retry cycle into structured debugging intelligence.


โœจ What is LoopLens MCP?

LoopLens is not a memory MCP. LoopLens is not just another logger.

It is a focused debugging intelligence layer that helps AI coding workflows understand:

  • what has already been tried ๐Ÿ”

  • what changed between attempts ๐Ÿงฉ

  • which failures keep repeating ๐Ÿšจ

  • whether the workflow is converging or thrashing ๐Ÿ“‰๐Ÿ“ˆ

  • what the next most promising debugging step should be ๐ŸŽฏ


Related MCP server: repomemory

๐Ÿค” Why LoopLens exists

AI coding tools can be amazing on first-pass fixes.

But repeated repair attempts often become chaotic:

  • same failing command again and again

  • same files edited repeatedly

  • same tests still red

  • new wording, same failure

  • regressions introduced while fixing something else

  • retries that look different but are actually the same loop

That is exactly where LoopLens helps.


๐Ÿง  Core capabilities

1. Iteration logging

Capture repair/debug attempts across a task.

2. Attempt linking

Detect whether a prompt is:

  • a new task

  • a continuation

  • a retry

  • a regression check

  • a strategy branch

3. Loop detection

Identify patterns such as:

  • identical retry loops

  • repeated error signatures

  • command retry loops

  • file oscillation

  • validation stagnation

  • evidence-free retries

  • regression after partial success

4. Attempt comparison

Compare attempt N vs N-1:

  • files changed

  • tools used

  • commands run

  • validations changed

  • hypothesis shifts

  • outcome shifts

5. Convergence analysis

Estimate whether the workflow is:

  • converging โœ…

  • weakly converging ๐Ÿค

  • stagnant ๐Ÿ˜

  • diverging ๐Ÿ“‰

  • regressing โš ๏ธ

6. Next-fix suggestions

Recommend the best next move:

  • gather more evidence

  • isolate root cause

  • narrow validation

  • revert harmful change

  • inspect external signals

  • stop editing and compare attempts

  • split task into subproblems

7. Connector observations

LoopLens can ingest signal from:

  • GitHub / GitLab

  • CI systems

  • Sentry

  • Jira / Linear

  • test runners

  • filesystem metadata

  • other MCP servers

LoopLens is the debugging brain ๐Ÿง  Other tools are signal sources ๐Ÿ“ก


๐Ÿ’ก Philosophy

Don't just log the attempt. Understand the iteration.

That means:

  • structured trajectories instead of flat logs

  • failure fingerprints instead of noisy raw output

  • loop diagnosis instead of generic analytics

  • actionable next-step guidance instead of passive storage


๐Ÿšซ Not a memory MCP

LoopLens does not try to become long-term user memory.

It focuses on:

  • observable debugging events

  • tool calls

  • validation results

  • explicit summaries

  • failure patterns

  • retry trajectories

It is built for debugging, evaluation, and improvement of coding workflows.


๐Ÿ›  Example use cases

  • "Why did the last 3 fixes fail?"

  • "Are we editing the same files without real progress?"

  • "Did the failure actually change?"

  • "Are we stuck in a retry loop?"

  • "Which attempt got us closest to success?"

  • "What should Claude try next?"

  • "Export the last 20 failed repair loops as eval cases."


๐Ÿš€ Quick Start

# Install
uv sync

# Run the MCP server
uv run looplens-mcp

๐Ÿ”Œ Claude Code Integration

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "looplens": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/looplens-mcp", "looplens-mcp"],
      "env": {
        "LOOPLENS_LOG_LEVEL": "INFO"
      }
    }
  }
}

โš™๏ธ Configuration

All settings use the LOOPLENS_ prefix:

Variable

Default

Description

LOOPLENS_DATA_DIR

~/.looplens

Base data directory

LOOPLENS_DB_PATH

~/.looplens/looplens.db

SQLite database path

LOOPLENS_LOG_LEVEL

INFO

Log level

LOOPLENS_LOOP_FREQUENCY_THRESHOLD

3

Min repeats to flag a loop

LOOPLENS_LOOP_WINDOW_SIZE

20

Sliding window size for detection

LOOPLENS_REDACTION_ENABLED

true

Auto-redact secrets from payloads

LOOPLENS_RETENTION_DAYS

90

Days before old sessions are pruned


๐Ÿ”ง MCP Tools Reference

Tool

Description

create_session

Create a new debug session

get_session

Get session details

list_sessions

List sessions with filters

close_session

Mark session complete/abandoned

ingest_event

Record a single tool event

ingest_batch

Record multiple events at once

get_session_events

Retrieve session event history

detect_loops

Run loop detection algorithms

get_loops

Get detected loop patterns

mark_false_positive

Mark a false detection

get_convergence

Get convergence score

analyze_convergence_trend

Analyze trend over time

export_eval_cases

Export as eval dataset

get_diagnostics

Server health metrics

annotate_event

Add metadata to an event

search_events

Search by tool name


๐Ÿ” Loop Types Detected

  • infinite โ€” same tool called with identical input repeatedly

  • oscillating โ€” alternating between states without converging

  • thrashing โ€” high-frequency oscillation across many tools

  • stuck โ€” no meaningful progress for extended period

  • tool_retry โ€” same tool retried after repeated failures


๐Ÿ— Architecture

looplens/
โ”œโ”€โ”€ server/          # MCP server wiring (app.py, __main__.py)
โ”œโ”€โ”€ tools/           # 16 MCP tool handlers
โ”œโ”€โ”€ resources/       # 4 MCP resource handlers
โ”œโ”€โ”€ prompts/         # 3 MCP prompt builders
โ”œโ”€โ”€ domain/          # Immutable domain models (Pydantic v2)
โ”œโ”€โ”€ storage/         # SQLAlchemy 2.0 async repositories
โ”œโ”€โ”€ ingestion/       # Event normalization pipeline
โ”œโ”€โ”€ loop_detection/  # 4 detection algorithms + classifier + scorer
โ”œโ”€โ”€ convergence/     # 5-metric scoring engine
โ”œโ”€โ”€ analytics/       # Orchestrator for detection + convergence
โ”œโ”€โ”€ security/        # Redactor, path guard, rate limiter
โ”œโ”€โ”€ connectors/      # Claude Code, JSON, JSONL event parsers
โ””โ”€โ”€ exports/         # Eval case exporter

๐ŸŒŸ Why it matters

One of the biggest weak points in AI coding today is what happens after the first fix fails.

LoopLens helps make retries:

  • measurable

  • comparable

  • diagnosable

  • learnable

Instead of:

"try something else"

you get:

"Attempt 3 repeated the same failure signature as attempt 2, edited the same files, and did not reduce validation severity โ€” likely retry loop. Best next step: gather more evidence before editing again."

That is the kind of debugging intelligence coding agents need.


๐ŸŒ Vision

LoopLens aims to become the iteration intelligence layer for agentic debugging:

  • better local debugging

  • better repair observability

  • better eval datasets

  • better failure analysis

  • better coding-agent improvement loops


๐Ÿงช Status

Early project / active build.

If this resonates with you, ideas, contributions, and feedback are very welcome ๐Ÿ™Œ


๐Ÿ“„ License

MIT


๐Ÿ”๐Ÿ” LoopLens MCP

See the loop. Break the loop.

Available Tools

16 tools
analyze_convergence_trendC

Analyze convergence trend over time for a session.

Inputs: session_id (required), window.

annotate_eventA

Add a key-value annotation to a specific event.

Inputs: key (required), value (required), event_id (required).

close_sessionB

Close a debug session as completed or abandoned.

Inputs: session_id (required), status.

create_sessionB

Create a new LoopLens debug session to track tool events.

Inputs: label, metadata, source_type.

detect_loopsB

Run loop detection algorithms on a session and return detected loop patterns.

Inputs: session_id (required), window_size.

export_eval_casesB

Export session data as structured eval cases for model evaluation.

Inputs: session_id (required), format.

get_convergenceB

Get convergence score for a session (computes if not cached).

Inputs: session_id (required).

get_diagnosticsA

Get LoopLens server diagnostics: session counts, event totals, DB path.

Inputs: no named parameters.

get_loopsC

Get all detected loop patterns for a session.

Inputs: session_id (required), include_false_positives.

get_sessionA

Get details for a debug session including loop count and convergence score.

Inputs: session_id (required).

get_session_eventsB

Retrieve events for a session with pagination.

Inputs: session_id (required), limit, offset.

ingest_batchB

Ingest multiple tool events at once.

Inputs: events (required).

ingest_eventB

Ingest a single tool event into a session.

Inputs: tool_name (required), session_id (required), status, tool_input, +3 more.

list_sessionsA

List debug sessions with optional status filter and pagination.

Inputs: limit, offset, status.

mark_false_positiveB

Mark a loop detection as a false positive.

Inputs: pattern_id (required).

search_eventsC

Search events in a session by tool name.

Inputs: session_id (required), limit, tool_name.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    B3.3/5.0

    Scored across 16 tools

    Disambiguation4/5

    Tools are largely distinct: session lifecycle, event ingestion/query, loop detection, convergence, and diagnostics each have clear separation. Minor overlap exists between get_session and get_convergence, but descriptions clarify their different purposes.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case, e.g., create_session, ingest_event, detect_loops. No mixed conventions or vague verbs, making the API predictable and easy to navigate.

    Tool Count4/5

    16 tools is slightly above the ideal 3-15 range, but each tool serves a distinct function within the domain. The count feels justified given the breadth of session management, event processing, analysis, and export capabilities.

    Completeness4/5

    The domain covers session lifecycle (create/get/list/close), event ingestion (single/batch), querying, annotation, loop detection, convergence analysis, and export. Lack of session update/delete is a minor gap, but core workflows are well supported.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      A Model Context Protocol server that empowers AI agents with metacognitive monitoring to detect reasoning loops and provide intelligent recovery using case-based reasoning and statistical analysis.
      9
      52 npm
      9
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that captures and recalls coding session memory (failures, decisions, diffs) for AI agents, enabling cross-agent continuity and preventing repeated mistakes.
      69 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that gives coding agents a persistent, chained memory of debugging investigations, tracking what's been tried, ruled out, and solved across sessions and scopes.
      10 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An AI-powered debugging MCP server that detects silent failures, captures browser network requests, and enables automated diagnostics, root-cause analysis, and multi-agent repair through MCP tools.
      1
      MIT