Nostr MCP Server

Instructions

Implementation Reference

• index.ts:1051-1095 (registration)

  MCP server.tool registration for the 'analyzeNip19' tool. Specifies the tool name, description, input schema (analyzeNip19ToolConfig), and the handler function that calls analyzeNip19, formats the result, and returns MCP-standard content blocks.
  server.tool( "analyzeNip19", "Analyze any NIP-19 entity or hex string to understand its type and contents", analyzeNip19ToolConfig, async ({ input }) => { try { const result = await analyzeNip19(input); if (result.success) { let response = `Analysis successful!\n\n`; response += `Type: ${result.type}\n\n`; response += formatAnalysisResult(result.type!, result.data); return { content: [ { type: "text", text: response, }, ], }; } else { return { content: [ { type: "text", text: `Analysis failed: ${result.message}`, }, ], }; } } catch (error) { console.error("Error in analyzeNip19 tool:", error); return { content: [ { type: "text", text: `Error during analysis: ${error instanceof Error ? error.message : "Unknown error"}`, }, ], }; } }, );
• utils/nip19-tools.ts:14-17 (schema)

  Zod input schema for the analyzeNip19 tool, validating a single string parameter.
  // Schema for analyzeNip19 tool export const analyzeNip19ToolConfig = { input: z.string().describe("The NIP-19 entity or hex string to analyze"), };
• utils/nip19-tools.ts:69-94 (handler)

  Primary handler function 'analyzeNip19' that wraps the core analysis logic, calls analyzeNip19Entity from conversion.ts, handles errors, and returns a standardized result object. Called by the MCP registration handler.
  export async function analyzeNip19( input: string ): Promise<{ success: boolean, message: string, type?: string, data?: any }> { try { const result = analyzeNip19Entity(input); if (!result.success) { return { success: false, message: result.message || 'Analysis failed' }; } return { success: true, message: result.message || 'Analysis successful', type: result.originalType, data: result.data }; } catch (error) { return { success: false, message: `Error during analysis: ${error instanceof Error ? error.message : 'Unknown error'}` }; } }
• utils/conversion.ts:340-389 (helper)

  Core helper function 'analyzeNip19Entity' that performs the actual NIP-19 decoding and analysis using the 'snstr' library's decode function. Detects hex strings or NIP-19 bech32 entities, applies relay URL filtering for security, and returns the entity type and data.
  export function analyzeNip19Entity(input: string): ConversionResult { try { const cleanInput = input.trim(); // Check if hex if (/^[0-9a-fA-F]{64}$/.test(cleanInput)) { return { success: true, originalType: 'hex', message: 'Valid 64-character hex string', data: cleanInput.toLowerCase() }; } // Try to decode as NIP-19 if (cleanInput.includes('1')) { const decoded = decode(cleanInput as `${string}1${string}`); // Apply security filtering for complex types let safeData = decoded.data; if (['nprofile', 'nevent', 'naddr'].includes(decoded.type)) { if (decoded.type === 'nprofile') { safeData = filterProfile(decoded.data); } else if (decoded.type === 'nevent') { safeData = filterEvent(decoded.data); } else if (decoded.type === 'naddr') { safeData = filterAddress(decoded.data); } } return { success: true, originalType: decoded.type, message: `Valid ${decoded.type} entity`, data: safeData }; } return { success: false, message: 'Input is not a valid NIP-19 entity or hex string' }; } catch (error) { return { success: false, message: `Analysis failed: ${error instanceof Error ? error.message : 'Unknown error'}` }; } }
• utils/nip19-tools.ts:96-141 (helper)

  Helper function 'formatAnalysisResult' used to generate human-readable output strings for different NIP-19 entity types, called in both the wrapper handler and MCP handler.
  /** * Format analysis result for display */ export function formatAnalysisResult(type: string, data: any): string { switch (type) { case 'hex': return `Hex String: ${data}`; case 'npub': return `Public Key (npub): ${data}`; case 'nsec': return `Private Key (nsec): ${data}`; case 'note': return `Note ID: ${data}`; case 'nprofile': return [ `Profile Entity:`, ` Public Key: ${data.pubkey}`, ` Relays: ${data.relays?.length ? data.relays.join(', ') : 'None'}` ].join('\n'); case 'nevent': return [ `Event Entity:`, ` Event ID: ${data.id}`, ` Author: ${data.author || 'Not specified'}`, ` Kind: ${data.kind || 'Not specified'}`, ` Relays: ${data.relays?.length ? data.relays.join(', ') : 'None'}` ].join('\n'); case 'naddr': return [ `Address Entity:`, ` Identifier: ${data.identifier}`, ` Public Key: ${data.pubkey}`, ` Kind: ${data.kind}`, ` Relays: ${data.relays?.length ? data.relays.join(', ') : 'None'}` ].join('\n'); default: return `Unknown type: ${type}`; } }