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).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues