Paper Search MCP

Instructions

Implementation Reference

• src/mcp/handleToolCall.ts:347-370 (handler)

  MCP tool handler case for 'search_springer'. Validates API key, calls SpringerSearcher.search with parameters, formats and returns JSON response with paper results.

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

• src/mcp/schemas.ts:159-170 (schema)

  Zod input schema validation for search_springer tool parameters including query, filters, and pagination.

  export const SearchSpringerSchema = z
    .object({
      query: z.string().min(1),
      maxResults: z.number().int().min(1).max(100).optional().default(10),
      year: z.string().optional(),
      author: z.string().optional(),
      journal: z.string().optional(),
      subject: z.string().optional(),
      openAccess: z.boolean().optional(),
      type: z.enum(['Journal', 'Book', 'Chapter']).optional()
    })
    .strip();

• src/mcp/tools.ts:390-420 (registration)

  MCP tool registration entry for 'search_springer' including name, description, and input schema definition.

  {
    name: 'search_springer',
    description:
      'Search academic papers from Springer Nature database. Uses Metadata API by default (all content) or OpenAccess API when openAccess=true (full text available). Same API key works for both.',
    inputSchema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'Search query string' },
        maxResults: {
          type: 'number',
          minimum: 1,
          maximum: 100,
          description: 'Maximum number of results to return'
        },
        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' },
        subject: { type: 'string', description: 'Subject area filter' },
        openAccess: {
          type: 'boolean',
          description: 'Search only open access content'
        },
        type: {
          type: 'string',
          enum: ['Journal', 'Book', 'Chapter'],
          description: 'Publication type filter'
        }
      },
      required: ['query']
    }
  },

• src/platforms/SpringerSearcher.ts:105-234 (helper)

  Core search implementation in SpringerSearcher class. Handles API selection (Meta v2 or OpenAccess), builds query with filters, calls Springer API, parses responses, and returns Paper objects. Includes rate limiting, error handling, and fallback logic.

  async search(query: string, options: SearchOptions = {}): Promise<Paper[]> {
    const customOptions = options as any;
    if (!this.apiKey) {
      throw new Error('Springer API key is required');
    }
  
    const maxResults = Math.min(options.maxResults || 10, 100);
    const papers: Paper[] = [];
  
    try {
      // Decide which API to use
      let useOpenAccess = customOptions.openAccess === true;
      
      // If openAccess is requested and we haven't tested the API yet, test it
      if (useOpenAccess && this.hasOpenAccessAPI === undefined) {
        await this.testOpenAccessAPI();
      }
      
      // Fall back to Meta API if OpenAccess API is not available
      if (useOpenAccess && !this.hasOpenAccessAPI) {
        logDebug('OpenAccess API not available, using Meta API with filtering');
        useOpenAccess = false;
      }
      
      // Build query parameters
      const params: any = {
        q: query,
        api_key: useOpenAccess ? this.openAccessApiKey : this.apiKey,
        s: 1, // start index
        p: maxResults // page size
      };
  
      // Add filters - Note: Some filters may require premium access
      if (options.author) {
        const sanitizedAuthor = this.sanitizeQueryValue(options.author);
        params.q += ` name:"${sanitizedAuthor}"`;
      }
  
      if (options.journal) {
        const sanitizedJournal = this.sanitizeQueryValue(options.journal);
        params.q += ` pub:"${sanitizedJournal}"`;
      }
  
      if (options.year) {
        // Year filter may cause 403 for some API keys
        if (options.year.includes('-')) {
          const [startYear, endYear] = options.year.split('-');
          params.q += ` year:${startYear} TO ${endYear || '*'}`;
        } else {
          params.q += ` year:${options.year}`;
        }
      }
  
      if (customOptions.subject) {
        // Subject filter may cause 403 for some API keys
        const sanitizedSubject = this.sanitizeQueryValue(customOptions.subject);
        params.q += ` subject:"${sanitizedSubject}"`;
      }
  
      if (customOptions.type) {
        // Type filter generally works
        params.q += ` type:${customOptions.type}`;
      }
  
      await this.rateLimiter.waitForPermission();
  
      // Choose the appropriate API
      let response: any;
      if (useOpenAccess) {
        // Use OpenAccess API (if available)
        response = await this.openAccessClient.get<SpringerResponse>('/json', { params });
      } else {
        // Use Meta v2 API
        response = await this.metadataClient.get<SpringerResponse>('/json', { params });
      }
  
      // Handle different response structures
      // Meta v2 API: records contains the actual papers, result contains metadata
      // OpenAccess API: might use either records or result for the actual papers
      let results: SpringerResult[] = [];
      
      // For Meta v2 API, records is always the array of papers
      if (response.data.records && Array.isArray(response.data.records)) {
        results = response.data.records;
      } 
      // For older API versions or different response format
      else if (response.data.result && Array.isArray(response.data.result) && 
               response.data.result.length > 0 && 
               response.data.result[0].title) {
        // If result contains actual papers (has title field), use it
        results = response.data.result as SpringerResult[];
      }
      
      if (results && results.length > 0) {
        for (const result of results) {
          const paper = this.parseResult(result);
          if (paper) {
            // If openAccess filter was requested but using Meta API, filter results
            if (customOptions.openAccess && !useOpenAccess && result.openaccess !== 'true') {
              continue;
            }
            papers.push(paper);
          }
        }
      }
  
      return papers;
    } catch (error: any) {
      if (error.response?.status === 401) {
        this.handleHttpError(error, 'search');
      }
      if (error.response?.status === 403) {
        // Some filters require premium access
        logWarn('Springer API returned 403 - some filters may require premium access');
        // Try a simpler query without advanced filters
        if (options.year || customOptions.subject) {
          logDebug('Retrying without year/subject filters...');
          const simpleOptions = { ...options };
          delete simpleOptions.year;
          delete (simpleOptions as any).subject;
          return this.search(query, simpleOptions);
        }
        this.handleHttpError(error, 'search');
      }
      if (error.response?.status === 429) {
        this.handleHttpError(error, 'search');
      }
      this.handleHttpError(error, 'search');
    }
  }

