searchQuery

Instructions

Implementation Reference

• src/index.ts:211-291 (handler)

  The primary handler for the 'searchQuery' tool. Converts query to CID, searches the Cyber knowledge graph using cyberClient.search(), processes results, optionally retrieves and summarizes content from IPFS for top results, and formats output as content items.

  private async handleSearchQuery(args: {
    query: string;
    page?: number;
    retrieveContent?: boolean;
    limit?: number;
  }) {
    try {
      // Convert query to CID if necessary
      const queryCid = isValidCID(args.query) ? args.query : await getIpfsHash(args.query);
      const page = args.page || 0;
      const retrieveContent = args.retrieveContent || false;
      const limit = args.limit || 5;
  
      if (!this.cyberClient) {
        throw new Error('Cyber client not initialized');
      }
      
      let results;
      try {
        results = await this.cyberClient.search(queryCid, page);
      } catch (searchError: any) {
        // If particle not found, show the query and its hash
        if (searchError?.message?.includes('particle not found')) {
          return {
            content: [{
              type: 'text',
              text: `No particle found for query: "${args.query}"\nCalculated hash: ${queryCid}\n\nThis means no cyberlinks have been created from this particle yet.`
            }],
          };
        }
        throw searchError;
      }
  
      const contentItems: ContentItem[] = [];
  
      // Add header with search info
      contentItems.push({
        type: 'text',
        text: `Search results for: ${args.query}\nQuery CID: ${queryCid}\n\nFound ${results.result?.length || 0} cyberlinks`,
      });
  
      if (!results || !results.result || results.result.length === 0) {
        return { content: contentItems };
      }
  
      // Process each result
      for (let i = 0; i < results.result.length; i++) {
        const result = results.result[i];
        
        // Add result info
        contentItems.push({
          type: 'text',
          text: `\n--- Result ${i + 1} ---\nCID: ${result.particle}\nRank: ${result.rank || 'N/A'}`,
        });
  
        // Retrieve content if requested and within limit
        if (retrieveContent && i < limit) {
          const contentItem = await this.retrieveContentByCID(result.particle);
          
          // Add prefix for context
          if (contentItem.type === 'text' && contentItem.text && !contentItem.text.startsWith('Error')) {
            contentItem.text = `Content:\n${contentItem.text.length > 200 ? contentItem.text.substring(0, 200) + '...' : contentItem.text}`;
          }
          
          contentItems.push(contentItem);
        }
      }
  
      return { content: contentItems };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error searching: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:89-117 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining the name, description, and input schema for 'searchQuery'.

  {
    name: 'searchQuery',
    description: 'Search the Cyber knowledge graph and optionally retrieve content from IPFS',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query (CID or text)',
        },
        page: {
          type: 'number',
          description: 'Page number for pagination (default: 0)',
          default: 0,
        },
        retrieveContent: {
          type: 'boolean',
          description: 'Whether to retrieve actual content from IPFS gateway (default: false)',
          default: false,
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results to retrieve content for (default: 5)',
          default: 5,
        },
      },
      required: ['query'],
    },
  },

• src/index.ts:92-116 (schema)

  Input schema definition for the 'searchQuery' tool, specifying parameters like query (required), page, retrieveContent, and limit.

  inputSchema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: 'Search query (CID or text)',
      },
      page: {
        type: 'number',
        description: 'Page number for pagination (default: 0)',
        default: 0,
      },
      retrieveContent: {
        type: 'boolean',
        description: 'Whether to retrieve actual content from IPFS gateway (default: false)',
        default: false,
      },
      limit: {
        type: 'number',
        description: 'Maximum number of results to retrieve content for (default: 5)',
        default: 5,
      },
    },
    required: ['query'],
  },

• src/index.ts:293-318 (helper)

  Supporting helper function used by 'searchQuery' (and 'getCyberlink') to fetch content from IPFS via the Cyber gateway, handling text and images.

  private async retrieveContentByCID(cid: string): Promise<ContentItem> {
    try {
      const { content, mimeType, isImage } = await fetchContentFromGateway(
        this.config.cyberGateway,
        cid
      );
  
      if (isImage) {
        return {
          type: 'image',
          data: content, // base64 encoded image data
          mimeType,
        };
      } else {
        return {
          type: 'text',
          text: content,
        };
      }
    } catch (error) {
      return {
        type: 'text',
        text: `Error retrieving content: ${error instanceof Error ? error.message : String(error)}`,
      };
    }
  }