scholar-mcp 1.0.0

package/dist/research/utils.js

@@ -0,0 +1,54 @@
+import { createHash, randomUUID } from 'node:crypto';
+export const nowIso = () => new Date().toISOString();
+export const makeStableId = (parts, prefix) => {
+    const value = parts.filter(Boolean).join('|');
+    if (!value) {
+        return `${prefix}_${randomUUID()}`;
+    }
+    const digest = createHash('sha1').update(value).digest('hex').slice(0, 16);
+    return `${prefix}_${digest}`;
+};
+export const normalizeWhitespace = (input) => input.replace(/\s+/g, ' ').trim();
+export const normalizeDoi = (doi) => {
+    if (!doi) {
+        return null;
+    }
+    return doi
+        .trim()
+        .replace(/^https?:\/\/(dx\.)?doi\.org\//i, '')
+        .toLowerCase();
+};
+export const parseYear = (input) => {
+    if (typeof input === 'number' && Number.isInteger(input) && input >= 1000 && input <= 2100) {
+        return input;
+    }
+    if (typeof input === 'string') {
+        const match = input.match(/(?:19|20)\d{2}/);
+        if (match?.[0]) {
+            const year = Number.parseInt(match[0], 10);
+            if (year >= 1000 && year <= 2100) {
+                return year;
+            }
+        }
+    }
+    return null;
+};
+export const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+export const tokenizeForRanking = (input) => normalizeWhitespace(input)
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .split(' ')
+    .filter((token) => token.length >= 3);
+export const overlapScore = (a, b) => {
+    if (a.length === 0 || b.length === 0) {
+        return 0;
+    }
+    const bSet = new Set(b);
+    let overlap = 0;
+    for (const token of a) {
+        if (bSet.has(token)) {
+            overlap += 1;
+        }
+    }
+    return overlap / Math.max(a.length, b.length);
+};

package/dist/scholar/errors.js

@@ -0,0 +1,30 @@
+export class ScholarError extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.name = 'ScholarError';
+    }
+}
+export class ScholarFetchError extends ScholarError {
+    url;
+    status;
+    constructor(message, url, status, details) {
+        super(message, details);
+        this.url = url;
+        this.status = status;
+        this.name = 'ScholarFetchError';
+    }
+}
+export class ScholarBlockedError extends ScholarFetchError {
+    constructor(message, url, details) {
+        super(message, url, undefined, details);
+        this.name = 'ScholarBlockedError';
+    }
+}
+export class ScholarParseError extends ScholarError {
+    constructor(message, details) {
+        super(message, details);
+        this.name = 'ScholarParseError';
+    }
+}

package/dist/scholar/scholar-client.js

@@ -0,0 +1,99 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { ScholarBlockedError, ScholarFetchError } from './errors.js';
+const SCHOLAR_SEARCH_PATH = '/scholar';
+const SCHOLAR_CITATIONS_PATH = '/citations';
+const USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36';
+const BLOCK_PATTERNS = [
+    /detected unusual traffic/i,
+    /not a robot/i,
+    /please show you're not a robot/i,
+    /accounts\.google\.com\/v3\/signin/i,
+    /sorry\/index/i
+];
+const toSearchParams = (values) => {
+    const params = new URLSearchParams();
+    Object.entries(values).forEach(([key, value]) => {
+        if (value === undefined) {
+            return;
+        }
+        params.set(key, String(value));
+    });
+    return params;
+};
+export class ScholarClient {
+    config;
+    lastRequestAt = 0;
+    constructor(config) {
+        this.config = config;
+    }
+    async fetchScholarSearch(params) {
+        return this.fetchHtml(SCHOLAR_SEARCH_PATH, params);
+    }
+    async fetchAuthorProfile(authorId, language) {
+        return this.fetchHtml(SCHOLAR_CITATIONS_PATH, {
+            user: authorId,
+            hl: language
+        });
+    }
+    async fetchHtml(path, params) {
+        const requestUrl = new URL(path, this.config.scholarBaseUrl);
+        requestUrl.search = toSearchParams(params).toString();
+        let attempt = 0;
+        let lastError;
+        while (attempt <= this.config.scholarRetryAttempts) {
+            await this.waitBeforeRequest();
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.config.scholarTimeoutMs);
+            try {
+                const response = await fetch(requestUrl, {
+                    method: 'GET',
+                    headers: {
+                        'user-agent': USER_AGENT,
+                        accept: 'text/html,application/xhtml+xml'
+                    },
+                    signal: controller.signal
+                });
+                const html = await response.text();
+                if (!response.ok) {
+                    throw new ScholarFetchError(`Google Scholar returned HTTP ${response.status}`, requestUrl.toString(), response.status, { statusText: response.statusText });
+                }
+                this.assertNotBlocked(html, requestUrl.toString());
+                return { html, url: requestUrl.toString() };
+            }
+            catch (error) {
+                lastError = error;
+                const isLastAttempt = attempt >= this.config.scholarRetryAttempts;
+                if (isLastAttempt) {
+                    break;
+                }
+                await sleep(this.config.scholarRetryDelayMs);
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+            attempt += 1;
+        }
+        if (lastError instanceof Error) {
+            throw lastError;
+        }
+        throw new ScholarFetchError('Unknown Google Scholar fetch error', requestUrl.toString());
+    }
+    assertNotBlocked(html, url) {
+        if (BLOCK_PATTERNS.some((pattern) => pattern.test(html))) {
+            throw new ScholarBlockedError('Google Scholar blocked or challenged this request. Try slower request settings or run from a different network.', url);
+        }
+    }
+    async waitBeforeRequest() {
+        if (this.config.scholarRequestDelayMs <= 0) {
+            this.lastRequestAt = Date.now();
+            return;
+        }
+        const now = Date.now();
+        const elapsed = now - this.lastRequestAt;
+        const delay = this.config.scholarRequestDelayMs - elapsed;
+        if (delay > 0) {
+            await sleep(delay);
+        }
+        this.lastRequestAt = Date.now();
+    }
+}

