io.github.lonniev/excalibur-mcp

Generate a patron's account statement at this operator. Returns the patron's purchase history, active credit tranches, per-tool usage breakdown, and recent daily usage logs. This is the patron's spending account — not the operator's Authority tax balance. Free — no credits consumed. Proof of npub ownership is required to prevent statement-scraping of arbitrary patrons. Args: npub: The patron's Nostr public key (npub1...). dpop_token: Raw JSON of a kind-27235 Nostr event signed by npub — not base64, not NIP-98 'Authorization: Nostr <b64>' framing. Its `u` tag must hold THIS tool's exact name (from tools/list), not the endpoint URL; content:"", created_at within 60s of now, and a random `nonce` tag recommended. Or a cached dpop_token phrase. days: Number of days of daily usage history to include (default 30).

Generate a visual SVG infographic of your account statement. Returns the same data as account_statement, rendered as a dark-themed SVG graphic with balance hero, metrics cards, health gauge, tranche table, and tool usage breakdown. Costs 1 api_sat per call. Proof is verified by ``debit_or_deny`` before any cost is incurred. Args: npub: The Nostr public key (npub1...) whose statement to render. dpop_token: Raw JSON of a kind-27235 Nostr event signed by npub — not base64, not NIP-98 'Authorization: Nostr <b64>' framing. Its `u` tag must hold THIS tool's exact name (from tools/list), not the endpoint URL; content:"", created_at within 60s of now, and a random `nonce` tag recommended. Or a cached dpop_token phrase. days: Number of days of daily usage history to include (default 30).

Check this operator's adoption-request status at a chosen Authority. Free. Polls the Authority MCP-to-MCP for the status of this operator's request (pending / approved / rejected / provisioned).

Start the OAuth2 authorization flow. Returns an authorization URL. Open it in a browser to log in and authorize. Then call ``check_oauth_status`` with the same npub to complete. Free. Proof of npub ownership is required so an observer cannot DOS your account by initiating OAuth flows in your name. Do NOT call this pre-emptively. If a session may still be valid, attempt the live tool call first and only begin OAuth when it fails with ``upstream_auth_refresh_needed``. A 'pending' ``check_oauth_status`` is not evidence that an existing session has lapsed. Args: npub: Your DPYC patron npub (npub1...). dpop_token: Raw JSON of a kind-27235 Nostr event signed by npub — not base64, not NIP-98 'Authorization: Nostr <b64>' framing. Its `u` tag must hold THIS tool's exact name (from tools/list), not the endpoint URL; content:"", created_at within 60s of now, and a random `nonce` tag recommended. Or a cached dpop_token phrase.

Check this operator's tax balance at the Authority. Returns the sats available for certifying patron credit purchases. When this balance reaches zero, patron top-ups cannot be certified and the operator must call purchase_credits on the Authority. This is the operator's own funding — not a patron balance. Free.

Check a patron's credit balance at this operator. This is the patron's spending balance — credits purchased via Lightning for tool calls at this operator. For the operator's own balance at the Authority (needed to certify patron purchases), use authority_check_balance instead. Free — no credits required. Proof of npub ownership is required to prevent anyone-with-the-registry from enumerating balances. Args: npub: The Nostr public key (npub1...) whose balance to check. dpop_token: Raw JSON of a kind-27235 Nostr event signed by npub — not base64, not NIP-98 'Authorization: Nostr <b64>' framing. Its `u` tag must hold THIS tool's exact name (from tools/list), not the endpoint URL; content:"", created_at within 60s of now, and a random `nonce` tag recommended. Or a cached dpop_token phrase.

Check whether the OAuth2 authorization flow has completed. Call after opening the authorization URL from ``begin_oauth`` and completing the login in your browser. Free. Proof of npub ownership is required: OAuth status exposes which upstream services a patron has connected. A 'pending' result here does NOT prove an existing session has lapsed — it only reports this authorization attempt. To find out whether a session still works, attempt the live call; fall back to ``begin_oauth`` only on an explicit ``upstream_auth_refresh_needed`` error. Args: npub: The same Nostr public key (npub1...) used in begin_oauth. dpop_token: Raw JSON of a kind-27235 Nostr event signed by npub — not base64, not NIP-98 'Authorization: Nostr <b64>' framing. Its `u` tag must hold THIS tool's exact name (from tools/list), not the endpoint URL; content:"", created_at within 60s of now, and a random `nonce` tag recommended. Or a cached dpop_token phrase.

