convez.ai
MCP ServerDados & AnalyticsAvançado
chrbailey

SAP Transaction Forensics

chrbailey/SAP-Transaction-Forensics

Correlação de transações ERP+CRM para descoberta de fraude e desvios

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP para descoberta de padrões forenses em transações de ERP e CRM, correlacionando dados estruturados (SAP) com textos não-estruturados (emails, notas, tickets). Implementa detecção determinística de 18 ferramentas de análise plus camada de aprendizado com loop Worker/Critic para descobrir novos padrões de fraude, desperdício e desvios de conformidade.

Instalação

$npx convez-ai chrbailey/SAP-Transaction-Forensics

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
4
Acompanhando
1
Saúde
85%
Último commit
há 6 dias
Versão
v3.0.1
Issues abertas
21
Contribuidores
2

Casos de uso

  • Auditoria interna e detecção de fraude em ERP
  • Análise de conformidade SOX/ITGC com evidência textual
  • Investigação de desperdício operacional em sales orders e invoices
  • Descoberta de padrões anômalos em dados transacionais históricos

Veredito

Ferramenta robusta de forensics com testes extensivos (1.600+ casos) que une detecção determinística com descoberta de padrões via IA. Ideal para auditores e analistas de compliance em ambientes SAP/Salesforce, mas exige expertise em ERP e interpretação de anomalias.

README

A tradução para o português deste README ainda está na fila.

SAP Transaction Forensics

Forensic pattern discovery for ERP transaction data. Not a rule engine — a learning system.

▶ Open the live demo — no install →

SAP Transaction Forensics — live demo

The Core Insight

Structured data tells you what happened. Unstructured text tells you why.

Every enterprise system generates two kinds of data. Structured transactions — timestamps, amounts, stage changes, user IDs — tell you the official story. Unstructured text — the emails, Slack threads, tickets, meeting notes, timesheets, SOWs, and order notes that surround those transactions — tell you what actually happened. The gap between them is where fraud, waste, and dysfunction hide.

Structured data saysUnstructured text reveals
"Deal in Negotiation for 6 months""Customer said not ready — Sales moved it forward anyway. No sign-off."
"Purchase Order created 03/15""Requisition wasn't approved yet. Create the PO now, paperwork later."
"Phase 2: On Track, Green""We're 3 weeks behind. Tell the client we're on track while we figure it out."

This tool correlates both sides and surfaces the contradictions. It has been used on real engagements — see Field Case Studies (3M+ ERP records, $103K in waste found, ITGC/SOX violations) — and ships a synthetic demo so you can watch the same detector classes fire without touching a real system.

The Problem

Existing forensic tools ship with hardcoded rules. "Flag invoices over $X." "Alert on vendor master changes." These rules miss new patterns and fire on irrelevant ones. Every ERP is different. Every client's fraud signature is different. A static rule engine cannot keep up.

The Approach

This project has two layers:

  1. Detection layer — 18 analysis/data MCP tools plus 9 governance tools implementing well-known forensic checks (SoD conflicts, conformance deviations, journal anomalies). Deterministic, tested, callable from Claude Code.
  2. Discovery layer — a Worker/Critic/Ralph loop that proposes new patterns from your data, validates them against evidence, and grows a persistent pattern library. See pattern-discovery/.

The detection layer finds things you know to look for. The discovery layer finds things you didn't.

▶ See It Working — No Install

Open the live demo dashboard →

A read-only forensic pass over 214 Salesforce opportunities and their linked SAP sales orders surfaces 117 anomaly instances across 10 categories — plus the contradictions between what CRM and ERP each claim happened. Click any finding to inspect the underlying records. Nothing to install; it runs in your browser.

The dashboard is generated by the analysis pipeline itself (deterministic, seed 42), not hand-authored. What you see is exactly what the tool produces.

Run the same dashboard locally (≈60 seconds)

No SAP access required. Synthetic data included.

git clone https://github.com/chrbailey/SAP-Transaction-Forensics.git
cd SAP-Transaction-Forensics
pip install numpy pandas scipy scikit-learn faker click   # one-time
make demo-web                          # generate data → run forensics → open dashboard

make demo-web generates synthetic Salesforce + SAP data, runs the full forensic analysis, and opens the dashboard at http://localhost:8000. To rebuild the data without serving, use make bake-demo. To open the dashboard with zero setup, just open demo/index.html in a browser — the findings are baked in.

Drive it from Claude Code (the full toolset)

make demo                              # generates synthetic data + runs analysis
cd mcp-server && npm install && npm run build && cd ..
claude                                 # opens Claude Code with 27 registered tools

Then ask Claude: "Run a conformance check against the o2c-simple reference model."

Full walkthrough: QUICKSTART.md · Five-question demo: scripts/demo-walkthrough.md · Pattern discovery: pattern-discovery/README.md

Full portfolio dashboard — 6 analysis lenses

Beyond the synthetic demo, the portfolio dashboard (live at /portfolio/) presents six forensic lenses over real datasets. It was consolidated here from the now-archived transaction-forensics repo so everything lives in one place.

LensData sourceScaleKey finding
OverviewArchitecture + thesis—Structured-vs-unstructured gap analysis
CRM PipelineKaggle CRM Sales Opportunities8,800 opportunitiesWin rates, velocity, quarter-end compression
BPI ChallengeBPI Challenge 2019 (4TU.ResearchData)251,734 POs · 1.6M events57K payment blocks, resource concentration
IDES ComplianceSAP IDES demo system3,132 cases (O2C + P2P)7 compliance violations in SAP's own reference data
Client Cases3 anonymized engagements3M+ ERP records$103K savings, credit-hold overrides, SOD violations
NLP PatternsSalesforce/HERB (HuggingFace)37,064 documents11 communication clusters, approval bottlenecks

