io.github.mdfifty50-boop/agent-guard
Constitutional guardrails and loop detection for AI agents
Open source Open in the app JSON README (API)
About
Constitutional guardrails and loop detection for AI agents
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- mdfifty50-boop
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.3
- Last push
- 2026-04-24T13:40:49Z
- Repository state
- ativo
- Language
- JavaScript
- Added
- 2026-08-29 04:00:46
- Updated
- 2026-08-29 04:00:46
- Origin id
io.github.mdfifty50-boop/agent-guard
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.git
cd agent-guard-mcp
npm install
node src/index.js
```
## Tools
### register_agent
Register an agent for monitoring.
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `agent_id` | string | required | Unique agent identifier |
| `max_iterations` | number | 100 | Max iterations before forced stop |
| `progress_threshold` | number | 0.3 | Min 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.
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `agent_id` | string | required | Agent identifier |
| `tool_name` | string | required | Tool being called |
| `args` | object | required | Arguments passed |
| `result_preview` | string | `""` | 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.
| Param | Type | Description |
|-------|------|-------------|
| `agent_id` | string | Agent 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.
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `agent_id` | string | required | Agent identifier |
| `max_repeats` | number | 3 | Trigger after N identical actions |
| `action` | string | `"warn"` | `"warn"`, `"block"`, or `"suggest_alternative"` |
### check_circuit_breaker
Pre-flight check before executing a tool. Call this BEFORE the actual tool call.
| Param | Type | Description |
|-------|------|-------------|
| `agent_id` | string | Agent identifier |
| `proposed_tool` | string | Tool about to be called |
| `proposed_args` | object | Arguments 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.
| Param | Type | Description |
|-------|------|-------------|
| `agent_id` | string | Agent 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
| URI | Description |
|-----|-------------|
| `agent-guard://agents` | All monitored agents with current status |
## Usage Pattern
```
1. register_agent — at agent startup
2. Before each tool call:
a. check_circuit_breaker — should this action proceed?
b. Execute the tool
c. log_action — record what happened
3. 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