Check the payment status of a Lightning invoice. Call after paying the invoice from purchase_credits. Free — no credits required. Proof of npub ownership is required to prevent credit-grant front-running by an observer of the invoice ID. Args: invoice_id: The invoice ID returned by purchase_credits. npub: The Nostr public key (npub1...) that purchased the invoice. dpop_token: Raw JSON of a kind-27235 Nostr event signed by npub — not base64, not NIP-98 'Authorization: Nostr <b64>' framing. Its `u` tag must hold THIS tool's exact name (from tools/list), not the endpoint URL; content:"", created_at within 60s of now, and a random `nonce` tag recommended. Or a cached dpop_token phrase.

Preview the effective cost of a tool call. Shows the base cost and any constraint effects (discounts, free trials, surge pricing). Free — no credits required. Args: tool_id: Either the tool's UUID (from the pricing model) or a bare capability string (e.g. ``"deal_scenario"``). FE callers usually have the capability name; this resolves both so the FE doesn't need to derive UUIDs locally. tool_kwargs: Optional JSON object with tool call parameters for ad valorem / categorical-multiplier pricing preview (e.g. '{"amount_sats": 5000}' or '{"difficulty": "sovereign", "mode": "live"}').

Check whether a previously-cached dpop_token is still valid. Mirrors ``check_oauth_status`` for the npub-proof flow: a calling agent can ask "will my next paid call accept this dpop_token?" before burning credits on a guaranteed failure. Free, no side effects — does not evict the cache or touch relays. Args: patron_npub: Required. The patron's npub (npub1...). dpop_token: Required. The dpop_token phrase returned by ``request_npub_proof`` / ``receive_npub_proof``.

Store a new post (draft or scheduled). Returns its ``post_id``. Args: doc: The editable Doc — a JSON object whose consumed key is ``blocks``, a list of block objects. A minimal static post is one block: ``{"blocks": [{"text": "gm. stack sats.", "flags": []}]}``. Blocks are joined with a blank line between them to form ``text_cache``. Each block: - ``text`` (str): the block's copy (for a dynamic block, a prompt). - ``flags`` (list): editor highlight regions, each ``{"start": int, "end": int, "note": str, "colorIdx": int}`` (char offsets into ``text``) — pass ``[]`` when there are none. - ``dynamic`` (bool, optional): when true ``text`` is a prompt the server resolves with an LLM at post time; ``fallback`` (str) is posted if it fails, and ``domains``/``maxFetches``/``runtimeLimit`` bound its web access. Voice/bans live in your separate Voice profile and the schedule in ``publish_at``/``recurrence``/``cease_at`` — neither belongs in ``doc``. text_cache: Composed text (blocks joined) for scheduler + list excerpts. publish_at: ISO-8601 first/next publish time; required when status='scheduled'. recurrence: ``{"freq": "daily|weekly|monthly", "interval": n}`` or null. cease_at: ISO-8601 stop time for recurrence; null = open-ended. status: ``draft`` or ``scheduled``. client_req_id: Idempotency key — re-sending the same id returns the same post without a second charge. title: Optional human label for the post; the list falls back to the first body line when it is blank. npub: Your DPYC patron Nostr public key for credit attribution.

Delete a coupon. Cascades to all patron redemptions. Any chain step referencing the deleted coupon_id becomes a no-op (the constraint returns neutral on unknown ids) — the Studio surfaces orphan references as warnings. RESTRICTED to operator — requires proof.

