MCB — Minimal Context Base

Declarative contract architecture for AI agent systems.

MCB is an open standard and runtime for building systems as self-contained blocks with explicit contracts.

Any project — in any language — can adopt MCB by writing .mcb manifest files and using the mcb CLI/runtime to validate and orchestrate.

---

Why MCB

• Contracts first — every block declares input, output, and error before implementation
• Language agnostic — the manifest is YAML; the implementation is in impl/ (any language)
• AI-native — subagents are embedded in active blocks, scoped only to their manifest
• Local-first — works with local LLMs (MLX, Ollama, vLLM) via OpenAI-compatible APIs
• Composable — blocks connect through declared contracts, not hardcoded imports

---

Quick Start

1. Install

npm install @mcblang/mcb
# or
npx @mcblang/mcb validate ./my-system.mcb

2. Define a system

# my-system.mcb/manifest.mcb
system: my-system
version: 1.0.0
blocks:
  - auth
  - dashboard
flows:
  - main

# my-system.mcb/blocks/auth.mcb/manifest.mcb
block: auth
version: 1.0.0
layer: backend
input:
  name: credentials
  type:
    email: string
    password: string
does: validates user credentials
output:
  name: token
  type:
    access_token: string
    expires_in: number
error:
  name: auth_failure
  type:
    code: number
    message: string
depends: []

3. Validate

npx mcb validate ./my-system.mcb --write

4. Run a flow

export MCB_BACKEND_URL=http://localhost:8080   # MLX, Ollama, vLLM, OpenAI...
export MCB_BACKEND_MODEL=qwen3-1.7b
npx mcb run ./my-system.mcb main '{"email":"a@b.com","password":"123"}'

---

Architecture

┌─────────────────────────────────────┐
│  System (.mcb)                      │
│  ┌─────────┐  ┌─────────┐          │
│  │ Block A │──│ Block B │          │
│  │manifest │  │manifest │          │
│  │  impl/  │  │  impl/  │          │
│  └────┬────┘  └────┬────┘          │
│       │            │                │
│       └────┬───────┘                │
│            ▼                        │
│  ┌─────────────────────┐            │
│  │  MCB Runtime        │            │
│  │  - validate contracts│            │
│  │  - orchestrate flows │            │
│  │  - invoke subagents  │            │
│  └─────────────────────┘            │
└─────────────────────────────────────┘

---

Block Types

Type	Description	Subagent
Passive	Deterministic logic. Direct execution.	No
Active	Requires reasoning or decision.	Yes, scoped to block manifest

---

Backends Supported

Any OpenAI-compatible server:

• MLX — mlx_lm.server (local Apple Silicon)
• Ollama — local models
• vLLM — production inference
• LiteLLM — proxy gateway
• OpenAI / Anthropic / Groq — cloud APIs

# MLX example
mlx_lm.server --model mlx-community/Qwen3-1.7B-Instruct-4bit --port 8080

# Ollama example
ollama run qwen3:1.7b

# Then point MCB
export MCB_BACKEND_URL=http://localhost:8080
export MCB_BACKEND_MODEL=qwen3-1.7b

---

Specification

See spec/MCB-SPEC.md for the full open standard.

---

CLI Reference

mcb validate <dir> [--write]   Validate system, optionally write schema.mcb
mcb run <dir> <flow> [input]   Execute a flow with JSON input
mcb ping <url>                 Check LLM server health
mcb schema <dir>               Generate schema.mcb only
mcb help                       Show help

---

Programmatic API

import { MCBRuntime } from "@mcblang/mcb";

const runtime = new MCBRuntime({
  systemDir: "./my-system.mcb",
  backend: {
    baseUrl: "http://localhost:8080",
    apiKey: process.env.OPENAI_API_KEY, // optional
  },
});

const { blocks, flows, validation } = runtime.load();
if (!validation.valid) throw new Error("Invalid system");

const results = await runtime.executeFlow(flows[0], blocks, { name: "world" });

---

Example

See examples/hello-world.mcb/ for a minimal working system.

---

License

MIT — mcblang