MFP — Python Implementation

Production-ready Python implementation of the Mirror Frame Protocol

This is the reference Python implementation of MFP, a protocol for secure, peer-to-peer communication between autonomous agents. It provides end-to-end encrypted channels, federated message transport, and a minimal API for agent lifecycle management.

Protocol Specification: For the complete MFP protocol design and specification, see mfp-spec

Features

• Symmetric design — no client/server distinction, all agents are peers
• End-to-end encryption — AES-256-GCM AEAD with HMAC-SHA-256 key derivation
• Federation-ready — bilateral channels, recovery protocols, TCP transport
• Production hardening — circuit breakers, timeouts, health checks, metrics
• High performance — Merkle tree for O(log N) global state updates
• Library-first — runtime embeds in any Python process
• Standalone server — YAML-configured process for managing agents
• Type-safe — full type annotations with py.typed marker

Installation

pip install pymfp

Or install from source:

git clone https://github.com/Madahub-dev/MFP.git
cd MFP
pip install -e .

Quickstart

5-minute hello world between two agents:

from mfp import Runtime, RuntimeConfig, bind, mfp_send, mfp_channels

# Create a runtime
config = RuntimeConfig()
runtime = Runtime(config)

# Define two simple agent callables
# Each receives a DeliveredMessage and returns None
def alice(msg):
    print(f"Alice received: {msg.payload.decode()}")

def bob(msg):
    print(f"Bob received: {msg.payload.decode()}")

# Bind agents to the runtime
alice_handle = bind(runtime, alice)
bob_handle = bind(runtime, bob)

# Establish a channel between them (Layer 2 / admin operation)
channel_id = runtime.establish_channel(alice_handle.agent_id, bob_handle.agent_id)

# Send a message from Alice to Bob
receipt = mfp_send(
    alice_handle,
    channel_id=channel_id,
    payload=b"Hello from Alice!",
)

print(f"Message sent, receipt step: {receipt.step}")

# Shutdown
runtime.shutdown()

Run this script to see agents communicate through MFP channels.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Application                          │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Public API: Runtime, bind/unbind, mfp_send/channels/status │
└─────────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
   ┌─────────┐         ┌─────────┐        ┌──────────┐
   │ Runtime │◄────────┤  Agent  │◄───────┤ Storage  │
   │ Pipeline│         │Lifecycle│        │  Engine  │
   └─────────┘         └─────────┘        └──────────┘
        │                                       │
        ▼                                       ▼
   ┌─────────┐                            ┌──────────┐
   │  Core:  │                            │Federation│
   │ Crypto, │                            │Transport │
   │ Frames  │                            └──────────┘
   └─────────┘

Layers:

• Core — cryptographic primitives, frame construction/validation
• Runtime — agent callable pipeline, hooks, error handling
• Agent — lifecycle management (bind/unbind), tool interface
• Storage — persistent state, message queues, channel records
• Federation — bilateral channels, recovery, wire protocol, TCP server

Documentation

Python Implementation:

• Quickstart Guide — step-by-step tutorial
• Production Guide — deployment and operations
• API Reference — library interface documentation
• Server Guide — standalone server configuration
• Architecture — implementation design deep-dive
• Security Model — threat model and guarantees
• Contributing — development setup and guidelines

Protocol Specification:

• MFP Spec Repository — complete protocol design and specification

CLI Usage

Launch the standalone server:

mfp-server --config runtime.yaml

Or using Python module syntax:

python -m mfp --config runtime.yaml

Development

Set up development environment:

# Clone and install with dev dependencies
git clone https://github.com/Madahub-dev/MFP.git
cd MFP
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=mfp --cov-report=term-missing

Project Status

Version: 1.0.0 (Stable)

All 7 implementation phases complete. Full single-runtime pipeline, persistence (SQLite), federation (TCP bilateral channels), async support, per-channel message ordering, audit events with redaction, and sliding window rate limiting. See IMPLEMENTATION.md for the full changelog.

Test Coverage: 813 tests passing (591 unit, 191 integration, 27 E2E, 4 benchmark)

License

Apache License 2.0 — see LICENSE for details.

Related Repositories

• mfp-spec — MFP protocol specification and design documentation

Credits

MFP Python Implementation — authored by Akil Abderrahim and Claude Sonnet 4.5