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}`;
    }
  }