Skip to main content
Glama
Workflow Intelligence MCP

Workflow Intelligence MCP

by cmchetanm
README.md
# Workflow Intelligence MCP

<p align="center">
  <strong>Turn fragmented enterprise processes into measurable, controlled agentic workflows.</strong>
</p>

<p align="center">
  <a href="#architecture"><img src="https://img.shields.io/badge/Architecture-Layered%20MCP-blue.svg" alt="Architecture"></a>
  <a href="#mcp-tools"><img src="https://img.shields.io/badge/MCP%20Tools-3%20Domain%20Suites-brightgreen.svg" alt="MCP Tools"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.12%2B-blue.svg" alt="Python 3.12+"></a>
  <a href="https://github.com/modelcontextprotocol/python-sdk"><img src="https://img.shields.io/badge/MCP%20SDK-Official%20Python-orange.svg" alt="MCP SDK"></a>
  <a href="#license"><img src="https://img.shields.io/badge/License-Apache%202.0-green.svg" alt="License"></a>
</p>

---

## Executive Summary

Enterprise businesses rely on complex webs of workflow engines, ERP systems, databases, and manual approval chains. While workflow engines like **Temporal** and **n8n** excel at executing predefined sequences, organizations face critical operational hurdles:

- **Invisible Inefficiencies:** Undetected approval queues, unnecessary activity repetitions, and human handoff delays.
- **Fragile Exception Handling:** Workflows that halt abruptly due to minor schema drifts, missing vendor records, or data mismatches, requiring tedious manual triage.
- **Unexplained Metric Deviations:** Operational costs spike or SLA cycle times inflate, but operational dashboards only show *what* happened, not *why* it happened or *which source records* caused it.

**Workflow Intelligence MCP** is a specialized Model Context Protocol server that sits alongside workflow engines as a dedicated **process intelligence, exception reasoning, and business decision layer**.

```
┌────────────────────────────────────────────────────────────────────────┐
│                      WORKFLOW INTELLIGENCE MCP                         │
├──────────────────────────┬─────────────────────────┬───────────────────┤
│ 1. Process Discovery     │ 2. Exception Resolver   │ 3. Decision Intel │
│    Engine (`process_`)   │    (`exception_`)       │    (`decision_`)  │
├──────────────────────────┼─────────────────────────┼───────────────────┤
│ • Event log ingestion    │ • Exception triage      │ • KPI deviation   │
│ • PM4Py reconstruction   │ • Context retrieval     │   root-cause      │
│ • Bottleneck detection   │ • Recovery suggestions  │ • DuckDB analysis │
│ • Automation scoring     │ • Escalation routing    │ • Evidence briefs │
└──────────────────────────┴─────────────────────────┴───────────────────┘
```

---

## Core Differentiators

1. **Intelligence, Not Execution:** Complements existing workflow orchestrators (Temporal, n8n) rather than replacing them.
2. **Deterministic Computing:** All metrics, aggregations, process graphs, and numerical KPIs are computed using deterministic code (PM4Py, DuckDB, Pandas, SQL). **Reports, narratives, and recommendations are formulated deterministically from verified numbers—eliminating LLM hallucinations in analytical calculations.**
3. **Verifiable Data Provenance:** Every insight, recommendation, and brief generated by the server links explicitly to underlying dataset identifiers, file SHA-256 digests, and deterministic query logic.

---

<a name="architecture"></a>
## System Architecture

The server adheres to a strict, modular layered architecture where MCP handlers remain thin transport layers that delegate directly to isolated application services and adapters.