• src/mcp/searchers.ts:37-81 (helper)

  Initializes all searchers including SpringerSearcher instance using environment variables, making it available as searchers.springer for tool handlers.

  export function initializeSearchers(): Searchers {
    if (searchers) return searchers;
  
    logDebug('Initializing searchers...');
  
    const arxivSearcher = new ArxivSearcher();
    const wosSearcher = new WebOfScienceSearcher(process.env.WOS_API_KEY, process.env.WOS_API_VERSION);
    const pubmedSearcher = new PubMedSearcher(process.env.PUBMED_API_KEY);
    const biorxivSearcher = new BioRxivSearcher('biorxiv');
    const medrxivSearcher = new MedRxivSearcher();
    const semanticSearcher = new SemanticScholarSearcher(process.env.SEMANTIC_SCHOLAR_API_KEY);
    const iacrSearcher = new IACRSearcher();
    const googleScholarSearcher = new GoogleScholarSearcher();
    const sciHubSearcher = new SciHubSearcher();
    const scienceDirectSearcher = new ScienceDirectSearcher(process.env.ELSEVIER_API_KEY);
    const springerSearcher = new SpringerSearcher(
      process.env.SPRINGER_API_KEY,
      process.env.SPRINGER_OPENACCESS_API_KEY
    );
    const wileySearcher = new WileySearcher(process.env.WILEY_TDM_TOKEN);
    const scopusSearcher = new ScopusSearcher(process.env.ELSEVIER_API_KEY);
    const crossrefSearcher = new CrossrefSearcher(process.env.CROSSREF_MAILTO);
  
    searchers = {
      arxiv: arxivSearcher,
      webofscience: wosSearcher,
      pubmed: pubmedSearcher,
      wos: wosSearcher,
      biorxiv: biorxivSearcher,
      medrxiv: medrxivSearcher,
      semantic: semanticSearcher,
      iacr: iacrSearcher,
      googlescholar: googleScholarSearcher,
      scholar: googleScholarSearcher,
      scihub: sciHubSearcher,
      sciencedirect: scienceDirectSearcher,
      springer: springerSearcher,
      wiley: wileySearcher,
      scopus: scopusSearcher,
      crossref: crossrefSearcher
    };
  
    logDebug('Searchers initialized successfully');
    return searchers;
  }