Remove a single patron credential field. Deletes one field from stored credentials without affecting other fields. Free. Proof of npub ownership is required — this is a write to the patron's sensitive credential vault. Args: npub: The patron's Nostr public key (npub1...). dpop_token: Raw JSON of a kind-27235 Nostr event signed by npub — not base64, not NIP-98 'Authorization: Nostr <b64>' framing. Its `u` tag must hold THIS tool's exact name (from tools/list), not the endpoint URL; content:"", created_at within 60s of now, and a random `nonce` tag recommended. Or a cached dpop_token phrase. field: The credential field name to remove.

Delete a stored post. Default is a soft delete (``status='archived'``); pass ``hard=True`` to remove the row permanently.

Delete one of your saved snippets by id. Free and owner-scoped.

Redeem a ``resolve_dynamic_block`` claim check (free, proof-gated). Poll this with the ``claim_check`` from ``resolve_dynamic_block`` until ``status == "done"`` (the resolved fragment is ``result.text``). While the job runs it returns ``{"status": "running", "poll_after_seconds": N}``; on failure ``{"status": "error", ...}`` (the start fare is refunded); an unknown or aged-out claim returns ``{"status": "expired", ...}``. Owner-scoped — only the npub that started the job can redeem it. Also acts as the watchdog: a stalled job is re-kicked when polled.

Remove a coupon from this patron's redemption list. Cosmetic only — the coupon itself still exists at the operator, and the patron can re-redeem the same code later while the window allows. Free — requires proof of ``npub``.

Delete vaulted credentials for a specific service and npub. For operator credentials, pass the operator's own npub. For patron credentials, pass the patron's npub. Always requires proof of npub ownership — a deletion is as destructive as a write. Args: service: The credential service to forget. npub: The Nostr public key (npub1...) whose credentials to forget. dpop_token: Raw JSON of a kind-27235 Nostr event signed by npub — not base64, not NIP-98 'Authorization: Nostr <b64>' framing. Its `u` tag must hold THIS tool's exact name (from tools/list), not the endpoint URL; content:"", created_at within 60s of now, and a random `nonce` tag recommended. Or a cached dpop_token phrase. Free.

Read an npub's public Nostr profile (NIP-01 kind-0 metadata). Free, no proof — the data is already public on relays. Returns the latest metadata fields (name, display_name, about, picture, banner, nip05, website, lud16) or an empty profile if none is published.

Generate a Merkle inclusion proof that a patron's balance was included in a Bitcoin-notarized snapshot. Args: notarization_id: The notarization record ID. npub: The patron's Nostr public key (npub1...).

Report this operator's configuration readiness. Shows which operator settings are configured, which are missing, and how to deliver each missing value. For patron-level credential status, use get_patron_onboarding_status instead. Free.

List stored patron credential field names (not values). Returns the names of fields stored for a patron, plus each field's ``delivered_at`` ISO-8601 timestamp when known (null for secrets vaulted before timestamps were recorded). Values are never exposed — use this to verify which fields are configured and how old each one is. Free. Proof of npub ownership is required: the list of configured fields is itself sensitive (reveals which integrations a patron has set up). Args: npub: The patron's Nostr public key (npub1...). dpop_token: Raw JSON of a kind-27235 Nostr event signed by npub — not base64, not NIP-98 'Authorization: Nostr <b64>' framing. Its `u` tag must hold THIS tool's exact name (from tools/list), not the endpoint URL; content:"", created_at within 60s of now, and a random `nonce` tag recommended. Or a cached dpop_token phrase.

Report a patron's credential readiness for this operator. For set-once services (eXcalibur, TheBrain), shows which patron secrets are configured and which are missing. For dynamic/OAuth2 services (Schwab), reports that no patron credentials are needed. Free. Proof of npub ownership is required because credential presence is sensitive information about the patron's setup. Args: patron_npub: The patron's Nostr public key (npub1...). dpop_token: A kind-27235 Nostr event signed by patron_npub for this tool.

Read one stored post by id (owner-scoped).

Patron: raw metrics snapshot series for one owned post. Returns the append-only ``post_metrics_snapshot`` rows (impressions, likes, clicks, cadence_key, t_offset, link_placement, snippet_ids) ordered by capture time. Empty when the post has not been harvested yet.