The NLP pipeline behind the last tab lives in herb-nlp/ (TF-IDF + KMeans, optional BERTopic, network + temporal analysis).

Proven in the Field

Three real consulting engagements motivated this tool. Anonymized, but the figures are actual. Full write-ups in docs/CASE_STUDIES.md.

EngagementWhat structured data showedWhat the text/forensics revealedResult
Healthcare — NetSuite license audit (289 users)A clean user list8 dormant full-access licenses, ~53 departed employees still licensed, 4 "approve-only" users$103,896/yr savings · 14.4× ROI · 0.8-mo payback
MedTech — ticket forensics during acquisition (2,525 tickets)Normal operationsDummy MRP transactions, mutating item numbers, "URGENT" escalation culture, 257 access-request ticketsOrganizational stress invisible in the ERP, surfaced from text
Connected hardware — high-growth ERP + ITGC (3M+ records)Orders shipped, invoiced, clearedCredit holds overridden to ship anyway, 28.6% account return rate, 7 admin users (one terminated), broken approval chainsSOX-relevant control gaps documented with evidence

Each maps to a detector class in this repo (segregation-of-duties, policy override, temporal impossibility, reality-gap). The synthetic demo plants these same patterns so you can see them fire with no access to a real system.

What This Is Not

  • Not a governance tool. For pre-execution approval of AI agent actions, see PromptSpeak.
  • Not a self-healing system. It finds problems. Humans decide what to do.
  • Not a commercial product. MIT licensed. Built by an independent consultant (Christopher Bailey, ERP Access Inc, 29 years in ERP — SAP, NetSuite, Oracle, Workday).

License: MIT Node.js Python Tests


What's New: Evidence Infrastructure

Full evidence lifecycle from extraction through reviewer handoff, with cryptographic verification at every step.

FeatureDescription
Provenance GraphField-level DAG tracing every finding to system/table/record/field/value/timestamp
Extraction Registry19 named, versioned, deterministic extraction paths across SAP, Salesforce, and NetSuite
Contradiction Engine12-category typed taxonomy with risk scoring and type-specific weights
Schema Validator19-table IDES reference schema (438 fields) with pre-flight validation and customization detection
Reality-Gap DetectorThree-way gap analysis: reference models vs documented business rules vs actual event logs
Finding Lifecycle8-state machine with SQLite persistence, transition history, and deduplication
Reviewer HandoffSelf-contained audit artifacts verifiable without model access
2,048 Passing Tests1,611 MCP + 367 pattern engine + 44 synthetic data + 24 discovery + 2 viewer; 42 skipped

The evidence infrastructure is implemented and tested as source modules. Its nine tool definitions are not yet registered in the live MCP tool list; see QUICKSTART.md for the currently callable tools.

Sample Evidence Chain

Finding: AMOUNT_DIVERGENCE on Sales Order 0000045123
  Evidence:
    Left:  SAP.VBAK.0000045123.NETWR = 125,000.00  (extracted 2025-09-15T14:22:00Z)
    Right: SFDC.Opportunity.006R00000123.Amount = 118,750.00  (extracted 2025-09-15T14:22:01Z)
    Delta: 5.3% ($6,250.00)
  Provenance:
    Extraction Path: sap-o2c-order-headers v1.0
    Replay Hash: sha256:a7f3b2...
  State: CONFIRMED → REMEDIATION (transitioned 2025-09-16 by reviewer@corp.com)

Alternative Paths (Without Claude Code)

If you're not using Claude Code, the underlying tools can still be run directly:

Option A: Docker Compose (Browser UI)

docker-compose up --build
# Open browser to http://localhost:8080

Option B: Analyze Your CSV Exports

# Export from SE16: VBAK, VBAP, LIKP, LIPS, VBRK, VBRP, STXH/STXL
# Place files in ./input-data/
docker-compose run pattern-engine --input-dir /app/input-data --output-dir /app/output

Option C: Live RFC Connection

# Copy and edit configuration
cp .env.rfc.example .env.rfc
# Edit .env.rfc with your SAP connection details

# Run with RFC adapter
docker-compose --profile rfc up mcp-server-rfc

See Installation Guide for detailed setup instructions.

Option D: Analyze Salesforce Data

# 1. Generate synthetic SFDC data (200 Opportunities, 10 planted anomaly patterns)
cd synthetic-data
python3 src/generate_sfdc.py --count 200 --accounts 50 --output sfdc_output/ --seed 42

# 2. Run the forensic analysis
cd ../pattern-engine
python3 scripts/analyze_sfdc.py

# Or bring your own SFDC export:
# Place Opportunity, Account, StageHistory CSVs in ./data/sfdc/
# python3 scripts/analyze_sfdc.py --data-dir ../data/sfdc

Evidence Infrastructure

The evidence infrastructure provides a complete chain of custody from raw system data through forensic findings to reviewer-ready audit packets.

Provenance Graph

Every finding traces back to specific fields in specific records in specific systems through a directed acyclic graph (DAG). Each extraction record captures:

  • System - SAP, Salesforce, or NetSuite
  • Table - Source table (e.g., VBAK, Opportunity)
  • Record ID - Specific document or record
  • Field - Individual field name
  • Value - Extracted value at time of extraction
  • Timestamp - When the extraction occurred
  • Replay Hash - SHA-256 hash for independent re-verification

