IncidentVault

A shared incident-knowledge service: engineers and AI agents search prior incidents, read their timelines, log evidence, validated root causes, and fixes, and reuse runbooks instead of re-investigating from scratch. A Spring Boot + PostgreSQL API stores incident investigations with full-text search; a React UI gives engineers a searchable timeline view; a Python MCP server exposes the same knowledge base as tools so an AI agent (e.g. Claude) can pull validated troubleshooting steps mid-incident.

Live demo: incidentvault.vercel.app · API: incidentvault-wjvp.onrender.com

Architecture

flowchart LR
    Engineer["Engineer"] --> UI["React UI(frontend)"]
    UI --> API["Spring Boot API(backend)"]
    API --> DB[("PostgreSQL 16")]

    Agent["AI agent (Claude)"] --> MCP["MCP server(Python, stdio)"]
    MCP --> API

• Engineer path: the React UI (served by nginx, proxies /api/ to the backend) calls the Spring Boot REST API, which reads/writes PostgreSQL (full-text search via generated tsvector columns + GIN indexes).
• Agent path: the MCP server speaks MCP over stdio to the agent and plain HTTP to the Spring Boot API — same data, same contract, no UI.

Repo layout

incidentvault/
├── backend/            # Spring Boot 3.3 / Java 21 REST API (Flyway migrations, 21 tests)
├── mcp-server/         # Python MCP server (stdio) exposing incident knowledge as tools
├── frontend/           # React 18 + TypeScript + Vite UI, nginx reverse-proxy Dockerfile
├── docker-compose.yml  # Postgres 16 + backend + frontend (nginx)
└── README.md           # this file

Each workstream has its own README (backend/README.md, mcp-server/README.md, frontend/README.md) with deeper detail.

Prerequisites

• Java 21 (Maven wrapper ./mvnw is included in backend/)
• Node 24+, npm 10+
• Python 3.12+
• Docker + Docker Compose (for the compose path only)

Quickstart

Option A — Docker Compose (everything)

docker compose up --build

• App: http://localhost:3000
• API: http://localhost:8080/api
• Postgres: localhost:5432

Option B — run the pieces locally

Backend (needs Postgres at localhost:5432, e.g. via Docker):

docker run --name iv-postgres -e POSTGRES_USER=incidentvault \
  -e POSTGRES_PASSWORD=incidentvault -e POSTGRES_DB=incidentvault \
  -p 5432:5432 -d postgres:16
cd backend
./mvnw spring-boot:run   # Flyway applies V1 schema + V2 seed data automatically

Frontend (needs the backend running):

cd frontend
npm install
npm run dev              # serves at http://localhost:5173

MCP server setup

cd mcp-server
pip install -r requirements.txt

Then paste the incidentvault block from mcp-server/mcp.json.example into the mcpServers object of your Claude Desktop config (macOS: