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 delivery

Loading

WebRTC 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!

Loading

---

🏗️ 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 tracking

---

Features

• 🚀 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/core

Quick 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 P2P

---

Compatibility

• 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.