Export formats: DAG JSON (full graph), flat (tabular), Markdown (human-readable).

Extraction Registry

19 named, versioned, deterministic extraction paths ensure reproducible data collection:

DomainPathDescription
SAP O2Csap-o2c-order-headersSales order header fields (VBAK)
sap-o2c-order-itemsLine item details (VBAP)
sap-o2c-doc-flowDocument flow chain (VBFA)
sap-o2c-delivery-timingRequested vs actual delivery (LIKP/LIPS)
sap-o2c-invoice-timingInvoice creation and posting (VBRK/VBRP)
SAP FI/COsap-fico-journal-entriesJournal entry headers (BKPF)
sap-fico-line-itemsJournal line items (BSEG)
sap-fico-sod-conflictsSegregation of duties analysis
sap-fico-gl-balancesGL account balances
SAP P2Psap-p2p-purchase-ordersPurchase order data (EKKO/EKPO)
sap-p2p-requisitionsPurchase requisitions (EBAN)
sap-p2p-goods-receiptsGoods receipt documents (MKPF/MSEG)
sap-p2p-invoice-verificationInvoice verification (RBKP/RSEG)
Salesforcesfdc-opportunitiesOpportunity pipeline data
sfdc-stage-historyStage transition history
sfdc-activitiesTasks and events on records
NetSuitenetsuite-user-activityUser activity audit trail
netsuite-transaction-summaryTransaction summaries
netsuite-login-historyLogin and access history

Each path is versioned and produces deterministic output for the same input, enabling SHA-256 replay verification.

Contradiction Engine

Cross-system contradiction detection with a 12-category typed taxonomy:

CategoryWhat It Detects
AMOUNT_DIVERGENCEDollar amounts that differ beyond tolerance across systems
DATE_CONFLICTDates that disagree between matched records
STATUS_INCOMPATIBLEStatus fields that cannot logically coexist
ENTITY_MISMATCHCustomer/vendor/material IDs that do not match across systems
QUANTITY_DIVERGENCEQuantities that differ beyond tolerance
APPROVAL_BYPASSTransactions that bypassed required approval steps
TEMPORAL_IMPOSSIBILITYEvents that occur in an impossible sequence
DUPLICATE_REFERENCEMultiple records claiming the same reference number
ORPHAN_RECORDRecords in one system with no counterpart in the other
RETROACTIVE_CHANGEChanges made to records after they were finalized
SOD_VIOLATIONSame user performing conflicting duties
SCHEMA_GHOSTFields or values that reference non-existent schema elements

Risk scoring uses type-specific weights. Severity levels: CRITICAL, HIGH, MEDIUM, LOW, INFO.

Schema Validator

Pre-flight validation of extraction paths against client schemas before any data is pulled.

  • Reference schema: 19 tables, 438 fields from an actual SAP IDES dump
  • Path validation: Verifies that every field referenced by an extraction path exists in the client schema
  • Customization detection: Identifies Z-tables, Z-fields, and custom namespaces
  • Gap reporting: Shows exactly which fields are missing and which paths are affected

Reality-Gap Detector

Three-way gap analysis comparing what should happen, what is documented, and what actually happens:

Gap TypeComparisonExample
Design GapReference model vs documented rulesSoD policy exists but no enforcing control configured
Compliance GapDocumented rules vs actual eventsThree-way match required but invoices posted without GR
Shadow ProcessActual events vs all documented modelsGoods receipts posted on weekends with no approval workflow

Includes a rule parser with standard rulesets for SAP, NetSuite, and Salesforce.

Finding Lifecycle Manager

8-state machine tracking every finding from detection through resolution:

DETECTED → TRIAGED → INVESTIGATING → CONFIRMED → REMEDIATION → RESOLVED
                 ↘                       ↘              ↗
              FALSE_POSITIVE         ACCEPTED_RISK
  • SQLite persistence with full transition history (who, when, from-state, to-state)
  • Deduplication prevents the same finding from being logged twice
  • Four finding sources: contradiction, reality_gap, conformance, fi_co_anomaly
  • Risk scores (0.0-1.0) computed from finding type and severity

Reviewer Handoff Packets

Self-contained audit artifacts that can be verified without model access:

  • Executive Summary - Scope, systems analyzed, key metrics, risk distribution
  • Rendered Findings - Each finding with severity, evidence tables, and provenance chain
  • Extraction Manifest - Every extraction path used, with parameters and SHA-256 replay hashes
  • Reproduction README - Step-by-step instructions to re-run the analysis independently
  • Reviewer Checklist - 25-item verification checklist covering completeness, accuracy, and methodology

SFDC Forensic Analysis

The Salesforce adapter maps Opportunity pipeline data through the same pattern engine used for SAP:

Field Mapping (SFDC → SAP Normalized)

SFDC ConceptSAP EquivalentMapping
Opportunity.IdVBELNPadded to 10 chars
RecordType.NameAUARTNew Business→ZNEW, Renewal→ZREN, Upsell→ZUPS
Account.IdKUNNRPadded to 10 chars
Opportunity.AmountNETWRDirect
Stage transitionsVBFA (doc flow)Each stage change → flow entry
Task/EventSTXH/STXL (texts)Activity subject + description → doc text
Account (safe fields)KNA1Industry, State, Country only (no PII)

Cross-System Correlation

