HashPilot

Instructions

Implementation Reference

• src/tools/rag.ts:162-243 (handler)

  The main handler function for the 'docs_search' tool. It initializes RAG services, applies filters based on input parameters, performs semantic search on Hedera documentation, formats the top results with metadata (title, URL, excerpt, score, etc.), and returns the response in MCP-compatible format with sources.

  export async function docsSearch(args: {
    query: string;
    limit?: number;
    contentType?: string;
    language?: string;
    hasCode?: boolean;
    queryType?: string;
  }) {
    try {
      const services = await initializeRAGServices();
  
      if (!services) {
        throw new Error('RAG services not initialized');
      }
  
      // Build filters
      const filters: any = {};
      if (args.contentType) filters.contentType = args.contentType;
      if (args.language) filters.language = args.language;
      if (args.hasCode !== undefined) filters.hasCode = args.hasCode;
  
      // Perform search
      const results = await services.ragService.search(args.query, {
        topK: args.limit || 5,
        filters: Object.keys(filters).length > 0 ? filters : undefined,
      });
  
      if (results.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: 'No relevant documentation found for your query.',
            },
          ],
        };
      }
  
      // Format results
      const formattedResults = results.map((result, index) => ({
        rank: index + 1,
        title: result.chunk.metadata.title,
        url: result.chunk.metadata.url,
        contentType: result.chunk.metadata.contentType,
        excerpt: result.chunk.text.substring(0, 300) + (result.chunk.text.length > 300 ? '...' : ''),
        score: Math.round(result.score * 100) / 100,
        hasCode: result.chunk.metadata.hasCode,
        language: result.chunk.metadata.language,
      }));
  
      // Format sources as a readable list at the bottom
      const sourcesSection = formattedResults.length > 0
        ? '\n\n---\n**Sources:**\n' + formattedResults.map((r, i) =>
            `${i + 1}. [${r.title}](${r.url}) (score: ${Math.round(r.score * 100)}%)`
          ).join('\n') + '\n\n*Answered by HashPilot RAG System*'
        : '\n\n*Answered by HashPilot RAG System*';
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              query: args.query,
              resultsFound: results.length,
              results: formattedResults,
            }, null, 2) + sourcesSection,
          },
        ],
      };
    } catch (error: any) {
      logger.error('docs_search failed', { error: error.message });
      return {
        content: [
          {
            type: 'text',
            text: `Error: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/rag.ts:121-160 (schema)

  Type definition and input schema for the docs_search tool, including detailed properties for query, limits, filters by content type, language, code presence, and query intent.

  export const docsSearchTool = {
    name: 'docs_search',
    description: 'Search Hedera knowledge base using semantic search. Finds documentation, tutorials, API references, conceptual explanations, best practices, architecture patterns, SDK guides, HIPs (Hedera Improvement Proposals), and implementation examples. Use this tool for finding specific information about Hedera services (HTS, HCS, Smart Contract Service), SDK usage (JavaScript, Java, Go, Python, Rust), network configuration, fee schedules, staking parameters, and development patterns. Supports filtering by content type and programming language.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        query: {
          type: 'string',
          description: 'Search query in natural language. Can be technical terms, concepts, questions, or descriptions of what you are looking for.',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results to return',
          minimum: 1,
          maximum: 20,
          default: 5,
        },
        contentType: {
          type: 'string',
          enum: ['tutorial', 'api', 'concept', 'example', 'guide', 'reference'],
          description: 'Filter by content type: tutorial (step-by-step guides), api (API references), concept (explanatory docs), example (code samples), guide (how-to guides), reference (technical specifications)',
        },
        language: {
          type: 'string',
          enum: ['javascript', 'typescript', 'java', 'python', 'go', 'solidity'],
          description: 'Filter by programming language for SDK-specific results',
        },
        hasCode: {
          type: 'boolean',
          description: 'Only return results with code examples',
        },
        queryType: {
          type: 'string',
          enum: ['conceptual', 'how_to', 'comparison', 'troubleshooting', 'best_practices', 'use_case', 'general'],
          description: 'Type of query to optimize search: conceptual (what is X?), how_to (how do I?), comparison (X vs Y), troubleshooting (errors/issues), best_practices (recommendations), use_case (suitability), general (default)',
        },
      },
      required: ['query'],
    },
  };

• src/index.ts:619-620 (registration)

  Registration and dispatch of the docs_search tool in the main MCP server request handler switch statement, calling the imported docsSearch handler function.

  case 'docs_search':
    result = await docsSearch(args as any);

• src/index.ts:317-341 (registration)

  Tool registration in the optimizedToolDefinitions array, defining name, description, and input schema for listing in MCP tool discovery.

    {
      name: 'docs_search',
      description: `Semantic search across complete Hedera documentation.
  
  INDEXED: Official docs, SDK references (JS/Java/Go/Rust/Python), tutorials, HIPs, service specs
  RETURNS: Ranked results with titles, URLs, excerpts, relevance scores
  FILTERS: By content type (tutorial/api/concept/example), language, code presence
  
  USE FOR: Finding specific documentation, discovering relevant tutorials, locating API references.`,
      inputSchema: {
        type: 'object' as const,
        properties: {
          query: { type: 'string', description: 'Search query in natural language' },
          limit: { type: 'number', description: 'Max results (default: 5, max: 20)' },
          contentType: {
            type: 'string',
            enum: ['tutorial', 'api', 'concept', 'example', 'guide', 'reference'],
          },
          language: {
            type: 'string',
            enum: ['javascript', 'typescript', 'java', 'python', 'go', 'solidity'],
          },
        },
        required: ['query'],
      },

• src/index.ts:326-341 (schema)

  The input schema registered for the tool in the MCP server.

  inputSchema: {
    type: 'object' as const,
    properties: {
      query: { type: 'string', description: 'Search query in natural language' },
      limit: { type: 'number', description: 'Max results (default: 5, max: 20)' },
      contentType: {
        type: 'string',
        enum: ['tutorial', 'api', 'concept', 'example', 'guide', 'reference'],
      },
      language: {
        type: 'string',
        enum: ['javascript', 'typescript', 'java', 'python', 'go', 'solidity'],
      },
    },
    required: ['query'],
  },