ops-assistant-mcp

An MCP server that exposes internal documents and a SaaS board (Monday.com, as an example integration) as tools, plus small command-line agents that call those tools with either Gemini or Claude.

The goal is a compact, readable reference for the general pattern: expose narrow tools over MCP, let a model call them, control what it is allowed to change, and keep a record of what it did.

question ─► agent.py / agent_gemini.py ──MCP (stdio)──► server.py
             (LLM tool-calling loop)                      ├─ search_knowledge_base  [read]
                                                          ├─ list_board_items       [read]
                                                          └─ create_board_item      [write, two-step]
                                  every tool call ─► guard.py ─► audit.jsonl

Tools

Related MCP server: Nexxupp MCP Server

Design notes

• Keyword search instead of a vector database. For policies, naming conventions and price lists, questions are usually exact-term lookups. FTS5 needs no embedding service and the index is rebuilt from the markdown files at startup. Common question words are ignored and weak matches are dropped, so an unanswerable question returns an explicit NO_MATCHES result instead of noise. A semantic or hybrid layer would be the next step for fuzzier questions.

• Read-only by default. Write tools are refused unless OPS_WRITE_ENABLED=1.

• Allowlist. OPS_ALLOWED_TOOLS=search_knowledge_base,list_board_items limits which tools can run.

• Audit log. Every tool call, including denied ones, appends a JSON line to audit.jsonl (tool, access type, arguments, outcome, duration).

• Dry-run mode. Without MONDAY_API_TOKEN, the Monday client serves a local sample board and keeps writes in memory, so everything runs without an external account.

Safety model: what is and isn't enforced

Enforced by the server:

• A write can only execute with a confirmation_token that the server issued in an earlier preview call, for the same arguments. Tokens are single-use and expire after 5 minutes.

• Writes are disabled unless the operator turns them on; tool access can be restricted by allowlist.

Enforced by the command-line agents:

• When the model tries to execute a write, the terminal asks the person to approve it (OPS_AUTO_APPROVE=1 skips the prompt for automated runs).

Not guaranteed:

• The server cannot know whether a human saw the preview. Human approval lives in the client, so any other client built on this server must implement its own approval step.

• The audit log is a local file with no tamper protection, and there is no per-user authentication or permission model; permissions are per deployment.

Quick start

Requires Python 3.11+.

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev,gemini]"        # or ".[dev,claude]", or both
pytest

Choose a model provider and set its key:

export GEMINI_API_KEY=...             # Google AI Studio
python -m ops_assistant.agent_gemini "How many PTO days carry over, and when do they expire?"

export ANTHROPIC_API_KEY=...          # Anthropic Console
python -m ops_assistant.agent "How many PTO days carry over, and when do they expire?"

Model names change over time. Set GEMINI_MODEL or ANTHROPIC_MODEL to a current model from the provider's model list. Free-tier quotas are limited per model, and each question can use several requests. Inspect what the model did with tail -n 5 audit.jsonl.

The docs/ folder and fixtures/board.json contain fictional sample data.

Configuration

Adding another integration

1. Write a small client module (see monday.py): authentication, one method per operation, errors raised clearly.

2. In server.py, add a function per operation with @mcp.tool() and @guarded("read") or @guarded("write"). Write the docstring for the model: it becomes the tool description.

3. For anything that changes data, reuse the preview-and-token pattern from create_board_item, and add the tool name to WRITE_TOOLS in common.py so the agents ask for approval.

4. Add tests with the HTTP layer mocked, like tests/test_monday_live_shape.py.

Tests

19 tests run offline without credentials: search behavior, the audit log and permissions, the two-step write flow (including token reuse, argument mismatch and expiry), the approval prompt, an end-to-end run of the real server over stdio, both agent loops against scripted model replies, and the shape of Monday.com requests with HTTP mocked.

Limitations

• The Monday.com client is exercised only through mocked HTTP and the dry-run fixture; it has not been validated against a live account.

• Calls to Gemini and Claude are not covered by automated tests.

• Search is keyword-based and the index is rebuilt in memory on each start.

• Pending write tokens are stored in memory, so they do not survive a server restart.

License

MIT, see LICENSE.