search_scopus
Search the Scopus database for academic papers using filters like author, journal, year, and subject to find relevant research articles.
Instructions
Search the Scopus abstract and citation database (requires Elsevier API key)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query string | |
| maxResults | No | Maximum number of results (max 25 per request) | |
| year | No | Year filter (e.g., "2023", "2020-2023") | |
| author | No | Author name filter | |
| journal | No | Journal name filter | |
| affiliation | No | Institution/affiliation filter | |
| subject | No | Subject area filter | |
| openAccess | No | Filter for open access articles only | |
| documentType | No | Document type: ar=article, cp=conference paper, re=review, bk=book, ch=chapter |
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; } }