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:

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:

guardian_restore_workflow(workflowId)
  -> read .agentops/workflows/<workflowId>.json
  -> restore all successful checkpoints

See docs/architecture.md for details.

---

Setup

Install dependencies and build:

npm install
npm run build

Run checks:

npm run check
npm test

Start the MCP server:

npm start

---

MCP Configuration Example

Use the built JavaScript entrypoint:

{
  "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:

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.

---

Capstone Materials

• Video script
• Live MCP test
• Architecture
• Tool audit
• Writeup draft
• Submission checklist
• Screenshot checklist

---

Agent Instructions

To make another AI assistant use the Guardian workflow consistently, copy the relevant rules from AGENTS.md.example into that assistant's project rules file.

Recommended default:

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.