search_documents

Instructions

Implementation Reference

• iia_mcp_server.ts:338-376 (handler)

  Core handler function that executes the search_documents tool. Searches the indexed documents based on query, filters by optional category, limits results, calculates relevance, extracts excerpts, formats output for MCP response.

  private async searchDocuments(query: string, category?: string, limit: number = 10): Promise<any> {
    const results: SearchResult[] = [];
    
    for (const [filePath, metadata] of this.documentIndex.entries()) {
      if (category && metadata.category !== category) {
        continue;
      }
  
      const relevance = this.calculateRelevance(query, metadata, filePath);
      if (relevance > 0) {
        const content = await this.getDocumentContent(filePath);
        const excerpt = this.extractExcerpt(content, query);
        
        results.push({
          file: filePath,
          title: metadata.title,
          category: metadata.category,
          relevance,
          excerpt,
        });
      }
    }
  
    results.sort((a, b) => b.relevance - a.relevance);
    const topResults = results.slice(0, limit);
  
    const formattedResults = topResults.map(result => 
      `**${result.title}** (${result.category})\n${result.excerpt}\n*File: ${result.file}*`
    ).join('\n\n---\n\n');
  
    return {
      content: [
        {
          type: 'text',
          text: `Found ${results.length} documents matching "${query}":\n\n${formattedResults}`,
        },
      ],
    };
  }

• iia_mcp_server.ts:205-229 (registration)

  Tool registration in the ListTools handler, defining name, description, and input schema.

  {
    name: 'search_documents',
    description: 'Search IIA documents by keywords, standard numbers, or topics',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query (keywords, standard number, or topic)',
        },
        category: {
          type: 'string',
          description: 'Filter by category (standards, guidance, topics, glossary)',
          enum: ['standards', 'guidance', 'topics', 'glossary'],
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results to return',
          default: 10,
        },
      },
      required: ['query'],
    },
  },
  {

• iia_mcp_server.ts:29-35 (schema)

  Type definition for search results used in the handler.

  interface SearchResult {
    file: string;
    title: string;
    category: string;
    relevance: number;
    excerpt: string;
  }

• iia_mcp_server.ts:378-408 (helper)

  Helper function to calculate relevance score for documents matching the search query.

  private calculateRelevance(query: string, metadata: DocumentMetadata, filePath: string): number {
    const lowerQuery = query.toLowerCase();
    let score = 0;
  
    // Exact standard number match
    if (metadata.standardNumber === query) {
      score += 100;
    }
  
    // Title matches
    if (metadata.title.toLowerCase().includes(lowerQuery)) {
      score += 50;
    }
  
    // Tag matches
    if (metadata.tags.some(tag => tag.toLowerCase().includes(lowerQuery))) {
      score += 30;
    }
  
    // Filename matches
    if (filePath.toLowerCase().includes(lowerQuery)) {
      score += 20;
    }
  
    // Partial standard number match
    if (metadata.standardNumber && metadata.standardNumber.includes(query)) {
      score += 40;
    }
  
    return score;
  }

• iia_mcp_server.ts:410-423 (helper)

  Helper function to extract relevant excerpt from document content around the query match.

  private extractExcerpt(content: string, query: string): string {
    const lines = content.split('\n');
    const lowerQuery = query.toLowerCase();
    
    for (let i = 0; i < lines.length; i++) {
      if (lines[i].toLowerCase().includes(lowerQuery)) {
        const start = Math.max(0, i - 1);
        const end = Math.min(lines.length, i + 3);
        return lines.slice(start, end).join('\n').substring(0, 200) + '...';
      }
    }
    
    return lines.slice(0, 3).join('\n').substring(0, 200) + '...';
  }

• iia_mcp_server.ts:307-308 (registration)

  Dispatch case in CallToolRequestSchema handler that routes to the searchDocuments method.

  case 'search_documents':
    return this.searchDocuments(args.query, args.category, args.limit);