nostr-bray 1.11.0 → 1.13.0

package/README.md

@@ -4,6 +4,7 @@
 
 [![CI](https://github.com/forgesworn/bray/actions/workflows/ci.yml/badge.svg)](https://github.com/forgesworn/bray/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/nostr-bray)](https://www.npmjs.com/package/nostr-bray)
+[![coverage](https://img.shields.io/badge/coverage-96%25-brightgreen)](./package.json)
 [![licence](https://img.shields.io/npm/l/nostr-bray)](./LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-ESM-blue)](./tsconfig.json)
 

package/dist/cli.js

@@ -24,10 +24,24 @@ import * as fmt from './format.js';
 const args = process.argv.slice(2);
 const command = args[0];
 // No command = start MCP server
-if (!command || command === 'serve') {
+if (!command) {
     await import('./index.js');
     process.exit(0);
 }
+// Serve = in-memory test relay
+if (command === 'serve' && !args.includes('--help')) {
+    const { startRelay } = await import('./serve.js');
+    const hostname = args.includes('--hostname') ? args[args.indexOf('--hostname') + 1] : 'localhost';
+    const port = args.includes('--port') ? parseInt(args[args.indexOf('--port') + 1], 10) : 10547;
+    const eventsFile = args.includes('--events') ? args[args.indexOf('--events') + 1] : undefined;
+    const relay = startRelay({ hostname, port, eventsFile, quiet: args.includes('--quiet') });
+    console.error(`nostr-bray test relay running at ${relay.url}`);
+    console.error('Press Ctrl+C to stop');
+    process.on('SIGINT', () => { relay.close(); process.exit(0); });
+    process.on('SIGTERM', () => { relay.close(); process.exit(0); });
+    // Keep process alive
+    await new Promise(() => { });
+}
 // Per-command help: `nostr-bray post --help`
 if (args.includes('--help') && command && command !== 'help' && command !== '--help' && command !== '-h') {
     const help = getCommandHelp(command);
@@ -130,6 +144,7 @@ Utility:
 
 Modes:
   (no command)                        Start MCP server (stdio)
+  serve [--port N] [--events file]    Start in-memory test relay
   shell                               Interactive REPL (persistent relay connection)
 
 Environment:

package/dist/help.js

@@ -84,6 +84,7 @@ export const COMMAND_HELP = {
     count: { usage: 'count [--kinds N,N] [--authors X,X] [--since N]', description: 'Count events matching a filter on relays.', examples: ['nostr-bray count --kinds 1', 'nostr-bray count --kinds 1,7 --authors abc123...'] },
     fetch: { usage: 'fetch <nip19>', description: 'Fetch events by nip19 code (note, nevent, nprofile, npub, naddr). Resolves the entity and queries relays.', examples: ['nostr-bray fetch note1...', 'nostr-bray fetch nevent1...', 'nostr-bray fetch npub1...'] },
     shell: { usage: 'shell', description: 'Start an interactive REPL with a persistent relay connection. Supports tab autocomplete. Type "help" for commands, "exit" to quit.', examples: ['nostr-bray shell'] },
+    serve: { usage: 'serve [--port N] [--hostname H] [--events file.jsonl] [--quiet]', description: 'Start an in-memory Nostr relay for testing. Implements NIP-01 (events, subscriptions, EOSE) and NIP-11 (relay info). Events live in memory only — no persistence. Optionally pre-load events from a JSONL file.', examples: ['nostr-bray serve', 'nostr-bray serve --port 7777', 'nostr-bray serve --events test-data.jsonl', 'nostr-bray serve --port 7777 --quiet'] },
 };
 /** Get formatted help for a single command */
 export function getCommandHelp(cmd) {

package/dist/identity/tools.js

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { toolResponse } from '../tool-response.js';
+import * as fmt from '../format.js';
 import { handleIdentityCreate, handleIdentityDerive, handleIdentityDerivePersona, handleIdentitySwitch, handleIdentityList, handleIdentityProve, } from './handlers.js';
 import { handleBackupShamir, handleRestoreShamir } from './shamir.js';
 import { hexId } from '../validation.js';
@@ -54,12 +56,13 @@ export function registerIdentityTools(server, deps) {
     });
     server.registerTool('identity_list', {
         description: 'List all known identities (master + all derived). Returns array of { npub, purpose, index, personaName }. Never includes private keys. Use this to see what identities are available before switching.',
+        inputSchema: {
+            output: z.enum(['json', 'human']).default('json').describe('Response format'),
+        },
         annotations: { readOnlyHint: true },
-    }, async () => {
+    }, async ({ output }) => {
         const result = handleIdentityList(deps.ctx);
-        return {
-            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-        };
+        return toolResponse(result, output, fmt.formatIdentityList);
     });
     server.registerTool('identity_prove', {
         description: 'Create a cryptographic linkage proof between the master key and the active identity. "blind" (default) proves they share a master without revealing how the child was derived. "full" also reveals the purpose and index. Returns a LinkageProof object that can be verified by anyone with nsec-tree. Use trust_proof_publish to make it permanent on relays.',

package/dist/relay/tools.js

@@ -1,18 +1,19 @@
 import { z } from 'zod';
 import { relayUrl } from '../validation.js';
+import { toolResponse } from '../tool-response.js';
+import * as fmt from '../format.js';
 import { handleRelayList, handleRelaySet, handleRelayAdd, handleRelayInfo } from './handlers.js';
 export function registerRelayTools(server, deps) {
     server.registerTool('relay_list', {
         description: 'List the relay set (read/write) for the active identity. Optionally check for shared relays with another identity.',
         inputSchema: {
             compareWithNpub: z.string().optional().describe('Compare shared relays with this npub'),
+            output: z.enum(['json', 'human']).default('json').describe('Response format'),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ compareWithNpub }) => {
+    }, async ({ compareWithNpub, output }) => {
         const result = handleRelayList(deps.ctx, deps.pool, compareWithNpub);
-        return {
-            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-        };
+        return toolResponse(result, output, fmt.formatRelays);
     });
     server.registerTool('relay_set', {
         description: 'Publish a kind 10002 relay list for the active identity. Warns if a relay list already exists.',

package/dist/serve.d.ts

@@ -0,0 +1,16 @@
+/**
+ * In-memory Nostr relay for testing purposes.
+ *
+ * Implements NIP-01 (events, subscriptions, EOSE) and NIP-11 (relay info).
+ * No persistence — events live in memory until the process exits.
+ */
+export interface ServeOptions {
+    hostname?: string;
+    port?: number;
+    eventsFile?: string;
+    quiet?: boolean;
+}
+export declare function startRelay(opts?: ServeOptions): {
+    url: string;
+    close: () => void;
+};

package/dist/serve.js

@@ -0,0 +1,175 @@
+/**
+ * In-memory Nostr relay for testing purposes.
+ *
+ * Implements NIP-01 (events, subscriptions, EOSE) and NIP-11 (relay info).
+ * No persistence — events live in memory until the process exits.
+ */
+import { WebSocketServer, WebSocket } from 'ws';
+import { createServer } from 'node:http';
+import { readFileSync } from 'node:fs';
+import { verifyEvent } from 'nostr-tools/pure';
+/** Check if an event matches a single filter */
+function matchFilter(filter, event) {
+    if (filter.ids && !filter.ids.includes(event.id))
+        return false;
+    if (filter.kinds && !filter.kinds.includes(event.kind))
+        return false;
+    if (filter.authors && !filter.authors.includes(event.pubkey))
+        return false;
+    if (filter.since && event.created_at < filter.since)
+        return false;
+    if (filter.until && event.created_at > filter.until)
+        return false;
+    // Tag filters (#e, #p, #t, #d, etc.)
+    for (const key of Object.keys(filter)) {
+        if (key.startsWith('#')) {
+            const vals = filter[key];
+            if (!vals || !Array.isArray(vals))
+                continue;
+            const tagName = key.slice(1);
+            const eventTagValues = event.tags.filter(t => t[0] === tagName).map(t => t[1]);
+            if (!vals.some(v => eventTagValues.includes(v)))
+                return false;
+        }
+    }
+    return true;
+}
+/** Check if an event matches any filter in a list */
+function matchFilters(filters, event) {
+    return filters.some(f => matchFilter(f, event));
+}
+export function startRelay(opts = {}) {
+    const hostname = opts.hostname ?? 'localhost';
+    const port = opts.port ?? 10547;
+    const quiet = opts.quiet ?? false;
+    const log = quiet ? () => { } : (...args) => console.error('[relay]', ...args);
+    const events = new Map();
+    const subscriptions = new Map();
+    // Pre-load events from JSONL file
+    if (opts.eventsFile) {
+        const lines = readFileSync(opts.eventsFile, 'utf-8').split('\n').filter(Boolean);
+        for (const line of lines) {
+            try {
+                const event = JSON.parse(line);
+                events.set(event.id, event);
+            }
+            catch { /* skip malformed lines */ }
+        }
+        log(`Loaded ${events.size} events from ${opts.eventsFile}`);
+    }
+    const httpServer = createServer((req, res) => {
+        // NIP-11 relay info document
+        if (req.headers.accept?.includes('application/nostr+json')) {
+            res.writeHead(200, { 'Content-Type': 'application/nostr+json' });
+            res.end(JSON.stringify({
+                name: 'nostr-bray test relay',
+                description: 'In-memory relay for testing',
+                supported_nips: [1, 11],
+                software: 'nostr-bray',
+                version: '0.1.0',
+            }));
+            return;
+        }
+        res.writeHead(200, { 'Content-Type': 'text/plain' });
+        res.end('nostr-bray test relay — connect via WebSocket');
+    });
+    const wss = new WebSocketServer({ server: httpServer });
+    wss.on('connection', (ws) => {
+        const clientSubs = new Set();
+        log('Client connected');
+        ws.on('message', (raw) => {
+            let msg;
+            try {
+                msg = JSON.parse(raw.toString());
+            }
+            catch {
+                ws.send(JSON.stringify(['NOTICE', 'Invalid JSON']));
+                return;
+            }
+            if (!Array.isArray(msg) || msg.length < 2) {
+                ws.send(JSON.stringify(['NOTICE', 'Invalid message format']));
+                return;
+            }
+            const type = msg[0];
+            if (type === 'EVENT') {
+                const event = msg[1];
+                if (!event?.id || !event?.sig || !event?.pubkey) {
+                    ws.send(JSON.stringify(['OK', event?.id ?? '', false, 'invalid: missing fields']));
+                    return;
+                }
+                if (!verifyEvent(event)) {
+                    ws.send(JSON.stringify(['OK', event.id, false, 'invalid: signature verification failed']));
+                    return;
+                }
+                // Store event
+                events.set(event.id, event);
+                ws.send(JSON.stringify(['OK', event.id, true, '']));
+                log(`Stored event ${event.id.slice(0, 8)}... kind:${event.kind}`);
+                // Notify matching subscriptions
+                for (const sub of subscriptions.values()) {
+                    if (matchFilters(sub.filters, event) && sub.ws.readyState === WebSocket.OPEN) {
+                        sub.ws.send(JSON.stringify(['EVENT', sub.id, event]));
+                    }
+                }
+            }
+            else if (type === 'REQ') {
+                const subId = msg[1];
+                const filters = msg.slice(2);
+                // Register subscription
+                const sub = { id: subId, filters, ws };
+                const key = `${subId}-${Date.now()}`;
+                subscriptions.set(key, sub);
+                clientSubs.add(key);
+                // Send matching stored events
+                let count = 0;
+                const limit = filters.reduce((min, f) => Math.min(min, f.limit ?? Infinity), Infinity);
+                const matching = [...events.values()]
+                    .filter(e => matchFilters(filters, e))
+                    .sort((a, b) => b.created_at - a.created_at)
+                    .slice(0, limit === Infinity ? undefined : limit);
+                for (const event of matching) {
+                    ws.send(JSON.stringify(['EVENT', subId, event]));
+                    count++;
+                }
+                // EOSE
+                ws.send(JSON.stringify(['EOSE', subId]));
+                log(`REQ ${subId}: ${count} events, ${filters.length} filter(s)`);
+            }
+            else if (type === 'CLOSE') {
+                const subId = msg[1];
+                for (const key of clientSubs) {
+                    if (subscriptions.get(key)?.id === subId) {
+                        subscriptions.delete(key);
+                        clientSubs.delete(key);
+                    }
+                }
+                ws.send(JSON.stringify(['CLOSED', subId, '']));
+            }
+            else if (type === 'COUNT') {
+                const subId = msg[1];
+                const filters = msg.slice(2);
+                const count = [...events.values()].filter(e => matchFilters(filters, e)).length;
+                ws.send(JSON.stringify(['COUNT', subId, { count }]));
+            }
+            else {
+                ws.send(JSON.stringify(['NOTICE', `Unknown message type: ${type}`]));
+            }
+        });
+        ws.on('close', () => {
+            for (const key of clientSubs) {
+                subscriptions.delete(key);
+            }
+            log('Client disconnected');
+        });
+    });
+    httpServer.listen(port, hostname, () => {
+        log(`Listening on ws://${hostname}:${port}`);
+    });
+    return {
+        url: `ws://${hostname}:${port}`,
+        close: () => {
+            wss.close();
+            httpServer.close();
+        },
+    };
+}

package/dist/social/tools.js

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import { hexId } from '../validation.js';
+import { toolResponse } from '../tool-response.js';
+import * as fmt from '../format.js';
 import { handleSocialPost, handleSocialReply, handleSocialReact, handleSocialProfileGet, handleSocialProfileSet, handleContactsGet, handleContactsFollow, handleContactsUnfollow, handleSocialDelete, handleSocialRepost, } from './handlers.js';
 import { handleDmSend, handleDmRead } from './dm.js';
 import { handleNotifications, handleFeed } from './notifications.js';
@@ -90,14 +92,13 @@ export function registerSocialTools(server, deps) {
         inputSchema: {
             pubkeyHex: hexId.describe('Hex pubkey to fetch profile for'),
             npub: z.string().optional().describe('Bech32 npub (used for relay routing, defaults to active identity)'),
+            output: z.enum(['json', 'human']).default('json').describe('Response format'),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ pubkeyHex, npub }) => {
+    }, async ({ pubkeyHex, npub, output }) => {
         const resolvedNpub = npub ?? deps.ctx.activeNpub;
         const profile = await handleSocialProfileGet(deps.pool, resolvedNpub, pubkeyHex);
-        return {
-            content: [{ type: 'text', text: JSON.stringify(profile, null, 2) }],
-        };
+        return toolResponse(profile, output, fmt.formatProfile);
     });
     server.registerTool('social_profile_set', {
         description: 'Set the kind 0 profile for the active identity. Warns if profile already exists — set confirm: true to overwrite.',
@@ -161,25 +162,25 @@ export function registerSocialTools(server, deps) {
     });
     server.registerTool('dm_read', {
         description: 'Read direct messages addressed to the active identity. Decrypts both NIP-17 (gift wrap) and NIP-04 (legacy). Each message includes { from, content, protocol, decrypted }. Gracefully handles decryption failures without crashing.',
+        inputSchema: {
+            output: z.enum(['json', 'human']).default('json').describe('Response format'),
+        },
         annotations: { readOnlyHint: true },
-    }, async () => {
+    }, async ({ output }) => {
         const messages = await handleDmRead(deps.ctx, deps.pool);
-        return {
-            content: [{ type: 'text', text: JSON.stringify(messages, null, 2) }],
-        };
+        return toolResponse(messages, output, fmt.formatDms);
     });
     server.registerTool('social_notifications', {
         description: 'Fetch notifications for the active identity — mentions, replies, reactions, and zap receipts.',
         inputSchema: {
             since: z.number().optional().describe('Unix timestamp — only fetch notifications after this time'),
             limit: z.number().int().min(1).max(200).default(50).describe('Max notifications to return'),
+            output: z.enum(['json', 'human']).default('json').describe('Response format'),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ since, limit }) => {
+    }, async ({ since, limit, output }) => {
         const notifications = await handleNotifications(deps.ctx, deps.pool, { since, limit });
-        return {
-            content: [{ type: 'text', text: JSON.stringify(notifications, null, 2) }],
-        };
+        return toolResponse(notifications, output, fmt.formatNotifications);
     });
     server.registerTool('social_feed', {
         description: 'Fetch the kind 1 text note feed. Optionally filter by authors.',
@@ -187,26 +188,24 @@ export function registerSocialTools(server, deps) {
             authors: z.array(hexId).optional().describe('Hex pubkeys to filter by'),
             since: z.number().optional().describe('Unix timestamp — only fetch posts after this time'),
             limit: z.number().int().min(1).max(100).default(20).describe('Max posts to return'),
+            output: z.enum(['json', 'human']).default('json').describe('Response format'),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ authors, since, limit }) => {
+    }, async ({ authors, since, limit, output }) => {
         const feed = await handleFeed(deps.ctx, deps.pool, { authors, since, limit });
-        return {
-            content: [{ type: 'text', text: JSON.stringify(feed, null, 2) }],
-        };
+        return toolResponse(feed, output, fmt.formatFeed);
     });
     server.registerTool('contacts_get', {
         description: 'Fetch the contact list (kind 3 follows) for a pubkey. Returns pubkeys, relay hints, and petnames.',
         inputSchema: {
             pubkeyHex: hexId.describe('Hex pubkey to fetch contacts for'),
             npub: z.string().optional().describe('Bech32 npub for relay routing (defaults to active identity)'),
+            output: z.enum(['json', 'human']).default('json').describe('Response format'),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ pubkeyHex, npub }) => {
+    }, async ({ pubkeyHex, npub, output }) => {
         const contacts = await handleContactsGet(deps.pool, npub ?? deps.ctx.activeNpub, pubkeyHex);
-        return {
-            content: [{ type: 'text', text: JSON.stringify(contacts, null, 2) }],
-        };
+        return toolResponse(contacts, output, fmt.formatContacts);
     });
     server.registerTool('contacts_follow', {
         description: 'Follow a Nostr pubkey. Fetches current contact list, adds the pubkey, publishes updated kind 3.',

package/dist/tool-response.d.ts

@@ -0,0 +1,19 @@
+/** Standard output format parameter — add to any tool's inputSchema */
+export declare const outputFormatParam: {
+    readonly description: "Response format: \"json\" (default, structured data) or \"human\" (readable text)";
+};
+/**
+ * Build an MCP tool response with optional human formatting.
+ *
+ * Usage in tool registrations:
+ *   return toolResponse(data, args.output, formatFn)
+ *
+ * If output === 'human' and a formatter is provided, returns formatted text.
+ * Otherwise returns JSON (the default for MCP).
+ */
+export declare function toolResponse(data: unknown, output: string | undefined, humanFormatter?: (d: any) => string): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};

package/dist/tool-response.js

@@ -0,0 +1,19 @@
+/** Standard output format parameter — add to any tool's inputSchema */
+export const outputFormatParam = {
+    description: 'Response format: "json" (default, structured data) or "human" (readable text)',
+};
+/**
+ * Build an MCP tool response with optional human formatting.
+ *
+ * Usage in tool registrations:
+ *   return toolResponse(data, args.output, formatFn)
+ *
+ * If output === 'human' and a formatter is provided, returns formatted text.
+ * Otherwise returns JSON (the default for MCP).
+ */
+export function toolResponse(data, output, humanFormatter) {
+    if (output === 'human' && humanFormatter) {
+        return { content: [{ type: 'text', text: humanFormatter(data) }] };
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nostr-bray",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "MCP server giving AI agents sovereign Nostr identities — key derivation, personas, attestations, duress detection, zaps",
   "type": "module",
   "main": "dist/index.js",
@@ -17,6 +17,7 @@
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "lint": "tsc --noEmit",
     "start": "node dist/index.js"
@@ -89,6 +90,7 @@
     "@semantic-release/git": "^10.0.1",
     "@types/node": "^25.5.0",
     "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^4.1.1",
     "semantic-release": "^25.0.3",
     "typescript": "^6.0.2",
     "vitest": "^4.1.1"