nostr-bray 1.11.0 → 1.12.0

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.11.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",