nostr-bray 1.10.0 → 1.12.0

package/dist/cli.js

@@ -138,6 +138,7 @@ Environment:
   NOSTR_RELAYS                  Comma-separated relay URLs
   NWC_URI / NWC_URI_FILE        Nostr Wallet Connect URI
   TOR_PROXY                     SOCKS5h proxy URL
+  NOSTR_BRAY_OUTPUT             Default output: "human" (default) or "json"
 
 Quick examples:
   nostr-bray whoami                           # show your npub
@@ -149,7 +150,8 @@ Quick examples:
   nostr-bray shell                            # interactive mode
 
 Flags:
-  --json                              Output raw JSON instead of human-readable
+  --json                              Output raw JSON (for piping/scripts)
+  --human                             Force human-readable output
   --help                              Show help for a command
 
 Use 'nostr-bray <command> --help' for detailed help on any command.
@@ -176,10 +178,21 @@ config.secretKey = '';
 config.nwcUri = undefined;
 const masterRelays = await nip65.loadForIdentity(ctx.activeNpub);
 pool.reconfigure(ctx.activeNpub, masterRelays);
-const jsonMode = args.includes('--json');
-/** Print JSON (always) or human-readable (default) */
+// Default output mode from env (CLI-level --json/--human handled per-command)
+const envDefault = process.env.NOSTR_BRAY_OUTPUT === 'json' ? 'json' : 'human';
+/** Resolve output mode for a given set of args */
+function resolveOutputMode(cmdArgs) {
+    if (cmdArgs.includes('--json'))
+        return 'json';
+    if (cmdArgs.includes('--human'))
+        return 'human';
+    return envDefault;
+}
+// Top-level output mode (for single-command invocations)
+let currentOutputMode = resolveOutputMode(args);
+/** Print JSON or human-readable depending on output mode */
 function out(data, humanFormatter) {
-    if (jsonMode || !humanFormatter) {
+    if (currentOutputMode === 'json' || !humanFormatter) {
         console.log(JSON.stringify(data, null, 2));
     }
     else {
@@ -218,6 +231,7 @@ function parseShellLine(line) {
     return result;
 }
 async function run(cmdArgs) {
+    currentOutputMode = resolveOutputMode(cmdArgs);
     const command = cmdArgs[0];
     /** Require arg or throw */
     function req(index, usage) {

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/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.10.0",
+  "version": "1.12.0",
   "description": "MCP server giving AI agents sovereign Nostr identities — key derivation, personas, attestations, duress detection, zaps",
   "type": "module",
   "main": "dist/index.js",