Paper Search MCP

Instructions

Implementation Reference

• src/mcp/handleToolCall.ts:382-406 (handler)

  Tool handler case for 'search_scopus': validates API key, extracts parameters, calls ScopusSearcher.search(), formats and returns results as JSON text.

  case 'search_scopus': {
    const { query, maxResults, year, author, journal, affiliation, subject, openAccess, documentType } = args;
    if (!process.env.ELSEVIER_API_KEY) {
      throw new Error('Elsevier API key not configured. Please set ELSEVIER_API_KEY environment variable.');
    }
  
    const results = await searchers.scopus.search(query, {
      maxResults,
      year,
      author,
      journal,
      affiliation,
      subject,
      openAccess,
      documentType
    } as any);
  
    return jsonTextResponse(
      `Found ${results.length} Scopus papers.\n\n${JSON.stringify(
        results.map((paper: Paper) => PaperFactory.toDict(paper)),
        null,
        2
      )}`
    );
  }

• src/platforms/ScopusSearcher.ts:162-243 (handler)

  Core implementation of Scopus search: constructs advanced query syntax, makes API request to /content/search/scopus, parses XML/JSON response entries into Paper objects using private parseEntry method.

  async search(query: string, options: SearchOptions = {}): Promise<Paper[]> {
    const customOptions = options as any;
    if (!this.apiKey) {
      throw new Error('Scopus API key is required');
    }
  
    const maxResults = Math.min(options.maxResults || 10, 25); // Scopus max is 25 per request
    const papers: Paper[] = [];
  
    try {
      // Build Scopus search query
      let searchQuery = `TITLE-ABS-KEY(${query})`;
      
      if (options.author) {
        searchQuery += ` AND AUTHOR(${options.author})`;
      }
      
      if (options.journal) {
        searchQuery += ` AND SRCTITLE(${options.journal})`;
      }
      
      if (customOptions.affiliation) {
        searchQuery += ` AND AFFIL(${customOptions.affiliation})`;
      }
      
      if (customOptions.subject) {
        searchQuery += ` AND SUBJAREA(${customOptions.subject})`;
      }
      
      if (options.year) {
        if (options.year.includes('-')) {
          const [startYear, endYear] = options.year.split('-');
          searchQuery += ` AND PUBYEAR > ${parseInt(startYear) - 1}`;
          if (endYear) {
            searchQuery += ` AND PUBYEAR < ${parseInt(endYear) + 1}`;
          }
        } else {
          searchQuery += ` AND PUBYEAR = ${options.year}`;
        }
      }
  
      if (customOptions.openAccess) {
        searchQuery += ' AND OPENACCESS(1)';
      }
      
      if (customOptions.documentType) {
        const docTypeMap: Record<string, string> = {
          'ar': 'Article',
          'cp': 'Conference Paper',
          're': 'Review',
          'bk': 'Book',
          'ch': 'Book Chapter'
        };
        searchQuery += ` AND DOCTYPE(${docTypeMap[customOptions.documentType]})`;
      }
  
      await this.rateLimiter.waitForPermission();
  
      const response = await this.client.get<ScopusSearchResponse>('/content/search/scopus', {
        params: {
          query: searchQuery,
          count: maxResults,
          start: 0,
          view: 'COMPLETE',
          field: 'dc:identifier,dc:title,dc:creator,prism:publicationName,prism:coverDate,prism:doi,prism:url,prism:volume,prism:issueIdentifier,prism:pageRange,citedby-count,dc:description,authkeywords,author,affiliation,openaccess,eid'
        }
      });
  
      const entries = response.data['search-results']?.entry || [];
  
      for (const entry of entries) {
        const paper = await this.parseEntry(entry);
        if (paper) {
          papers.push(paper);
        }
      }
  
      return papers;
    } catch (error: any) {
      this.handleHttpError(error, 'search');
    }
  }

• src/mcp/schemas.ts:178-190 (schema)

  Zod schema definition for search_scopus input validation: defines query (required), maxResults (1-25), filters for year/author/journal/affiliation/subject/openAccess/documentType.

  export const SearchScopusSchema = z
    .object({
      query: z.string().min(1),
      maxResults: z.number().int().min(1).max(25).optional().default(10),
      year: z.string().optional(),
      author: z.string().optional(),
      journal: z.string().optional(),
      affiliation: z.string().optional(),
      subject: z.string().optional(),
      openAccess: z.boolean().optional(),
      documentType: z.enum(['ar', 'cp', 're', 'bk', 'ch']).optional()
    })
    .strip();

• src/mcp/tools.ts:433-463 (registration)

  MCP tool registration: defines 'search_scopus' tool metadata including name, description, and inputSchema matching the Zod schema for MCP SDK compatibility.

  {
    name: 'search_scopus',
    description: 'Search the Scopus abstract and citation database (requires Elsevier API key)',
    inputSchema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'Search query string' },
        maxResults: {
          type: 'number',
          minimum: 1,
          maximum: 25,
          description: 'Maximum number of results (max 25 per request)'
        },
        year: { type: 'string', description: 'Year filter (e.g., "2023", "2020-2023")' },
        author: { type: 'string', description: 'Author name filter' },
        journal: { type: 'string', description: 'Journal name filter' },
        affiliation: { type: 'string', description: 'Institution/affiliation filter' },
        subject: { type: 'string', description: 'Subject area filter' },
        openAccess: {
          type: 'boolean',
          description: 'Filter for open access articles only'
        },
        documentType: {
          type: 'string',
          enum: ['ar', 'cp', 're', 'bk', 'ch'],
          description: 'Document type: ar=article, cp=conference paper, re=review, bk=book, ch=chapter'
        }
      },
      required: ['query']
    }
  },

• src/mcp/schemas.ts:266-273 (schema)

  Schema parsing dispatcher: routes 'search_scopus' arguments to SearchScopusSchema.parse() for runtime validation.

      case 'search_scopus':
        return SearchScopusSchema.parse(args);
      case 'search_crossref':
        return SearchCrossrefSchema.parse(args);
      default:
        return args;
    }
  }