@0xhoneyjar/beacon-schema

@0xhoneyjar/beacon-schema

Sealed Effect Schema for the Freeside MCP federation beacon contract. Workspace package inside freeside-mcp-gateway/packages/beacon-schema/.

Cycle C v0.3 broadcast layer · base shape (schema_version: "2"). Cycle D extends the docs.* block additively (no breaking change · v0.2.0 bump).

Disambiguation

Two names look similar — they are not the same thing.

Read it as: construct-beacon HELPS YOU AUTHOR a beacon.yaml; @0xhoneyjar/beacon-schema VALIDATES that your beacon.yaml conforms to the federation contract.

Install

pnpm add -D @0xhoneyjar/beacon-schema
# requires effect ^3.10.0 as peerDep

Use · validate a beacon at runtime

import { BeaconV2Schema, decodeBeacon } from "@0xhoneyjar/beacon-schema";
import { Effect } from "effect";

const result = await Effect.runPromise(
  decodeBeacon(JSON.parse(rawBeaconJson))
);
// result is a typed BeaconV2 · throws on invalid input

Use · YAML→JSON adapter (build step)

npx build-beacon-json --in beacon.yaml --out app/.well-known/beacon.json

Wired into each construct's package.json:

{
  "scripts": {
    "build:beacon": "build-beacon-json --in beacon.yaml --out app/.well-known/beacon.json"
  }
}

Exit codes:

Use · JSON Schema export

import { BeaconV2JsonSchema } from "@0xhoneyjar/beacon-schema";
// canonical JSON Schema · publish at /.well-known/beacon-schema/v2.json

Schema shape (v2)

# beacon.yaml v2 · minimal
schema_version: "2"
mcp:
  shape: data | tool | proxy
  paths: [stdio, remote-http]
  remote: { transport: streamable-http, endpoint: ... }    # required if paths includes remote-http
  auth: { kind: none | api-key, header?, credentials_ref? }
  capabilities: [tools, resources, prompts, sampling, logging]
  tools: [...]
  pricing: { model: free | per-call | subscription | pay-per-call, description }
  publisher: <org>

Auth refine rules

credentials_ref.key convention

SCREAMING_SNAKE_CASE only (Railway env-var pattern · max 128 chars).

docs: block

Cycle C ships docs: Schema.optional(Schema.Unknown) — accepts any docs payload during the transition. Cycle D files an additive PR replacing Schema.Unknown with a concrete DocsBlockSchema (tagline + example_invocations + assets + changelog_url). See Cycle D coordination contract.

Develop

pnpm install        # from repo root · workspace setup
pnpm typecheck      # tsc --noEmit
pnpm build          # tsc -b → dist/
pnpm test           # tsx --test tests/*.test.ts (14 tests)

Versioning

License

MIT