Get the active pricing model for this operator. Free. If no model exists, self-initializes a scaffold with all registered tools at 0 sats. No economic data from code.

Read recent scheduler-tick outcomes. Each ``process_scheduled_posts`` run — fired by the Cloudflare cron Worker or a manual trigger — records its summary. This surfaces them so the FE debug log can show what the Worker is doing: the per-tick heartbeat (proof it ran) and per-post outcomes (posted / skip+error reasons like ``insufficient_balance`` or ``oauth_token_expired``). Owner-scoped: the operator sees every tick in full; any other proven patron sees the global heartbeat (``processed`` count + ``run_at``) plus only the per-post entries for THEIR OWN posts. Free; npub proof required. Returns ``{runs:[{run_at, summary}], scope}``.

Read one of your saved snippets by id (full row incl. ``doc`` block document). Free and owner-scoped. Returns ``{"success": true, "snippet": …}`` or ``snippet_not_found``.

Read your saved writing Voice — a profile blurb plus a list of "banned construction" chips (``{text, on}``) the editor passes to ``refine_post_region``. Owner-scoped; priced by the operator's pricing model (use ``check_price``). When you have not saved a Voice yet this returns an empty one (``{"voice": {"profile": "", "bans": []}}``) so the editor can seed its own defaults, not an error.

Fetch the connected X account's handle and name for this patron (free). Uses the patron's vaulted X OAuth token to call X's ``/users/me``. Returns ``{connected: true, username, name, profile_image_url}`` when connected, or the OAuth situation (``connected`` absent) when X isn't linked yet. Used to show the real @handle on the editor's tweet-card preview.

Operator-only: one cadence-aware metrics harvest sweep. Drains due ``metrics_harvest_job`` rows (t+15m … t+28d), fetches X ``non_public_metrics`` / ``organic_metrics`` under each patron's OAuth context, and appends ``post_metrics_snapshot`` rows. A missed cadence is permanent data loss — failed jobs retry up to 5 attempts then land in the dead-letter queue; pass ``requeue_dead_id`` to retry one. Also runs as phase 3 of every ``process_scheduled_posts`` tick.

Return canonical (tool_id, mcp_name, …) for every registered tool. The authoritative source for any client (Studio, agents, FE) that needs to know how this MCP identifies its tools. Reconcile uses this output to UUID-join against the stored pricing model — no name-based UUID derivation, no guessing. If the operator renames a function or rebrands a slug, the mcp_name in this output changes but tool_id stays. That's the whole point of the canonical-UUID design. Free, no side effects.

List all available constraint types and their parameter schemas. Returns the type, category, description, and parameter specs for every constraint that can be used in a pricing pipeline. Free — no credits required.

List every coupon this operator has minted (newest first). Each row carries the current ``times_redeemed`` counter — the Studio renders a progress bar from this against ``total_uses``. RESTRICTED to operator — requires proof.

List the coupons this patron has redeemed on this operator. Returns both active and exhausted redemptions with a per-row ``status`` (``active`` / ``window_closed`` / ``patron_limit`` / ``total_limit``). Free — requires proof of ``npub``.

List recent Bitcoin notarization records. Args: limit: Maximum records to return (default 20). status: Optional filter (e.g., 'submitted', 'confirmed').

List your stored posts, server-side sorted, filtered, and offset-paginated. Optional ``status`` filter — a single status or a comma-separated set (e.g. ``draft,scheduled``), matched as set membership. ``sort_col`` is one of ``created|updated|status|scheduled`` (default ``created``); ``sort_dir`` is ``asc|desc``. ``search`` is a case-insensitive regular expression matched against the post text. ``date_from``/``date_to`` (``YYYY-MM-DD``, end-inclusive) bound the ``date_field`` column, one of ``created|updated|scheduled|sent`` (default ``created``). ``template_id`` filters to the sent occurrences a recurring template fired. ``page`` is 0-indexed; ``page_size`` is 1..100. Each row carries ``is_recurring``, ``has_dynamic``, and ``template_id`` (set on sent occurrences). Returns ``{posts:[…], total, page, page_size}`` reflecting the filtered set.