```mermaid
flowchart TD
    Client["MCP Clients\n(Claude Desktop / Cursor / Custom Agents)"]
    
    subgraph MCP_Protocol ["MCP Protocol Layer"]
        Transport["FastMCP Server\n(STDIO / Streamable HTTP)"]
        Handlers["Thin Tool & Resource Handlers"]
    end
    
    subgraph Validation ["Validation & Security Layer"]
        Pydantic["Pydantic V2 Schemas\n(Input / Output Contracts)"]
        AuthZ["Authorization & Access Policy"]
    end
    
    subgraph Services ["Application Services"]
        Dependencies["ServiceContainer\n(Dependency Injection)"]
        PS["ProcessService\n(Process Mining & Reconstruction)"]
        ES["ExceptionService\n(Triage & Root Cause Resolution)"]
        DS["DecisionService\n(KPI & Decision Briefs)"]
        AS["AnalyticsService\n(DuckDB Query Engine)"]
        EVS["EvidenceService\n(Record Matching & Provenance)"]
    end
    
    subgraph Adapters ["Integration Adapters"]
        PMAdapter["PM4Py Adapter"]
        DuckAdapter["DuckDB / SQL Adapter"]
        WorkflowAdapter["Temporal / n8n Connectors"]
        FileAdapter["CSV / JSON / Parquet Loaders"]
    end
    
    subgraph Storage ["Persistence & State"]
        PG[(PostgreSQL State)]
        Duck[(In-Memory / Local DuckDB)]
    end

    Client <--> Transport
    Transport --> Handlers
    Handlers --> Pydantic
    Pydantic --> AuthZ
    AuthZ --> Dependencies
    Dependencies --> Services
    PS --> PMAdapter
    ES --> WorkflowAdapter
    ES --> EVS
    DS --> AS
    AS --> DuckAdapter
    DuckAdapter --> Duck
    WorkflowAdapter --> PG
    PMAdapter --> FileAdapter
```

---

<a name="mcp-tools"></a>
## The Three Core MCP Tools

### 1. Process Discovery Engine (`process_*`)

Ingests operational event logs, reconstructs execution paths using process mining, identifies systemic bottlenecks, and calculates objective automation suitability scores.

| Tool Name | Parameters | Output Schema | Purpose |
|---|---|---|---|
| `process_analyze_business_process` | `source_uri` (str)<br>`case_id_col` (str)<br>`activity_col` (str)<br>`timestamp_col` (str) | `ProcessAnalysisResult` | Ingests event logs, computes transition matrices, case statistics, and path variants. |
| `process_identify_bottlenecks` | `source_uri` (str)<br>`threshold_std_dev` (float, default 2.0) | `BottleneckReport` | Detects abnormal queue durations, repeated task loops, and departmental handoff delays. |
| `process_score_automation_opportunities` | `source_uri` (str)<br>`min_frequency` (int, default 10) | `AutomationScoreReport` | Evaluates repetitive activities against volume, variance, and manual touchpoints to rank automation targets. |

#### Example Invocations & Output

```json
// Tool: process_identify_bottlenecks
{
  "source_uri": "sample-data/procurement_events.csv",
  "threshold_std_dev": 2.0
}
```

```json
// Response
{
  "total_cases_analyzed": 1420,
  "bottlenecks": [
    {
      "stage": "Finance Approval -> Vendor Selection",
      "avg_duration_hours": 74.2,
      "baseline_duration_hours": 12.0,
      "deviation_score": 3.8,
      "primary_cause": "Pending manual budget verification",
      "affected_case_count": 312
    }
  ],
  "recommendations": [
    "Introduce automated budget pre-checks for purchase requisitions under $5,000."
  ]
}
```

---

### 2. Workflow Exception Resolver (`exception_*`)

Investigates execution failures across automated pipelines, fetches contextual records from databases or workflow histories, reconciles discrepancies, and determines safe recovery or escalation paths.

| Tool Name | Parameters | Output Schema | Purpose |
|---|---|---|---|
| `exception_investigate_workflow` | `case_id` (str)<br>`workflow_type` (str)<br>`failure_payload` (dict) | `ExceptionInvestigationResult` | Classifies failures (validation, API timeout, record mismatch) and gathers case history. |
| `exception_recommend_resolution` | `exception_id` (str)<br>`policy_context` (dict, optional) | `ResolutionPlan` | Produces actionable remediation steps (e.g., entity deduplication, automated retry, or manual correction). |
| `exception_escalate_case` | `case_id` (str)<br>`reason` (str)<br>`target_department` (str) | `EscalationResult` | Routes unresolvable or high-risk exceptions to authorized human operators with full audit context. |