When both SFDC and SAP data are loaded, the entity resolver matches records using:

  1. Explicit ID (confidence 0.99) — Opportunity.SAP_Order_Number__c == VBAK.VBELN
  2. Proximity (confidence 0.50-0.95) — Account name similarity + amount tolerance + date proximity
  3. Temporal sequence (Phase 2) — Monotonic SFDC→SAP event chain validation

Anomalies detected across matched pairs:

  • Timing gaps — SFDC close to SAP order creation > 30 days
  • Amount discrepancies — SFDC Amount vs SAP NETWR > 5% tolerance
  • Sequence violations — SAP order created before SFDC close
  • Missing handoffs — SFDC Closed Won with no corresponding SAP order

Planted Anomaly Patterns (Synthetic Data)

The SFDC generator plants 10 detectable patterns at controlled rates:

PatternRateWhat It Tests
Stage skip5%Conformance: mandatory stages bypassed
Quarter-end compression40% of wonTemporal: period-end deal clustering
Ghost pipeline10% of late-stageCorrelation: zero activities on active deals
Stage regression3%Conformance: backward stage movement
Amount inflation8%Correlation: >50% amount increase at close
Split deal6%Cross-entity: same account, duplicate deals within 7 days
Speed anomaly5%Temporal: created to closed in <3 days
Stale pipeline15% of openTemporal: no movement for >90 days
Owner swap at close4% of wonConformance: owner changes in final stage
Cross-system gap6% of SAP-linkedCross-system: >30 day SFDC→SAP timing gap

What You Get

+-----------------------------------------------------------------------------------+
|                              Pattern Discovery Report                              |
+-----------------------------------------------------------------------------------+
| Pattern: "Credit Hold Escalation"                                                  |
| ----------------------------------------------------------------------------------|
| Finding: Orders with 'CREDIT HOLD' in notes have 3.2x longer fulfillment cycles   |
|                                                                                    |
| Occurrence: 234 orders (4.7% of dataset)                                           |
| Sales Orgs: 1000 (64%), 2000 (36%)                                                 |
| Confidence: HIGH (p < 0.001)                                                       |
|                                                                                    |
| Caveat: Correlation only - does not imply causation                                |
+-----------------------------------------------------------------------------------+

Key Features:

  • Text Pattern Discovery - Find hidden patterns in order notes, rejection reasons, and delivery instructions
  • Document Flow Analysis - Trace complete order-to-cash chains with timing at each step
  • Outcome Correlation - Identify text patterns that correlate with delays, partial shipments, or returns
  • Evidence-Based Reporting - Every pattern links to specific documents with field-level provenance
  • Privacy-First Design - PII redaction enabled by default, shareable output mode for external review

v2.0 Features

Natural Language Interface

Ask questions about your SAP processes in plain English:

User: "Why are orders from sales org 1000 taking longer to ship?"

System: Based on analysis of 5,234 orders:
- Average delay: 4.2 days vs 1.8 days for other orgs
- Root cause: 73% have "CREDIT HOLD" in notes
- Recommendation: Review credit check thresholds for org 1000

Confidence: HIGH | Evidence: 847 documents analyzed

Supports multiple LLM providers:

  • Ollama (local, private) - Default for air-gapped environments
  • OpenAI (GPT-4) - For cloud deployments
  • Anthropic (Claude) - Alternative cloud option

OCEL 2.0 Export

Export to the Object-Centric Event Log standard for advanced process mining:

{
  "ocel:version": "2.0",
  "ocel:objectTypes": ["order", "item", "delivery", "invoice"],
  "ocel:events": [...],
  "ocel:objects": [...]
}
  • Captures multi-object relationships (order → items → deliveries → invoices)
  • Compatible with PM4Py, Celonis, and other OCEL tools
  • Export formats: JSON, XML, SQLite

Conformance Checking

Compare actual SAP processes against expected Order-to-Cash models:

Conformance Report: 94.2% (4,712 / 5,000 cases)

Deviations Detected:
├── CRITICAL: Invoice before Goods Issue (23 cases)
├── MAJOR: Skipped Delivery step (187 cases)
└── MINOR: Duplicate Order Created (78 cases)
  • Pre-built O2C reference models (simple and detailed)
  • Severity scoring: Critical / Major / Minor
  • Deviation types: skipped steps, wrong order, missing activities

Visual Process Maps

Generate process flow diagrams with bottleneck highlighting:

graph LR
    A[Order Created] -->|2.1 days| B[Delivery Created]
    B -->|0.5 days| C[Goods Issued]
    C -->|3.2 days| D[Invoice Created]

    style C fill:#f8d7da
  • Output formats: Mermaid (Markdown), GraphViz (DOT), SVG
  • Color-coded bottleneck severity (green/yellow/red)
  • Timing annotations between process steps

Predictive Monitoring

ML-based prediction for process outcomes:

Order 0000012345 - Risk Assessment:
├── Late Delivery: 78% probability (HIGH RISK)
│   └── Factors: credit_block, order_value > $50k
├── Credit Hold: 45% probability (MEDIUM RISK)
└── Est. Completion: 8.2 days

Prediction Types:

  • Late Delivery - Probability based on case age, progress, stalls, rework
  • Credit Hold - Likelihood based on credit check status, complexity
  • Completion Time - Estimated hours remaining based on progress/pace

29 Extracted Features:

  • Temporal: case age, time since last event, avg time between events
  • Activity: milestones reached, rework detection, loop count, backtracks
  • Resource: unique resources, handoff count
  • Risk indicators: stalled cases, credit holds, rejections, blocks

