Skip to main content
Glama

Checkpoint: mcp-workflow-adapter

License Python 3.11+

Production-grade, domain-neutral Model Context Protocol (MCP) workflow durability and orchestration library.

Core Systems Thesis: Remembering a conversation is not the same as knowing the authoritative state of a business process.

Conversational interfaces excel at natural language understanding and clarification. However, multi-step professional procedures require authoritative backend execution state: knowing which checklist steps actually committed before a network drop, which numeric readings passed server-side bounds validation, whether a retried tool call already executed, whether another operator is using the physical instrument, and what domain escalation policies govern out-of-range exceptions.

mcp-workflow-adapter provides a pure hexagonal core that decouples conversational agents from stateful business process durability.


Key Capabilities

  • Domain-Neutral Hexagonal Ports: Zero domain strings or hardcoded schemas in core contracts (DomainPolicyPort, StorageBackendPort, OrchestratorPort, NotificationPort).

  • Zero AWS SDK Leakage in Core: Core modules (models.py, errors.py, ports.py, state_machine.py, idempotency.py, redaction.py, auth.py, well_known.py, mcp_server.py, backends/local.py) contain zero boto3 or botocore imports. AWS dependencies are strictly confined to optional backends/aws_*.py plugins.

  • 4-State Business State Machine: Strictly limited to CREATED, RUNNING, BLOCKED, and COMPLETED. Transient database, network, or orchestration failures never mark a business workflow failed—they preserve committed state and raise retryable BACKEND_UNAVAILABLE errors.

  • Atomic Idempotency & Replay Envelopes: Canonical JSON SHA-256 payload hashing with atomic ledger commits. Replays return stored results with duplicate: True; payload mismatches trigger IDEMPOTENCY_CONFLICT.

  • Multi-Session Disambiguation & Active Asset Locks: Start mutations atomically acquire physical asset locks (ASSET#<asset_id>). Ambiguous status queries across multiple active workflows prompt structured voice disambiguation instead of guessing.

  • Transactional Notification Engine: Writes notifications atomically to an outbox within the same transaction as state mutations, dispataching via sinks without blocking workflow commits.

  • Streamable HTTP Transport & Headerless 401: Streamable HTTP ASGI server (POST /mcp) implementing the Alexa+ headerless 401 authentication contract with RFC 9728 protected resource discovery.

  • Local & Cloud Storage Backends:

    • LocalBackend: File-backed SQLite in WAL mode (PRAGMA journal_mode=WAL, BEGIN IMMEDIATE transactions).

    • AWSBackend: Single-table DynamoDB (TransactWriteItems) + Fenced AWS Step Functions Reconciler (R1–R8).


Related MCP server: nano-vm-mcp

5-Minute Quick Start (Local Offline Mode)

# 1. Install in editable development mode
pip install -e ".[dev]"

# 2. Run the offline test suite
pytest tests/unit tests/contract

# 3. Execute the secondary domain example (Industrial Pump Inspection)
python examples/industrial_pump_inspection.py

Core Architecture

               +----------------------------------------+
               |  Conversational Client (Alexa+ / LLM)  |
               +----------------------------------------+
                                   |
                         HTTP POST /mcp (Streamable)
                                   v
               +----------------------------------------+
               |       Streamable HTTP MCP Server       |
               | (auth.py, well_known.py, mcp_server.py)|
               +----------------------------------------+
                                   |
                                   v
             +---------------------------------------------+
             |         Hexagonal Ports & Contracts         |
             |       (DomainPolicyPort, StoragePort)       |
             +---------------------------------------------+
               /                                         \
              v                                           v
+-------------------------------+       +------------------------------------+
|         LocalBackend          |       |             AWSBackend             |
|   (SQLite WAL + Local Sink)   |       | (DynamoDB TransactWriteItems + SFN)|
+-------------------------------+       +------------------------------------+

License

This project is licensed under the Apache License, Version 2.0. See LICENSE for details.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers