nostr-bray 1.27.1 → 1.27.3

package/dist/catalog.d.ts

@@ -32,4 +32,25 @@ export declare class ActionCatalog {
  * Promoted tools go to the real server; everything else goes to the catalog.
  */
 export declare function createCatalogProxy(server: McpServer, catalog: ActionCatalog, promoted: Set<string>): McpServer;
+/**
+ * Coerce execute-action's `params`/`parameters` argument into a plain object.
+ *
+ * Accepts either:
+ *   - an object (the canonical shape), passed through unchanged
+ *   - a JSON string literal that parses to an object (some MCP clients serialise
+ *     record-typed fields this way because the compiled JSON Schema has no
+ *     fixed properties list)
+ *   - undefined (returns an empty object)
+ *
+ * Rejects malformed JSON strings and JSON that does not parse to a plain object
+ * (e.g. arrays, numbers, null), returning a structured error the caller can
+ * surface to the client without crashing.
+ */
+export declare function coerceActionParams(raw: unknown): {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+};
 export {};

package/dist/catalog.js

@@ -104,21 +104,48 @@ export class ActionCatalog {
                     }],
             };
         });
+        // Accept either an object (the natural shape) or a JSON string literal.
+        // Some MCP clients (notably the Claude Code harness as of April 2026)
+        // serialise schema fields typed as z.record(z.unknown()) as a JSON string
+        // rather than a nested object, because the compiled JSON Schema has no
+        // fixed `properties` list. The handler below coerces strings by parsing
+        // them, returning a clean error on malformed JSON.
+        const paramsSchema = z.union([
+            z.record(z.string(), z.unknown()),
+            z.string(),
+        ]);
         server.registerTool('execute-action', {
             description: 'Execute an action found via search-actions. Pass the exact action name and its parameters.',
             inputSchema: {
                 action: z.string().describe('Action name from search-actions results'),
-                params: z.record(z.string(), z.unknown()).optional().describe('Parameters for the action (see search-actions results for expected params). Alias: parameters.'),
+                params: paramsSchema.optional().describe('Parameters for the action (see search-actions results for expected params). ' +
+                    'Alias: parameters. Accepts a JSON object or a JSON string literal.'),
                 // Alias for clients that naturally reach for "parameters" rather than "params".
                 // Without this, MCP SDK strips unknown keys from the validated args and the
                 // inner action handler receives an empty object, causing spurious
                 // "expected string, received undefined" validation failures.
-                parameters: z.record(z.string(), z.unknown()).optional().describe('Alias for params. Either field is accepted.'),
+                parameters: paramsSchema.optional().describe('Alias for params. Either field is accepted. ' +
+                    'Accepts a JSON object or a JSON string literal.'),
             },
             annotations: { openWorldHint: true },
         }, async ({ action, params, parameters }) => {
-            const resolved = (params ?? parameters ?? {});
-            return catalog.execute(action, resolved);
+            const raw = params ?? parameters;
+            const coerced = coerceActionParams(raw);
+            if (!coerced.ok) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: coerced.error,
+                                action,
+                                hint: 'Pass params (or parameters) as a JSON object like ' +
+                                    '{"pubkeyHex":"..."}, or as a JSON string literal of the ' +
+                                    'same shape. Malformed JSON strings are rejected.',
+                            }, null, 2),
+                        }],
+                };
+            }
+            return catalog.execute(action, coerced.value);
         });
     }
 }
@@ -152,3 +179,53 @@ function extractParams(schema) {
     }
     return params;
 }
