@buzz/mcp

TypeScript Model Context Protocol (MCP) server for the CorePrt Nostr relay. Exposes 16 tools for talking to a CorePrt Nostr relay: identity, channels, messages, fetch & search, jobs, workflows, media, thread summaries, and WebSocket subscriptions. One operator identity per process, signed by BUZZ_PRIVATE_KEY. Speaks NIP-98 HTTP and NIP-42 WebSocket auth — no daemon, no Rust, just a stdio binary.

Run it as a child of any MCP-aware client (Claude Desktop, Cursor, Zed, ggcoder) and gain a Buzz workspace of tools. The full operator-facing manual is at docs/quickstart.md; this README is the 60-second pitch.

---

Status

All 6 planned PRs are shipped:

PR	Branch	What it adds
#1	feat/scaffold	package, stdio transport, McpServer factory
#2	feat/signer	local nsec holder + NIP-98 signedFetch + BIP-340
#3	feat/first-tool	buzz_post_message + typed event builders
#4	feat/tools	+11 more tools (identity, channels, fetch, jobs, media, summaries)
#5	feat/subscribe	+3 tools (buzz_subscribe, buzz_poll, buzz_unsubscribe)
#6	feat/docs	this PR — docs/quickstart.md, mcp-config.example.json, CHANGELOG.md

Ready to tag: v0.1.0.

---

Tool list (16)

Tools are registered in alphabetical order (REGISTERED_TOOLS in src/index.ts):

Tool	Read/Write	One-line
buzz_add_member	write	Publish a kind:9000 NIP-29 add_member event.
buzz_approve_workflow	write	Publish kind:46030 (approve) or kind:46031 (reject) referencing a workflow.
buzz_create_channel	write	Publish a kind:9007 NIP-29 create_channel event.
buzz_create_job	write	Publish a kind:43001 KIND_JOB_REQUEST event.
buzz_edit_message	write	Publish a kind:40003 edit referencing an existing message.
buzz_fetch_events	read	POST a NIP-01 filter to /query; returns the raw event array.
buzz_identity	read	Relay NIP-11 info doc + the operator's derived pubkey/npub.
buzz_list_channels	read	kind:9007 NIP-29 channels visible to the operator.
buzz_poll	read	Drain buffered EVENT frames from a sub_id (FIFO).
buzz_post_message	write	Publish a kind:9 NIP-29 stream message; reply via NIP-10.
buzz_post_thread_summary	write	Publish a kind:39005 KIND_THREAD_SUMMARY event.
buzz_react	write	Publish a kind:7 NIP-25 reaction.
buzz_search	read	NIP-50 free-text search (falls back to client-side includes).
buzz_subscribe	side-effect	Open a ["REQ", sub_id, filter] against the shared WS.
buzz_unsubscribe	side-effect	Send ["CLOSE", sub_id] and drop it from the manager.
buzz_upload_media	write	PUT /media/upload (or /upload); base64 or CWD-scoped path; max 1 MiB.

Grouped by category:

• Identity & Channels — buzz_identity, buzz_list_channels, buzz_create_channel, buzz_add_member.
• Messages — buzz_post_message, buzz_edit_message, buzz_react.
• Fetch & Search — buzz_fetch_events, buzz_search.
• Jobs & Workflows — buzz_create_job, buzz_approve_workflow.
• Media & Summaries — buzz_upload_media, buzz_post_thread_summary.
• Subscriptions — buzz_subscribe, buzz_poll, buzz_unsubscribe.

---

Quickstart

# Recommended for production: npx, no install
npx @buzz/mcp

# From source
git clone https://github.com/0xtsotsi/buzz-mcp && cd buzz-mcp
npm install && npm run build
node dist/cli.js    # or: npm link && buzz-mcp

Then drop one of the three variants from docs/mcp-config.example.json into ~/.gg/mcp.json (Track A pinned path, Track B npx, or Track B with raw ${VAR} env). Set BUZZ_PRIVATE_KEY in ~/.config/coreprt/buzz-mcp.env (chmod 600). Verify with buzz_identity.

The 60-second walkthrough, troubleshooting, and full env table are at docs/quickstart.md.

---

Package manager

This package is installed with npm, not pnpm. The lockfile committed to this repo is package-lock.json. If your local environment only has pnpm installed, get npm first (e.g. via corepack enable && corepack prepare npm@latest --activate, or via your Node installer of choice) and then run npm install. Do not commit a pnpm-lock.yaml.

---

Requirements

• Node.js ≥ 22 (declared in engines.node).
• npm ≥ 10.

Build & run

npm run build          # → dist/index.js, dist/cli.js + .d.ts files
npm run typecheck      # tsc --noEmit on src/
npm run typecheck:test # tsc --noEmit on test/
npm start              # node dist/cli.js
node dist/cli.js       # explicit form

The process speaks MCP over stdio — point your MCP client at buzz-mcp (or at node /path/to/repo/dist/cli.js) and the JSON-RPC handshake runs automatically. The BUZZ_PRIVATE_KEY and BUZZ_RELAY_URL env vars are read once at server boot; a missing BUZZ_PRIVATE_KEY throws a clear error.

Test

npm test               # vitest run — 93 tests across 13 files

The local block/buzz integration test is deferred — it spins up the Rust relay via Docker Compose and needs tmux + psql on the operator's Mac. A pure-JS happy-path suite (event building, signing, NIP-98 wrapping, subscription FSM) covers the public tool surface in npm test.

---

Layout

.
├── src/
│   ├── index.ts           # createServer() factory — wires all 16 tools
│   ├── cli.ts             # stdio entry point — the `buzz-mcp` bin
│   ├── relay/             # signer + signedFetch (NIP-98) + subscription FSM
│   │   ├── client.ts
│   │   ├── event-builder.ts
│   │   ├── signer.ts
│   │   └── subscription.ts
│   ├── tools/             # one file per category
│   │   ├── identity.ts
│   │   ├── messages.ts
│   │   ├── fetch.ts
│   │   ├── jobs.ts
│   │   ├── media.ts
│   │   ├── summaries.ts
│   │   └── subscribe.ts
│   └── util/              # shared helpers
│       ├── relay-call.ts  # timeout + ack parsing + error envelope
│       └── zod.ts
├── test/
│   ├── index.spec.ts      # createServer() + MCP tools/list smoke
│   └── unit/              # 12 vitest specs covering each tool
├── docs/
│   ├── quickstart.md
│   └── mcp-config.example.json
├── package.json           # name, version, deps, bin
├── tsconfig.json          # ES2022 / NodeNext / strict
├── tsconfig.test.json
├── vitest.config.ts
├── CHANGELOG.md
├── NOTICE                 # Apache-2.0 attribution
└── LICENSE                # Apache-2.0

The compiled output lives in dist/ and ships via the files field in package.json.

---

License

Apache-2.0. See LICENSE and NOTICE.

The Nostr protocol is the work of the Nostr community; CorePrt is a separate project maintained at https://github.com/0xtsotsi/coreprt.