@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.