#### Example Invocation & Output

```json
// Tool: exception_investigate_workflow
{
  "case_id": "PO-10042",
  "workflow_type": "purchase_order_creation",
  "failure_payload": {
    "error_code": "VENDOR_RECORD_MISMATCH",
    "submitted_name": "ABC Logistics LLC",
    "tax_identifier": "TX-992140"
  }
}
```

```json
// Response
{
  "investigation_id": "INV-8831",
  "case_id": "PO-10042",
  "root_cause_category": "Data Discrepancy",
  "explanation": "Submitted vendor 'ABC Logistics LLC' matches registered entity 'ABC Logistics Global Inc' with 98% confidence on tax ID 'TX-992140'.",
  "matched_records": [
    { "entity_id": "VEND-00412", "registered_name": "ABC Logistics Global Inc" }
  ],
  "can_auto_resolve": true,
  "recommended_action": "Remap vendor_id to VEND-00412 and resume workflow step: dispatch_po."
}
```

---

### 3. Business Decision Intelligence (`decision_*`)

Executes high-performance analytical queries using embedded DuckDB to evaluate business KPI shifts, identify underlying contributing segments, and produce verifiable decision briefs.

| Tool Name | Parameters | Output Schema | Purpose |
|---|---|---|---|
| `decision_analyze_kpi_performance` | `metric_name` (str)<br>`source_uri` (str)<br>`timeframe_current` (str)<br>`timeframe_baseline` (str)<br>`timeframe_column` (str, default "timeframe")<br>`custom_expression` (str, optional) | `PerformanceAnalysisResult` | Evaluates deterministic KPI variance across periods over any CSV/Parquet dataset with zero hardcoding. |
| `decision_explain_kpi_deviation` | `metric_name` (str)<br>`source_uri` (str)<br>`timeframe_current` (str)<br>`timeframe_baseline` (str)<br>`observed_delta` (float)<br>`timeframe_column` (str, default "timeframe")<br>`dimension` (str, optional)<br>`custom_expression` (str, optional) | `DeviationExplanation` | Explains variance drivers with dynamic dimension inference and statistical significance indicators. |
| `decision_generate_brief` | `topic` (str)<br>`metric_ids` (list[str]) | `DecisionBrief` | Synthesizes verified numbers, root causes, and recommended actions into an executive-ready brief with SHA-256 provenance links. |

#### Example Output: Structured Decision Brief

```markdown
# Operational Decision Brief: Q3 Procurement Cost Inflation
**Generated:** 2026-11-12 | **Target:** Operations & Procurement Leadership

### Executive Summary
Procurement processing costs experienced an increase of **+28.4%** ($68,000 vs. $52,000 baseline).

### Key Contributing Drivers (Verified via DuckDB)
- **Emergency Expedited Shipping:** Accounted for **64%** of cost increase across 32 purchase orders.
- **Supplier Off-Contract Orders:** Department 'Engineering Hardware' placed 41% of requests outside preferred vendor catalogs.

### Supporting Evidence & Provenance
- Dataset: `sample-data/procurement_costs.csv`
- Records Evaluated: 1,420 transactions
- Verified Calculation: `AVG(cost_per_order)` shifted from $49.52 to $65.21 ($p < 0.01$).

### Recommended Interventions
1. Implement vendor catalog constraints for requisitions exceeding $2,500.
2. Automate lead-time notifications to eliminate rush-order delivery fees.
```

---

## MCP Resources & Prompts

In addition to tools, Workflow Intelligence MCP exposes standardized protocol primitives:

### MCP Resources
- `workflow://process-maps/{process_name}`: Dynamic Directly-Follows Graphs resolved from any registered event log in `sample-data/`.
- `workflow://exceptions/active`: Real-time index of open workflow exceptions and priority queues from `ExceptionRepository`.
- `workflow://metrics/kpi-definitions`: Deterministic SQL definitions and calculation formulas.
- `workflow://audit/recent`: Recent immutable audit trail entries capturing system decisions and escalations.