+/**
+ * Coerce execute-action's `params`/`parameters` argument into a plain object.
+ *
+ * Accepts either:
+ *   - an object (the canonical shape), passed through unchanged
+ *   - a JSON string literal that parses to an object (some MCP clients serialise
+ *     record-typed fields this way because the compiled JSON Schema has no
+ *     fixed properties list)
+ *   - undefined (returns an empty object)
+ *
+ * Rejects malformed JSON strings and JSON that does not parse to a plain object
+ * (e.g. arrays, numbers, null), returning a structured error the caller can
+ * surface to the client without crashing.
+ */
+export function coerceActionParams(raw) {
+    if (raw === undefined || raw === null) {
+        return { ok: true, value: {} };
+    }
+    if (typeof raw === 'string') {
+        const trimmed = raw.trim();
+        if (trimmed === '') {
+            return { ok: true, value: {} };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                error: `Invalid parameters: could not parse JSON string (${message})`,
+            };
+        }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return {
+                ok: false,
+                error: 'Invalid parameters: JSON string must decode to an object, not an array or primitive',
+            };
+        }
+        return { ok: true, value: parsed };
+    }
+    if (typeof raw === 'object' && !Array.isArray(raw)) {
+        return { ok: true, value: raw };
+    }
+    return {
+        ok: false,
+        error: `Invalid parameters: expected an object or JSON string, received ${typeof raw}`,
+    };
+}

package/dist/relay/tools.js

