Content
# AgentOps Guardian MCP
## Capstone Summary
Track: Agents for Business
Problem: AI coding agents can make risky local changes without rollback.
Solution: MCP safety agent that reviews actions, checkpoints files, and restores workflow state.
Demo: `guardian_run_workflow` blocks unsafe writes, creates checkpoints, and `guardian_restore_workflow` restores files.
Course concepts: MCP, agent loop, skills/rules, security guardrails.
On-demand safety agent for AI coding workflows.
AgentOps Guardian MCP is a local-first Model Context Protocol server that helps developers inspect AI-agent workspaces, review risky actions, create rollback checkpoints, and restore files when an AI coding workflow goes wrong.
The project is designed for the **Agents for Business** track: it reduces the operational cost of using AI coding agents in real development teams.
---
## Key Features
- **One-call agent workflow:** `guardian_run_workflow` plans, inspects, scores, reviews a proposed action, checkpoints files, persists compact workflow state, and returns a compact decision.
- **Workflow rollback:** `guardian_restore_workflow` restores all files checkpointed by a saved Guardian workflow.
- **Backup first:** `safe_checkpoint`, `restore_latest`, and `prepare_safe_edit` remain direct recovery tools before risky edits.
- **Agent/MCP inspection:** `inspect_agent_environment_components` reports local agents, MCP servers, skills, plugins, hooks, model providers, and app integrations.
- **Cheap by default:** compact output, short in-memory inspector cache, no background daemon, no constant logging, and no automatic token-heavy summaries.
- **Security review:** deterministic checks flag shell execution, file writes without approval, destructive commands, publishing commands, and secret-looking actions.
---
## Architecture
The main loop is:
```text
proposed action
-> guardian_run_workflow
-> plan
-> inspect agent/MCP environment
-> score and triage risks
-> review proposed action
-> create checkpoints
-> persist workflow state
-> return decision and next action
```
If the result is wrong:
```text
guardian_restore_workflow(workflowId)
-> read .agentops/workflows/<workflowId>.json
-> restore all successful checkpoints
```
See [docs/architecture.md](docs/architecture.md) for details.
---
## Setup
Install dependencies and build:
```bash
npm install
npm run build
```
Run checks:
```bash
npm run check
npm test
```
Start the MCP server:
```bash
npm start
```
---
## MCP Configuration Example
Use the built JavaScript entrypoint:
```json
{
"mcpServers": {
"agentops-guardian": {
"command": "node",
"args": ["C:/absolute/path/to/agentops-guardian-mcp/dist/index.js"]
}
}
}
```
On Windows, use absolute paths and escape backslashes if your MCP host requires JSON escaping.
---
## Main Tools
- `guardian_run_workflow` — top-level agent workflow.
- `guardian_restore_workflow` — restore all checkpointed files from a workflow.
- `safe_checkpoint` — quick backup for one file.
- `restore_latest` — restore the latest checkpoint for one file.
- `prepare_safe_edit` — review an edit and checkpoint target files.
- `inspect_agent_environment_components` — inspect local agent/MCP components.
- `score_agent_surface` — compact risk score for the local agent surface.
- `triage_guardian_findings` — group findings into must-fix, review, informational, and ignored buckets.
- `review_agent_action_plan` — deterministic safety review for a proposed action.
---
## Demo
Run the deterministic workflow demo:
```bash
npm run build
npm run demo:workflow
```
The demo creates a test file, proposes a risky shell action, runs the Guardian workflow, creates a checkpoint, persists workflow state, and returns `needs_user_approval` instead of executing the command.
For the live MCP test evidence, see [docs/live-mcp-test.md](docs/live-mcp-test.md).
---
## Capstone Materials
- [Video script](docs/video-script.md)
- [Live MCP test](docs/live-mcp-test.md)
- [Architecture](docs/architecture.md)
- [Tool audit](docs/tool-audit.md)
- [Writeup draft](WRITEUP_DRAFT.md)
- [Submission checklist](TODO_CAPSTONE.md)
- [Screenshot checklist](docs/screenshots/README.md)
---
## Agent Instructions
To make another AI assistant use the Guardian workflow consistently, copy the relevant rules from [AGENTS.md.example](AGENTS.md.example) into that assistant's project rules file.
Recommended default:
```text
Before risky file edits, call guardian_run_workflow.
Proceed only when the workflow decision is ready.
If the edit goes wrong, call guardian_restore_workflow with the workflowId.
```
---
## Design Principles
- Local-first.
- On-demand only.
- Deterministic checks before LLM interpretation.
- Compact output by default.
- No background monitoring.
- No continuous event logging.
- Rollback before risky action.
---
## License
MIT. See [LICENSE](LICENSE).
