Skip to content
Back to search

mcp-ops-agent

MCP server and Claude agent for shop operations: the agent proposes, people approve, everything is audited

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/locquangnguyen8--mcp-ops-agent/badge.svg)](/listings/locquangnguyen8--mcp-ops-agent)

HTML

<a href="/listings/locquangnguyen8--mcp-ops-agent"><img src="/api/listings/locquangnguyen8--mcp-ops-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
ops-agent seed                 # create data/shop.db
pytest -q                      # 24 tests, no API key needed

Give the agent a task (needs `ANTHROPIC_API_KEY`):

ops-agent ask "Which products are below their reorder level? Propose restocking the two most urgent to 2x their reorder level."
ops-agent approvals list
ops-agent approvals approve 1
ops-agent approvals reject 2 --note "Supplier is out of stock"
ops-agent audit

The agent uses `claude-opus-5-5` at medium effort, with a server-side fallback model if a request is declined. Override them with `OPS_AGENT_MODEL` and `OPS_AGENT_EFFORT`.

What the approval side looks like (real output):

$ ops-agent approvals list
#1    stock_adjustment  {"quantity_change": 24, "sku": "FRZ-BUN-6"}
      reason: Supplier delivery of 24 units

$ ops-agent approvals approve 1 --by manager
FRZ-BUN-6 stock 4 -> 28 - applied

$ ops-agent approvals approve 1 --by manager
Not applied: Action 1 is already applied

$ ops-agent audit
2026-11-22T02:11:15+00:00  agent      #1    proposed               FRZ-BUN-6 stock 4 -> 28
2026-11-22T02:11:15+00:00  manager    #1    approved_and_applied   FRZ-BUN-6 stock 4 -> 28

And when the agent tries something a rule forbids, the server returns a tool error that the agent passes on to the user:

