{
  "markdown": "# agent-guard-mcp\n\nMCP server that detects and prevents infinite agent loops — the #1 reliability problem in agentic systems.\n\nProvides circuit breakers, pattern detection, stuck-agent analysis, and recovery recommendations via the Model Context Protocol.\n\n## Install\n\n```bash\nnpx agent-guard-mcp\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-guard\": {\n      \"command\": \"npx\",\n      \"args\": [\"agent-guard-mcp\"]\n    }\n  }\n}\n```\n\n### From source\n\n```bash\ngit clone https://github.com/mdfifty50-boop/agent-guard-mcp.git\ncd agent-guard-mcp\nnpm install\nnode src/index.js\n```\n\n## Tools\n\n### register_agent\n\nRegister an agent for monitoring.\n\n| Param | Type | Default | Description |\n|-------|------|---------|-------------|\n| `agent_id` | string | required | Unique agent identifier |\n| `max_iterations` | number | 100 | Max iterations before forced stop |\n| `progress_threshold` | number | 0.3 | Min unique/total action ratio to be \"making progress\" |\n\n### log_action\n\nLog an agent action for loop detection. Maintains a rolling window of the last 50 actions.\n\n| Param | Type | Default | Description |\n|-------|------|---------|-------------|\n| `agent_id` | string | required | Agent identifier |\n| `tool_name` | string | required | Tool being called |\n| `args` | object | required | Arguments passed |\n| `result_preview` | string | `\"\"` | Brief result preview (max 200 chars) |\n\nReturns early warnings when repeated patterns are detected.\n\n### detect_loop\n\nCheck if an agent is stuck in an infinite loop.\n\n| Param | Type | Description |\n|-------|------|-------------|\n| `agent_id` | string | Agent to check |\n\nReturns:\n- `is_stuck` — boolean\n- `confidence` — 0.0 to 1.0\n- `pattern` — `healthy`, `exact_repeat`, `low_diversity`, or `exact_repeat_and_low_diversity`\n- `suggestion` — human-readable recovery advice\n- `repeated_actions` — list of repeated signatures with counts\n\n### set_circuit_breaker\n\nConfigure automatic intervention when action patterns repeat.\n\n| Param | Type | Default | Description |\n|-------|------|---------|-------------|\n| `agent_id` | string | required | Agent identifier |\n| `max_repeats` | number | 3 | Trigger after N identical actions |\n| `action` | string | `\"warn\"` | `\"warn\"`, `\"block\"`, or `\"suggest_alternative\"` |\n\n### check_circuit_breaker\n\nPre-flight check before executing a tool. Call this BEFORE the actual tool call.\n\n| Param | Type | Description |\n|-------|------|-------------|\n| `agent_id` | string | Agent identifier |\n| `proposed_tool` | string | Tool about to be called |\n| `proposed_args` | object | Arguments about to be passed |\n\nReturns `proceed: false` when the circuit breaker fires (block mode only).\n\n### get_stuck_report\n\nDetailed analysis of why an agent is stuck.\n\n| Param | Type | Description |\n|-------|------|-------------|\n| `agent_id` | string | Agent to analyze |\n\nReturns: action history, pattern analysis, token waste estimate, diversity ratio, top repeated patterns, and recovery recommendations.\n\n### get_health_dashboard\n\nOverview of all monitored agents. No parameters.\n\nReturns all agents sorted by risk score with their status (STUCK/HEALTHY), action counts, and circuit breaker config.\n\n## Resources\n\n| URI | Description |\n|-----|-------------|\n| `agent-guard://agents` | All monitored agents with current status |\n\n## Usage Pattern\n\n```\n1. register_agent — at agent startup\n2. Before each tool call:\n   a. check_circuit_breaker — should this action proceed?\n   b. Execute the tool\n   c. log_action — record what happened\n3. Periodically:\n   - detect_loop — am I stuck?\n   - get_health_dashboard — how are all agents doing?\n4. On stuck detection:\n   - get_stuck_report — what went wrong and how to recover\n```\n\n## Tests\n\n```bash\nnpm test\n```\n\n## License\n\nMIT\n",
  "bytes": 3785,
  "sha": "1387eba50d0356f001231202076266a8b568024e5f1e886b7e743e7ce24023f4",
  "repo_slug": "mdfifty50-boop/agent-guard-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mdfifty50_boop_agent_guard_97831217/readme"
}