Why This Instead of S/4HANA?

ConsiderationS/4HANA MigrationTransaction Forensics
Timeline18-36 monthsHours to first insights
Cost$10M-$100M+Free (MIT license)
RiskBusiness disruptionZero - read-only access
Data LocationCloud/hostedOn-premise only
PrerequisitesGreenfield/brownfield projectWorks with existing ECC 6.0
Process VisibilityAfter migrationBefore any changes
Use CaseFull transformationProcess discovery & optimization

This tool does not replace S/4HANA. It helps you understand your current processes before making migration decisions - or find optimization opportunities in your existing ECC system.


Installation

Prerequisites

  • Docker & Docker Compose (recommended)
  • OR Node.js 20-25 and Python 3.10+ for local development

Quick Install

git clone https://github.com/chrbailey/SAP-Transaction-Forensics.git
cd transaction-forensics
docker-compose up --build

Detailed Setup

See docs/adapter_guide.md for:

  • RFC adapter configuration for ECC 6.0
  • OData adapter configuration for S/4HANA
  • CSV import from SE16 exports
  • Air-gapped installation options

LLM Configuration (v2.0)

Configure the natural language interface in .env:

# Option 1: Local Ollama (default, private)
LLM_PROVIDER=ollama
OLLAMA_HOST=http://localhost:11434
LLM_MODEL=llama3

# Option 2: OpenAI
LLM_PROVIDER=openai
LLM_API_KEY=<YOUR_OPENAI_KEY>
LLM_MODEL=gpt-4

# Option 3: Anthropic
LLM_PROVIDER=anthropic
LLM_API_KEY=<YOUR_ANTHROPIC_KEY>
LLM_MODEL=claude-3-sonnet-20240229

For air-gapped environments, use Ollama with locally downloaded models.


Demos

Interactive demos for all v2.0 process mining tools. No SAP connection required - all demos use synthetic data.

cd mcp-server

# Natural Language Interface - ask questions in plain English
npx tsx ../demos/ask_process_demo.ts
npx tsx ../demos/ask_process_demo.ts --interactive  # Interactive mode

# OCEL 2.0 Export - export to process mining standard format
npx tsx ../demos/export_ocel_demo.ts

# Conformance Checking - compare against O2C reference model
npx tsx ../demos/check_conformance_demo.ts

# Visual Process Maps - generate Mermaid flowcharts
npx tsx ../demos/visualize_process_demo.ts

# Predictive Monitoring - ML-based risk predictions
npx tsx ../demos/predict_outcome_demo.ts
DemoDescription
ask_process_demo.tsNatural language queries with LLM integration
export_ocel_demo.tsOCEL 2.0 export with object/event breakdown
check_conformance_demo.tsDeviation detection and severity scoring
visualize_process_demo.tsMermaid diagrams with bottleneck highlighting
predict_outcome_demo.tsRisk predictions and alerts
salt_adapter_demo.tsReal SAP O2C data from SALT dataset
visualize_process_bpi_demo.tsProcess maps with real P2P data (BPI 2019)
predict_outcome_bpi_demo.tsRisk predictions with real P2P data (BPI 2019)
ask_process_bpi_demo.tsNatural language queries on P2P data

Real SAP Data

BPI Challenge 2019 (P2P)

Use real SAP Purchase-to-Pay data from the BPI Challenge 2019 for testing with authentic business patterns.

# Download and convert BPI 2019 data
python scripts/convert-bpi-xes.py

# Run demos with real P2P data
npx tsx demos/visualize_process_bpi_demo.ts 50
npx tsx demos/predict_outcome_bpi_demo.ts 30
npx tsx demos/ask_process_bpi_demo.ts

Dataset Statistics:

MetricValue
Total cases251,734
Total events1.5M+
Unique activities39
Process typePurchase-to-Pay (P2P)
SourceMultinational coatings company

Activities include: SRM workflows, Purchase Orders, Goods Receipts, Service Entries, Invoice Processing, Vendor interactions


SALT Dataset (O2C)

Use real SAP ERP data from SAP's SALT dataset on HuggingFace for testing with authentic business patterns.

Quick Start

# 1. Install Python dependencies
pip install datasets pyarrow

# 2. Download SALT dataset
python scripts/download-salt.py

# 3. Run demo with real data
cd mcp-server
npx tsx ../demos/salt_adapter_demo.ts

What's Included

SALT (Sales Autocompletion Linked Business Tables) contains:

TableDescriptionRecords
I_SalesDocumentSales order headers~1M+
I_SalesDocumentItemOrder line items~5M+
I_CustomerCustomer master data~100K
I_AddrOrgNamePostalAddressAddress data~100K

Using the SALT Adapter

import { SaltAdapter } from './adapters/salt/index.js';

const adapter = new SaltAdapter({
  maxDocuments: 10000,  // Limit for memory management
});

await adapter.initialize();

// Get real sales order data
const header = await adapter.getSalesDocHeader({ vbeln: '0000012345' });
const items = await adapter.getSalesDocItems({ vbeln: '0000012345' });

// Get dataset statistics
const stats = adapter.getStats();
console.log(`Loaded ${stats.salesDocuments} sales documents`);

Limitations

SALT contains sales orders only (no deliveries or invoices). For full Order-to-Cash testing:

  • Use SALT for sales order analysis and ML training
  • Use synthetic adapter for complete O2C flow testing
  • Combine both for comprehensive validation