Error executing tool propose_order_status_change: Order 1001 is delivered; its status can no longer change

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 122 lines
  1. # mcp-ops-agent
  2. [![ci](https://github.com/locquangnguyen8/mcp-ops-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/locquangnguyen8/mcp-ops-agent/actions/workflows/ci.yml)
  3. An **MCP server** that gives an AI agent access to a small online store's products, orders and sales, and a **Claude agent** that uses it, with one firm rule: **the agent can look at anything, but it cannot change anything.** It can only propose changes. A person approves or rejects each one, and every step is written to an audit log.
  4. That rule is enforced by the server, not by the prompt. The server has no approve tool, so no prompt injection or model mistake can apply a change.
  5. The data is synthetic: 12 products, 8 customers and 60 orders, generated with a fixed seed.
  6. ## How it works
  7. ```mermaid
  8. flowchart LR
  9. U[Person asks a question<br/>or gives a task] --> A[Claude agent<br/>tool runner]
  10. A <-->|MCP over stdio| S[shop-ops MCP server]
  11. S -->|read tools| DB[(SQLite)]
  12. S -->|propose_* tools<br/>validate, then queue| P[(pending_actions)]
  13. P --> H{Person reviews<br/>ops-agent approvals}
  14. H -- approve --> V[Re-validate against<br/>current data] --> DB
  15. H -- reject --> R[Rejected]
  16. S & H & V --> L[(audit_log)]
  17. ```
  18. **Read tools** (marked `read_only_hint` in MCP): `list_products`, `get_product`, `list_orders`, `get_order`, `sales_summary`, `list_pending_actions`.
  19. **Propose tools:** `propose_stock_adjustment`, `propose_price_change`, `propose_order_status_change`. Each one checks the business rules, queues the change and returns an `action_id`. Nothing is applied.
  20. **Business rules**, checked when a change is proposed and again when it's approved:
  21. | Change | Rule |
  22. |---|---|
  23. | Stock | Stock can't go below zero |
  24. | Price | Must stay above cost; changes over 30% must be made by a person directly |
  25. | Order status | Must follow new > paid > packed > shipped > delivered; can be cancelled only before shipping; delivered and cancelled orders are final |
  26. | Any change | A reason is required; an identical pending proposal is not duplicated |
  27. **Why re-validate at approval?** Data changes between proposal and approval. If two proposals each remove stock and both were valid alone, the second one can no longer be valid once the first is applied. The approval step re-checks it, rejects it as stale and records why.
  28. ## Quick start
  29. ```bash
  30. python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
  31. pip install -e ".[dev]"
  32. ops-agent seed # create data/shop.db
  33. pytest -q # 24 tests, no API key needed
  34. ```
  35. Give the agent a task (needs `ANTHROPIC_API_KEY`):
  36. ```bash
  37. ops-agent ask "Which products are below their reorder level? Propose restocking the two most urgent to 2x their reorder level."
  38. ops-agent approvals list
  39. ops-agent approvals approve 1
  40. ops-agent approvals reject 2 --note "Supplier is out of stock"
  41. ops-agent audit
  42. ```
  43. The agent uses `claude-opus-5-5` at medium effort, with a server-side fallback model if a request is declined. Override them with `OPS_AGENT_MODEL` and `OPS_AGENT_EFFORT`.
  44. What the approval side looks like (real output):
  45. ```
  46. $ ops-agent approvals list
  47. #1 stock_adjustment {"quantity_change": 24, "sku": "FRZ-BUN-6"}
  48. reason: Supplier delivery of 24 units
  49. $ ops-agent approvals approve 1 --by manager
  50. FRZ-BUN-6 stock 4 -> 28 - applied
  51. $ ops-agent approvals approve 1 --by manager
  52. Not applied: Action 1 is already applied
  53. $ ops-agent audit
  54. 2026-11-22T02:11:15+00:00 agent #1 proposed FRZ-BUN-6 stock 4 -> 28
  55. 2026-11-22T02:11:15+00:00 manager #1 approved_and_applied FRZ-BUN-6 stock 4 -> 28
  56. ```
  57. And when the agent tries something a rule forbids, the server returns a tool error that the agent passes on to the user:
  58. ```
  59. Error executing tool propose_order_status_change: Order 1001 is delivered; its status can no longer change
  60. ```
  61. ## Use the server from any MCP host
  62. The server is a standard MCP server over stdio, so Claude Desktop, Claude Code or any other MCP client can use it directly. For example, in an MCP host's JSON config:
  63. ```json
  64. {
  65. "mcpServers": {
  66. "shop-ops": {
  67. "command": "/path/to/.venv/bin/ops-mcp-server",
  68. "env": { "OPS_DB": "/path/to/data/shop.db" }
  69. }
  70. }
  71. }
  72. ```
  73. ## Tests
  74. | File | What it covers |
  75. |---|---|
  76. | `test_store.py` | Every business rule, proposal vs approval, stale proposals, duplicate proposals, audit trail, deterministic seed data |
  77. | `test_server.py` | The MCP server through a real MCP client: no approve tool exists, read-only annotations, rule violations come back as tool errors |
  78. | `test_agent.py` | The agent wiring, with a stand-in for Claude that makes real tool calls through the Anthropic SDK's MCP wrapper into the real server; checks that the database is unchanged until approval |
  79. ## Design decisions
  80. - **Approval lives in the server, not the agent loop.** A human-in-the-loop check written into the agent's loop or prompt can be bypassed by a different client. Here, every MCP client gets the same propose-only tools.
  81. - **Validate twice.** Validating at proposal gives the agent immediate feedback it can explain. Validating again at approval protects against stale data.
  82. - **Errors are information.** Rule violations are returned as MCP tool errors with a plain-English reason, so the agent can tell the user why something can't be done instead of retrying blindly.
  83. - **The agent loop runs locally.** The server and database are local, so the agent uses the Anthropic SDK's tool runner with the MCP tool helpers rather than a hosted agent service.
  84. ## Limitations
  85. - SQLite and a single approver role keep the demo small. A production version would add authentication, per-role approval limits (for example, price changes need a manager) and notifications for pending actions.
  86. - The agent's behaviour on real tasks is not covered by automated tests, because that needs a live model. The next step would be a scenario evaluation: a set of tasks with the expected proposals, run against the model on each change, like the release gate in [grounded-rag-eval](https://github.com/locquangnguyen8/grounded-rag-eval).
  87. ---
  88. Built by [Loc Nguyen](https://www.linkedin.com/in/loc-nguyen-ai/). The pattern (MCP integrations, agents that propose, and people who approve changes to authoritative records) is one I have used in production.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.