search_documentation

Instructions

Implementation Reference

• src/index.ts:358-438 (handler)

  The main handler function that performs the API call to search Mercado Pago documentation, processes the results, formats them as Markdown, and returns the response.

    private async handleSearchDocumentation(args: SearchDocumentationArgs, context: RequestContext) {
      try {
        const response = await this.api.get<SearchResult[]>(
          '/docs/v1/search',
          {
            params: {
              term: args.query,
              lang: args.language,
              siteId: args.siteId,
              maxResults: args.limit || 10
            }
          }
        );
  
        const results = response.data;
        if (!results || !Array.isArray(results)) {
          throw new McpError(
            ErrorCode.InternalError,
            'No search results available for the given query'
          );
        }
  
        if (results.length === 0) {
          return {
            content: [
              {
                type: 'text',
                text: `No documentation found for query "${args.query}". Try a different search term.`
              }
            ]
          };
        }
  
        // Format results as markdown
        const markdown = results.map(result => {
          if (!result.title && !result.content) {
            this.logger.debug('Incomplete search result', { result });
            return null;  // Skip invalid results
          }
  
          const title = result.title || 'Untitled';
          const content = result.content || 'No description available';
          const siteDomain = DemoMercadoPagoServer.SITE_DOMAINS[args.siteId];
          const url = this.buildDocumentationUrl(siteDomain, args.language, result.url || '');
          const score = result.score || 0;
  
          return `## ${title}
  ${content}
  
  🔗 [Read more](${url})
  
  Score: ${score}
  `;
        }).join('\n\n---\n\n');
  
        const formattedResults = `# Search Results for "${args.query}"
  Showing ${results.length} results
  
  ${results.length > 0 ? markdown : 'No results found.'}`;
  
        return {
          content: [
            {
              type: 'text',
              text: formattedResults
            }
          ]
        };
      } catch (error) {
        const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
        return {
          content: [
            {
              type: 'text',
              text: `Error searching documentation: ${errorMessage}`
            }
          ],
          isError: true
        };
      }
    }

• src/index.ts:74-79 (schema)

  TypeScript interface defining the input arguments for the search_documentation tool.

  interface SearchDocumentationArgs {
    language: Language;  // maps to lang
    query: string;      // maps to term
    siteId: SiteId;     // Required parameter
    limit?: number;     // maps to maxResults
  }

• src/index.ts:267-300 (registration)

  Registration of the search_documentation tool in the ListTools response, including name, description, and input schema.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: 'search_documentation',
            description: 'Search Mercado Pago documentation',
            inputSchema: {
              type: 'object',
              properties: {
                language: {
                  type: 'string',
                  enum: ['es', 'pt'],
                  description: 'Language of the documentation (es: Spanish, pt: Portuguese)'
                },
                query: {
                  type: 'string',
                  description: 'Search query'
                },
                siteId: {
                  type: 'string',
                  description: 'Site ID for documentation',
                  enum: ['MLB', 'MLM', 'MLA', 'MLU', 'MLC', 'MCO', 'MPE']
                },
                limit: {
                  type: 'number',
                  description: 'Maximum number of results to return (default: 10)',
                  minimum: 1,
                  maximum: 100
                }
              },
              required: ['language', 'query', 'siteId']
        }
      }
    ],
  }));

• src/index.ts:307-314 (registration)

  Dispatch logic in CallToolRequest handler that routes calls to search_documentation to its handler.

  if (request.params.name === 'search_documentation') {
    if (this.isSearchDocumentationArgs(request.params.arguments)) {
      const result = await this.handleSearchDocumentation(request.params.arguments, context);
      this.logRequestEnd(context);
      return result;
    }
    throw new McpError(ErrorCode.InvalidParams, 'Invalid search_documentation arguments');
  }

• src/index.ts:348-356 (helper)

  Type guard helper function to validate input arguments for search_documentation.

  private isSearchDocumentationArgs(args: unknown): args is SearchDocumentationArgs {
    if (!args || typeof args !== 'object') return false;
    const a = args as any;
    const validLanguage = (a.language && ['es', 'pt'].includes(a.language as Language));
    const validQuery = typeof a.query === 'string';
    const validSiteId = (a.siteId && DemoMercadoPagoServer.VALID_SITES.includes(a.siteId as SiteId));
    const validLimit = a.limit === undefined || (typeof a.limit === 'number' && a.limit >= 1 && a.limit <= 100);
    return validLanguage && validQuery && validSiteId && validLimit;
  }