Why Use Real Data?

AspectSynthetic DataSALT Real Data
PatternsRandom/artificialAuthentic business patterns
ML TrainingLimited accuracyReal-world feature distributions
DemosGood for UI testingCompelling for stakeholders
ValidationFunctional testingBusiness logic validation

Analysis Results

We've validated the MCP tools against real SAP datasets. View the detailed analysis:

DatasetSystemCasesEventsKey FindingsReport
SFDC SyntheticSalesforce2142,41710 anomaly patterns, 57% QE compression, 2 cross-system gapsRun: python3 pattern-engine/scripts/analyze_sfdc.py
BPI Challenge 2019SAP P2P251,7341.6M42 activities, 64-day median throughputView →
SAP IDES O2CSAP O2C6465,708158 variants, bottlenecks identifiedView →
SAP IDES P2PSAP P2P2,4867,4207 compliance violations detectedView →

Process Diagrams: Mermaid flowcharts for O2C and P2P

Validation baseline: 2,048 tests pass and 42 are skipped — 1,611 MCP server, 367 pattern engine, 44 synthetic data, 24 pattern discovery, and 2 viewer tests. CI also builds the server, runs the demos, and scans JavaScript, TypeScript, Python, and Actions with CodeQL.


Security & Compliance

This system is designed for enterprise security requirements.

ConcernHow We Address It
Data AccessRead-only BAPIs only - no write operations, no arbitrary SQL
Data LocationLocal by default; cloud LLM and SaaS adapters are opt-in
NetworkNo telemetry or phone-home; configured cloud providers require outbound access
PII ProtectionAutomatic redaction of emails, phones, names, addresses
Audit TrailEvery query logged with parameters, timestamps, row counts
Row LimitsDefault 200 rows per query, max 1000 - prevents bulk extraction
ProvenanceSHA-256 replay hashing on every extraction for independent verification
Handoff IntegrityReviewer packets are self-contained and verifiable without model access

See SECURITY.md for complete security documentation.


For SAP Basis Administrators

Required Authorizations

The RFC user requires display-only access to SD documents:

Authorization Object: S_RFC
  RFC_TYPE = FUGR
  RFC_NAME = STXR, 2001, 2051, 2056, 2074, 2077
  ACTVT = 16 (Execute)

Authorization Object: V_VBAK_VKO
  VKORG = [Your Sales Organizations]
  ACTVT = 03 (Display)

Authorization Object: V_VBAK_AAT
  AUART = * (or specific document types)
  ACTVT = 03 (Display)

Copy-paste ready role template: See docs/SAP_AUTHORIZATION.md

BAPIs Used (All Read-Only)

BAPIPurposeTables Accessed
BAPI_SALESORDER_GETLISTList sales ordersVBAK
SD_SALESDOCUMENT_READRead order header/itemsVBAK, VBAP
BAPI_SALESDOCU_GETRELATIONSDocument flow (VBFA)VBFA
BAPI_OUTB_DELIVERY_GET_DETAILDelivery detailsLIKP, LIPS
BAPI_BILLINGDOC_GETDETAILInvoice detailsVBRK, VBRP
READ_TEXTLong text fieldsSTXH, STXL
BAPI_CUSTOMER_GETDETAIL2Customer master (stub)KNA1
BAPI_MATERIAL_GET_DETAILMaterial master (stub)MARA

No direct table access. No RFC_READ_TABLE unless explicitly enabled.


Architecture

+------------------------------------------------------------------+
|                        Your Network                               |
|  +------------------------------------------------------------+  |
|  |                                                            |  |
|  |   +----------------+     +-------------------+             |  |
|  |   | SAP ECC 6.0    |     | Transaction       |             |  |
|  |   |                |     | Forensics Server  |             |  |
|  |   |  +----------+  |     |                   |             |  |
|  |   |  | SD/MM    |  | RFC |  +-------------+  |             |  |
|  |   |  | Tables   |<--------->| MCP Server  |  |             |  |
|  |   |  +----------+  | (R/O)|  +-------------+  |             |  |
|  |   |                |     |         |         |             |  |
|  |   +----------------+     |         v         |             |  |
|  |                          |  +-------------+  |             |  |
|  |   +----------------+     |  | Evidence    |  |             |  |
|  |   | Salesforce     |     |  | Engine      |  |             |  |
|  |   |                | API |  | +---------+ |  |             |  |
|  |   | Opportunities  |<------>| |Provenance| |  |             |  |
|  |   | Activities     |     |  | |Registry | |  |             |  |
|  |   +----------------+     |  | |Findings | |  |             |  |
|  |                          |  | +---------+ |  |             |  |
|  |   +----------------+     |  +-------------+  |             |  |
|  |   | NetSuite       |     |         |         |             |  |
|  |   |                | API |         v         |             |  |
|  |   | Users/Txns     |<--->|  +-------------+  |             |  |
|  |   +----------------+     |  | Pattern     |  |             |  |
|  |                          |  | Engine      |  |             |  |
|  |                          |  +-------------+  |             |  |
|  |                          |         |         |             |  |
|  |   +----------------+     |  +-------------+  |             |  |
|  |   | Browser        |<------>| Web Viewer  |  |             |  |
|  |   | (localhost)    |     |  +-------------+  |             |  |
|  |   +----------------+     +-------------------+             |  |
|  |                                                            |  |
|  +------------------------------------------------------------+  |
|                                                                   |
|             EXTERNAL CONNECTIONS ONLY WHEN CONFIGURED             |
+------------------------------------------------------------------+

