Architecture - UnitBuilds-CC/V.E.L.O.C.I.T.Y.-MCP GitHub Wiki

Architecture

Overview

V.E.L.O.C.I.T.Y. is a single Rust binary crate with a proc-macro sub-crate. All core operations run natively in Rust — no external process delegation required.

┌─────────────────────────────────────────────────────────┐
│                    Client Layer                          │
│  MCP Clients    Web/SDKs      Host Process    Plugins    │
│  (stdio)        (HTTP/WS)    (shmem)         (dynamic)  │
└──────┬──────────────┬─────────────┬─────────────┬───────┘
       │              │             │             │
┌──────▼──────────────▼─────────────▼─────────────▼───────┐
│                  Protocol Layer                          │
│  JSON-RPC      HTTP/SSE/WS     NMCP Binary    NDA-Native │
│  (stdio)       (Axum)          (shmem)        (shmem)    │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│                    Core Layer                            │
│  Tool Registry    Sandbox       NDA Ops      Plugins     │
│  (8 built-in)     (+ seccomp)   (compile/    (marketplace│
│                                  read/exec)   loading)   │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│                 Infrastructure                           │
│  Audit Log    Rate Limiter    Config    Observability     │
│  (10K ring)   (token bucket)  (TOML)   (OpenTelemetry)  │
│                                              │           │
│                              Prometheus Metrics          │
└──────────────────────────────────────────────────────────┘

Module Overview

Module	Purpose
`src/main.rs`	CLI entry point, config loading, mode dispatch
`src/lib.rs`	Library root with module declarations
`src/protocol/`	Protocol handlers (json_rpc, nmcp_binary, nda_native)
`src/transport/http.rs`	HTTP/SSE/WebSocket via Axum
`src/ipc/shmem.rs`	Memory-mapped shared memory buffer
`src/registry.rs`	Tool registration and dispatch
`src/sandbox.rs`	Capability-based sandbox
`src/sandbox/linux_seccomp.rs`	Linux seccomp-bpf syscall filters
`src/nda_converter.rs`	NDA binary document compiler
`src/nda_document.rs`	NDA parser with Merkle/Ed25519 verification
`src/nda_executor.rs`	NDA payload executor in sandbox
`src/plugins/`	Plugin system + marketplace
`src/observability/`	OpenTelemetry integration
`src/config.rs`	TOML configuration management
`src/audit.rs`	Global audit log (10K ring buffer)
`src/rate_limit.rs`	Token bucket rate limiter
`src/middleware.rs`	HTTP middleware (auth, CORS, logging)
`src/resources.rs`	MCP Resources & Prompts
`src/sampling.rs`	MCP Sampling protocol
`src/streaming.rs`	Streaming responses with progress
`src/oauth2.rs`	OAuth2 connector framework
`macros/`	Proc-macro crate for `#[mcp_tool]`
`client/`	Client SDKs (Rust, Python, TypeScript, Go)

Key Design Decisions

Single binary — No external runtime dependencies. Self-contained executable.
All native Rust — NDA operations, tool execution, protocol handling all in Rust.
Four transport modes — Each optimized for different use cases.
Capability sandbox — All execution goes through OS-enforced sandbox.
Feature flags — Optional functionality (HTTP, OAuth2, database, observability) gated behind Cargo features.

Repository Structure

V.E.L.O.C.I.T.Y.-MCP/
├── src/              # Server source code
├── macros/           # Proc-macro sub-crate
├── client/           # Client SDKs (4 languages)
├── docs/             # Documentation (USER_GUIDE, API, etc.)
├── tests/            # Integration + fuzz test suites
├── benches/          # Criterion benchmarks
├── monitoring/       # Prometheus/Grafana configs
├── deploy/           # Docker + Kubernetes manifests
├── Cargo.toml        # Dependencies and features
└── README.md         # Project overview