@mxp-protocol/core
v0.1.1
Published
MXP (Mesh eXchange Protocol) - High-performance binary protocol for AI agent communication
Maintainers
ferasawadiReadme
MXP JavaScript/TypeScript SDK
High-performance binary protocol for AI agent communication
The JavaScript/TypeScript implementation of MXP Protocol
📐 Architecture Overview
┌─────────────────────────────────────────────────────────────────────────────┐
│ YOUR APPLICATION │
│ (AI Agent, Chatbot, Multi-Agent System) │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ A2A COMPATIBILITY LAYER │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Message │ │ Task │ │ AgentCard │ │ JSON-RPC │ │
│ │ + Part │ │ + Artifact │ │ + Skills │ │ Request/Response │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────────┘ │
│ @mxp-protocol/core/a2a │
└─────────────────────────────────────────────────────────────────────────────┘
│
toMxp() ◄──┴──► fromMxp()
│
┌─────────────────────────────────────────────────────────────────────────────┐
│ MXP PROTOCOL CORE │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 64-byte Header │ │
│ │ ┌────────┬────────┬───────┬──────────┬──────────┬────────────────┐ │ │
│ │ │Version │ Type │ Flags │ Trace ID │ Msg ID │ Checksum │ │ │
│ │ │ 1 byte │ 1 byte │1 byte │ 8 bytes │ 8 bytes │ 8 bytes │ │ │
│ │ └────────┴────────┴───────┴──────────┴──────────┴────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Variable-length Payload │ │
│ │ (Your data - any binary format) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ @mxp-protocol/core │
└─────────────────────────────────────────────────────────────────────────────┘
│
encode() ◄─┴─► decode()
│
┌─────────────────────────────────────────────────────────────────────────────┐
│ WEBRTC TRANSPORT │
│ ┌───────────────┐ ┌───────────────┐ ┌──────────────────────────────┐ │
│ │ Signaling │ │ Peer │ │ RTCDataChannel │ │
│ │ (WebSocket) │───►│ Connection │───►│ (Reliable / Unreliable) │ │
│ └───────────────┘ └───────────────┘ └──────────────────────────────┘ │
│ @mxp-protocol/core/transport │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ NETWORK (P2P) │
│ DTLS Encrypted • NAT Traversal • ICE │
└─────────────────────────────────────────────────────────────────────────────┘🔄 How It Works
Message Flow: A2A to Wire
sequenceDiagram
participant App as Your App
participant A2A as A2A Layer
participant MXP as MXP Core
participant Transport as WebRTC
participant Network as Network
App->>A2A: Message.userText("Hello")
A2A->>MXP: toMxp(message)
Note over MXP: Add trace ID<br/>Add message ID<br/>Compute checksum
MXP->>Transport: encode(mxpMessage)
Note over Transport: 64-byte header<br/>+ payload
Transport->>Network: RTCDataChannel.send()
Note over Network: DTLS encrypted<br/>P2P deliveryWebRTC Connection Flow
sequenceDiagram
participant A as Peer A
participant S as Signaling Server
participant B as Peer B
Note over A,B: 1. Exchange Offers via Signaling
A->>S: Offer (SDP)
S->>B: Offer (SDP)
B->>S: Answer (SDP)
S->>A: Answer (SDP)
Note over A,B: 2. Exchange ICE Candidates
A->>S: ICE Candidate
S->>B: ICE Candidate
B->>S: ICE Candidate
S->>A: ICE Candidate
Note over A,B: 3. Direct P2P Connection
A->>B: MXP Message
B->>A: MXP Message
Note over A,B: Direct P2P via RTCDataChannel<br/>No server in the middle!🏗️ Protocol Stack Comparison
MXP (This SDK) Traditional (JSON/HTTP)
┌─────────────────────┐ ┌─────────────────────┐
│ Application │ │ Application │
├─────────────────────┤ ├─────────────────────┤
│ A2A Semantics │◄──────────►│ A2A Semantics │
├─────────────────────┤ ├─────────────────────┤
│ MXP Binary │ │ JSON │
│ (37x faster) │ │ (2.2μs/msg) │
├─────────────────────┤ ├─────────────────────┤
│ WebRTC / UDP │ │ HTTP / TCP │
│ (P2P, low lat) │ │ (server required) │
├─────────────────────┤ ├─────────────────────┤
│ DTLS (built-in) │ │ TLS (separate) │
└─────────────────────┘ └─────────────────────┘
✅ 37x faster encoding ❌ Slow JSON parsing
✅ P2P (no server) ❌ Server required
✅ Built-in tracing ❌ External tracing
✅ Native streaming ❌ HTTP streaming hacks🌐 Multi-Agent Communication
┌─────────────┐
│ Agent A │
│ (Browser) │
└──────┬──────┘
│
┌─────────────┼─────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Agent B │ │ Agent C │ │ Agent D │
│ (Node) │ │ (Browser)│ │ (Rust) │
└──────────┘ └──────────┘ └──────────┘
┌─────────────────────────────────────────────────────┐
│ All connections are: │
│ • Direct P2P (no central server for data) │
│ • Encrypted (DTLS) │
│ • Binary (MXP format) │
│ • Traceable (built-in trace IDs) │
│ • Wire-compatible (JS ↔ Rust ↔ any MXP impl) │
└─────────────────────────────────────────────────────┘📦 Module Structure
@mxp-protocol/core
│
├── Core ─────────────────────────────────────────────────
│ ├── Message # MXP message class
│ ├── encode/decode # Binary codec
│ ├── MessageType # Call, Response, Stream*, etc.
│ └── generateTraceId # Distributed tracing
│
├── /a2a ─────────────────────────────────────────────────
│ ├── Message # A2A message with parts
│ ├── Task/Artifact # Long-running operations
│ ├── AgentCard # Discovery (/.well-known/)
│ ├── toMxp/fromMxp # Conversion layer
│ └── JsonRpc* # HTTP gateway support
│
└── /transport ───────────────────────────────────────────
├── WebRTCTransport # Multi-peer manager
├── Peer # Single connection
├── *Signaling # Connection setup
└── ConnectionState # Lifecycle trackingFeatures
- 🚀 High Performance - Binary encoding ~37x faster than JSON
- 🔌 A2A Compatible - Works with Google's Agent-to-Agent protocol
- 📊 Built-in Tracing - Every message has a trace ID
- 🌊 Streaming Support - Native LLM token streaming
- 📦 Zero Dependencies - Lightweight core library
- 🔒 Type Safe - Full TypeScript support
Installation
pnpm add @mxp-protocol/core
# or
npm install @mxp-protocol/core
# or
yarn add @mxp-protocol/coreQuick Start
Basic Usage
import { Message, MessageType, encode, decode } from '@mxp-protocol/core';
// Create a message
const msg = Message.call('Hello, agent!');
// Encode to binary
const { bytes } = encode(msg);
console.log(`Encoded: ${bytes.length} bytes`);
// Decode from binary
const decoded = decode(bytes);
console.log(`Trace ID: ${decoded.traceId}`);
console.log(`Payload: ${decoded.payloadAsString()}`);A2A Compatibility
import { Message, toMxp, fromMxp, AgentCard } from '@mxp-protocol/core/a2a';
// Create an A2A message
const msg = Message.userText('Search for Rust tutorials');
// Convert to MXP for high-performance transport
const mxpMsg = toMxp(msg);
// Send over network...
// const bytes = encode(mxpMsg);
// Receive and convert back to A2A
const { method, message } = fromMxp(mxpMsg);
console.log(`Method: ${method}`);
console.log(`Text: ${message?.textContent()}`);Agent Discovery
import { AgentCard, AgentSkill } from '@mxp-protocol/core/a2a';
// Create an agent card with MXP support
const card = AgentCard.withMxp(
'My Agent',
'An AI assistant',
'https://api.example.com/agent',
'mxp://api.example.com:9000'
)
.withStreaming()
.withSkill(
new AgentSkill('search', 'Web Search', 'Search the internet')
.withTags(['search', 'web'])
);
// Serve at /.well-known/agent-card.json
console.log(card.toJSON());Streaming
Perfect for LLM token-by-token output:
┌──────────┐ ┌──────────┐
│ Client │ │ LLM │
│ │ │ Agent │
└────┬─────┘ └────┬─────┘
│ │
│ StreamOpen (prompt: "Write a poem") │
│ ─────────────────────────────────────────────────► │
│ │
│ StreamChunk ("Roses ") │
│ ◄─────────────────────────────────────────────────│
│ StreamChunk ("are ") │
│ ◄─────────────────────────────────────────────────│
│ StreamChunk ("red,") │
│ ◄─────────────────────────────────────────────────│
│ ... │
│ StreamClose │
│ ◄─────────────────────────────────────────────────│
│ │import { Message, toMxpStreamOpen, toMxpStreamChunk, toMxpStreamClose } from '@mxp-protocol/core/a2a';
// Open stream
const openMsg = toMxpStreamOpen(Message.userText('Write a poem'));
const streamId = openMsg.messageId;
// Send chunks
for (const token of generateTokens()) {
const chunk = toMxpStreamChunk(token, streamId);
// send chunk...
}
// Close stream
const closeMsg = toMxpStreamClose(streamId);Task Workflow (A2A)
For long-running operations with status updates:
┌─────────────────────────────────────────────────────────────────────┐
│ TASK LIFECYCLE │
└─────────────────────────────────────────────────────────────────────┘
┌───────────┐ ┌───────────┐ ┌─────────────────┐ ┌───────────┐
│ SUBMITTED │────►│ WORKING │────►│ INPUT_REQUIRED │────►│ COMPLETED │
└───────────┘ └───────────┘ └─────────────────┘ └───────────┘
│ │ │ │
│ │ │ │
│ ▼ ▼ │
│ ┌───────────┐ User provides │
│ │ FAILED │ more input │
│ └───────────┘ │ │
│ │ │
▼ ▼ ▼
┌───────────┐ Back to WORKING ┌───────────┐
│ CANCELED │ │ Artifacts │
└───────────┘ └───────────┘
import { Task, TaskState, Artifact } from '@mxp-protocol/core/a2a';
// Create task
const task = new Task();
console.log(task.id); // UUID
// Update status
task.setStatus(TaskState.Working);
// Add output artifacts
task.addArtifact(Artifact.text('summary', 'Here are the results...'));
task.addArtifact(Artifact.data('metrics', { accuracy: 0.95 }));
// Complete
task.setStatus(TaskState.Completed);WebRTC Transport (Peer-to-Peer)
import { WebRTCTransport, WebSocketSignaling } from '@mxp-protocol/core/transport';
import { Message } from '@mxp-protocol/core';
// Connect to signaling server
const signaling = new WebSocketSignaling('ws://signal.example.com', 'my-peer-id');
await signaling.connect();
// Create transport
const transport = new WebRTCTransport(signaling, { debug: true });
// Handle incoming messages
transport.on('message', ({ message, peerId }) => {
console.log(`From ${peerId}: ${message.payloadAsString()}`);
});
// Connect to another peer
await transport.connect('other-peer-id');
// Send a message
transport.send('other-peer-id', Message.call('Hello!'));
// Broadcast to all peers
transport.broadcast(Message.call('Hello everyone!'));Signaling Options
// WebSocket signaling (cross-device)
const ws = new WebSocketSignaling('ws://server/signal', 'peer-id');
// BroadcastChannel (same-origin, different tabs)
const bc = new BroadcastChannelSignaling('my-channel', 'peer-id');
// In-memory (testing)
const hub = new InMemorySignalingHub();
const provider = hub.createProvider('peer-id');API Reference
Core Module (@mxp-protocol/core)
| Export | Description |
|--------|-------------|
| Message | Core message class |
| MessageType | Message type enum |
| MessageFlags | Message flags enum |
| encode(msg) | Encode message to binary |
| decode(bytes) | Decode message from binary |
| generateTraceId() | Generate random trace ID |
A2A Module (@mxp-protocol/core/a2a)
| Export | Description |
|--------|-------------|
| Message | A2A message with parts |
| Part | Message part (text/file/data) |
| Task | Long-running task |
| Artifact | Task output |
| AgentCard | Agent discovery card |
| AgentSkill | Agent capability |
| toMxp(msg) | Convert A2A → MXP |
| fromMxp(mxp) | Convert MXP → A2A |
| JsonRpcRequest | JSON-RPC request |
| JsonRpcResponse | JSON-RPC response |
Transport Module (@mxp-protocol/core/transport)
| Export | Description |
|--------|-------------|
| WebRTCTransport | Peer-to-peer transport |
| Peer | Single peer connection |
| WebSocketSignaling | WebSocket signaling |
| BroadcastChannelSignaling | Same-origin signaling |
| InMemorySignalingHub | Testing signaling |
| ConnectionState | Connection states |
| ChannelMode | Reliable/unreliable modes |
🔌 Integration Patterns
Pattern 1: Browser-to-Browser (P2P)
┌─────────────┐ WebRTC ┌─────────────┐
│ Browser │◄───────────────────────►│ Browser │
│ Agent A │ (Direct P2P) │ Agent B │
└─────────────┘ └─────────────┘
│ │
└──────────┐ ┌────────────────┘
▼ ▼
┌─────────────────────┐
│ Signaling Server │ (Only for connection setup)
│ (WebSocket) │
└─────────────────────┘Pattern 2: Browser-to-Server
┌─────────────┐ WebRTC/WS ┌─────────────┐
│ Browser │◄──────────────────────►│ Server │
│ Client │ │ (Node.js) │
└─────────────┘ └─────────────┘
│
▼
┌─────────────┐
│ LLM / API │
└─────────────┘Pattern 3: Multi-Agent Mesh
┌─────────────┐
│ Agent A │
└──────┬──────┘
│
┌────────────┼────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Agent B │─│ Agent C │─│ Agent D │
└──────────┘ └──────────┘ └──────────┘
│ │ │
└────────────┴────────────┘
Full Mesh P2PCompatibility
- Node.js: 18+
- Browsers: Modern browsers with
crypto.getRandomValues - Deno: Supported
- Bun: Supported
Wire Compatibility
This SDK produces binary messages that are wire-compatible with the Rust implementation. You can send messages from JavaScript to Rust and vice versa.
Performance
| Operation | MXP | JSON | Speedup | |-----------|-----|------|---------| | Encode 256B | ~60ns | ~2.2μs | 37x | | Decode 256B | ~40ns | ~1.8μs | 45x |
Benchmarks from Rust implementation. JS performance varies by runtime.
Related
- mxp-protocol - Rust implementation (canonical)
- MXP Spec - Protocol specification
- A2A Guide - A2A compatibility guide
License
Licensed under either of:
- MIT license (LICENSE-MIT)
- Apache License, Version 2.0 (LICENSE-APACHE)
at your option.