Data Flow:

  1. MCP Server connects to SAP via RFC, Salesforce via API, NetSuite via API (all read-only)
  2. Extraction Registry executes named, versioned extraction paths
  3. Provenance Graph records field-level evidence for every extraction
  4. Contradiction Engine and Reality-Gap Detector analyze cross-system data
  5. Finding Lifecycle Manager tracks findings from detection through resolution
  6. Handoff Generator produces self-contained reviewer packets
  7. Web Viewer displays findings on localhost

With local adapters and a local LLM, data remains on your network. Salesforce, NetSuite, OpenAI, and Anthropic integrations require outbound connections when explicitly configured.


FAQ

Is this tool officially supported by SAP?

No. This is an independent open-source project. It uses standard SAP BAPIs that are publicly documented.

Will this impact SAP system performance?

Minimal impact. All queries are:

  • Read-only (no locks)
  • Row-limited (200 default, 1000 max)
  • Rate-limited (configurable)
  • Use standard BAPIs (not direct table access)

We recommend running initial analysis during off-peak hours.

What SAP modules are supported?

SD (Sales & Distribution), MM (Materials Management), and FI/CO (Financial Accounting / Controlling) document flows. Cross-system analysis with Salesforce CRM and NetSuite is also supported.

Does this work with SAP on any database?

Yes. The tool uses BAPIs which are database-agnostic. Works with HANA, Oracle, DB2, SQL Server, MaxDB.

Can I run this in an air-gapped environment?

Yes. The Docker images can be built offline and transferred. No external dependencies at runtime.

How do I validate the findings?

Every finding includes:

  • Field-level provenance tracing to system/table/record/field/value/timestamp
  • SHA-256 replay hashes for independent re-verification
  • Sample document numbers for verification in SAP (VA03, VL03N, VF03)
  • Statistical confidence intervals
  • Explicit caveats about correlation vs. causation

For formal review, the handoff module can produce a self-contained audit artifact with a 25-item reviewer checklist. The generate_handoff_packet MCP definition exists in source but is not yet registered in the live server.

What about GDPR/data protection?

  • PII redaction is enabled by default
  • No data leaves your network
  • Shareable mode applies additional redaction
  • See SECURITY.md for compliance considerations

Can I contribute or request features?

Yes. See CONTRIBUTING.md for guidelines. Feature requests via GitHub Issues.


Governance (PromptSpeak Integration)

The MCP server includes a governance layer based on PromptSpeak symbolic frames for pre-execution blocking and human-in-the-loop approval workflows.

Why Governance?

When AI agents access SAP data, you need controls to:

  • Prevent bulk extraction - Hold requests for large date ranges or row counts
  • Protect sensitive data - Require approval for searches containing PII patterns
  • Halt rogue agents - Circuit breaker to immediately stop misbehaving agents
  • Audit everything - Complete trail of all operations for compliance

PromptSpeak Frames

Every operation has a symbolic frame indicating mode, domain, action, and entity:

Frame: ⊕◐◀α
       │ │ │ └── Entity: α (primary agent)
       │ │ └──── Action: ◀ (retrieve)
       │ └────── Domain: ◐ (operational)
       └──────── Mode: ⊕ (strict)
SymbolCategoryMeaning
⊕ModeStrict - exact compliance required
⊘ModeNeutral - standard operation
⊖ModeFlexible - allow interpretation
⊗ModeForbidden - blocks all actions
◊DomainFinancial (invoices, values)
◐DomainOperational (orders, deliveries)
◀ActionRetrieve data
▲ActionAnalyze/search
●ActionValidate
α β γEntityPrimary/secondary/tertiary agent

Hold Triggers

Operations are automatically held for human approval when:

TriggerThresholdExample
Broad date range>90 daysdate_from: 2024-01-01, date_to: 2024-12-31
High row limit>500 rowslimit: 1000
Sensitive patternsSSN, credit card, passwordpattern: "social security"

Governance Workflow

Agent Request
     │
     ▼
┌─────────────┐     ┌─────────────┐
│ Circuit     │────▶│ BLOCKED     │ (if agent halted)
│ Breaker     │     └─────────────┘
└─────────────┘
     │ OK
     ▼
┌─────────────┐     ┌─────────────┐
│ Frame       │────▶│ BLOCKED     │ (if ⊗ forbidden)
│ Validation  │     └─────────────┘
└─────────────┘
     │ OK
     ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Hold        │────▶│ HELD        │────▶│ Human       │
│ Check       │     │ (pending)   │     │ Approval    │
└─────────────┘     └─────────────┘     └─────────────┘
     │ OK                                      │
     ▼                                         ▼
┌─────────────┐                         ┌─────────────┐
│ EXECUTE     │◀────────────────────────│ APPROVED    │
└─────────────┘                         └─────────────┘

Governance Tools

ToolPurpose
ps_precheckDry-run: check if operation would be allowed
ps_list_holdsList pending holds awaiting approval
ps_approve_holdApprove a held operation
ps_reject_holdReject a held operation with reason
ps_agent_statusCheck circuit breaker state for an agent
ps_halt_agentImmediately halt an agent (blocks all ops)
ps_resume_agentResume a halted agent
ps_statsGet governance statistics
ps_frame_docsGet PromptSpeak frame reference

Example: Hold and Approval Flow