package/dist/scholar/scholar-parser.js

@@ -0,0 +1,251 @@
+import { load } from 'cheerio';
+const TEXT_WHITESPACE = /\s+/g;
+const YEAR_REGEX = /(?:^|\D)((?:19|20)\d{2})(?:\D|$)/g;
+const AUTHOR_ID_REGEX = /[?&]user=([A-Za-z0-9_-]+)/;
+const normalizeText = (value) => value.replace(TEXT_WHITESPACE, ' ').trim();
+const parseNumber = (value) => {
+    const digits = value.replace(/[^\d]/g, '');
+    return digits.length === 0 ? 0 : Number.parseInt(digits, 10);
+};
+const parseNullableNumber = (value) => {
+    const digits = value.replace(/[^\d]/g, '');
+    if (digits.length === 0) {
+        return null;
+    }
+    return Number.parseInt(digits, 10);
+};
+const resolveUrl = (baseUrl, href) => {
+    if (!href) {
+        return null;
+    }
+    try {
+        return new URL(href, baseUrl).toString();
+    }
+    catch {
+        return null;
+    }
+};
+const extractYear = (input) => {
+    const years = [];
+    for (const match of input.matchAll(YEAR_REGEX)) {
+        const year = match[1];
+        if (year) {
+            years.push(Number.parseInt(year, 10));
+        }
+    }
+    return years.at(-1) ?? null;
+};
+const extractAuthorIds = (htmlChunk) => {
+    const ids = new Set();
+    for (const match of htmlChunk.matchAll(/[?&]user=([A-Za-z0-9_-]+)/g)) {
+        const authorId = match[1];
+        if (!authorId) {
+            continue;
+        }
+        ids.add(authorId);
+    }
+    return [...ids];
+};
+const extractAuthorIdsFromElement = ($, selector) => {
+    const ids = new Set();
+    $(selector).each((_, element) => {
+        const href = $(element).attr('href');
+        if (!href) {
+            return;
+        }
+        const match = href.match(AUTHOR_ID_REGEX);
+        if (match) {
+            const authorId = match[1];
+            if (authorId) {
+                ids.add(authorId);
+            }
+        }
+    });
+    return [...ids];
+};
+const parsePaperResult = (baseUrl, htmlChunk) => {
+    const $ = load(htmlChunk);
+    const titleAnchor = $('h3.gs_rt a').first();
+    const title = normalizeText(titleAnchor.text() || $('h3.gs_rt').first().text());
+    const authorsLine = normalizeText($('.gs_a').first().text());
+    const abstract = normalizeText($('.gs_rs').first().text());
+    let citedByCount = 0;
+    let citedByUrl = null;
+    let relatedArticlesUrl = null;
+    let versionsCount = 0;
+    let versionsUrl = null;
+    $('.gs_fl a').each((_, link) => {
+        const anchor = $(link);
+        const text = normalizeText(anchor.text());
+        const href = anchor.attr('href');
+        if (text.startsWith('Cited by')) {
+            citedByCount = parseNumber(text);
+            citedByUrl = resolveUrl(baseUrl, href);
+            return;
+        }
+        if (text.startsWith('Related articles')) {
+            relatedArticlesUrl = resolveUrl(baseUrl, href);
+            return;
+        }
+        const versionMatch = text.match(/^All\s+(\d+)\s+versions$/i);
+        if (versionMatch) {
+            const versionCount = versionMatch[1];
+            if (versionCount) {
+                versionsCount = Number.parseInt(versionCount, 10);
+            }
+            versionsUrl = resolveUrl(baseUrl, href);
+        }
+    });
+    const authorNode = $('.gs_a').first();
+    return {
+        title,
+        url: resolveUrl(baseUrl, titleAnchor.attr('href')),
+        authorsLine,
+        abstract,
+        year: extractYear(`${authorsLine} ${abstract}`),
+        citedByCount,
+        citedByUrl,
+        relatedArticlesUrl,
+        versionsCount,
+        versionsUrl,
+        pdfUrl: resolveUrl(baseUrl, $('.gs_ggsd a').first().attr('href')),
+        authorIds: extractAuthorIds($.html(authorNode) ?? '')
+    };
+};
+export const parseScholarSearchResult = (html, baseUrl, requestedUrl, query) => {
+    const $ = load(html);
+    const resultChunks = $('.gs_r.gs_or.gs_scl')
+        .toArray()
+        .map((el) => $.html(el))
+        .filter((chunk) => typeof chunk === 'string');
+    const papers = resultChunks.map((chunk) => parsePaperResult(baseUrl, chunk));
+    const nextHref = $('#gs_n a')
+        .toArray()
+        .map((el) => $(el))
+        .find((el) => normalizeText(el.text()).toLowerCase().includes('next'))
+        ?.attr('href');
+    let nextPageStart = null;
+    if (nextHref) {
+        try {
+            const nextUrl = new URL(nextHref, baseUrl);
+            const start = nextUrl.searchParams.get('start');
+            nextPageStart = start ? Number.parseInt(start, 10) : null;
+        }
+        catch {
+            nextPageStart = null;
+        }
+    }
+    const totalResultsText = normalizeText($('#gs_ab_md').first().text()) || null;
+    return {
+        query,
+        requestedUrl,
+        totalResultsText,
+        nextPageStart,
+        papers
+    };
+};
+export const extractAuthorIdsFromSearch = (html) => {
+    const $ = load(html);
+    const ids = new Set();
+    $('a[href*="/citations?user="]').each((_, element) => {
+        const href = $(element).attr('href');
+        if (!href) {
+            return;
+        }
+        const match = href.match(AUTHOR_ID_REGEX);
+        if (match) {
+            const authorId = match[1];
+            if (authorId) {
+                ids.add(authorId);
+            }
+        }
+    });
+    return [...ids];
+};
+const parseAuthorMetrics = ($) => {
+    const rows = $('#gsc_rsb_st tr').toArray();
+    let citationsAll = null;
+    let citationsSince = null;
+    let hIndexAll = null;
+    let hIndexSince = null;
+    let i10IndexAll = null;
+    let i10IndexSince = null;
+    rows.forEach((row) => {
+        const label = normalizeText($(row).find('td.gsc_rsb_sc1').text()).toLowerCase();
+        const values = $(row)
+            .find('td.gsc_rsb_std')
+            .toArray()
+            .map((cell) => normalizeText($(cell).text()));
+        if (!label || values.length === 0) {
+            return;
+        }
+        if (label.startsWith('citations')) {
+            citationsAll = parseNullableNumber(values[0] ?? '');
+            citationsSince = parseNullableNumber(values[1] ?? '');
+            return;
+        }
+        if (label.startsWith('h-index')) {
+            hIndexAll = parseNullableNumber(values[0] ?? '');
+            hIndexSince = parseNullableNumber(values[1] ?? '');
+            return;
+        }
+        if (label.startsWith('i10-index')) {
+            i10IndexAll = parseNullableNumber(values[0] ?? '');
+            i10IndexSince = parseNullableNumber(values[1] ?? '');
+        }
+    });
+    return {
+        citationsAll,
+        citationsSince,
+        hIndexAll,
+        hIndexSince,
+        i10IndexAll,
+        i10IndexSince
+    };
+};
+const parseAuthorPublication = ($, row, baseUrl) => {
+    const rowNode = $(row);
+    const titleAnchor = rowNode.find('.gsc_a_at').first();
+    const metadataRows = rowNode.find('.gs_gray').toArray().map((cell) => normalizeText($(cell).text()));
+    return {
+        title: normalizeText(titleAnchor.text()),
+        detailUrl: resolveUrl(baseUrl, titleAnchor.attr('href')),
+        authors: metadataRows[0] ?? '',
+        venue: metadataRows[1] ?? '',
+        year: parseNullableNumber(rowNode.find('.gsc_a_y .gsc_a_h').first().text() || rowNode.find('.gsc_a_y').first().text()),
+        citations: parseNumber(rowNode.find('.gsc_a_ac').first().text()),
+        citationsUrl: resolveUrl(baseUrl, rowNode.find('.gsc_a_ac').first().attr('href'))
+    };
+};
+export const parseScholarAuthorProfile = (html, baseUrl, authorId, maxPublications) => {
+    const $ = load(html);
+    const name = normalizeText($('#gsc_prf_in').text());
+    const affiliation = normalizeText($('.gsc_prf_il').first().text()) || null;
+    const verifiedLine = normalizeText($('#gsc_prf_ivh').text());
+    const verifiedEmailMatch = verifiedLine.match(/Verified email at ([^\s-][^\-]*)/i);
+    const publications = $('#gsc_a_b tr.gsc_a_tr')
+        .toArray()
+        .slice(0, maxPublications)
+        .map((row) => parseAuthorPublication($, row, baseUrl));
+    const profileAuthorIds = extractAuthorIdsFromElement($, '#gsc_prf_int a, .gs_a a');
+    const derivedAuthorId = profileAuthorIds[0] ?? authorId;
+    return {
+        authorId: derivedAuthorId,
+        authorName: name,
+        profileUrl: `${baseUrl}/citations?user=${encodeURIComponent(derivedAuthorId)}&hl=en`,
+        affiliation,
+        verifiedEmail: verifiedEmailMatch?.[1] ? normalizeText(verifiedEmailMatch[1]) : null,
+        homepageUrl: resolveUrl(baseUrl, $('#gsc_prf_ivh a').first().attr('href')),
+        interests: $('#gsc_prf_int a')
+            .toArray()
+            .map((el) => normalizeText($(el).text()))
+            .filter((interest) => interest.length > 0),
+        metrics: parseAuthorMetrics($),
+        publications
+    };
+};
+export const parseAuthorName = (html) => {
+    const $ = load(html);
+    const name = normalizeText($('#gsc_prf_in').first().text());
+    return name.length > 0 ? name : null;
+};

