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
Markdown
[](/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
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 -> 28And 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
- # mcp-ops-agent
- [](https://github.com/locquangnguyen8/mcp-ops-agent/actions/workflows/ci.yml)
- 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.
- 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.
- The data is synthetic: 12 products, 8 customers and 60 orders, generated with a fixed seed.
- ## How it works
- ```mermaid
- flowchart LR
- U[Person asks a question<br/>or gives a task] --> A[Claude agent<br/>tool runner]
- A <-->|MCP over stdio| S[shop-ops MCP server]
- S -->|read tools| DB[(SQLite)]
- S -->|propose_* tools<br/>validate, then queue| P[(pending_actions)]
- P --> H{Person reviews<br/>ops-agent approvals}
- H -- approve --> V[Re-validate against<br/>current data] --> DB
- H -- reject --> R[Rejected]
- S & H & V --> L[(audit_log)]
- ```
- **Read tools** (marked `read_only_hint` in MCP): `list_products`, `get_product`, `list_orders`, `get_order`, `sales_summary`, `list_pending_actions`.
- **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.
- **Business rules**, checked when a change is proposed and again when it's approved:
- | Change | Rule |
- |---|---|
- | Stock | Stock can't go below zero |
- | Price | Must stay above cost; changes over 30% must be made by a person directly |
- | Order status | Must follow new > paid > packed > shipped > delivered; can be cancelled only before shipping; delivered and cancelled orders are final |
- | Any change | A reason is required; an identical pending proposal is not duplicated |
- **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.
- ## Quick start
- ```bash
- 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`):
- ```bash
- 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
- ```
- ## Use the server from any MCP host
- 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:
- ```json
- {
- "mcpServers": {
- "shop-ops": {
- "command": "/path/to/.venv/bin/ops-mcp-server",
- "env": { "OPS_DB": "/path/to/data/shop.db" }
- }
- }
- }
- ```
- ## Tests
- | File | What it covers |
- |---|---|
- | `test_store.py` | Every business rule, proposal vs approval, stale proposals, duplicate proposals, audit trail, deterministic seed data |
- | `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 |
- | `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 |
- ## Design decisions
- - **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.
- - **Validate twice.** Validating at proposal gives the agent immediate feedback it can explain. Validating again at approval protects against stale data.
- - **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.
- - **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.
- ## Limitations
- - 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.
- - 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).
- ---
- 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 inFree to use. If it’s helped, pass it on.