HashPilot

Instructions

Implementation Reference

• src/tools/rag.ts:289-370 (handler)

  The main execution handler for the 'docs_ask' tool. Initializes RAG services, processes the question with intent detection, retrieves answer from ragService, formats response with sources and metadata.

  export async function docsAsk(args: {
    question: string;
    includeCodeExamples?: boolean;
    language?: string;
    contentType?: string;
    queryIntent?: string;
    expertiseLevel?: 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;
  
      // Auto-detect intent if not provided
      const detectedIntent = args.queryIntent || services.ragService.classifyQueryIntent(args.question);
      const expertiseLevel = args.expertiseLevel || 'intermediate';
  
      logger.info('Processing docs_ask with intent detection', {
        question: args.question.substring(0, 100),
        detectedIntent,
        providedIntent: args.queryIntent,
        expertiseLevel,
      });
  
      // Ask question with intent awareness
      const answer = await services.ragService.askQuestionWithIntent(args.question, {
        filters: Object.keys(filters).length > 0 ? filters : undefined,
        includeCodeExamples: args.includeCodeExamples || false,
        language: args.language,
        queryIntent: detectedIntent as any,
        expertiseLevel: expertiseLevel as any,
      });
  
      // Format response with enhanced metadata
      const response = {
        question: args.question,
        detectedIntent,
        expertiseLevel,
        answer: answer.answer,
        sources: answer.sources.map(source => ({
          title: source.title,
          url: source.url,
          relevance: Math.round(source.score * 100) / 100,
        })),
        hasCodeExamples: answer.hasCodeExamples,
        model: answer.model,
      };
  
      // Format sources as a readable list at the bottom
      const sourcesSection = answer.sources.length > 0
        ? '\n\n---\n**Sources:**\n' + answer.sources.map((source, i) =>
            `${i + 1}. [${source.title}](${source.url}) (relevance: ${Math.round(source.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(response, null, 2) + sourcesSection,
          },
        ],
      };
    } catch (error: any) {
      logger.error('docs_ask failed', { error: error.message });
      return {
        content: [
          {
            type: 'text',
            text: `Error: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/rag.ts:248-287 (schema)

  Tool definition including name, detailed description, and comprehensive input schema for 'docs_ask'.

  export const docsAskTool = {
    name: 'docs_ask',
    description: 'Answer ANY knowledge-based question about Hedera Network and ecosystem. Handles: conceptual questions (what is Hedera Consensus Service?), how-to questions (how to create tokens?), comparison questions (Hedera vs Ethereum, HTS vs ERC-20), best practices (security recommendations, gas optimization), troubleshooting (why did transaction fail?), architecture queries (how does hashgraph consensus work?), use case guidance (is Hedera suitable for my DeFi app?), security questions (auditing smart contracts), migration help (moving from Ethereum), SDK usage questions, network configuration, fee structures, staking mechanics, and any educational/learning questions. Returns AI-generated answers with source citations from official Hedera documentation, SDKs, HIPs, and tutorials. USE THIS TOOL FOR ALL QUESTIONS ABOUT HEDERA THAT DO NOT REQUIRE EXECUTING AN ACTION ON THE BLOCKCHAIN.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        question: {
          type: 'string',
          description: 'Any question about Hedera in natural language. Can be conceptual, technical, comparative, or practical.',
        },
        includeCodeExamples: {
          type: 'boolean',
          description: 'Include code examples in the answer when relevant',
          default: false,
        },
        language: {
          type: 'string',
          enum: ['javascript', 'typescript', 'java', 'python', 'go', 'solidity'],
          description: 'Preferred programming language for code examples',
        },
        contentType: {
          type: 'string',
          enum: ['tutorial', 'api', 'concept', 'example', 'guide', 'reference'],
          description: 'Filter sources by content type',
        },
        queryIntent: {
          type: 'string',
          enum: ['conceptual', 'how_to', 'comparison', 'troubleshooting', 'best_practices', 'use_case', 'architecture', 'migration', 'security', 'general'],
          description: 'Intent of the question to provide more targeted answers: conceptual (explain X), how_to (steps to do Y), comparison (X vs Y), troubleshooting (fix error), best_practices (recommendations), use_case (suitability check), architecture (system design), migration (platform transition), security (safety/audits), general (default)',
        },
        expertiseLevel: {
          type: 'string',
          enum: ['beginner', 'intermediate', 'advanced'],
          description: 'User expertise level to adjust answer complexity and detail',
          default: 'intermediate',
        },
      },
      required: ['question'],
    },
  };

• src/index.ts:343-371 (registration)

  The 'docs_ask' tool is registered in the main tool definitions array used by the MCP server for listing tools.

    {
      name: 'docs_ask',
      description: `Answer ANY knowledge question about Hedera using RAG.
  
  HANDLES: Conceptual (what is X?), how-to (how do I?), comparison (X vs Y), troubleshooting, best practices, architecture, security
  RETURNS: Comprehensive answer with code examples and source citations
  EXPERTISE: Adjustable for beginner/intermediate/advanced levels
  
  USE FOR: Learning Hedera concepts, getting implementation guidance, understanding best practices.
  THIS IS YOUR PRIMARY TOOL FOR HEDERA KNOWLEDGE QUESTIONS.`,
      inputSchema: {
        type: 'object' as const,
        properties: {
          question: { type: 'string', description: 'Question about Hedera' },
          expertiseLevel: {
            type: 'string',
            enum: ['beginner', 'intermediate', 'advanced'],
            description: 'User expertise level',
          },
          includeCodeExamples: { type: 'boolean', description: 'Include code in answer' },
          language: {
            type: 'string',
            enum: ['javascript', 'typescript', 'java', 'python', 'go', 'solidity'],
            description: 'Preferred language for examples',
          },
        },
        required: ['question'],
      },
    },

• src/index.ts:622-623 (registration)

  The main request handler dispatches calls to 'docs_ask' by invoking the imported docsAsk function.

  case 'docs_ask':
    result = await docsAsk(args as any);

• src/index.ts:51-51 (registration)

  Import of the docsAsk handler function from the rag module.

  import { docsSearch, docsAsk, docsGetExample, codeGenerate } from './tools/rag.js';