Unified API Adapter MCP server

// SPDX-License-Identifier: CC-BY-SA-4.0 // Copyright (c) Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk // SPDX-FileCopyrightText: 2024-2026 Jonathan D.A. Jewell (hyperpolymath) = Unified API Adapter :toc: :toc-placement: preamble

// ── Licensing ─────────────────────────────────────────────────────────────── image:https://img.shields.io/badge/Code-MPL--2.0-blue.svg?logo=mozilla[Code licence: MPL-2.0,link="https://opensource.org/licenses/MPL-2.0"] image:https://img.shields.io/badge/Docs-CC--BY--SA--4.0-blue.svg?logo=creativecommons[Docs licence: CC-BY-SA-4.0,link="https://creativecommons.org/licenses/by-sa/4.0/"] image:https://img.shields.io/badge/Provenance-Quantum--Safe-blueviolet[Quantum-Safe Provenance,link="docs/legal/EXHIBIT-B-QUANTUM-SAFE.txt"]

// ── Standard & quality gates ──────────────────────────────────────────────── image:https://img.shields.io/badge/RSR-Rhodium_Standard-9C27B0[Rhodium Standard Repository,link="https://github.com/hyperpolymath/rhodium-standard-repositories"] image:https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/hyperpolymath/unified-api-adapter/governance-badges/badges/k9.json[K9 conformance,link="https://github.com/hyperpolymath/unified-api-adapter/actions/workflows/dogfood-gate.yml"] image:https://api.scorecard.dev/projects/github.com/hyperpolymath/unified-api-adapter/badge[OpenSSF Scorecard,link="https://scorecard.dev/viewer/?uri=github.com/hyperpolymath/unified-api-adapter"] image:https://sonarcloud.io/api/project_badges/measure?project=hyperpolymath_unified-api-adapter&metric=alert_status[SonarQube Quality Gate,link="https://sonarcloud.io/summary/new_code?id=hyperpolymath_unified-api-adapter"] image:https://archive.softwareheritage.org/badge/origin/https://github.com/hyperpolymath/unified-api-adapter/[Archived in Software Heritage,link="https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/hyperpolymath/unified-api-adapter"]

// ── Provenance & ecosystem ────────────────────────────────────────────────── image:https://img.shields.io/badge/Idris-Inside-5E5086?logo=idris&logoColor=white[Idris Inside,link="https://github.com/hyperpolymath/proven"] image:https://img.shields.io/badge/Zig-Zero--overhead-F7A41D?logo=zig&logoColor=black[Zig Zero-overhead FFI,link="https://github.com/hyperpolymath/typed-wasm"] image:https://api.thegreenwebfoundation.org/greencheckimage/github.com[Green Web,link="https://www.thegreenwebfoundation.org/green-web-check/?url=github.com"]

One C ABI for every estate service protocol. A caller links this library and picks a transport by protocol tag, instead of each service re-rolling its own HTTP or MCP client.

[IMPORTANT]

Status: minted, no adapter code yet. This repository was initialised from rsr-template-repo on 2026-11-05. The adapter itself lands in the pull requests that follow, in the order given under <>. Nothing below is a claim that the code exists until those land.

== What this is

Two things already exist in the estate and are joined here:

• the protocol taxonomy from boj-server (Boj.Protocol): nine wire protocols (MCP, LSP, DAP, BSP, NeSy, Agentic, Fleet, gRPC, REST) with an Idris2-proven tag encoding (mirrored in Zig and seam-tested in boj-server; here the Idris2 side exists and the Zig side is still to come);
• the HTTP connector pool from developer-ecosystem/zig-api (connector.zig, uapi_connector_*), the only one of those protocols with a working client today.

In boj-server the taxonomy is a column of the cartridge catalogue: it records which protocols a cartridge exposes, and nothing routes a call by it. This adapter makes it a dispatch table.

The design rule: every protocol the ABI names either works or refuses. A call on a protocol with no transport returns UAPI_ERR_UNSUPPORTED. It is never silently accepted.

[[plan]] == Layers and plan

[cols="1,2,1"] |=== | Layer | Content | Source

| Idris2 ABI (src/interface/Abi/) | Protocol tag set and round-trip proofs; open endpoint registry; proof that dispatch is total and an unimplemented protocol maps to UAPI_ERR_UNSUPPORTED | boj-server Boj.Protocol, zig-api ZigApi.ABI.Connector

| Zig runtime (src/interface/ffi/) | Transport table indexed by protocol tag. REST: the zig-api connector, moved, not rewritten. MCP: a new JSON-RPC client over HTTP and stdio. The other seven protocols are declared and refuse. | zig-api connector.zig, core.zig; MCP is new

| C header (src/interface/generated/abi/) | Generated from the Idris2 ABI; never edited by hand | — |===

Once the adapter is published, developer-ecosystem/zig-api and boj-server take it as a pinned dependency instead of carrying their own copies, and UNIFIED-ZIG-API-STACK.adoc points here. Its first new consumer is svalinn (the stapeln edge gateway), which reaches vordr over MCP through it.

Proof obligations follow the estate proof policy (standards/3-practice/PROOF-POLICY.adoc): Idris2 for the ABI, Kani for the unsafe and FFI seams of Rust callers.

Proofs: 10 proven of 15; 4 open, 1 argued, all named in link:docs/EXPLAINME.adoc#proof-ledger[the proof ledger]. Proven means proven for the Idris2 model; the Zig runtime and the C boundary are open rows, and agreement with boj-server's taxonomy is argued.

== Where to go next

• link:docs/architecture/REPOSITORY-MAP.adoc[The repository map]: generated; what every directory is for.
• link:docs/status/ROADMAP.adoc[ROADMAP]: milestones and next actions.
• unified-api-adapter_chora.deed: the repo deed. It says what this repository is and is not, and where it sits in the estate.

== Licence

Code, configuration and scripts are link:LICENSE[Mozilla Public License 2.0] (MPL-2.0); prose documentation is CC-BY-SA-4.0. Both texts live in LICENSES/, and per-file SPDX-License-Identifier headers are authoritative. The GitHub-detected licence is MPL-2.0 (the root LICENSE). Long-term attribution uses Quantum-Safe Provenance — see link:docs/legal/EXHIBIT-B-QUANTUM-SAFE.txt[the Quantum-Safe Provenance exhibit].