# Agent Instructions: `mcp_servers/nostr_mcp`

> **Scope:** These instructions apply to files under `mcp_servers/nostr_mcp/`.

> **Maintenance rule:** NOT a changelog; if something stops being true, overwrite it.

## Purpose

mcp_servers/nostr_mcp

## What it is

MCP server for the Nostr protocol. Talks directly to relays (WebSocket) and manages
the user's identities. This is the "write/interact live" server — for querying the
ingested dataset use nostr_db_mcp instead.

## Files

- nostr_mcp.py     — FastMCP server ("mcp-nostr"), entrypoint. Defines the tools.
- nostr_client.py  — relay WebSocket client (connect, subscribe, publish).
- user_store.py    — identity storage (users.json).
- aliases.py       — pubkey alias resolution (aliases.json).
- config.json      — host/port + relay list.
- users.json       — user identities INCLUDING PRIVATE KEYS. Secret — do not commit
```text
                 real keys / do not leak.
```

- aliases.json     — pubkey aliases: `named` (human) + `auto` (generated).
- run.sh           — .venv + pip + python nostr_mcp.py.
- requirements.txt — mcp==1.26.0, uvicorn, websockets.

## Tools

- connect_relay(url) / disconnect_relay(url)
- get_events(filter, url?)         — query relays
- publish_event(event, url?)       — sign + publish (uses active user)
- check_relays(urls, filter?)      — probe relays
- add_user(name) / switch_user(name) / list_users()
- set_alias(name, hash) / list_aliases()

## Config / gotchas

- config.json: host 127.0.0.1, port 8010, relays = damus / nos.lol / nostr.band /
  nostr.wine / primal.
- Active user lives in users.json (`active` key); publish uses that identity's privkey.
- Uses its own .venv (run.sh); do not use the system python.
