io.github.lonniev/dpyc-oracle

Measured conclusion: Deep-tested. L2 outcome: tools_ok.

DPYC Social Contract community concierge — free MCP for membership, governance, and onboarding

Add to your agent

Copy this into your MCP client config:

{
  "mcpServers": {
    "dpyc-oracle": {
      "url": "https://dpyc-oracle.fastmcp.app/mcp",
      "transport": "streamable-http"
    }
  }
}

Measured tools (30)

• about

  Extended narration about DPYC, the Social Contract, and the Oracle. Fetches README.md and GOVERNANCE.md from the dpyc-community repo and assembles a comprehensive context answer.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• lookup_member

  Look up a member by their Nostr npub. Can look up any role's npub — citizen, operator, or authority. Returns the full member record if found, or a not-found message.

  Parameters:

  • npub (required) — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• get_tax_rate

  Explain how Tollbooth certification taxation works. Taxation is ad valorem and **per-Authority** — there is no single network-wide number, and the Oracle deliberately quotes none. The actual fee is the Authority's own accounting, set in its pricing model and reported at transaction time. This tool is a docent: it explains the model and points to the live source. For the exact figure, query the relevant Authority's ``check_price`` for ``certify_credits``.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• economic_model

  Explain the DPYC Social Contract economic model — qualitatively. Describes how value flows through the network: ad valorem certification fees, the cascade up the Certification Chain to the First Curator, and where the live numbers actually live. The Oracle quotes **no** rates, counts, or revenue figures — those belong to the Authorities' pricing models and the live registry, not to a docent. Free, unauthenticated.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• get_rulebook

  Fetch the DPYC Social Contract governance document. Returns the raw markdown of GOVERNANCE.md from the dpyc-community repo.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• how_to_join

  Tier-specific onboarding guide for joining the DPYC Social Contract. Covers all five tiers: Citizen, Advocate, Operator, Authority, and First Curator. Includes Nostr keygen instructions and practical next steps.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• who_is_first_curator

  Identify the First Curator (Prime Authority) of the Certification Chain. Returns the curator's npub, display name, and member record.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• network_versions

  Get current recommended versions of all Tollbooth components. Returns component versions, minimum compatibility, active protocols, and a short advisory summary. Data is fetched live from network-status.json in the dpyc-community repo.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• network_advisory

  Get current network deployment advisory. Returns human-readable guidance on what changed recently, urgent upgrades, and actions operators should take. Fetched live from ADVISORY.md in the dpyc-community repo.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• how_to_add_authority

  End-to-end guide for spinning up a new Tollbooth Authority. Returns the eight-step procedure covering identity, region selection, GitHub workspace, dpyc-community registry entry, Neon + BTCPay + Horizon deployment, BTCPay credential delivery via Secure Courier, the self-registration challenge-response with the parent Authority, and pre-funding the cert-fee balance. Fetched live from docs/how-to-add-authority.md in the dpyc-community repo.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• service_status

  Diagnostic: report this service's software versions and runtime info. Free, unauthenticated. Use to verify deployment versions across the DPYC ecosystem.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• list_services

  Enumerate the live DPYC service network with self-described summaries. Reads the member roster from the dpyc-community registry, then (when ``probe=True``) performs a lightweight MCP handshake against each member's public service endpoint to fetch that service's *own* self-description and tool inventory. Nothing about the services is hardcoded here — descriptions are authored by each service, and prices come from each Operator/Authority pricing model (call the service's ``check_price``). Resilient by design: per-service timeout, partial results, brief caching, and a registry-only fallback when an endpoint is asleep or unreachable. A sleeping service never breaks the listing. Free, unauthenticated.

  Parameters:

  • kind — string — Role filter — "all", "operator", "authority", or "advocate".
  • probe — boolean — Handshake each endpoint for a live self-description. Set False for a fast registry-only listing (no network fan-out).

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• get_relays

  Return the DPYC Nostr relay set, best first. The single source of truth is ``dpyc-community/relays.json``. An Operator seeds its relay set from here at cold start (its only fixed dependency is this Oracle endpoint), then reads its own bootstrap config from Nostr using just its nsec — no direct GitHub access. That file is a curated *guess*: it says which relays are worth using, not which are up this minute. Relays that an operator reported and the Oracle then proved unreachable are moved to the back of the list; everything else keeps its declared order, and nothing is ever dropped. This call never probes anything — it is on every operator's cold-start path, so it stays a lookup. Ranking improves only when someone hits a dead relay and says so via ``report_relay_failure``. Report failures only; successes need no announcement. Free.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• report_relay_failure

  Report that a relay in the DPYC set was unreachable, and re-rank it. A report does not set a relay's rank. It asks the Oracle to measure that relay *now*, and the Oracle's own probe decides. A false or mistaken report therefore costs one probe and changes nothing — no caller can demote a healthy relay by asserting that it is down. Report only failures. Successes are far too frequent to be worth carrying, and a relay that works needs no announcement.

  Parameters:

  • relay (required) — string — The relay that failed. Must already be in the DPYC set — this tool re-measures the curated set, it is not a probe-anything primitive that can be aimed at arbitrary hosts.
  • reporter_npub (required) — string — The reporting operator's npub.
  • signed_event (required) — string — A Nostr event signed by ``reporter_npub`` whose content contains the relay URL, created within the last few minutes. Stateless by design: no challenge is issued first, because a challenge store would not survive this service's recycles — and a relay report is most needed exactly when relays are broken.
  • mode — string — What was being attempted — ``"send"``, ``"read"``, or ``"unknown"``. Recorded for the human reading the logs.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• resolve_authority_for

  Resolve the certifying Authority for an operator npub. Returns the Authority's ``{npub, url, name}`` (from the operator's ``upstream_authority_npub``). Use this after bootstrap to learn — and verify — which Authority signed your config, without reading GitHub.

  Parameters:

  • npub (required) — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• resolve_service

  Resolve a DPYC service by ``name`` or ``npub``. Returns ``{npub, url, name, role, purchase_mode}`` where ``purchase_mode`` is the registry-topology fact ``"certified"`` or ``"direct"`` (not a price). Supply exactly one of ``name`` or ``npub``.

  Parameters:

  • name — string
  • npub — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• request_citizenship

  Begin the citizen registration process (Operator-owned flow). This is the **citizen** registration path. Called by the Operator on behalf of a patron — invokes the Oracle directly. No Authority npub is required or consulted. The patron's npub is registered as a Citizen in the DPYC community. The npub provided here becomes the user's **patron identity** — the keypair they will use for credit purchases and service access across all Tollbooth-monetized services. Not to be confused with **operator** registration, which goes through the Authority via a Nostr DM delegation request. Issues a cryptographic challenge that the applicant must sign with their Nostr private key (nsec) to prove they own the claimed npub. The nsec never leaves the applicant's device. Returns a challenge_id, nonce, and signing instructions. The applicant signs a Nostr event containing the nonce and submits it via confirm_citizenship within 10 minutes.

  Parameters:

  • npub (required) — string
  • display_name (required) — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• confirm_citizenship

  Complete the citizen registration by submitting a signed Nostr event. This is part of the **citizen** registration flow (Operator-owned). The Operator calls this on behalf of a patron after the patron has signed the cryptographic challenge from request_citizenship. Verifies: 1. The challenge exists and hasn't expired 2. The Schnorr signature is valid 3. The event's pubkey matches the claimed npub 4. The event content contains the issued nonce 5. The npub is not already registered On success, commits directly to dpyc-community/members/citizens/{npub}.json to register the new Citizen immediately.

  Parameters:

  • npub (required) — string
  • challenge_id (required) — string
  • signed_event_json (required) — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• register_authority

  Register a new Authority in the DPYC community registry. Called by an Authority service at the end of the onboarding protocol (after the candidate proves npub ownership and the Prime Authority approves). Commits a new ``members/authorities/{npub}.json`` file to dpyc-community on GitHub. The full Authority onboarding protocol is a 3-step Nostr DM challenge-response flow: 1. ``register_authority_npub(npub)`` — Authority sends DM challenge 2. ``confirm_authority_claim(npub)`` — verifies candidate DM, escalates to Prime 3. ``check_authority_approval(npub)`` — Prime approves, this tool is called

  Parameters:

  • authority_npub (required) — string — Nostr npub of the new Authority curator.
  • display_name (required) — string — Human-readable name for the Authority.
  • service_url (required) — string — Public MCP endpoint URL of the Authority service.
  • upstream_authority_npub (required) — string — npub of the sponsoring Authority (must already exist as a prime_authority or authority in the registry).

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• register_operator

  Register a new Operator in the DPYC community registry. Called by an Authority service when its owner approves an operator's adoption request; the request must be signed with the Authority's key.

  Parameters:

  • operator_npub (required) — string — Nostr npub of the new Operator.
  • display_name (required) — string — Human-readable name for the Operator service.
  • service_url (required) — string — Public MCP endpoint URL of the Operator service.
  • authority_npub (required) — string — npub of the sponsoring Authority (must already exist as an authority or prime_authority in the registry).

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• update_operator

  Update an existing Operator's registry entry. Used when an Operator moves to a new MCP endpoint, changes its display name, or needs to correct a registration. Called by an Authority when its owner approves the operator's update request; the request must be signed with that Authority's key.

  Parameters:

  • operator_npub (required) — string — Nostr npub of the Operator to update.
  • authority_npub (required) — string — npub of the requesting Authority (must be a registered authority or prime_authority).
  • service_url — string — New MCP endpoint URL (leave empty to keep current).
  • display_name — string — New display name (leave empty to keep current).

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• deregister_operator

  Remove an Operator from the DPYC community registry. Called by an Authority when the operator leaves it or the Authority disowns the operator; the request must be signed with the Authority's key. An Operator cannot exist without a sponsoring Authority, so deregistration removes the member file entirely, returning the Operator to initial state.

  Parameters:

  • operator_npub (required) — string — Nostr npub of the Operator to remove.
  • authority_npub (required) — string — npub of the Authority requesting deregistration (must be a registered authority or prime_authority).

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• register_advocate

  Register a new Advocate in the DPYC community registry. Advocates are community utility services that provide shared infrastructure (e.g., OAuth2 callback collectors) but aren't monetized Operators or certification Authorities. The request must be signed with ``npub``'s own key (NIP-98): a service registers itself, and no one can register an npub they do not hold.

  Parameters:

  • npub (required) — string — Nostr npub of the Advocate service.
  • display_name (required) — string — Human-readable name for the service.
  • service_name (required) — string — Machine-readable service identifier (e.g., "tollbooth-oauth2-collector").
  • service_url (required) — string — Public URL of the service.
  • service_description (required) — string — Short description of what the service does.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• check_ban_status

  Check whether an npub is banned from the DPYC Social Contract. Looks up the member in the community registry and checks whether their status is "banned". Unknown npubs are not considered banned (they simply aren't members). Free, unauthenticated. Used by operators during the cold path (credit purchases) to enforce community bans.

  Parameters:

  • npub (required) — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• renounce_membership

  Citizen self-removal from the DPYC Social Contract via automated PR. Not yet implemented — will create a GitHub PR to remove the member from the registry.

  Parameters:

  • npub (required) — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• initiate_ban_election

  Initiate a community ban election against a member. Not yet implemented — will create a GitHub Issue with a 72-hour discussion period and Lightning-funded economic voting.

  Parameters:

  • target_npub (required) — string
  • reason (required) — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• cast_ban_vote

  Cast a Lightning-funded vote in an active ban election. Not yet implemented — will verify npub membership, validate the election is active, and record the vote with a Lightning payment proof.

  Parameters:

  • election_id (required) — string
  • vote (required) — string
  • npub (required) — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• publish_campaign

  Publish a pricing campaign to the DPYC community. Commits both a machine-importable JSON file and a human-readable Markdown summary to the dpyc-community campaigns directory. The request must be signed with ``author_npub``'s key (NIP-98), so a campaign is published only under its author's own name.

  Parameters:

  • author_npub (required) — string — The npub of the person who designed the campaign.
  • operator_npub (required) — string — The npub of the operator the campaign is for.
  • campaign_json (required) — string — The full campaign export as a JSON string.
  • campaign_name — string — Optional display name. Derived from JSON if omitted.
  • campaign_markdown — string — Optional pre-rendered Markdown. If omitted, the Oracle generates a basic summary from the JSON.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• list_campaigns

  List published pricing campaigns from the DPYC community. Optionally filter by operator or author npub.

  Parameters:

  • author_npub — string — Filter to campaigns by this author (optional).
  • operator_npub — string — Filter to campaigns for this operator (optional).

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• get_campaign

  Retrieve a published pricing campaign.

  Parameters:

  • author_npub (required) — string — The campaign author's npub.
  • operator_npub (required) — string — The target operator's npub.
  • slug (required) — string — The campaign slug (directory name).
  • format — string — "json" for importable data, "markdown" for readable summary.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

Repository

Measured by MCPYP probing. Untested fields are omitted, never estimated. Listing is always free; MCPYP never proxies calls or stores user tokens.