CQRS separates write (commands) and read (events) — but there is no common way to discover what commands a service accepts, what events it produces, or how to interact with it, without reading bespoke documentation or source code.
BEST is a specification for service interoperability: how domain services expose their command ingestion surface and published events, and how callers — AI agents, Process Managers, UIs, other services — discover and interact with them, across any runtime, platform, language, or transport. BEST doesn't care how a service works internally; it only defines the interaction surface: what commands go in, what events come out, and how to discover the service.
SPEC.md is the consolidated specification — the whole protocol in one document: design, discovery, commands, events, queries, transports, conformance, and security. Start there.
The same content is browsable per-topic at behavioralstate.io, rendered from the pages under specs/.
Upgrading an implementation from 0.8.x? See MIGRATION.md — 0.9.0 renamed the protocol short name (BSP → BEST) and made the envelope a conformant CloudEvents 1.0 profile.
For what's done, in flight, and planned — including the IANA/RFC standards track — see ROADMAP.md.
The most recent stable release is v0.9.0. To read the spec exactly as released, browse the repo at tag v0.9.0; the
mainbranch is the work in progress.
The machine-readable protocol definitions live under protocol/v1/ and are the source of truth:
| Path | Contents |
|---|---|
protocol/v1/schemas/ |
JSON Schema files for all capabilities |
protocol/v1/services/ |
OpenAPI specs for the HTTP transport |
protocol/v1/examples/ |
Example manifests and payloads |
# Validate protocol schemas
node scripts/validate-schemas.mjs
# Validate example payloads
node scripts/validate-examples.mjs
# Run the website locally
cd website && npm install && npm run devbest-mcp is the reference MCP server for BEST. Point it at any BEST-compliant endpoint and any MCP-capable LLM client (Claude Desktop, VS Code Copilot, Cursor, ChatGPT Desktop) can discover and interact with it immediately.
npx @behavioralstate/best-mcpstdio config (VS Code Copilot, Cursor, Claude Desktop):
{
"mcpServers": {
"my-service": {
"command": "npx",
"args": ["@behavioralstate/best-mcp"],
"env": {
"BEST_MYAPP_BASE_URL": "https://api.example.com/best",
"BEST_MYAPP_API_KEY": "<your-api-key>"
}
}
}
}Per-app BEST_<APP>_* variables are the recommended configuration mode (default auth: X-Api-Key header). Multi-tenant endpoints, multiple connections, bearer/query-param auth, HTTP transport for ChatGPT Desktop, and per-request credential overrides are all covered in the mcp-server README. Production deployments should pin an exact version (e.g. @behavioralstate/best-mcp@2.0.0).
best-validate runs the spec's conformance checklist against any live endpoint: it fetches the discovery manifest and validates it against the published JSON Schemas, checks the capability declaration rules, probes every required endpoint of each active capability, and verifies the error format and auth enforcement. All probes are non-destructive — the only POST sent is a command with an intentionally unknown type, which a conformant endpoint rejects before queuing.
# Public endpoint
npx @behavioralstate/best-validate https://api.example.com
# Authenticated endpoint (X-Api-Key by default; see --auth-type/--auth-header)
npx @behavioralstate/best-validate https://api.example.com --api-key <key>
# Multi-tenant host — expands tenants.manifest and validates the tenant manifest too
npx @behavioralstate/best-validate https://api.example.com --api-key <key> --tenant <tenantId>
# Pre-0.9.0 endpoint (BSP naming, relative dataschema tolerated as warnings)
npx @behavioralstate/best-validate https://api.example.com --legacy-bsp
# CI usage — machine-readable report, exit code as the verdict
npx @behavioralstate/best-validate https://api.example.com --jsonThe report lists each check as OK/WARN/FAIL grouped by section (discovery, multi-tenancy, commands, events, queries) and ends with a verdict. Exit code 0 = conformant (warnings allowed), 1 = at least one failure, 2 = internal error. Without --api-key, protected routes are still checked for existence — a 401 counts as "route exists, auth enforced".
Full option reference: validate-cli/README.md. The --legacy-bsp flag is temporary and will be removed once known pre-0.9.0 deployments have migrated (see MIGRATION.md).
This repo has two independent versioned artifacts. Running one release does not release the other. Always use the scripts — never tag manually.
| Artifact | Tag prefix | Command | Outcome |
|---|---|---|---|
@behavioralstate/best-mcp npm package |
mcp/v* |
./scripts/release-mcp.sh [x.y.z] |
CI publishes to npm |
@behavioralstate/best-validate npm package |
validate/v* |
./scripts/release-validate.sh [x.y.z] |
CI publishes to npm |
| BEST protocol spec + website | spec/v* |
./scripts/release.sh x.y.z [--prerelease] |
CI builds the site image → GHCR → IaC deploy PR |
release-mcp.sh with no argument auto-bumps the patch version. release.sh requires a clean main checkout, bumps version.json (the single source of truth for {{BEST_VERSION}} placeholders), updates this README's release references, tags, and creates the GitHub Release. When releasing both in one session, release best-mcp first.
- Website & Documentation
- GitHub Issues — bug reports & feature requests
- Contributing — how to contribute