Incident Triage MCP

<!-- mcp-name: io.github.felixkwasisarpong/incident-triage-mcp -->

Incident Triage MCP is a Model Context Protocol (MCP) server for incident triage. It provides safe, auditable tools for evidence retrieval, deterministic summaries, ticket workflows, and notifications.

What This Project Is

• MCP control plane for incident triage tools.
• Compatible with local (stdio) and networked (streamable-http) MCP clients.
• Designed for standalone mode, Docker Compose, and Kubernetes.

What This Project Is Not

• Not a standalone LLM agent platform.
• Not a provider credentials vault.
• Not a replacement for your evidence pipeline; it consumes normalized evidence bundles.

Architecture Snapshot

• MCP server stays thin and policy-focused.
• Evidence collection runs in Airflow (optional) and writes EvidenceBundle artifacts.
• Agents call MCP tools only.
• Contract stability is defined under spec/.

For full details, see docs/ARCHITECTURE.md.

Core Tools

Mutating actions are guarded by RBAC, dry_run, confirm_token, audit logging, and idempotency.

Provider Matrix

Quick Start

Local (stdio)

python -m venv .venv
source .venv/bin/activate
pip install -e .

MCP_TRANSPORT=stdio \
WORKFLOW_BACKEND=none \
EVIDENCE_BACKEND=fs \
EVIDENCE_DIR=./evidence \
incident-triage-mcp

Local agent run (single incident)

incident-triage-agent \
  --incident-id INC-123 \
  --service payments-api \
  --artifact-store fs \
  --artifact-dir ./evidence \
  --compact

Docker (streamable-http)

docker run --rm -p 3333:3333 \
  -e MCP_TRANSPORT=streamable-http \
  -e WORKFLOW_BACKEND=none \
  -e EVIDENCE_BACKEND=fs \
  ghcr.io/felixkwasisarpong/incident-triage-mcp:latest

Optional local stack (Airflow + Postgres + MinIO + MCP):

docker compose up --build

Kubernetes: One Agent Job Per Trigger

This is the recommended runtime pattern:

1. Incoming trigger (webhook/manual) arrives.
2. Dispatcher (or operator) creates one Kubernetes Job per incident.
3. Job runs incident-triage-agent once and exits.
4. Agent calls MCP tools over HTTP.
5. MCP optionally triggers Airflow DAG (incident_evidence_v1) and consumes bundle from fs/s3.

Deploy MCP server (Helm)

helm upgrade --install incident-triage-mcp ./charts/incident-triage-mcp \
  --namespace incident-triage --create-namespace \
  --set image.repository=ghcr.io/felixkwasisarpong/incident-triage-mcp \
  --set image.tag=0.2.8 \
  --set env.MCP_TRANSPORT=streamable-http \
  --set env.MCP_HTTP_AUTH_MODE=api_key \
  --set secretEnv.MCP_HTTP_API_KEY=change-me

Trigger one incident with a single-run agent Job

kubectl -n incident-triage create job triage-inc-123 \
  --image=ghcr.io/felixkwasisarpong/incident-triage-mcp:0.2.8 \
  -- incident-triage-agent \
  --incident-id INC-123 \
  --service payments-api \
  --mcp-url http://incident-triage-mcp/mcp \
  --mcp-api-key change-me \
  --compact

Ensure single-run behavior

• Use deterministic job names per incident (triage-inc-<incident_id>).
• Reject duplicates at dispatcher level if job already exists.
• Keep ticket creates idempotent with idempotency_key.
• Configure Job lifecycle controls (backoffLimit, activeDeadlineSeconds, ttlSecondsAfterFinished).

Configuration Essentials

Profile templates live in deploy/profiles/:

• local.env.example
• staging.env.example
• prod.env.example

Testing

Run full tests:

pytest -q

Run contract checks only:

pytest -q tests/test_contract_evidence_bundle.py tests/test_contract_mcp_tools.py
python scripts/validate_contrib.py

Releases

Install from PyPI

pip install incident-triage-mcp==X.Y.Z

Pull container image

docker pull ghcr.io/felixkwasisarpong/incident-triage-mcp:X.Y.Z

Supported image tags:

• X.Y.Z (exact)
• X.Y (minor stream)
• latest

For release workflow details, see docs/RELEASING.md.

Project Layout

incident-triage-mcp/
  src/incident_triage_mcp/      # MCP server + tools + adapters
  spec/                         # versioned contracts
  airflow/dags/                 # evidence pipeline
  charts/incident-triage-mcp/   # Helm chart
  k8s/                          # Kubernetes manifests
  contrib/                      # polyglot contribution area
  docs/                         # architecture, release, governance docs

Support And Triage

• Discussions: https://github.com/felixkwasisarpong/incident-triage-mcp/discussions
• Issues: https://github.com/felixkwasisarpong/incident-triage-mcp/issues
• Security reports: SECURITY.md

Documentation Index

• docs/ARCHITECTURE.md
• docs/CONTRIBUTION_GUIDE.md
• docs/REPO_LAYOUT.md
• docs/VERSIONING.md
• docs/RELEASING.md
• docs/MAINTAINERS_RUNBOOK.md

Contributing

Read CONTRIBUTING.md before opening a PR.

License

MIT