contextvm-sdk

Rust SDK for the ContextVM protocol — MCP over Nostr.

A complete implementation enabling Model Context Protocol (MCP) servers and clients to communicate over the Nostr network with decentralized discovery, cryptographic identity, and optional end-to-end encryption.

Architecture

┌──────────────────────────────────────────────────────────┐
│                    Your Application                       │
├──────────────┬───────────────┬────────────────────────────┤
│   Gateway    │     Proxy     │        Discovery           │
│  (server →   │  (nostr →     │  (find servers &           │
│    nostr)    │    client)    │   capabilities)            │
├──────────────┴───────────────┴────────────────────────────┤
│                    Transport Layer                         │
│            NostrServerTransport / NostrClientTransport     │
├───────────────────────────────────────────────────────────┤
│  Core          │  Encryption     │  Relay    │  Signer    │
│  (types,       │  (NIP-44,       │  (pool    │  (key      │
│   JSON-RPC,    │   NIP-59        │   mgmt)   │   mgmt)    │
│   validation)  │   gift wrap)    │           │            │
├────────────────┴─────────────────┴───────────┴────────────┤
│                   Nostr Network (relays)                   │
└───────────────────────────────────────────────────────────┘

Protocol

ContextVM maps MCP's JSON-RPC 2.0 messages onto Nostr events:

Messages are routed using Nostr p tags (recipient pubkey) and correlated with e tags (request event ID).

Installation

Add to your Cargo.toml:

[dependencies]
contextvm-sdk = { git = "https://github.com/ContextVM/rs-sdk" }

Or pin a published release from crates.io:

[dependencies]
contextvm-sdk = "0.2.1"

Quick Start

Gateway — Expose a Local MCP Server via Nostr

use contextvm_sdk::gateway::{NostrMCPGateway, GatewayConfig};
use contextvm_sdk::transport::server::NostrServerTransportConfig;
use contextvm_sdk::core::types::{ServerInfo, EncryptionMode};
use contextvm_sdk::signer;

#[tokio::main]
async fn main() -> contextvm_sdk::Result<()> {
    let keys = signer::generate();

    let config = GatewayConfig::new(
        NostrServerTransportConfig::default()
            .with_encryption_mode(EncryptionMode::Optional)
            .with_server_info(
                ServerInfo::default()
                    .with_name("My MCP Server")
                    .with_about("Tools via Nostr"),
            )
            .with_announced_server(true),
    );

    let mut gateway = NostrMCPGateway::new(keys, config).await?;
    let mut requests = gateway.start().await?;
    gateway.announce().await?;

    while let Some(req) = requests.recv().await {
        println!("Request: {:?}", req.message);
        // Process and respond:
        // gateway.send_response(&req.event_id, response).await?;
    }
    Ok(())
}

Proxy — Connect to a Remote MCP Server via Nostr

use contextvm_sdk::proxy::{NostrMCPProxy, ProxyConfig};
use contextvm_sdk::transport::client::NostrClientTransportConfig;
use contextvm_sdk::core::types::EncryptionMode;
use contextvm_sdk::signer;

#[tokio::main]
async fn main() -> contextvm_sdk::Result<()> {
    let keys = signer::generate();

    let config = ProxyConfig::new(
        NostrClientTransportConfig::default()
            .with_server_pubkey("abc123...server_hex_pubkey")
            .with_encryption_mode(EncryptionMode::Optional),
    );

    let mut proxy = NostrMCPProxy::new(keys, config).await?;
    let mut responses = proxy.start().await?;

    // Send an MCP request
    let request = contextvm_sdk::JsonRpcMessage::Request(contextvm_sdk::JsonRpcRequest {
        jsonrpc: "2.0".into(),
        id: serde_json::json!(1),
        method: "tools/list".into(),
        params: None,
    });
    proxy.send(&request).await?;

    // Receive response
    if let Some(msg) = responses.recv().await {
        println!("Response: {:?}", msg);
    }
    Ok(())
}

Discovery — Find MCP Servers on Nostr

use contextvm_sdk::{discovery, signer, RelayPool};

#[tokio::main]
async fn main() -> contextvm_sdk::Result<()> {
    let keys = signer::generate();
    let pool = RelayPool::new(keys).await?;
    let relays = vec!["wss://relay.damus.io".into()];
    pool.connect(&relays).await?;

    let servers = discovery::discover_servers(pool.client(), &relays).await?;
    for server in &servers {
        println!("Server: {} ({:?})", server.pubkey, server.server_info.name);

        let tools = discovery::discover_tools(pool.client(), &server.pubkey_parsed, &relays).await?;
        println!("  Tools: {}", tools.len());
    }
    Ok(())
}

Documentation

The in-repo Rust SDK guides live in docs/README.md:

• For most users, the main pattern is: build an rmcp server or client, then attach NostrServerTransport or NostrClientTransport.

• docs/overview.md

• docs/server-transport.md

• docs/client-transport.md

• docs/open-stream.md

• docs/discovery.md

• docs/encryption.md

• docs/transport-modes.md

• docs/stateless.md

• docs/oversized-transfer.md

• docs/rmcp.md

• docs/transports.md

• docs/gateway.md

• docs/proxy.md

Module Overview

Configuration

Encryption Modes

Encryption uses NIP-44 for payload encryption and NIP-59 (Gift Wrap) for metadata-private delivery. Server announcements (kinds 11316–11320) are always public.

Messages too large for a single relay event are fragmented into ordered frames and reassembled by the receiver (CEP-22 oversized transfer, enabled by default; it adds no event kind — frames ride inside notifications/progress messages). See docs/oversized-transfer.md for the timeout model and tuning.

Open-ended streaming (CEP-41) lets a server tool emit an ordered sequence of chunks back to the client while a request is in flight. The client consumes them as an async Stream via call_tool_stream. Unlike CEP-22, the stream supplements the final JSON-RPC response rather than replacing it. Disabled by default; opt in with with_open_stream(OpenStreamConfig::enabled()). See docs/open-stream.md for the writer and client APIs and the keepalive timer model.

Server Transport Config

Client Transport Config

When relay_urls is empty, start() runs automatic relay resolution: configured relays > nprofile hints > CEP-17 kind 10002 discovery > fallback probing > bootstrap defaults.

References

• ContextVM Specification
• ContextVM TypeScript SDK
• Model Context Protocol
• Nostr Protocol
• NIP-44 Encryption
• NIP-59 Gift Wrap

License

MIT