### MCP Prompts
- `process_bottleneck_review`: Pre-structured prompt for comprehensive operational workflow analysis.
- `exception_triage_session`: Interactive step-by-step assistant for reconciling ambiguous case failures.
- `management_decision_brief`: Standardized template for generating executive operational reports.

---

## End-to-End Walkthrough: Procurement Lifecycle

The server demonstrates its integrated intelligence loop through a single end-to-end procurement process:

```
Step 1: Discover
Event Logs Ingested ──► PM4Py detects 74-hour approval queues in Finance.
                        Score ranking identifies 'Requisition Approval' as #1 automation target.
        │
        ▼
Step 2: Resolve
Execution Halts    ──► A high-value PO fails at vendor dispatch.
                        Exception service triages fuzzy vendor mismatch, retrieves tax record,
                        and safely auto-heals the workflow with full audit logging.
        │
        ▼
Step 3: Decide
Quarterly Review   ──► Executive asks: 'Why did procurement costs spike 28%?'
                        Decision Intelligence queries transaction logs, attributes the increase
                        to rush delivery fees caused by the upstream approval bottleneck,
                        and drafts an evidence-backed decision brief.
```

---

## Installation & Quickstart

### Prerequisites
- Python `>= 3.12`
- Docker & Docker Compose (Optional, for containerized deployment)

### 1. Local Setup

```bash
# Clone the repository
git clone https://github.com/coder-aadii/Workflow-Intelligence-MCP.git
cd Workflow-Intelligence-MCP

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install package and dependencies in editable mode
pip install -e ".[dev]"
```

### 2. Environment Configuration

```bash
cp .env.example .env
# Edit .env to set your database or analytical paths
```

### 3. Running the Server

#### Option A: Standard I/O (STDIO) — Default for local desktop agents
```bash
python -m workflow_intelligence.server --transport stdio
```

#### Option B: Unified Dual-Transport (Streamable HTTP + Legacy SSE) — Recommended for Docker
```bash
python -m workflow_intelligence.server --transport unified --port 8000
```
This serves:
- Streamable HTTP endpoint: `POST http://127.0.0.1:8000/mcp`
- Legacy SSE endpoint: `GET http://127.0.0.1:8000/sse`
- Health check probe: `GET http://127.0.0.1:8000/health`
- Readiness probe: `GET http://127.0.0.1:8000/ready`

#### Option C: Standalone Streamable HTTP
```bash
python -m workflow_intelligence.server --transport streamable-http --port 8000
```

#### Option D: Standalone SSE
```bash
python -m workflow_intelligence.server --transport sse --port 8000
```

---

## MCP Client Configuration