// 1. Agent makes a request that triggers hold
const result = await mcp.callTool('search_doc_text', {
  pattern: 'delivery',
  date_from: '2024-01-01',
  date_to: '2024-12-31',  // >90 days triggers hold
});
// Returns: { held: true, hold_id: 'hold_abc123', reason: 'broad_date_range' }

// 2. Supervisor reviews pending holds
const holds = await mcp.callTool('ps_list_holds', {});
// Returns: [{ holdId: 'hold_abc123', tool: 'search_doc_text', severity: 'medium' }]

// 3. Supervisor approves
const approved = await mcp.callTool('ps_approve_hold', {
  hold_id: 'hold_abc123',
  approved_by: 'supervisor@example.com'
});
// Returns: { allowed: true, auditId: 'audit_xyz789' }

Example: Emergency Agent Halt

// Immediately block a misbehaving agent
await mcp.callTool('ps_halt_agent', {
  agent_id: 'agent-123',
  reason: 'Excessive query rate detected'
});

// All subsequent requests from this agent are blocked
const result = await mcp.callTool('get_doc_text', {
  doc_type: 'order',
  doc_key: '0000000001',
  _agent_id: 'agent-123'  // Identifies the agent
});
// Returns: { error: 'Governance Blocked', message: 'Agent halted: Excessive query rate' }

// Resume when issue is resolved
await mcp.callTool('ps_resume_agent', { agent_id: 'agent-123' });

MCP Tools Reference

SAP Data Tools

ToolPurposeReturns
search_doc_textFind documents by text patterndoc_type, doc_key, snippet, match_score
get_doc_textGet all text fields for a documentheader_texts[], item_texts[]
get_doc_flowGet order-delivery-invoice chainchain with keys, statuses, dates
get_sales_doc_headerOrder header detailssales_org, customer, dates, values
get_sales_doc_itemsOrder line itemsmaterials, quantities, values
get_delivery_timingRequested vs actual deliverytimestamps, variance analysis
get_invoice_timingInvoice creation/postinginvoice dates, accounting refs
get_master_stubSafe master data attributeshashed IDs, categories (no PII)

Process Mining Tools (v2.0)

ToolPurposeReturns
ask_processNatural language queriesanswer, confidence, evidence, recommendations
export_ocelExport to OCEL 2.0 formatOCEL JSON/XML with objects and events
check_conformanceCompare against O2C modelconformance_rate, deviations, severity_summary
visualize_processGenerate process diagramsMermaid/DOT/SVG with bottleneck highlighting
predict_outcomeML-based outcome predictionpredictions, alerts, risk_levels, factors

FI/CO Forensic Tools

ToolPurposeReturns
analyze_journal_entriesJournal entry anomaly detectionanomalies, risk_scores, patterns
analyze_sodSegregation of duties analysisconflicts, violation_count, users
analyze_gl_balancesGL account balance analysisbalance_anomalies, trends
get_fi_documentRetrieve FI document detailsheader, line_items, amounts
generate_fi_assessmentFI/CO risk assessment reportassessment, findings, recommendations

Evidence Infrastructure Modules (Not Yet MCP-Registered)

These definitions and executors are implemented and tested in source, but they are not included in the current allTools registry. They are not callable from Claude Code until registration and adapter routing are completed.

ToolPurposeReturns
query_provenanceTrace evidence chain for a findingDAG/flat/Markdown with field-level provenance
list_extraction_pathsList available extraction pathspath definitions with system, version, fields
run_extractionExecute a named extraction pathextracted records with provenance and replay hash
detect_contradictionsCross-system contradiction detectiontyped contradictions with severity and evidence
validate_schemaPre-flight schema validationpath compatibility, missing fields, customizations
analyze_reality_gapsThree-way gap analysisdesign gaps, compliance gaps, shadow processes
manage_findingCreate/transition/query findingsfinding state, history, risk score
get_finding_summaryAggregated finding statisticscounts by state, source, severity, avg risk
generate_handoff_packetProduce reviewer handoff packetexecutive summary, findings, manifest, checklist

Governance Tools

ToolPurposeReturns
ps_precheckCheck if operation would be allowedwouldAllow, wouldHold, reason
ps_list_holdsList pending holdsArray of hold requests
ps_approve_holdApprove a held operationExecution result with auditId
ps_reject_holdReject a held operationSuccess boolean
ps_agent_statusGet agent circuit breaker stateisAllowed, state, haltReason
ps_halt_agentHalt an agent immediatelyhalted, agent_id
ps_resume_agentResume a halted agentresumed, agent_id
ps_statsGet governance statisticsholds, haltedAgents, auditEntries
ps_frame_docsGet PromptSpeak documentationFrame format reference

License

MIT License - See LICENSE

This is enterprise-friendly open source:

  • Use commercially without restriction
  • Modify and distribute freely
  • No copyleft obligations
  • No warranty (provided as-is)

Support

  • Documentation: docs/
  • Issues: GitHub Issues
  • Security: See SECURITY.md for vulnerability reporting

AI Authorship

This project was built with Claude Code (Anthropic). All commits are co-authored as reflected in git history. The architecture, design decisions, and analysis methodology are the author's; the implementation was pair-programmed with AI assistance.


Disclaimer

This tool is provided as-is for process analysis purposes. It does not modify SAP data. Users are responsible for:

  • Ensuring compliance with organizational data access policies
  • Validating findings before making business decisions
  • Proper configuration of SAP authorizations

Correlation does not imply causation. All pattern findings should be verified against actual business processes.

Ver o original no GitHub

Bom para

Relacionados