{
  "markdown": "# nostr-bray\n\n**Trust-aware Nostr MCP for AI and humans.** 258 tools across 29 groups. Model-agnostic. Works with Claude, ChatGPT, Gemini, Cursor, Windsurf, or any MCP client.\n\n[![npm](https://img.shields.io/npm/v/nostr-bray)](https://www.npmjs.com/package/nostr-bray)\n[![CI](https://github.com/forgesworn/bray/actions/workflows/ci.yml/badge.svg)](https://github.com/forgesworn/bray/actions/workflows/ci.yml)\n[![licence](https://img.shields.io/npm/l/nostr-bray)](./LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-ESM-blue)](./tsconfig.json)\n[![GitHub Sponsors](https://img.shields.io/github/sponsors/TheCryptoDonkey?logo=githubsponsors&color=ea4aaa&label=Sponsor)](https://github.com/sponsors/TheCryptoDonkey)\n\n## Quick Start\n\nInstall globally or run via npx:\n\n```bash\nnpm install -g nostr-bray\n```\n\nNew to Nostr? Mint a key first -- this works before anything is configured\nand prints your npub plus a 24-word mnemonic (write it down; it is the key):\n\n```bash\nnpx nostr-bray create\n```\n\nAdd to your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"nostr\": {\n      \"command\": \"npx\",\n      \"args\": [\"nostr-bray\"],\n      \"env\": {\n        \"NOSTR_SECRET_KEY\": \"nsec1...\",\n        \"NOSTR_RELAYS\": \"wss://relay.damus.io,wss://nos.lol\"\n      }\n    }\n  }\n}\n```\n\nThen ask your AI to call `whoami` to verify it works.\n\nFor production use, prefer [Heartwood](https://github.com/forgesworn/heartwood) or any NIP-46 bunker (your key never leaves your signing device):\n\n```json\n{\n  \"mcpServers\": {\n    \"nostr\": {\n      \"command\": \"npx\",\n      \"args\": [\"nostr-bray\"],\n      \"env\": {\n        \"BUNKER_URI\": \"bunker://...\",\n        \"NOSTR_RELAYS\": \"wss://relay.damus.io,wss://nos.lol\"\n      }\n    }\n  }\n}\n```\n\n### Auth tiers (best to worst)\n\n| Tier | Method | Key exposure |\n|------|--------|-------------|\n| **Heartwood** | Dedicated signing appliance (`BUNKER_URI`) | Key never leaves the signing device. Supports nsec-tree derivation, per-client permissions, and device-backed attestations. |\n| **Software bunker** | Any NIP-46 bunker (`BUNKER_URI`) | Key held by a separate process. Never seen by bray. |\n| **ncryptsec** | NIP-49 encrypted key (`NOSTR_NCRYPTSEC`) | Key encrypted at rest, decrypted in memory at startup. |\n| **Key file** | File path (`NOSTR_SECRET_KEY_FILE`) | Key on disk, read once, env var deleted. |\n| **Env var** | Inline secret (`NOSTR_SECRET_KEY`) | Key visible in process environment. Use only for development. |\n\n## Tool Groups\n\n| Group | Tools | Key examples |\n|-------|------:|--------------|\n| **Identity** | 16 | `whoami`, `identity-derive-persona`, `identity-switch`, `identity-prove`, `nip05-lookup` |\n| **Social** | 15 | `social-post`, `social-reply`, `social-feed`, `contacts-follow`, `social-notifications` |\n| **Direct Messages** | 4 | `dm-send`, `dm-read`, `dm-conversation` |\n| **Trust** | 22 | `trust-attest`, `trust-ring-prove`, `trust-spoken-challenge`, `trust-attest-chain` |\n| **Dispatch** | 13 | `dispatch-send`, `dispatch-check`, `dispatch-reply`, `dispatch-capability-discover` |\n| **Relay** | 13 | `relay-query`, `relay-set`, `relay-discover`, `cast-spell`, `relay-health` |\n| **Moderation** | 16 | `label-create`, `list-mute`, `list-bookmark`, `list-followset-create`, `moderation-filter` |\n| **Marketplace** | 16 | `marketplace-discover`, `marketplace-call`, `listing-create`, `listing-search` |\n| **Safety** | 14 | `canary-session-create`, `canary-group-create`, `canary-duress-signal`, `safety-activate` |\n| **Blossom** | 10 | `blossom-upload`, `blossom-mirror`, `blossom-verify`, `blossom-repair` |\n| **Privacy** | 10 | `privacy-commit`, `privacy-prove-range`, `privacy-prove-age`, `privacy-publish-proof` |\n| **Zap** | 9 | `zap-send`, `zap-balance`, `zap-make-invoice`, `zap-decode` |\n| **Wallet service** | 5 | `wallet-grant`, `wallet-grants`, `wallet-revoke`, `wallet-refill`, `wallet-serve` |\n| **Vault** | 9 | `vault-create`, `vault-encrypt`, `vault-share`, `vault-rotate` |\n| **Workflow** | 7 | `trust-score`, `verify-person`, `identity-setup`, `relay-health`, `feed-discover` |\n| **Signet** | 7 | `signet-badge`, `signet-vouch`, `signet-credentials`, `signet-challenge` |\n| **Communities** | 5 | `community-create`, `community-feed`, `community-post`, `community-approve` |\n| **Badges** | 4 | `badge-create`, `badge-award`, `badge-accept`, `badge-list` |\n| **Groups (NIP-29)** | 20 | `group-inspect`, `group-invite-create`, `group-forum-comment`, `group-delete` |\n| **Articles** | 3 | `article-publish`, `article-read`, `article-list` |\n| **Calendar** | 3 | `calendar-create`, `calendar-read`, `calendar-rsvp` |\n| **Wiki** | 3 | `wiki-publish`, `wiki-read`, `wiki-list` |\n| **Search** | 3 | `search-notes`, `search-profiles`, `hashtag-feed` |\n| **Scheduling** | 4 | `post-schedule`, `post-queue-list`, `post-queue-cancel`, `publish-event` |\n| **Community NIPs** | 2 | `nip-publish`, `nip-read` |\n| **Utility** | 20 | `decode`, `validate-event`, `verify-event`, `nip44-encrypt`, `tombstone` |\n| **Sync (NIP-77)** | 1 | `sync-plan` (pull/push are explicit CLI and SDK operations) |\n| **Handler** | 2 | `handler-publish`, `handler-discover` |\n| **Catalog** | 2 | `search-actions`, `execute-action` |\n\nUse `search-actions` to find tools by keyword, then `execute-action` to run them.\n\nProtocol foundations: [semantic event validation](docs/event-validation.md),\n[NIP-77 reconciliation](docs/sync.md), and [relay-scoped NIP-29 groups](docs/nip29-groups.md).\n\n## Dispatch: AI-to-AI Collaboration\n\nDispatch lets AI agents collaborate over encrypted Nostr DMs. Any MCP-capable client can send structured tasks to other agents and receive results back.\n\n**13 message types:** send, check, reply, ack, status, cancel, refuse, failure, query, propose, capability-publish, capability-discover, capability-read.\n\n**NIP-89 capability discovery:** Agents publish what they can do. Other agents discover capabilities by topic, then route tasks to the right collaborator automatically.\n\n```\ndispatch-send(\"alice\", \"think\", \"Analyse the trade-offs of NIP-44 vs NIP-04\")\ndispatch-check()                    → inbox with pending tasks\ndispatch-reply(taskId, result)      → send results back encrypted\n```\n\nAll messages are NIP-44 encrypted. Recipients are resolved by name, NIP-05, npub, or hex.\n\n## Identity Resolver\n\nEvery tool that accepts a recipient uses universal identity resolution. You never need to look up hex pubkeys manually.\n\nAccepted formats:\n- **Name** -- `\"alice\"` (resolved from your dispatch contacts)\n- **NIP-05** -- `\"alice@example.com\"` (HTTP lookup)\n- **npub** -- `\"npub1abc...\"` (NIP-19 decode)\n- **Hex** -- `\"a1b2c3...\"` (64-character passthrough)\n\n## Scheduled Posting\n\nSign events now, publish later. Events are signed immediately with your current key, then held in a queue until the scheduled time.\n\n```\npost-schedule(\"Good morning!\", \"2026-04-01T08:00:00Z\")\npost-queue-list()          → view pending scheduled posts\npost-queue-cancel(id)      → cancel before it publishes\n```\n\n## NIP Coverage\n\nnostr-bray implements or integrates the following NIPs:\n\n| NIP | What |\n|-----|------|\n| **NIP-01** | Events, signing, relay protocol |\n| **NIP-02** | Follow lists |\n| **NIP-05** | DNS identity (lookup, verify, relay hints) |\n| **NIP-09** | Event deletion |\n| **NIP-11** | Relay information |\n| **NIP-17** | Private DMs (gift wrap, default) |\n| **NIP-19** | bech32 encoding (npub, nsec, nprofile, nevent, naddr) |\n| **NIP-23** | Long-form articles (kind 30023) |\n| **NIP-22** | Schema-correct comments for group forums |\n| **NIP-29** | Relay-scoped groups, chat, forums, invitations and administration |\n| **NIP-32** | Labels |\n| **NIP-40** | Expiration tags |\n| **NIP-42** | Relay auth |\n| **NIP-44** | Encrypted payloads v2 |\n| **NIP-45** | Event counts |\n| **NIP-46** | Nostr Connect (bunker) |\n| **NIP-49** | Private key encryption (ncryptsec) |\n| **NIP-50** | Search |\n| **NIP-51** | Lists (mute, pin, follow sets, bookmarks) |\n| **NIP-52** | Calendar events |\n| **NIP-54** | Wiki pages |\n| **NIP-57** | Lightning zaps |\n| **NIP-58** | Badges |\n| **NIP-65** | Relay list metadata |\n| **NIP-72** | Communities |\n| **NIP-77** | Negentropy ID reconciliation with truthful REQ fallback |\n| **NIP-78** | Application-specific data |\n| **NIP-85** | Trust rankings |\n| **NIP-89** | Recommended applications (dispatch capability discovery) |\n| **NIP-96** | HTTP file storage (Blossom) |\n| **NIP-99** | Classified listings |\n| **NIP-A7** | Spells (kind 777 — cast saved queries) |\n| **NIP-VA** | Verifiable attestations (kind 31000) |\n\n## Configuration\n\n### Config file (recommended)\n\nCreate `~/.config/bray/config.json` (or `~/.nostr/bray.json`):\n\n```json\n{\n  \"bunkerUriFile\": \"/Users/you/.nostr/bunker-uri\",\n  \"relays\": [\"wss://relay.damus.io\", \"wss://nos.lol\"],\n  \"trustMode\": \"annotate\"\n}\n```\n\nSecrets are referenced by **file path** (`bunkerUriFile`, `secretKeyFile`, `nwcUriFile`) so they never appear in the config itself.\n\nSearch order: `BRAY_CONFIG` env var > `$XDG_CONFIG_HOME/bray/config.json` > `~/.nostr/bray.json`.\n\n### Environment variables\n\n| Variable | Description |\n|----------|-------------|\n| `BRAY_CONFIG` | Path to config file |\n| `BUNKER_URI` | NIP-46 bunker URL (safest) |\n| `BUNKER_URI_FILE` | Path to bunker URI file |\n| `NOSTR_SECRET_KEY` | nsec, hex, or BIP-39 mnemonic |\n| `NOSTR_SECRET_KEY_FILE` | Path to secret key file |\n| `NOSTR_NCRYPTSEC` | NIP-49 encrypted key |\n| `NOSTR_NCRYPTSEC_PASSWORD` | Password for ncryptsec |\n| `NWC_URI_FILE` | Path to a private `0600` file containing the NWC bearer URI |\n| `NOSTR_RELAYS` | Comma-separated relay URLs |\n| `NOSTR_FORBID_PUBKEY` | Comma-separated npubs or hex this process must never sign as. See below. |\n| `TOR_PROXY` | SOCKS5h proxy for Tor |\n| `NIP04_ENABLED` | Set `1` to enable legacy NIP-04 DMs |\n| `TRANSPORT` | `stdio` (default) or `http` |\n| `PORT` | HTTP port (default 3000) |\n\nAll secret env vars are deleted from `process.env` before parsing can fail.\nRaw `NWC_URI` is refused; use `NWC_URI_FILE` or `wallet connect <nwc-file>` so\nthe bearer credential never appears in a process environment, command argument\nor MCP tool argument.\n\n### Keys this process must never be\n\nAn agent that comes up holding the wrong key is indistinguishable from one\nworking correctly. Every signature verifies, every tool succeeds, and the\nonly symptom is that `whoami` quietly answers with somebody else's npub —\nwhich the driving model has no reason to doubt, because it is its own tool\ntelling it.\n\nThe worst version is a **principal's** key: a person's own. An agent signing\nas its principal can attest that it belongs to itself, and approve its own\nrequests, because it *is* the principal those checks look for.\n\n```bash\nNOSTR_FORBID_PUBKEY=npub1yourownkey...,npub1anotherhuman...\n```\n\nor `forbidPubkeys` in the config file. Either takes npubs or hex. Activating\none of those keys throws instead — at startup, on `identity-switch`, and on\n`bunker --persona` alike, because the check sits at the moment an identity\nbecomes active rather than at any one entry point. An entry that cannot be\nparsed is an error too: a list nobody can read must not silently permit\neverything.\n\nThe active npub is printed on stderr on every start, so the answer to \"which\nkey is this?\" does not depend on asking the agent.\n\n## Handing out a wallet connection\n\n`zap-send` spends through the NWC URI you configured. That URI is an\nunbounded capability over the wallet behind it: every method it supports, no\nceiling, until it is rotated. Handing one to an agent hands over everything.\n\n`wallet-grant` issues connections over the same wallet that are narrower.\n\n```\nwallet-grant   { name: \"research-agent\", methods: [\"get_info\",\"pay_invoice\"],\n                 budgetMsat: 50000, maxPaymentMsat: 5000 }\nwallet-grants  # what exists, what it may do, what it has spent\nwallet-revoke  { nameOrId: \"research-agent\" }\nwallet-refill  { nameOrId: \"research-agent\", budgetMsat: 50000 }\nwallet-serve   { action: \"start\" }\n```\n\nWhat a connection may do is an allowlist, and the default grants no spending\nand does not disclose the balance: `get_info`, `make_invoice`,\n`lookup_invoice`. Both of the others are opt-in per connection, and **a\nconnection that can spend must carry a budget** - there is no unlimited grant\nto issue by accident.\n\nThe rules exist because a payment cannot be recalled:\n\n- A request is answered **once**. Its id is persisted *before* the payment is\n  attempted, so a process that dies mid-payment comes back knowing not to try\n  again - a relay will hand the same signed request over twice.\n- Requests on one connection are **serialised**, so two arriving together\n  cannot both read the same remaining budget.\n- A request older than five minutes is not answered, whatever its own\n  `expiration` tag claims.\n- Each connection has **its own service key**: two grants share nothing a\n  relay can correlate, and revoking one is deleting a key.\n- The budget is charged what the **invoice** says, decoded here. A budget\n  checked against a figure the payer supplied is not a budget.\n- A claimed payment whose preimage does not settle the invoice is refused\n  rather than passed on. Repeating an unproven claim would make this service\n  the one telling the lie.\n\nGrants live in `wallet-grants.json` (0600, per identity), and they are\nanswered **only while `wallet-serve` is running** - which is to say, only for\nas long as this process is alive. That is worth telling whoever you hand a URI\nto: a connection that works while an MCP session is open is a different\npromise from one that works overnight.\n\n## CLI\n\n```bash\nnpx nostr-bray whoami                    # show your npub\nnpx nostr-bray post \"hello from bray!\"   # publish a note\nnpx nostr-bray persona work              # derive a work persona\nnpx nostr-bray prove blind               # create a linkage proof\nnpx nostr-bray --help                    # see all commands\n```\n\n## Documentation\n\n- **[Usage Guide](./docs/guide.md)** -- walkthroughs for identity, DMs, attestations, payments, and duress\n- **[Examples](./examples/)** -- MCP config files and CLI workflow scripts\n- **[Contributing](./CONTRIBUTING.md)** -- setup, architecture, testing, and conventions\n\n## For AI Assistants\n\nSee [llms.txt](./llms.txt) for a concise summary optimised for AI context windows, or [llms-full.txt](./llms-full.txt) for complete tool documentation with parameter details.\n\n## Part of the ForgeSworn Toolkit\n\n[ForgeSworn](https://forgesworn.dev) builds open-source cryptographic identity, payments, and coordination tools for Nostr.\n\n| Library | What it does |\n|---------|-------------|\n| [nsec-tree](https://github.com/forgesworn/nsec-tree) | Deterministic sub-identity derivation |\n| [ring-sig](https://github.com/forgesworn/ring-sig) | SAG/LSAG ring signatures on secp256k1 |\n| [range-proof](https://github.com/forgesworn/range-proof) | Pedersen commitment range proofs |\n| [canary-kit](https://github.com/forgesworn/canary-kit) | Coercion-resistant spoken verification |\n| [spoken-token](https://github.com/forgesworn/spoken-token) | Human-speakable verification tokens |\n| [toll-booth](https://github.com/forgesworn/toll-booth) | L402 payment middleware |\n| [geohash-kit](https://github.com/forgesworn/geohash-kit) | Geohash toolkit with polygon coverage |\n| [nostr-attestations](https://github.com/forgesworn/nostr-attestations) | NIP-VA verifiable attestations |\n| [dominion](https://github.com/forgesworn/dominion) | Epoch-based encrypted access control |\n| [nostr-veil](https://github.com/forgesworn/nostr-veil) | Privacy-preserving Web of Trust |\n\n## Licence\n\nMIT\n",
  "bytes": 15544,
  "sha": "a7b6dbc06f05ba6ee2c31760c6bd3870fa0f50b929a9b4de3e5cbd76435621ec",
  "repo_slug": "forgesworn/bray",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_dev_forgesworn_bray_f8f1aa65/readme"
}