### Claude Desktop (STDIO)
Add the server definition to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "workflow-intelligence": {
      "command": "/path/to/Workflow-Intelligence-MCP/.venv/bin/python",
      "args": ["-m", "workflow_intelligence.server", "--transport", "stdio"],
      "env": {
        "WORKFLOW_ENV": "development",
        "DATABASE_URL": "postgresql+asyncpg://postgres:postgres@localhost:5432/workflow_intelligence"
      }
    }
  }
}
```

### Streamable HTTP Client (Claude Desktop / Remote Agent)
When running over the network in production with bearer token authentication:

```json
{
  "mcpServers": {
    "workflow-intelligence-remote": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-mcp-auth-token"
      }
    }
  }
}
```

### Legacy SSE Client
```json
{
  "mcpServers": {
    "workflow-intelligence-sse": {
      "url": "http://127.0.0.1:8000/sse",
      "headers": {
        "Authorization": "Bearer your-secure-mcp-auth-token"
      }
    }
  }
}
```

### Cursor IDE Configuration
In Cursor's `Features > MCP Servers` settings:
- **Name:** `workflow-intelligence`
- **Type:** `command`
- **Command:** `python -m workflow_intelligence.server --transport stdio`

---

## Environment Variables Reference

| Variable | Description | Default |
|---|---|---|
| `WORKFLOW_ENV` | Application environment (`development`, `staging`, `production`) | `development` |
| `SERVER_TRANSPORT` | MCP transport mechanism (`stdio`, `sse`, `streamable-http`, `unified`) | `stdio` |
| `SERVER_HOST` | Host address for network transports | `127.0.0.1` |
| `SERVER_PORT` | Port for HTTP transports | `8000` |
| `MCP_AUTH_TOKEN` | Bearer token for network endpoints (mandatory in production) | `None` |
| `TRUSTED_AUTH_GATEWAY` | Gateway indicator; in production, `MCP_AUTH_TOKEN` is strictly mandatory and cannot be bypassed | `false` |
| `ALLOWED_DATA_DIRS` | Comma-separated allowlist of accessible data directories | `sample-data,data,local` |
| `MAX_FILE_SIZE_BYTES` | Maximum allowable file size before ingestion rejection | `209715200` (200MB) |
| `ANALYSIS_TIMEOUT_SECONDS` | Timeout for process mining with process-isolated termination | `60.0` |
| `QUERY_TIMEOUT_MS` | Timeout for analytical DuckDB queries in milliseconds | `30000` (30s) |
| `DATABASE_URL` | PostgreSQL asyncpg connection string | `postgresql+asyncpg://postgres:postgres@localhost:5432/workflow_intelligence` |
| `DUCKDB_PATH` | Path to persistent DuckDB file (or `:memory:`) | `:memory:` |
| `REDIS_URL` | Redis URL for workflow caching | `redis://localhost:6379/0` |
| `LOG_LEVEL` | Structured logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | `INFO` |

---

## Real-World Dataset Benchmarks

Workflow-Intelligence-MCP was validated against high-volume, real-world enterprise datasets:

### 1. BPIC19 Flat Event Log (`local/BPIC19_flat.csv`)
- **Scale:** 1,595,923 events | 251,734 cases | 42 unique activities
- **Execution Time:** 332.73s (~5.5 min)
- **Peak RAM:** 1,260.51 MB (~1.26 GB)
- **Results:** Discovered 11,973 variants and 498 directly-follows transitions.
- **Resource Safety:** Bounded execution via OS process isolation guarantees that timed-out workloads cannot consume unbounded CPU or leak memory.

### 2. Insurance Claims Event Log (`local/Insurance_claims_event_log.csv`)
- **Scale:** 180,000 events | 30,000 cases | 6 unique activities
- **Execution Time:** 55.98s
- **Peak RAM:** 291.09 MB
- **Operational Bottleneck Detected:** `First Notification of Loss (FNOL) -> Assign Claim` (avg duration 360.25 hours / 15 days, impacting 29,807 claims / 99.36%).
- **Automation Potential:** FNOL identified as #1 candidate for RPA/automated ingestion.
- **DuckDB Analytical Validation:** Aggregated claim amounts across Collision ($5,498.07 avg), Comprehensive ($5,502.13 avg), and Liability ($5,495.59 avg) with zero procurement assumptions.

> **Benchmark Reproduction:** Benchmarks can be executed locally against large event logs in `local/` using `python3 scripts/regression_test.py`.

---

## Operations & Disaster Recovery Runbook

### Health Probes
- **Liveness Probe:** `GET http://127.0.0.1:8000/health` -> returns `{"status": "healthy"}`
- **Readiness Probe:** `GET http://127.0.0.1:8000/ready` -> validates DB connectivity and returns `{"status": "ready"}`

### PostgreSQL Backup & Recovery
```bash
# Backup database to SQL dump
docker compose exec -T postgres pg_dump -U postgres workflow_intelligence > wimcp_backup_$(date +%Y%m%d_%H%M%S).sql

# Restore database from backup
docker compose exec -T postgres psql -U postgres workflow_intelligence < wimcp_backup_20261116.sql
```