@@ -6,6 +6,7 @@ import { handleRelayList, handleRelaySet, handleRelayAdd, handleRelayInfo, handl
 import { handleRelayCount } from './count.js';
 import { handleRelayAuth } from './auth.js';
 import { handleCastSpell } from './spell.js';
+import { flatOrWrapped, mergeFlatAndWrapped } from '../util/schema.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.',
@@ -119,28 +120,44 @@ export function registerRelayTools(server, deps) {
         };
     });
     server.registerTool('relay-count', {
-        description: 'Count events matching a filter without fetching them (NIP-45). Sends a COUNT request to each relay. Falls back to fetch-and-count (capped at 1000) if the relay does not support NIP-45. Results show per-relay counts with fallback/estimated flags.',
+        description: 'Count events matching a filter without fetching them (NIP-45). Sends a COUNT request to each relay. Falls back to fetch-and-count (capped at 1000) if the relay does not support NIP-45. Results show per-relay counts with fallback/estimated flags. Filter fields may be supplied either as top-level arguments or wrapped in a single "filter" object (both shapes are accepted).',
         inputSchema: {
             relays: z.array(relayUrl).describe('Relay URLs to count from'),
-            kinds: z.array(z.number().int()).optional().describe('Event kinds to filter by'),
-            authors: z.array(z.string()).optional().describe('Hex pubkeys of event authors'),
-            tags: z.record(z.string(), z.array(z.string())).optional().describe('Tag filters as key-value pairs'),
-            since: z.number().int().optional().describe('Unix timestamp lower bound'),
-            until: z.number().int().optional().describe('Unix timestamp upper bound'),
+            ...flatOrWrapped({
+                ids: z.array(z.string()).optional().describe('Event IDs (hex) to count'),
+                kinds: z.array(z.number().int()).optional().describe('Event kinds to filter by'),
+                authors: z.array(z.string()).optional().describe('Hex pubkeys of event authors'),
+                tags: z.record(z.string(), z.array(z.string())).optional().describe('Tag filters as key-value pairs'),
+                since: z.number().int().optional().describe('Unix timestamp lower bound'),
+                until: z.number().int().optional().describe('Unix timestamp upper bound'),
+                limit: z.number().int().min(1).max(500).optional().describe('Maximum number of events to count per relay'),
+                search: z.string().optional().describe('Full-text search query (NIP-50)'),
+            }, 'filter'),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ relays, kinds, authors, tags, since, until }) => {
+    }, async (args) => {
+        // Honour either the canonical top-level shape or a nested `filter` wrapper
+        // alias. Without the merge the MCP SDK strips the unknown top-level key and
+        // COUNT is sent with no selector, returning relay-wide totals.
+        const merged = mergeFlatAndWrapped(args, 'filter');
+        const relays = args.relays;
         const filter = {};
-        if (kinds?.length)
-            filter.kinds = kinds;
-        if (authors?.length)
-            filter.authors = authors;
-        if (since)
-            filter.since = since;
-        if (until)
-            filter.until = until;
-        if (tags) {
-            for (const [key, values] of Object.entries(tags)) {
+        if (merged.ids?.length)
+            filter.ids = merged.ids;
+        if (merged.kinds?.length)
+            filter.kinds = merged.kinds;
+        if (merged.authors?.length)
+            filter.authors = merged.authors;
+        if (merged.since)
+            filter.since = merged.since;
+        if (merged.until)
+            filter.until = merged.until;
+        if (merged.limit !== undefined)
+            filter.limit = merged.limit;
+        if (merged.search)
+            filter.search = merged.search;
+        if (merged.tags) {
+            for (const [key, values] of Object.entries(merged.tags)) {
                 const tagKey = key.startsWith('#') ? key : `#${key}`;
                 filter[tagKey] = values;
             }

package/dist/social/tools.js

@@ -3,6 +3,7 @@ import { hexId } from '../validation.js';
 import { resolveRecipient, resolveRecipients, resolveWithProfile } from '../resolve.js';
 import { toolResponse } from '../tool-response.js';
 import * as fmt from '../format.js';
+import { flatOrWrapped, mergeFlatAndWrapped } from '../util/schema.js';
 import { VeilScoring } from '../veil/scoring.js';
 import { TrustCache } from '../veil/cache.js';
 import { handleSocialPost, handleSocialReply, handleSocialReact, handleSocialProfileGet, handleSocialProfileSet, handleContactsGet, handleContactsSearch, handleContactsFollow, handleContactsUnfollow, handleSocialDelete, handleSocialRepost, handlePublishEvent, } from './handlers.js';
@@ -121,24 +122,49 @@ export function registerSocialTools(server, deps) {
         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.',
+        description: 'Set the kind 0 profile for the active identity. Warns if profile already exists — set confirm: true to overwrite. Profile fields may be supplied either as top-level arguments or wrapped in a single "profile" object (both shapes are accepted).',
         inputSchema: {
-            name: z.string().optional().describe('Display name'),
-            about: z.string().optional().describe('About / bio text'),
-            picture: z.string().optional().describe('Profile picture URL'),
-            nip05: z.string().optional().describe('NIP-05 identifier'),
-            banner: z.string().optional().describe('Banner image URL'),
-            lud16: z.string().optional().describe('Lightning address'),
+            ...flatOrWrapped({
+                name: z.string().optional().describe('Display name'),
+                about: z.string().optional().describe('About / bio text'),
+                picture: z.string().optional().describe('Profile picture URL'),
+                nip05: z.string().optional().describe('NIP-05 identifier'),
+                banner: z.string().optional().describe('Banner image URL'),
+                lud16: z.string().optional().describe('Lightning address'),
+            }, 'profile'),
             confirm: z.boolean().default(false).describe('Set true to overwrite existing profile'),
         },
         annotations: { readOnlyHint: false, destructiveHint: true },
-    }, async ({ confirm, ...fields }) => {
-        // Filter out undefined fields
+    }, async (args) => {
+        // Honour either the canonical flat shape or a nested `profile` wrapper. The
+        // handler's own interface takes `{ profile, confirm }`, so clients reading
+        // that contract naturally send the wrapped shape. Without the merge the
+        // MCP SDK strips the unknown top-level key and `handleSocialProfileSet`
+        // receives an empty profile, which with `confirm: true` would wipe the
+        // user's kind 0 content.
+        const { confirm } = args;
+        const merged = mergeFlatAndWrapped(args, 'profile');
+        // Re-strip `confirm` which lives at the top level alongside the profile
+        // fields but is not part of the kind 0 content.
         const profile = {};
-        for (const [k, v] of Object.entries(fields)) {
+        for (const [k, v] of Object.entries(merged)) {
+            if (k === 'confirm')
+                continue;
             if (v !== undefined)
                 profile[k] = v;
         }
+        // Data-loss guard: refuse to publish a kind 0 event with no content even
+        // when `confirm: true` is set. This is belt-and-braces against future
+        // regressions of the wrapper-stripping bug: if every profile field is
+        // stripped somewhere upstream, we stop here rather than signing an empty
+        // event that would wipe the user's existing profile.
+        if (Object.keys(profile).length === 0) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            error: 'Refusing to publish an empty profile. Supply at least one field (name, about, picture, nip05, banner, or lud16), either at the top level or inside a "profile" object.',
+                        }, null, 2) }],
+            };
+        }
         const result = await handleSocialProfileSet(deps.ctx, deps.pool, { profile, confirm });
         if (!result.published && result.warning) {
             return {

package/dist/util/schema.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+/**
+ * Helpers for tools whose MCP clients send arguments in either a flat shape or
+ * a single nested wrapper object.
+ *
+ * Background
+ * ----------
+ * The MCP SDK normalises every tool's inputSchema into a strict `z.object` with
+ * default strip behaviour, which silently drops unknown top-level keys. For
+ * filter-like or options-like tools, real clients routinely reach for a natural
+ * wrapper name ("filter", "profile", "options") even when the tool exposes the
+ * underlying fields at the top level. Without an explicit alias, the wrapper is
+ * stripped and the handler runs against an empty argument set.
+ *
+ * Two bugs in this class (`execute-action` at catalog.ts and `relay-query` at
+ * relay/tools.ts) have already been fixed by hand with ad-hoc alias declarations
+ * and merge logic. This module factors that pattern out so every new filter- or
+ * options-shaped tool can opt in with one line at the schema and one line at the
+ * top of the handler.
+ *
+ * Usage
+ * -----
+ *   server.registerTool('my-tool', {
+ *     inputSchema: {
+ *       // Any non-wrapper fields (required or optional) declared as normal:
+ *       relays: z.array(z.string()),
+ *       // Then spread the wrapped subset alongside them:
+ *       ...flatOrWrapped({
+ *         kinds: z.array(z.number()).optional(),
+ *         authors: z.array(z.string()).optional(),
+ *       }, 'filter'),
+ *     },
+ *   }, async (args) => {
+ *     const merged = mergeFlatAndWrapped<{
+ *       kinds?: number[]; authors?: string[];
+ *     }>(args, 'filter')
+ *     // Use merged.kinds, merged.authors as normal.
+ *   })
+ */
+/**
+ * Build a zod input-schema fragment declaring a set of flat fields plus a
+ * single wrapper-object alias carrying the same fields.
+ *
+ * The returned object is a `ZodRawShape` ready to spread into an MCP tool's
+ * inputSchema. Every flat field is forwarded as-is so any required/optional
+ * semantics declared by the caller are preserved at the top level. The wrapper
+ * field is always optional and contains every flat field with `.optional()`
+ * applied, so a caller can supply any subset inside the wrapper.
+ *
+ * The wrapper is emitted as a named zod field, which means it survives both
+ * the MCP SDK's outer schema strip **and** the ActionCatalog's inner strip at
+ * `src/catalog.ts` (for catalog-routed tools).
+ */
+export declare function flatOrWrapped<F extends z.ZodRawShape>(flat: F, wrapperName: string): F & Record<string, z.ZodOptional<z.ZodObject<z.ZodRawShape>>>;
+/**
+ * Merge the wrapper object with the top-level fields of an MCP tool's args.
+ *
+ * Precedence: top-level values win on conflict. This preserves the canonical
+ * shape as authoritative while letting clients that only supplied the wrapper
+ * still have every field reach the handler. Fields present only in the wrapper
+ * fall through to the merged result, and the wrapper key itself is removed
+ * from the output.
+ *
+ * Unknown fields inside the wrapper are passed through verbatim -- zod has
+ * already validated them against the wrapper schema at the SDK boundary, so
+ * anything the handler sees in the wrapper was declared by the caller.
+ *
+ * Empty args or a missing wrapper both yield a copy of the original top-level
+ * fields with the wrapper key stripped, so callers can blindly pass the
+ * merged object into their existing handler shape.
+ */
+export declare function mergeFlatAndWrapped<T extends Record<string, unknown>>(args: Record<string, unknown> | undefined, wrapperName: string): T;

package/dist/util/schema.js

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+/**
+ * Helpers for tools whose MCP clients send arguments in either a flat shape or
+ * a single nested wrapper object.
+ *
+ * Background
+ * ----------
+ * The MCP SDK normalises every tool's inputSchema into a strict `z.object` with
+ * default strip behaviour, which silently drops unknown top-level keys. For
+ * filter-like or options-like tools, real clients routinely reach for a natural
+ * wrapper name ("filter", "profile", "options") even when the tool exposes the
+ * underlying fields at the top level. Without an explicit alias, the wrapper is
+ * stripped and the handler runs against an empty argument set.
+ *
+ * Two bugs in this class (`execute-action` at catalog.ts and `relay-query` at
+ * relay/tools.ts) have already been fixed by hand with ad-hoc alias declarations
+ * and merge logic. This module factors that pattern out so every new filter- or
+ * options-shaped tool can opt in with one line at the schema and one line at the
+ * top of the handler.
+ *
+ * Usage
+ * -----
+ *   server.registerTool('my-tool', {
+ *     inputSchema: {
+ *       // Any non-wrapper fields (required or optional) declared as normal:
+ *       relays: z.array(z.string()),
+ *       // Then spread the wrapped subset alongside them:
+ *       ...flatOrWrapped({
+ *         kinds: z.array(z.number()).optional(),
+ *         authors: z.array(z.string()).optional(),
+ *       }, 'filter'),
+ *     },
+ *   }, async (args) => {
+ *     const merged = mergeFlatAndWrapped<{
+ *       kinds?: number[]; authors?: string[];
+ *     }>(args, 'filter')
+ *     // Use merged.kinds, merged.authors as normal.
+ *   })
+ */
+/**
+ * Build a zod input-schema fragment declaring a set of flat fields plus a
+ * single wrapper-object alias carrying the same fields.
+ *
+ * The returned object is a `ZodRawShape` ready to spread into an MCP tool's
+ * inputSchema. Every flat field is forwarded as-is so any required/optional
+ * semantics declared by the caller are preserved at the top level. The wrapper
+ * field is always optional and contains every flat field with `.optional()`
+ * applied, so a caller can supply any subset inside the wrapper.
+ *
+ * The wrapper is emitted as a named zod field, which means it survives both
+ * the MCP SDK's outer schema strip **and** the ActionCatalog's inner strip at
+ * `src/catalog.ts` (for catalog-routed tools).
+ */
+export function flatOrWrapped(flat, wrapperName) {
+    const wrappedShape = {};
+    for (const [key, type] of Object.entries(flat)) {
+        // Each wrapper field is always optional so the caller can send any subset.
+        // `.optional()` on an already-optional zod type is idempotent, so this is
+        // safe whether the flat schema marked the field optional or not.
+        wrappedShape[key] = type.optional();
+    }
+    const wrapper = z.object(wrappedShape).optional().describe(`Alias: all ${wrapperName} fields wrapped in a single object. Merged with any ` +
+        'top-level fields; top-level values win on conflict.');
+    return {
+        ...flat,
+        [wrapperName]: wrapper,
+    };
+}
+/**
+ * Merge the wrapper object with the top-level fields of an MCP tool's args.
+ *
+ * Precedence: top-level values win on conflict. This preserves the canonical
+ * shape as authoritative while letting clients that only supplied the wrapper
+ * still have every field reach the handler. Fields present only in the wrapper
+ * fall through to the merged result, and the wrapper key itself is removed
+ * from the output.
+ *
+ * Unknown fields inside the wrapper are passed through verbatim -- zod has
+ * already validated them against the wrapper schema at the SDK boundary, so
+ * anything the handler sees in the wrapper was declared by the caller.
+ *
+ * Empty args or a missing wrapper both yield a copy of the original top-level
+ * fields with the wrapper key stripped, so callers can blindly pass the
+ * merged object into their existing handler shape.
+ */
+export function mergeFlatAndWrapped(args, wrapperName) {
+    if (!args)
+        return {};
+    const { [wrapperName]: wrapper, ...flat } = args;
+    const wrapperObj = (wrapper && typeof wrapper === 'object' ? wrapper : {});
+    const merged = { ...wrapperObj };
+    for (const [key, value] of Object.entries(flat)) {
+        // Top-level values win on conflict. Undefined counts as "not supplied"
+        // so a wrapper value can still surface through an unset top-level key.
+        if (value !== undefined)
+            merged[key] = value;
+    }
+    return merged;
+}

package/dist/util/tools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { hexId } from '../validation.js';
 import { resolveRecipient } from '../resolve.js';
+import { flatOrWrapped, mergeFlatAndWrapped } from './schema.js';
 import { handleKeyEncrypt, handleKeyDecrypt } from './ncryptsec.js';
 import { handleDecode, handleEncodeNpub, handleEncodeNote, handleEncodeNprofile, handleEncodeNevent, handleEncodeNaddr, handleVerify, handleCount, handleFetch, handleKeyPublic, handleEncodeNsec, handleFilter, handleNipList, handleNipShow, handleTombstone, } from './handlers.js';
 export function registerUtilTools(server, deps) {
@@ -96,21 +97,46 @@ export function registerUtilTools(server, deps) {
         return { content: [{ type: 'text', text: plaintext }] };
     });
     server.registerTool('count', {
-        description: 'Count events matching a filter on the active identity\'s relays.',
+        description: 'Count events matching a filter on the active identity\'s relays. Filter fields may be supplied either as top-level arguments or wrapped in a single "filter" object (both shapes are accepted).',
         inputSchema: {
-            kinds: z.array(z.number().int()).optional().describe('Event kinds to count'),
-            authors: z.array(hexId).optional().describe('Author hex pubkeys'),
-            since: z.number().optional().describe('Unix timestamp lower bound'),
+            ...flatOrWrapped({
+                ids: z.array(z.string()).optional().describe('Event IDs (hex) to count'),
+                kinds: z.array(z.number().int()).optional().describe('Event kinds to count'),
+                authors: z.array(hexId).optional().describe('Author hex pubkeys'),
+                tags: z.record(z.string(), z.array(z.string())).optional().describe('Tag filters as key-value pairs'),
+                since: z.number().int().optional().describe('Unix timestamp lower bound'),
+                until: z.number().int().optional().describe('Unix timestamp upper bound'),
+                limit: z.number().int().min(1).max(500).optional().describe('Maximum number of events to count'),
+                search: z.string().optional().describe('Full-text search query (NIP-50)'),
+            }, 'filter'),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ kinds, authors, since }) => {
+    }, async (args) => {
+        // Honour either the canonical top-level shape or a nested `filter` wrapper
+        // alias. Without the merge the MCP SDK strips the unknown top-level key and
+        // the count runs against an empty filter, inflating the result.
+        const merged = mergeFlatAndWrapped(args, 'filter');
         const filter = {};
-        if (kinds)
-            filter.kinds = kinds;
-        if (authors)
-            filter.authors = authors;
-        if (since)
-            filter.since = since;
+        if (merged.ids?.length)
+            filter.ids = merged.ids;
+        if (merged.kinds?.length)
+            filter.kinds = merged.kinds;
+        if (merged.authors?.length)
+            filter.authors = merged.authors;
+        if (merged.since)
+            filter.since = merged.since;
+        if (merged.until)
+            filter.until = merged.until;
+        if (merged.limit !== undefined)
+            filter.limit = merged.limit;
+        if (merged.search)
+            filter.search = merged.search;
+        if (merged.tags) {
+            for (const [key, values] of Object.entries(merged.tags)) {
+                const tagKey = key.startsWith('#') ? key : `#${key}`;
+                filter[tagKey] = values;
+            }
+        }
         const result = await handleCount(deps.pool, deps.ctx.activeNpub, filter);
         return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nostr-bray",
-  "version": "1.27.1",
+  "version": "1.27.3",
   "description": "Trust-aware Nostr for AI and humans. Three dimensions of trust -- verification, proximity, and access -- woven into every interaction.",
   "type": "module",
   "main": "dist/index.js",