package/dist/scholar/scholar-service.js

@@ -0,0 +1,202 @@
+import { ScholarParseError } from './errors.js';
+import { extractAuthorIdsFromSearch, parseAuthorName, parseScholarAuthorProfile, parseScholarSearchResult } from './scholar-parser.js';
+import { ScholarClient } from './scholar-client.js';
+const normalizeName = (value) => value
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+const nameSimilarity = (requestedName, candidateName) => {
+    const requested = normalizeName(requestedName);
+    const candidate = normalizeName(candidateName);
+    if (!requested || !candidate) {
+        return 0;
+    }
+    if (requested === candidate) {
+        return 1;
+    }
+    if (candidate.includes(requested) || requested.includes(candidate)) {
+        return 0.9;
+    }
+    const requestedTokens = new Set(requested.split(' '));
+    const candidateTokens = new Set(candidate.split(' '));
+    let overlap = 0;
+    requestedTokens.forEach((token) => {
+        if (candidateTokens.has(token)) {
+            overlap += 1;
+        }
+    });
+    return overlap / Math.max(requestedTokens.size, candidateTokens.size, 1);
+};
+export class ScholarService {
+    client;
+    config;
+    logger;
+    constructor(client, config, logger) {
+        this.client = client;
+        this.config = config;
+        this.logger = logger;
+    }
+    static fromConfig(config, logger) {
+        return new ScholarService(new ScholarClient(config), config, logger);
+    }
+    async searchKeywords(input) {
+        const numResults = clamp(input.numResults, 1, this.config.scholarMaxResultsPerRequest);
+        const params = {
+            q: input.query,
+            hl: input.language,
+            as_sdt: '0,5',
+            num: numResults,
+            start: input.start
+        };
+        const { html, url } = await this.client.fetchScholarSearch(params);
+        const parsed = parseScholarSearchResult(html, this.config.scholarBaseUrl, url, input.query);
+        return {
+            ...parsed,
+            papers: parsed.papers.slice(0, numResults)
+        };
+    }
+    async searchAdvanced(input) {
+        const numResults = clamp(input.numResults, 1, this.config.scholarMaxResultsPerRequest);
+        const params = {
+            q: input.query,
+            hl: input.language,
+            as_sdt: '0,5',
+            num: numResults,
+            start: input.start,
+            as_sauthors: input.author,
+            as_epq: input.exactPhrase,
+            as_eq: input.excludeWords,
+            as_occt: input.titleOnly ? 'title' : undefined
+        };
+        if (input.yearRange) {
+            params.as_ylo = input.yearRange[0];
+            params.as_yhi = input.yearRange[1];
+        }
+        const { html, url } = await this.client.fetchScholarSearch(params);
+        const parsed = parseScholarSearchResult(html, this.config.scholarBaseUrl, url, input.query);
+        return {
+            ...parsed,
+            papers: parsed.papers.slice(0, numResults)
+        };
+    }
+    async getAuthorInfo(authorName, maxPublications, language) {
+        const publicationLimit = clamp(maxPublications, 1, this.config.scholarMaxResultsPerRequest);
+        try {
+            const authorId = await this.findBestAuthorId(authorName, language);
+            const { html } = await this.client.fetchAuthorProfile(authorId, language);
+            return parseScholarAuthorProfile(html, this.config.scholarBaseUrl, authorId, publicationLimit);
+        }
+        catch (error) {
+            this.logger.warn('Falling back to paper-based author summary', {
+                authorName,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            return this.buildAuthorFallback(authorName, publicationLimit, language);
+        }
+    }
+    async buildAuthorFallback(authorName, maxPublications, language) {
+        const search = await this.searchAdvanced({
+            query: authorName,
+            author: authorName,
+            numResults: maxPublications,
+            start: 0,
+            language
+        });
+        const publications = search.papers.map((paper) => ({
+            title: paper.title,
+            detailUrl: paper.url,
+            authors: paper.authorsLine,
+            venue: paper.authorsLine,
+            year: paper.year,
+            citations: paper.citedByCount,
+            citationsUrl: paper.citedByUrl
+        }));
+        return {
+            authorId: 'unresolved',
+            authorName,
+            profileUrl: `${this.config.scholarBaseUrl}/scholar?q=${encodeURIComponent(authorName)}`,
+            affiliation: null,
+            verifiedEmail: null,
+            homepageUrl: null,
+            interests: [],
+            metrics: {
+                citationsAll: null,
+                citationsSince: null,
+                hIndexAll: null,
+                hIndexSince: null,
+                i10IndexAll: null,
+                i10IndexSince: null
+            },
+            publications
+        };
+    }
+    async findBestAuthorId(authorName, language) {
+        const candidateIds = new Set();
+        const strategies = [
+            {
+                q: `"${authorName}"`,
+                as_sauthors: authorName
+            },
+            {
+                q: `${authorName} research`,
+                as_sauthors: authorName
+            },
+            {
+                q: authorName,
+                as_sauthors: authorName
+            }
+        ];
+        for (const strategy of strategies) {
+            const { html } = await this.client.fetchScholarSearch({
+                ...strategy,
+                hl: language,
+                as_sdt: '0,5',
+                num: this.config.scholarMaxResultsPerRequest
+            });
+            extractAuthorIdsFromSearch(html).forEach((id) => candidateIds.add(id));
+            if (candidateIds.size >= 10) {
+                break;
+            }
+        }
+        if (candidateIds.size === 0) {
+            throw new ScholarParseError(`Unable to discover a Google Scholar profile for "${authorName}".`);
+        }
+        const limitedCandidates = [...candidateIds].slice(0, 10);
+        let bestId = null;
+        let bestScore = 0;
+        for (const candidateId of limitedCandidates) {
+            try {
+                const { html } = await this.client.fetchAuthorProfile(candidateId, language);
+                const candidateName = parseAuthorName(html);
+                if (!candidateName) {
+                    continue;
+                }
+                const score = nameSimilarity(authorName, candidateName);
+                this.logger.debug('Evaluated author candidate', {
+                    requested: authorName,
+                    candidateId,
+                    candidateName,
+                    score
+                });
+                if (score > bestScore) {
+                    bestScore = score;
+                    bestId = candidateId;
+                }
+                if (score >= 0.98) {
+                    break;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        if (!bestId) {
+            throw new ScholarParseError(`Unable to match a Google Scholar profile to "${authorName}".`);
+        }
+        return bestId;
+    }
+}

package/dist/scholar/types.js

@@ -0,0 +1 @@
+export {};

package/dist/version.js

@@ -0,0 +1,14 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+export const getPackageVersion = () => {
+    try {
+        const pkg = require('../package.json');
+        if (typeof pkg.version === 'string' && pkg.version.trim().length > 0) {
+            return pkg.version;
+        }
+    }
+    catch {
+        // Fall through to static fallback.
+    }
+    return '0.0.0';
+};