### Rollback Procedure
If a deployment fails, rollback safely without data loss:
```bash
# Graceful stop
docker compose stop workflow-intelligence-mcp

# Roll back code to pre-hardening tag/checkpoint
git checkout checkpoint-pre-hardening

# Rebuild and start container
docker compose up -d --build
```

---

## Repository Structure

```text
workflow-intelligence-mcp/
├── src/
│   └── workflow_intelligence/
│       ├── server.py                   # FastMCP server entrypoint & lifecycle
│       ├── config.py                   # Pydantic Settings configuration
│       ├── dependencies.py             # Dependency injection container
│       │
│       ├── tools/                      # Thin MCP tool endpoints
│       │   ├── process_discovery.py    # process_* endpoints
│       │   ├── exception_resolver.py   # exception_* endpoints
│       │   └── decision_intelligence.py# decision_* endpoints
│       │
│       ├── resources/                  # MCP Resources (process maps, metrics)
│       ├── prompts/                    # MCP Prompt templates
│       │
│       ├── services/                   # Core business logic
│       │   ├── process_service.py      # PM4Py wrappers & mining logic
│       │   ├── exception_service.py    # Failure classification & resolution
│       │   ├── decision_service.py     # KPI root-cause & decision engine
│       │   ├── analytics_service.py    # DuckDB deterministic calculations
│       │   ├── evidence_service.py     # Provenance tracking & record matching
│       │   └── reporting_service.py    # Markdown briefs and visual reports
│       │
│       ├── adapters/                   # Integration boundaries
│       │   ├── process_mining/         # PM4Py adapter
│       │   ├── analytics/              # DuckDB engine adapter
│       │   ├── database/               # SQLAlchemy persistence adapter
│       │   └── workflow_engine/        # Temporal and n8n connectors
│       │
│       └── schemas/                    # Pydantic V2 IO contracts
│
├── tests/
│   ├── unit/                          # Service algorithms & validation tests
│   ├── integration/                   # Adapters & storage tests
│   ├── protocol/                      # MCP server tool invocation tests
│   └── fixtures/                      # Mock event logs & transaction data
│
├── sample-data/                       # Datasets for demonstrations & tests
├── demo/                              # Walkthrough scripts & client configs
├── .gitignore
├── pyproject.toml
├── README.md
├── AGENTS.md                          # Agent operating guide
└── LICENSE
```

---

## Testing & Quality Assurance

The codebase enforces a 4-layer testing regime:

```bash
# Run complete test suite
pytest

# Run unit tests only
pytest tests/unit

# Run MCP protocol tests (verifies tool discovery & schema contracts)
pytest tests/protocol

# Run with test coverage
pytest --cov=workflow_intelligence --cov-report=term-missing
```

---

## Roadmap

- [x] Initial design, protocol architecture, and AGENTS.md operational manual.
- [x] **v0.1.0 (MVP):** Core Pydantic schemas, PM4Py CSV log reconstruction, DuckDB analytics service, FastMCP STDIO server.
- [x] **v0.5.0 (Engineering Maturity):** PostgreSQL repository persistence, Temporal/n8n mock connectors, MCP Resources & Prompts, Docker Compose setup.
- [x] **v1.0.0 (Production Ready):** Complete CI/CD GitHub Actions, end-to-end procurement demo with synthetic ERP datasets, OpenTelemetry tracing.
- [x] **v1.0.1 (Enterprise Hardening):** Zero-hardcoding, dynamic SQL metric injection, universal dataset support (Amul dairy cold-chain benchmarks).

---

## Contributing

Contributions are welcome! Please ensure that:
1. All business logic is encapsulated within `src/workflow_intelligence/services/`, not inside tool handlers.
2. Calculations and aggregations remain 100% deterministic.
3. Every new tool is backed by unit and protocol tests.
4. Read [AGENTS.md](AGENTS.md) for full architectural conventions.

---

## License

This project is licensed under the [Apache 2.0 License](LICENSE).