Agent Guard

io.github.mdfifty50-boopPublished by GitHub account mdfifty50-boopv0.1.3Updated Oct 24, 2026

Constitutional guardrails and loop detection for AI agents

VerifiedSTDIODesktop onlyDeveloper ToolsAI & ML

Overview

AI-generated overview

A local MCP server that monitors AI agents for repetitive loops, offering circuit breakers, stuck-agent analysis and recovery advice.

What you can do
Register agents with iteration limits and progress thresholds, and log each tool call with its arguments and a short result preview for rolling-window loop detection. Detect whether an agent is stuck, with a confidence score, pattern type, repeated actions and a recovery suggestion. Configure circuit breakers that warn, block or suggest alternatives after repeated identical actions, and run a pre-flight check before a tool call. Produce a detailed stuck report with action history, token-waste estimate and recommendations, plus a health dashboard of all monitored agents sorted by risk. Expose the list of monitored agents as a resource.
When to use it
Useful when building or running agentic systems that can get stuck repeating the same tool calls, and you want an in-band check that flags loops, blocks repeated actions and suggests recovery. Best suited to agents that can be wired to call the logging and pre-flight tools around each tool call.
Requirements
Runs as a local stdio process, typically started with npx agent-guard-mcp or from source with Node.js and npm install. No accounts, API keys or environment variables are declared. Desktop client only; no web executable.
Before you install
The server keeps agent state in memory for the running process, so monitoring only covers agents registered in that session. Block mode can stop tool calls the agent intended to make, so configure thresholds deliberately. Logged arguments and result previews are passed to the server, so avoid sending secrets in them.

Installation

In SourceWeft

  1. Open Agent Guard in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

agent-guard-mcp

MCP server that detects and prevents infinite agent loops — the #1 reliability problem in agentic systems.

Provides circuit breakers, pattern detection, stuck-agent analysis, and recovery recommendations via the Model Context Protocol.

Install

bash
npx agent-guard-mcp

Claude Desktop

Add to claude_desktop_config.json:

json
{  "mcpServers": {    "agent-guard": {      "command": "npx",      "args": ["agent-guard-mcp"]    }  }}

From source

bash
git clone https://github.com/mdfifty50-boop/agent-guard-mcp.gitcd agent-guard-mcpnpm installnode src/index.js

Tools

register_agent

Register an agent for monitoring.

ParamTypeDefaultDescription
agent_idstringrequiredUnique agent identifier
max_iterationsnumber100Max iterations before forced stop
progress_thresholdnumber0.3Min unique/total action ratio to be "making progress"

log_action

Log an agent action for loop detection. Maintains a rolling window of the last 50 actions.

ParamTypeDefaultDescription
agent_idstringrequiredAgent identifier
tool_namestringrequiredTool being called
argsobjectrequiredArguments passed
result_previewstring""Brief result preview (max 200 chars)

Returns early warnings when repeated patterns are detected.

detect_loop

Check if an agent is stuck in an infinite loop.

ParamTypeDescription
agent_idstringAgent to check

Returns:

  • is_stuck — boolean
  • confidence — 0.0 to 1.0
  • pattern — healthy, exact_repeat, low_diversity, or exact_repeat_and_low_diversity
  • suggestion — human-readable recovery advice
  • repeated_actions — list of repeated signatures with counts

set_circuit_breaker

Configure automatic intervention when action patterns repeat.

ParamTypeDefaultDescription
agent_idstringrequiredAgent identifier
max_repeatsnumber3Trigger after N identical actions
actionstring"warn""warn", "block", or "suggest_alternative"

check_circuit_breaker

Pre-flight check before executing a tool. Call this BEFORE the actual tool call.

ParamTypeDescription
agent_idstringAgent identifier
proposed_toolstringTool about to be called
proposed_argsobjectArguments about to be passed

Returns proceed: false when the circuit breaker fires (block mode only).

get_stuck_report

Detailed analysis of why an agent is stuck.

ParamTypeDescription
agent_idstringAgent to analyze

Returns: action history, pattern analysis, token waste estimate, diversity ratio, top repeated patterns, and recovery recommendations.

get_health_dashboard

Overview of all monitored agents. No parameters.

Returns all agents sorted by risk score with their status (STUCK/HEALTHY), action counts, and circuit breaker config.

Resources

URIDescription
agent-guard://agentsAll monitored agents with current status

Usage Pattern

1. register_agent — at agent startup2. Before each tool call:   a. check_circuit_breaker — should this action proceed?   b. Execute the tool   c. log_action — record what happened3. Periodically:   - detect_loop — am I stuck?   - get_health_dashboard — how are all agents doing?4. On stuck detection:   - get_stuck_report — what went wrong and how to recover

Tests

bash
npm test

License

MIT

Source: README.md at commit ebeb97e

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.3LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.