
trustbeacon
io.github.CloudCorpRecords/trustbeacon
Behavioral trust scores, attestation checks and preflight verdicts for MCP servers.
Documentation
trustbeacon
Before your agent trusts an unfamiliar MCP server, check the beacon. trustbeacon is a local forwarding client for the hosted Dominion Observatory service: it answers tools/list on your own machine from the captured tool definitions and forwards every call to the Observatory, returning the results exactly as the service sends them back.
The built surface covers trust scores and reliability metrics for MCP servers, ClawHub skill supply-chain checks, signed pre-invocation verification and attestation checks, preflight due-diligence verdicts with signed receipts, interaction reporting, leaderboards and behavioral baselines, anomaly checks, server registration and history, Observatory-wide statistics, and compliance-report export. Nothing is scored, stored or computed locally — the package is a pipe, not an observatory.
This is a labelled subset rebuild: the upstream capture enumerates fourteen tools, and thirteen are built here. The remaining tool, paid_trust_verdict, is an explicit x402 pay-then-call service where payment is the sole mode of operation, so it is omitted — not registered, not served in tools/list, and not available on the CLI.
The tools
check_trust— Trust score and reliability metrics for any MCP server (server_urlrequired): trust score, latency, uptime, success rate and usage counts.clawhub_skill_trust— Supply-chain trust for a ClawHub (OpenClaw) skill (skillrequired), returned as a PASS/UNCERTAIN/FAIL badge with a 0–100 score.verify_before_call— Signed pre-invocation verification before sending money, credentials, private data or write access to a server (server_urlrequired). Its captured schema is served verbatim, including the optionalpayment_txproperty; this client never originates a payment itself.verify_attestation— Cryptographic verification of a Dominion signed attestation (JWS) (jwsrequired), checked statelessly against the published public key.preflight_check— Pre-flight due-diligence verdict on a server or ClawHub skill (targetrequired), with a signed, timestamped diligence receipt.report_interaction— Report the outcome of calling an MCP server (server_urlandsuccessrequired) to contribute to the trust network.get_leaderboard— Top-rated MCP servers, optionally filtered by category. No parameter is required.get_baselines— Behavioral baselines for a tool category (categoryrequired): what normal latency and success rates look like.check_anomaly— Whether observed behavior from a server is anomalous compared to baselines (server_urlrequired).register_server— Register a new MCP server in the Observatory (server_urlandnamerequired) so it can start building a trust score. Registration is free.get_server_history— Daily trust score and performance history for a server over the last 30 days (server_urlrequired).observatory_stats— Overall Observatory statistics: servers tracked, interactions recorded, coverage by category and data freshness. No parameter is required.get_compliance_report— Compliance-ready audit trail of recorded interactions, formatted for EU AI Act Article 12 and the Singapore IMDA framework. No parameter is required.
Install and run
As an MCP server via npm:
npx -y @reneturcios/trustbeacon mcp
MCP client configuration:
{
"mcpServers": {
"trustbeacon": {
"command": "npx",
"args": ["-y", "@reneturcios/trustbeacon", "mcp"]
}
}
}
As a container:
docker run -i ghcr.io/cloudcorprecords/trustbeacon
docker run --rm ghcr.io/cloudcorprecords/trustbeacon check_trust '{"server_url":"https://example.workers.dev/mcp"}'
CLI
One binary serves both the command line and the MCP server. Each tool is a subcommand taking a single JSON string with that tool's arguments:
trustbeacon check_trust '{"server_url":"https://example.workers.dev/mcp"}'
trustbeacon preflight_check '{"target":"https://example.workers.dev/mcp"}'
trustbeacon observatory_stats '{}'
trustbeacon --version
Exit codes: 0 when the forwarded call succeeds, 1 when the upstream result is an error, and 2 for usage problems such as an unknown subcommand or a malformed JSON argument.
Configuration
DOMINIONOBSERVATORY_MCP_URL— Overrides the upstream endpoint. The default is the pinned hosted endpoint,https://dominionobservatory.com/mcp. (The override variable is a reconstruction added by this rebuild.)
The upstream registry record declares no headers, so no authentication header is ever sent, under any environment.
Upstream failures — a JSON-RPC error from the service, a non-2xx response, an unreadable body, or a request that fails outright — are reported to the caller as an error result whose text starts with trustbeacon error:.
How forwarding works
The first forwarded call opens a session: an initialize request (protocol version 2025-03-26), followed by a notifications/initialized notification, then the tools/call itself. If the service answers the initialize request with an Mcp-Session-Id header, that value is carried on every later request, and the open session is reused for the rest of the process. Replies are accepted either as plain JSON or as server-sent events. Successful results pass through verbatim, including any isError flag and any extra fields the service includes.
Development
npm install
npm run build # tsc -> dist/ (dist/cli.js is the bin)
npm test # tsx --test test/*.test.ts — stubbed upstream, no network
npm run dev # run the CLI from source
The test suite checks the served tool list against the captured surface, asserts the omitted paid_trust_verdict tool is absent at the registry, MCP and CLI levels, exercises the session handshake and its reuse, verifies that no Authorization header is ever sent, and verifies that arguments go upstream untouched and results come back untouched.
License
MIT — see LICENSE. Copyright (c) 2026 Rene Turcios.
@reneturcios/trustbeaconnpm install @reneturcios/trustbeaconghcr.io/cloudcorprecords/trustbeacon:0.1.0docker pull ghcr.io/cloudcorprecords/trustbeacon:0.1.0:undefinedRelated Servers
io.github.CloudCorpRecords/abandoncheck
Judge whether a dependency is maintained, from factual signals: releases, commits, archival.
io.github.CloudCorpRecords/actionbridge
Zapier exposed actions as MCP tools via a generic action runner.
io.github.CloudCorpRecords/actionpin
GitHub Actions supply-chain hardener: audit workflows for unpinned actions and build a SHA pin plan.