Advanced Paper Search

Instructions

Implementation Reference

• src/index.ts:152-212 (registration)

  Registration of the search_papers_advanced tool, including schema definition with Zod and the inline async handler that performs validation, API call via client, formatting, and error handling.

  server.registerTool(
    "search_papers_advanced",
    {
      title: "Advanced Paper Search",
      description: "Advanced paper search functionality supporting multiple search criteria",
      inputSchema: {
        keyword: z.string().optional().describe("Search keyword"),
        venue: z.string().optional().describe("Venue/journal name"),
        author: z.string().optional().describe("Author name"),
        page: z.number().min(0).default(0).describe("Page number, starting from 0"),
        size: z.number().min(1).max(10).default(10).describe("Number of papers per page, maximum 10"),
        order: z.enum(["year", "n_citation"]).optional().describe("Sort order: year (by publication year) or n_citation (by citation count)")
      }
    },
    async ({ keyword, venue, author, page, size, order }) => {
      try {
        // Validate at least one search condition is provided
        if (!keyword && !venue && !author) {
          return {
            content: [{
              type: "text",
              text: JSON.stringify({
                error: "Validation Error",
                message: "At least one of keyword, venue, or author must be provided"
              }, null, 2)
            }],
            isError: true
          };
        }
  
        const result = await aminerClient.searchPapers({
          keyword,
          venue,
          author,
          page,
          size,
          order
        });
        
        const formattedResult = aminerClient.formatSearchResults(result);
        
        return {
          content: [{
            type: "text",
            text: JSON.stringify(formattedResult, null, 2)
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: "text",
            text: JSON.stringify({
              error: "Search failed",
              message: error instanceof Error ? error.message : 'Unknown error'
            }, null, 2)
          }],
          isError: true
        };
      }
    }
  );

• src/aminer-client.ts:27-94 (handler)

  Core implementation of paper search logic: constructs query parameters from inputs, makes authenticated GET request to AMiner API, validates and parses response, computes pagination info, handles various errors.

  async searchPapers(params: SearchParams): Promise<SearchResult> {
    // Validate required parameters
    if (!params.keyword && !params.venue && !params.author) {
      throw new Error('At least one of keyword, venue, or author must be provided');
    }
  
    if (params.size > 10) {
      throw new Error('Size parameter cannot exceed 10');
    }
  
    // Build query parameters
    const searchParams = new URLSearchParams();
    if (params.keyword) searchParams.append('keyword', params.keyword);
    if (params.venue) searchParams.append('venue', params.venue);
    if (params.author) searchParams.append('author', params.author);
    searchParams.append('page', params.page.toString());
    searchParams.append('size', params.size.toString());
    if (params.order) searchParams.append('order', params.order);
  
    const url = `${this.config.baseUrl}?${searchParams.toString()}`;
  
    try {
      const response = await fetch(url, {
        method: 'GET',
        headers: {
          'Authorization': this.config.apiKey,
          'Content-Type': 'application/json',
        },
      });
  
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
      }
  
      const data = await response.json() as AminerSearchResponse;
  
      // Add detailed response data check
      if (!data) {
        throw new Error('API returned empty response');
      }
  
      if (!data.success) {
        throw new Error(`API Error (${data.code}): ${data.msg}`);
      }
  
      // Check the completeness of the response data
      if (typeof data.total !== 'number') {
        console.warn('API response missing or invalid total field, defaulting to 0');
      }
  
      // Ensure data.data is not null, if it is null, use an empty array
      const papers = data.data || [];
      const total = data.total || 0;
  
      return {
        papers,
        total,
        page: params.page,
        size: params.size,
        hasMore: (params.page + 1) * params.size < total,
      };
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`Failed to search papers: ${error.message}`);
      }
      throw new Error('Unknown error occurred while searching papers');
    }
  }

• src/aminer-client.ts:165-198 (helper)

  Helper function called by the tool handler to format raw search results into a structured JSON response with summary statistics, indexed papers (formatted via formatPaper), and pagination details.

  formatSearchResults(result: SearchResult): SearchResultFormatted {
    const { papers, total, page, size, hasMore } = result;
    
    // Ensure papers is not null or undefined
    const formattedPapers = papers && Array.isArray(papers) 
      ? papers.map((paper, index) => {
          const formattedPaper = this.formatPaper(paper);
          // Only process successfully formatted papers, skip error results
          if ('error' in formattedPaper) {
            return null;
          }
          return {
            index: page * size + index + 1,
            ...formattedPaper
          };
        }).filter((paper): paper is NonNullable<typeof paper> => paper !== null)
      : [];
  
    return {
      summary: {
        total,
        page: page + 1,
        size,
        hasMore,
        currentPageResults: formattedPapers.length
      },
      papers: formattedPapers,
      pagination: {
        currentPage: page + 1,
        nextPage: hasMore ? page + 2 : null,
        previousPage: page > 0 ? page : null
      }
    };
  }

• src/aminer-client.ts:120-160 (helper)

  Helper function to format individual raw paper data from AMiner API into a clean, user-friendly structure, preferring Chinese fields where available, handling missing data gracefully.

  formatPaper(paper: AminerPaper | null | undefined): Paper | ErrorResult {
    // Add empty value check
    if (!paper) {
      return {
        error: "Invalid Paper Data",
        message: "No paper information available."
      };
    }
  
    const title = paper.title_zh || paper.title || 'N/A';
    const authors = paper.authors && Array.isArray(paper.authors) 
      ? paper.authors.map((author) => ({
          name: author?.name_zh || author?.name || 'Unknown',
          org: author?.org || null
        }))
      : [];
    const venue = paper.venue ? {
      name_zh: paper.venue.name_zh || null,
      name_en: paper.venue.name_en || null,
      alias: paper.venue.alias || null
    } : null;
    const year = paper.year || null;
    const citations = paper.n_citation || 0;
    const abstract = paper.abstract_zh || paper.abstract || null;
    const doi = paper.doi || null;
    const url = paper.url || null;
    const keywords = paper.keywords_zh || paper.keywords || [];
  
    return {
      title,
      authors,
      venue,
      year,
      citations,
      abstract,
      doi,
      url,
      keywords,
      language: paper.language || null
    };
  }

• src/types.ts:60-67 (schema)

  TypeScript interface defining the SearchParams used by searchPapers method, matching the Zod inputSchema of the MCP tool.

  export interface SearchParams {
    keyword?: string;
    venue?: string;
    author?: string;
    page: number;
    size: number;
    order?: 'year' | 'n_citation';
  }