MXP Nexus Core

Shared business logic library for the MXP Nexus platform.

Overview

This library provides common functionality used by both the CLI tool (mxpnexus-cli) and HTTP API server (mxpnexus-api):

• Agent lifecycle — scaffolding, Docker bundling, Kind deployments
• Registry client — zero-copy MXP discovery with automatic retry
• Stack management — local registry/redis/kind orchestration
• Shared models — strongly typed data contracts reused across services

Usage

Add to your Cargo.toml:

[dependencies]
mxpnexus-core = "0.1.1"

use mxpnexus_core::{agent, registry, RegistryClient};
use mxpnexus_core::models::{AgentGenerateOptions, AgentBundleOptions, AgentDeployOptions};
use tokio::runtime::Runtime;

fn main() -> mxpnexus_core::Result<()> {
    let rt = Runtime::new()?;
    rt.block_on(async move {
        // Registry queries
        let agents = registry::list_agents(None).await?;
        println!("Found {} agents", agents.len());

        // Agent scaffolding
        let project_dir = agent::generate(&AgentGenerateOptions { name: "demo-agent".into() }).await?;
        println!("Generated project at {project_dir}");

        // Bundle + deploy
        agent::bundle(&AgentBundleOptions::default()).await?;
        agent::deploy(&AgentDeployOptions::default()).await?;

        Ok(())
    })
}

Example

use mxpnexus_core::{registry, RegistryClient};

#[tokio::main]
async fn main() -> mxpnexus_core::Result<()> {
    // Use the global convenience API (reads MXPNEXUS_REGISTRY_ADDR)
    let online = registry::list_agents(Some("agent.*")).await?;
    println!("{} agents are online", online.len());

    // Or manage your own client with a custom timeout
    let client = RegistryClient::new("127.0.0.1:9000", Some(std::time::Duration::from_secs(2)))?;
    let agent = client.get_agent("demo-agent")?;
    println!("agent '{}' is {}", agent.name, agent.status as u8);

    Ok(())
}

Modules

• agent - Agent lifecycle operations (generate, bundle, deploy, status, logs, delete)
• agent::kind - Kind-specific helpers (image loading, kubectl invocations, deployment records)
• registry - Async-friendly MXP discovery client + RegistryClient
• stack - Stack management operations (start/status/stop local Kind + registry + Redis)
• models - Shared models used across CLI/API/core
• error - Unified error type + helper constructors

Configuration

The registry helpers honour the following environment variables:

Agent generation/deployment inherits the standard MXP agent variables (MXP_AGENT_NAME, MXP_AGENT_CAPABILITIES, etc.) and persists deployment metadata under ~/.mxp/deployments/kind/.

Stack orchestration example

use mxpnexus_core::{stack, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let status = stack::start(None, None, None, true).await?;
    println!(
        "Registry {}, Redis {}",
        status.registry.address, status.redis.address
    );

    // ... run integration tests ...

    stack::stop().await
}

Release workflow

1. Format + lint + test (cargo fmt, cargo clippy -p mxpnexus-core --all-targets -- -D warnings, cargo test -p mxpnexus-core).
2. Bump version in Cargo.toml.
3. Tag the release (git tag v0.x.y && git push origin --tags).
4. Publish via the GitHub Actions workflow (requires CARGO_REGISTRY_TOKEN secret) or run cargo publish locally.

Development

cargo build
cargo test
cargo clippy --all -- -D warnings

License

Dual-licensed under MIT OR Apache-2.0.