bifrost (0.6.3)
Installation
pip install --index-url https://gitea.phasefinal.com/api/packages/vh/pypi/simple/ --extra-index-url https://pypi.org/simple bifrostAbout this package
MCP-in-reverse protocol for agent-platform ↔ consumer-tool integration.
Bifrost
Wire protocol + reference implementations for MCP-in-reverse: a way for consumer applications to expose tools to LLM agents running inside Worldtree-style agent platforms.
In Norse mythology, Bifrost is the rainbow bridge connecting Asgard (the realm of the gods) to Midgard (the realm of mortals). Heimdall is its watchman. Both names map to existing Worldtree subsystems — Heimdall is the codebase's auth/access-control layer — so the mythology mirrors the architecture: Bifrost-routes-through-Heimdall is the natural shape.
What problem it solves
Today's LLM-agent platforms let agents call tools, but the tools live on the platform side. A platform that wants to support consumer-side tools (where the consumer owns the auth, the state, the business logic) has to either (a) absorb the tools into the platform (mission creep — the platform becomes a junkdrawer of consumer features) or (b) ship a separate sidecar protocol the platform has to maintain.
Bifrost is option (c): the consumer runs an MCP server (or an MCP-compatible endpoint), the platform connects to it on behalf of its agents, the agent invokes consumer tools through the standard MCP wire format. The platform never executes consumer code; the consumer never absorbs platform-specific tooling. The bridge is the trust boundary.
What lives here
| Path | Contents |
|---|---|
docs/bifrost-spec-v1.md |
Canonical protocol doc, frozen at each major version. |
docs/handshake.md |
Capability negotiation deep-dive. |
docs/error-vocabulary.md |
Three-layer error taxonomy: Bifrost-level vs MCP-level vs consumer-tool errors. |
docs/lifecycle.md |
Session bind → MCP connect → tools → unbind. |
schemas/v1/ |
JSON Schema files, one per message type. Validated in CI. |
reference_server/ |
Small Python module consumers vendor or fork as their starting MCP server. |
conformance/ |
Test suite both sides run. server_conformance.py tests a consumer's MCP server; client_conformance.py tests a platform's MCP client. |
clients/ |
Canonical client libraries for non-Worldtree consumers. Deferred to v0.2. |
What does NOT live here
- Worldtree's MCP-client integration code — that's a Worldtree concern; lives in
core/transports/bifrost_client.pyinside Worldtree. - Heimdall integration on the Worldtree side.
- Worldtree's session-binding plumbing for Bifrost endpoints — Conversation API surface, lives in Worldtree.
- Consumer-specific tool implementations — each consumer's own repo.
Status
Pre-1.0. Architectural calls locked in via Worldtree issue
#160's
frame-pass comment (2026-05-09). Sub-questions pending /vor 160.
Reference server, schemas, and conformance suite to be authored
after that resolves.
Tracking issue (cross-repo): Worldtree #160.
Versioning
Three independent semver tracks once 1.0 ships:
- Bifrost protocol (this repo) — spec doc is the source of truth; schemas + reference server + conformance suite carry the same major version.
- Worldtree — declares which Bifrost protocol version range it
supports in its release notes (
Bifrost: ^1.0). - Consumer applications — each consumer's own semver; they declare the Bifrost protocol version they implement.
Pre-1.0: breaking changes allowed. Post-1.0: strict semver with deprecation windows. Once any non-Worldtree-team consumer ships against 1.0.0, breaking changes require 2.0.0 + a deprecation period.
Why a separate repo
Bifrost is consumed by multiple independent applications (SEA, Skaldsong, Vor, Althing, Saga RPG, plus future siblings), none of which should pull all of Worldtree to use the protocol. Separating the repo at bootstrap is cheaper than extracting it later — different commit cadences, different release cycles, different audit boundaries, different consumer access models all converge cleanly when the boundary is real from the start, and degrade messily when it's bolted on later.
Sibling Corviduo projects (reference)
- Worldtree — multi-agent framework; first Bifrost consumer (MCP-client side)
- Skaldsong — story-generation engine; Bifrost consumer (YAML-validation tools)
- Vast Blue SEA — multi-agent web app; Bifrost consumer (enterprise orchestration tools)
- Vor — pre-contract design partner; Bifrost consumer (frame-clarification tools in v2)
- Sleipnir — AFK orchestrator
- althing — agent-to-agent message bus; Bifrost consumer (UI-state tools)
- Galdrabok — Sleipnir-preflight skill author
- task-board — per-session web UI
- corviduo-project-template — canonical scaffold this repo seeded from