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

Ready to tag: v0.1.0.

Related MCP server: Basic MCP Server

Tool list (16)

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

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.