Agentic Ops-App Builder

An LLM agent that connects to a data ontology over MCP, answers natural-language questions with real queried data, proposes human-approved actions, and generates operational dashboards on demand — a self-built, Palantir-AIP-style operational tool.

Lineage: this project evolves my earlier AI website-builder agent

into "LLM operates over an enterprise ontology with governance": same agent-loop DNA, but every capability is now typed, whitelisted, previewed, human-approved, and audited. It pairs with disaster-response-hq (Project 1), whose FastAPI ontology this agent can consume directly.

The 3-prompt demo

Run everything (offline, no API key needed):

.venv/bin/python scripts/demo.py

Or type these into the web app:

Related MCP server: Foggy Data MCP Bridge

What is MCP, and how this mirrors Palantir AIP

MCP (Model Context Protocol) is an open protocol that gives an LLM a typed, discoverable, bounded tool surface over external systems. A server exposes tools (name + description + JSON Schema); any client — an agent, an IDE, a chat app — connects, lists them, and calls them. The protocol boundary is the governance boundary: the model can only do what the server exposes.

This project is a miniature of Palantir's AIP architecture:

How human-in-the-loop works

 user ──ask──▶ Agent (LLM)                 MCP server                FastAPI (operator)
                │  propose_action(...) ──▶ validate params
                │                          run constraint checks
                │                          build before/after PREVIEW   (no mutation)
                │ ◀── proposal + action_id ─┘
 UI shows preview card ──── human clicks Approve ──▶ approve_action(operator_key)
                                                     └─ mints SINGLE-USE token
                                                   execute_action(token)
                                                     ├─ re-validates vs CURRENT state
                                                     ├─ applies the change
                                                     └─ audit log: proposed→approved→executed

Three enforcement layers keep the agent proposal-only:

1. Whitelist — approve_action / reject_action / execute_action are stripped from the LLM's tool list; the agent loop rejects any call to a tool it wasn't given.

2. Capability gating — approval requires an OPERATOR_KEY that exists only in the orchestration server's process (injected into the MCP subprocess env). No LLM context ever contains it, so an agent cannot mint approval tokens even in principle.

3. Token mechanics — tokens are single-use (secrets.compare_digest, burned on first use) and execution re-validates every constraint against current state, so a stale approval can't overdraw a depot.

The same philosophy governs dashboards: the agent emits a strictly validated JSON spec (extra="forbid", 3 widget types, bounded sizes) that fixed React components interpret — never HTML, JSX, or executable code.

Architecture

 React 18 + Vite + TS + Tailwind          FastAPI (port 8100)              MCP server (stdio subprocess)
 ┌──────────────┬───────────────┐   WS    ┌──────────────────────┐  MCP    ┌─────────────────────────┐
 │ Chat panel   │ Actions cards │ ◀─────▶ │ /ws  agent events    │ ◀─────▶ │ 9 tools over ontology   │
 │ (markdown)   │ Live trace    │  HTTP   │ /actions/{id}/approve│  stdio  │ ┌─ StubOntology (dflt)  │
 │              │ Dashboard     │ ◀─────▶ │ /actions/{id}/reject │         │ └─ HttpOntology ──▶ Project 1
 │              │ canvas        │         │ /audit  /health      │         │    (disaster-response-hq)
 └──────────────┴───────────────┘         │ OpsAgent loop + LLM  │         └─────────────────────────┘
                                          │ (Claude ⟷ MockLLM)  │
                                          └──────────────────────┘

Run it

# Backend
python3.11 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest                  # 60 tests, fully offline
.venv/bin/python scripts/demo.py            # scripted 3-prompt demo (mock LLM)
.venv/bin/python scripts/smoke_mcp.py       # raw MCP stdio smoke run

# CLI
.venv/bin/python -m ops_agent.cli --llm mock "Which units are critically low on water?"

# Web app: API on :8100, frontend on :5174
LLM_MODE=mock .venv/bin/python -m uvicorn ops_agent.server:app --port 8100
cd frontend && npm install && npm run dev   # open http://localhost:5174
npm test                                    # 8 Vitest component tests

# Real LLM (claude-opus-4-8; key read from env, never hardcoded)
export ANTHROPIC_API_KEY=sk-ant-...
.venv/bin/python -m ops_agent.cli "Which units are critically low on water?"

# Against Project 1's live ontology instead of the stub
ONTOLOGY_BACKEND=http ONTOLOGY_API_URL=http://localhost:8000 ...

LLM modes — LLM_MODE=auto (default: live if ANTHROPIC_API_KEY is set, else mock) / mock / live. The MockLLM behaves like a tool-calling model (grounding query → filtered query → answer; action parsing; dashboard building) so every flow — including tests and the demo — runs offline and deterministically.

Milestones

• M1 MCP server: read-only ontology tools over a swappable backend + tests

• M2 Agent loop: LLM tool-calling over MCP, whitelist, audit events, CLI

• M3 FastAPI WebSocket streaming + React chat/trace UI

• M4 propose → human approve (operator-key + single-use token) → execute → audit

• M5 dashboard spec generation (safe JSON) + React renderer (recharts)

• M6 demo script, screenshots, this README