List your saved post snippets, server-side sorted, filtered, and offset-paginated. ``sort_col`` is one of ``favorite|created|updated|name`` (default ``favorite``); ``sort_dir`` is ``asc|desc``. ``search`` is a case-insensitive regular expression matched against the snippet name or body. ``date_from``/``date_to`` (``YYYY-MM-DD``, end-inclusive) bound the ``date_field`` column, one of ``created|updated`` (default ``created``). ``page`` is 0-indexed; ``page_size`` is 1..200. Free, owner-scoped. Returns ``{snippets:[…], total, page, page_size}`` reflecting the filtered set.

Create a new operator-owned discount coupon. Args: name: The catchy code patrons type to redeem (operator-scoped uniqueness). discount_percent: Percentage off the base price (0-100). valid_from: ISO-8601 datetime when the coupon becomes active. valid_until: ISO-8601 datetime when the coupon expires. uses_per_patron: How many tool calls one patron can claim the discount on (default 1; pass null/None for unlimited within the window). total_uses: Aggregate cap across all patrons (default None = unlimited). Returns the new coupon row. RESTRICTED to operator — requires proof (nsec-signed kind-27235 or cached dpop_token token).

Build a Merkle tree of all patron balances and submit the root to Bitcoin via OpenTimestamps. Operator-only background task. Bitcoin confirmation takes 1-6 hours. Free — no credits required.

Describe the DPYC ecosystem via the Oracle. Free.

Get the current DPYC certification tax rate. Free.

Get DPYC onboarding instructions from the Oracle. Free.

Look up a DPYC community member by npub. Free.

Get active network advisories from the Oracle. Free.

Publish a public Nostr note (kind 1) authored by your proven npub. eXcalibur cannot sign a note *as* you — a Nostr event must be signed by the key it claims to come from, and eXcalibur never holds your nsec. So for this one note it mints a fresh, ephemeral "scribe" keypair, signs with it, and ``p``-tags YOUR npub as the author. The p-tag renders the note as a real mention and places it in your own Nostr mentions, so you can see — and disown — anything published in your name. The author is always your **proven** npub from this session (the same npub you pass for billing); it is never a free-form argument, so no caller can scribe as anyone else. The note publishes to the DPYC relay set. The call **succeeds if at least one** relay accepts it; the response lists every relay's accept/reject and the accepted/attempted counts so you can see the note's real reach — a one-relay publish never reads as a clean broadcast. Args: message: The note text to publish. npub: Your DPYC patron npub (npub1...) — proven, billed, and recorded as the note's author.

Patron: derived reach scores across your harvested post corpus. Computes escape velocity (t+15m vs rolling median), breakout ratio (impressions ÷ followers), link-placement cohort medians, and snippet/voice attribution from the durable snapshot store — signals that come from owning the curve, not proxying a single X endpoint.

Patron: SVG infographic of post performance (gold-steel theme). Mirrors ``account_statement_infographic`` — a dark-themed SVG of corpus size, median t+15m impressions, top posts, and link-placement cohorts.

Post a text tweet with markdown formatting converted to Unicode rich text. Accepts standard markdown inline formatting and converts it to Unicode Mathematical Alphanumeric Symbols that render as styled text on X: **bold** -> bold *italic* -> italic ***bold italic*** -> bold italic `monospace` -> monospace Args: text: Tweet content with optional markdown formatting. npub: Your DPYC patron Nostr public key (npub1...) for credit attribution.

Post a tweet with a hero banner image to X/Twitter. Provide either an image_url (fetched and attached) or banner_svg (rendered to PNG and attached). Text supports the same markdown formatting as post_tweet. Args: text: Tweet content with optional markdown formatting. image_url: URL of an image to attach to the tweet. banner_svg: Self-contained SVG markup string, converted to PNG. npub: Your DPYC patron Nostr public key (npub1...) for credit attribution.