scholar-mcp 1.0.0

package/dist/research/citation-service.js

@@ -0,0 +1,407 @@
+import { Cite } from '@citation-js/core';
+import '@citation-js/plugin-csl';
+import '@citation-js/plugin-bibtex';
+import '@citation-js/plugin-doi';
+import { clamp, normalizeDoi, normalizeWhitespace, overlapScore, tokenizeForRanking } from './utils.js';
+const styleTemplateMap = {
+    apa: 'apa',
+    ieee: 'ieee',
+    chicago: 'chicago-author-date',
+    vancouver: 'vancouver'
+};
+const extractQuery = (manuscriptText, cursorContext) => {
+    const context = (cursorContext && cursorContext.trim().length > 0 ? cursorContext : manuscriptText).slice(-2500);
+    const tokens = tokenizeForRanking(context).filter((token) => token.length > 3);
+    const counts = new Map();
+    for (const token of tokens) {
+        counts.set(token, (counts.get(token) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 12)
+        .map(([token]) => token)
+        .join(' ')
+        .trim();
+};
+const normalizeStyle = (style) => styleTemplateMap[style] ?? 'apa';
+const toCsl = (work) => {
+    const authorList = work.authors.map((author) => {
+        const parts = author.name.trim().split(/\s+/);
+        const family = parts.length > 1 ? parts[parts.length - 1] : parts[0] ?? author.name;
+        const given = parts.length > 1 ? parts.slice(0, -1).join(' ') : '';
+        return {
+            family,
+            given
+        };
+    });
+    const id = work.doi ? `doi:${work.doi}` : work.paperId;
+    return {
+        id,
+        type: 'article-journal',
+        DOI: work.doi ?? undefined,
+        title: work.title,
+        author: authorList,
+        issued: work.year
+            ? {
+                'date-parts': [[work.year]]
+            }
+            : undefined,
+        'container-title': work.venue ?? undefined,
+        URL: work.url ?? undefined
+    };
+};
+const formatSingleReference = (work, style, locale) => {
+    const csl = toCsl(work);
+    const cite = new Cite([csl]);
+    let formatted = '';
+    try {
+        formatted = cite
+            .format('bibliography', {
+            format: 'text',
+            template: normalizeStyle(style),
+            lang: locale
+        })
+            .trim();
+    }
+    catch {
+        const authorLabel = work.authors[0]?.name ?? 'Unknown';
+        const yearLabel = work.year ?? 'n.d.';
+        formatted = `${authorLabel} (${yearLabel}). ${work.title}.`;
+    }
+    let bibtex = '';
+    try {
+        bibtex = cite.format('bibtex').trim();
+    }
+    catch {
+        const key = (work.authors[0]?.name ?? 'work').replace(/[^a-zA-Z0-9]/g, '') + (work.year ?? 'nd');
+        bibtex = `@article{${key},\n  title={${work.title}},\n  year={${work.year ?? ''}}\n}`;
+    }
+    return {
+        id: String(csl.id ?? work.paperId),
+        csl,
+        formatted,
+        bibtex,
+        sourceWork: work
+    };
+};
+const buildInlineSuggestion = (style, works) => {
+    const first = works.slice(0, 3);
+    if (first.length === 0) {
+        return '';
+    }
+    if (style === 'ieee' || style === 'vancouver') {
+        return first.map((_, index) => `[${index + 1}]`).join(', ');
+    }
+    return first
+        .map((work) => {
+        const family = work.authors[0]?.name.split(' ').at(-1) ?? 'Unknown';
+        const year = work.year ?? 'n.d.';
+        return `(${family}, ${year})`;
+    })
+        .join('; ');
+};
+const parseNumericInlineCitations = (manuscriptText) => {
+    const numbers = new Set();
+    const invalidChunks = [];
+    for (const match of manuscriptText.matchAll(/\[([^\]]+)\]/g)) {
+        const inner = match[1]?.trim() ?? '';
+        if (!inner) {
+            continue;
+        }
+        const chunks = inner.split(/[;,]/).map((chunk) => chunk.trim()).filter((chunk) => chunk.length > 0);
+        let parsedChunk = false;
+        for (const chunk of chunks) {
+            const single = chunk.match(/^(\d{1,4})$/);
+            if (single?.[1]) {
+                numbers.add(Number.parseInt(single[1], 10));
+                parsedChunk = true;
+                continue;
+            }
+            const range = chunk.match(/^(\d{1,4})\s*[-–]\s*(\d{1,4})$/);
+            if (range?.[1] && range[2]) {
+                const start = Number.parseInt(range[1], 10);
+                const end = Number.parseInt(range[2], 10);
+                if (start <= end && end - start <= 100) {
+                    for (let value = start; value <= end; value += 1) {
+                        numbers.add(value);
+                    }
+                    parsedChunk = true;
+                    continue;
+                }
+            }
+        }
+        if (!parsedChunk) {
+            invalidChunks.push(`[${inner}]`);
+        }
+    }
+    return {
+        numbers: [...numbers].sort((a, b) => a - b),
+        invalidChunks
+    };
+};
+const parseAuthorYearCitations = (manuscriptText) => {
+    const citations = [];
+    for (const match of manuscriptText.matchAll(/\(([^()]*?(?:19|20)\d{2}[a-z]?[^()]*)\)/g)) {
+        const raw = match[0] ?? '';
+        const block = match[1] ?? '';
+        const parts = block.split(';').map((value) => normalizeWhitespace(value)).filter((value) => value.length > 0);
+        for (const part of parts) {
+            const authorMatch = part.match(/^([A-Z][A-Za-z'`\-]+)(?:\s+et al\.)?(?:\s*&\s+[A-Z][A-Za-z'`\-]+)?\s*,\s*(?:19|20)\d{2}[a-z]?/);
+            if (!authorMatch?.[1]) {
+                continue;
+            }
+            citations.push({
+                author: authorMatch[1],
+                raw
+            });
+        }
+    }
+    return citations;
+};
+const findReferenceYear = (reference) => {
+    if (reference.sourceWork.year) {
+        return reference.sourceWork.year;
+    }
+    const match = reference.formatted.match(/(?:19|20)\d{2}/);
+    return match?.[0] ? Number.parseInt(match[0], 10) : null;
+};
+const findReferenceTitle = (reference) => {
+    const title = normalizeWhitespace(reference.sourceWork.title ?? '');
+    if (title.length > 0) {
+        return title;
+    }
+    const parts = reference.formatted.split('.').map((part) => normalizeWhitespace(part));
+    const candidate = parts.find((part) => part.length > 10 && !/(?:19|20)\d{2}/.test(part));
+    return candidate ?? null;
+};
+const findReferenceAuthors = (reference) => {
+    if (reference.sourceWork.authors.length > 0) {
+        return reference.sourceWork.authors.map((author) => author.name).filter((name) => name.length > 0);
+    }
+    const authorPrefix = normalizeWhitespace(reference.formatted.split('(')[0] ?? '');
+    if (authorPrefix.length === 0) {
+        return [];
+    }
+    return authorPrefix
+        .split(/,|&| and /i)
+        .map((part) => normalizeWhitespace(part))
+        .filter((part) => part.length > 0);
+};
+const findReferenceSource = (reference) => {
+    const source = normalizeWhitespace(reference.sourceWork.venue ?? '');
+    if (source.length > 0) {
+        return source;
+    }
+    if (reference.sourceWork.url || reference.sourceWork.doi) {
+        return reference.sourceWork.url ?? reference.sourceWork.doi ?? null;
+    }
+    return null;
+};
+const buildCompletenessDiagnostic = (reference, index) => {
+    const missingElements = [];
+    const suggestions = [];
+    const authors = findReferenceAuthors(reference);
+    if (authors.length === 0) {
+        missingElements.push('author');
+    }
+    const year = findReferenceYear(reference);
+    if (!year) {
+        missingElements.push('year');
+    }
+    const title = findReferenceTitle(reference);
+    if (!title) {
+        missingElements.push('title');
+    }
+    const source = findReferenceSource(reference);
+    if (!source) {
+        missingElements.push('source');
+    }
+    const doi = normalizeDoi(reference.sourceWork.doi);
+    const hasUrl = Boolean(reference.sourceWork.url);
+    const hasPersistentIdentifier = Boolean(doi || hasUrl);
+    if (doi && !reference.formatted.toLowerCase().includes('doi.org/')) {
+        suggestions.push(`Reference ${index + 1}: include DOI as canonical URL (https://doi.org/${doi}).`);
+    }
+    if (!hasPersistentIdentifier) {
+        suggestions.push(`Reference ${index + 1}: add DOI or stable URL for traceability.`);
+    }
+    return {
+        referenceId: reference.id,
+        label: `[${index + 1}] ${reference.formatted}`,
+        missingElements,
+        missingPersistentIdentifier: !hasPersistentIdentifier,
+        suggestions
+    };
+};
+const findDuplicateReferences = (references) => {
+    const seen = new Map();
+    const duplicates = [];
+    references.forEach((reference, index) => {
+        const doi = normalizeDoi(reference.sourceWork.doi);
+        const title = normalizeWhitespace(reference.sourceWork.title ?? reference.formatted)
+            .toLowerCase()
+            .replace(/[^a-z0-9\s]/g, ' ')
+            .replace(/\s+/g, ' ')
+            .trim();
+        const year = reference.sourceWork.year ?? findReferenceYear(reference) ?? 'na';
+        const key = doi ? `doi:${doi}` : `title:${title}:year:${year}`;
+        const previous = seen.get(key);
+        if (previous !== undefined) {
+            duplicates.push(`Reference ${previous + 1} duplicates reference ${index + 1}.`);
+            return;
+        }
+        seen.set(key, index);
+    });
+    return duplicates;
+};
+export class CitationService {
+    literatureService;
+    constructor(literatureService) {
+        this.literatureService = literatureService;
+    }
+    async suggestContextualCitations(input) {
+        const query = extractQuery(input.manuscriptText, input.cursorContext);
+        const fallbackQuery = query.length > 0 ? query : input.manuscriptText.slice(0, 200);
+        const graphResult = await this.literatureService.searchGraph({
+            query: fallbackQuery,
+            limit: clamp(input.k * 3, input.k, 30),
+            sources: ['semantic_scholar', 'openalex', 'crossref']
+        });
+        const contextTokens = tokenizeForRanking(input.cursorContext ?? input.manuscriptText);
+        const currentYear = new Date().getFullYear();
+        const scored = graphResult.results
+            .map((work) => {
+            const text = `${work.title} ${work.abstract ?? ''} ${work.fieldsOfStudy.join(' ')}`;
+            const overlap = overlapScore(contextTokens, tokenizeForRanking(text));
+            const citationScore = Math.log10(work.citationCount + 1) / 4;
+            const recencyScore = work.year ? 1 / Math.max(1, currentYear - work.year + 1) : 0.2;
+            const finalScore = 0.55 * overlap +
+                0.3 * Math.min(1, citationScore) +
+                0.15 * clamp(recencyScore * Math.max(0, input.recencyBias), 0, 1);
+            return {
+                work,
+                relevanceScore: finalScore,
+                rationale: `overlap=${overlap.toFixed(2)}, citations=${work.citationCount}, year=${work.year ?? 'n/a'}`,
+                matchedContext: (work.abstract ?? work.title).slice(0, 280)
+            };
+        })
+            .sort((a, b) => b.relevanceScore - a.relevanceScore)
+            .slice(0, input.k);
+        return {
+            queryUsed: fallbackQuery,
+            suggestions: scored,
+            inlineSuggestion: buildInlineSuggestion(input.style, scored.map((candidate) => candidate.work))
+        };
+    }
+    async buildReferenceList(input) {
+        const locale = input.locale ?? 'en-US';
+        let works = input.works ?? [];
+        if (works.length === 0 && input.manuscriptText) {
+            const suggestions = await this.suggestContextualCitations({
+                manuscriptText: input.manuscriptText,
+                style: input.style,
+                k: 15,
+                recencyBias: 0.6
+            });
+            works = suggestions.suggestions.map((candidate) => candidate.work);
+        }
+        const deduped = new Map();
+        for (const work of works) {
+            const key = work.doi ?? work.paperId;
+            if (!deduped.has(key)) {
+                deduped.set(key, work);
+            }
+        }
+        const entries = [...deduped.values()].map((work) => formatSingleReference(work, input.style, locale));
+        const cite = new Cite(entries.map((entry) => entry.csl));
+        let bibliographyText = '';
+        try {
+            bibliographyText = cite
+                .format('bibliography', {
+                format: 'text',
+                template: normalizeStyle(input.style),
+                lang: locale
+            })
+                .trim();
+        }
+        catch {
+            bibliographyText = entries.map((entry) => entry.formatted).join('\n');
+        }
+        let bibtex = '';
+        try {
+            bibtex = cite.format('bibtex').trim();
+        }
+        catch {
+            bibtex = entries.map((entry) => entry.bibtex).join('\n\n');
+        }
+        return {
+            style: input.style,
+            locale,
+            references: entries,
+            bibliographyText,
+            bibtex
+        };
+    }
+    validateManuscriptCitations(manuscriptText, references, options) {
+        const numericCitationParse = parseNumericInlineCitations(manuscriptText);
+        const numericCitations = numericCitationParse.numbers;
+        const authorYearCitations = parseAuthorYearCitations(manuscriptText);
+        const placeholders = [...manuscriptText.matchAll(/\[(?:\?|TODO|CITATION)\]/gi)].map((match) => match[0] ?? '');
+        const missingReferences = new Set();
+        for (const value of numericCitations) {
+            if (value < 1 || value > references.length) {
+                missingReferences.add(`[${value}]`);
+            }
+        }
+        for (const citation of authorYearCitations) {
+            const matched = references.some((entry) => entry.formatted.toLowerCase().includes(citation.author.toLowerCase()));
+            if (!matched) {
+                missingReferences.add(citation.raw);
+            }
+        }
+        const uncitedReferences = references
+            .map((entry, index) => ({
+            label: `[${index + 1}] ${entry.formatted}`,
+            referenced: numericCitations.includes(index + 1) ||
+                authorYearCitations.some((citation) => entry.formatted.toLowerCase().includes(citation.author.toLowerCase()))
+        }))
+            .filter((entry) => !entry.referenced)
+            .map((entry) => entry.label);
+        const completenessDiagnostics = references.map((reference, index) => buildCompletenessDiagnostic(reference, index));
+        const normalizationSuggestions = [...new Set(completenessDiagnostics.flatMap((item) => item.suggestions))];
+        const styleWarnings = [...placeholders, ...numericCitationParse.invalidChunks];
+        if (references.length === 0) {
+            styleWarnings.push('Reference list is empty.');
+        }
+        if (numericCitations.length > 0 && authorYearCitations.length > 0) {
+            styleWarnings.push('Mixed numeric and author-year inline citation patterns detected.');
+        }
+        const expectedStyle = options?.style;
+        if (expectedStyle === 'ieee' || expectedStyle === 'vancouver') {
+            if (authorYearCitations.length > 0) {
+                styleWarnings.push(`Expected numeric citations for ${expectedStyle.toUpperCase()} style.`);
+            }
+        }
+        if (expectedStyle === 'apa' || expectedStyle === 'chicago') {
+            if (numericCitations.length > 0) {
+                styleWarnings.push(`Expected author-year citations for ${expectedStyle.toUpperCase()} style.`);
+            }
+        }
+        if (expectedStyle === 'apa') {
+            const referencesMissingDoiUrl = completenessDiagnostics.filter((item) => item.missingPersistentIdentifier).length;
+            if (referencesMissingDoiUrl > 0) {
+                styleWarnings.push(`${referencesMissingDoiUrl} reference(s) are missing a DOI/URL, which weakens APA traceability requirements.`);
+            }
+        }
+        return {
+            inlineCitationCount: numericCitations.length + authorYearCitations.length,
+            referenceCount: references.length,
+            missingReferences: [...missingReferences],
+            uncitedReferences,
+            styleWarnings,
+            duplicateReferences: findDuplicateReferences(references),
+            completenessDiagnostics,
+            normalizationSuggestions
+        };
+    }
+}

package/dist/research/errors.js

@@ -0,0 +1,36 @@
+export class ResearchError extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.name = 'ResearchError';
+    }
+}
+export class ResearchProviderError extends ResearchError {
+    provider;
+    status;
+    constructor(message, provider, status, details) {
+        super(message, details);
+        this.provider = provider;
+        this.status = status;
+        this.name = 'ResearchProviderError';
+    }
+}
+export class IngestionError extends ResearchError {
+    constructor(message, details) {
+        super(message, details);
+        this.name = 'IngestionError';
+    }
+}
+export class DocumentNotFoundError extends ResearchError {
+    constructor(documentId) {
+        super(`Document not found: ${documentId}`, { documentId });
+        this.name = 'DocumentNotFoundError';
+    }
+}
+export class JobNotFoundError extends ResearchError {
+    constructor(jobId) {
+        super(`Ingestion job not found: ${jobId}`, { jobId });
+        this.name = 'JobNotFoundError';
+    }
+}

package/dist/research/extraction-service.js

@@ -0,0 +1,109 @@
+import { normalizeWhitespace } from './utils.js';
+const splitSentences = (text) => text
+    .split(/(?<=[.!?])\s+/)
+    .map((sentence) => normalizeWhitespace(sentence))
+    .filter((sentence) => sentence.length > 20);
+const collectByPatterns = (sections, patterns, confidence) => {
+    const output = [];
+    for (const section of sections) {
+        const sentences = splitSentences(section.text);
+        for (const sentence of sentences) {
+            if (patterns.some((pattern) => pattern.test(sentence))) {
+                output.push({
+                    text: sentence,
+                    confidence,
+                    sectionId: section.id
+                });
+            }
+        }
+    }
+    return output.slice(0, 25);
+};
+const uniqueList = (items) => {
+    const set = new Set();
+    for (const item of items) {
+        const normalized = normalizeWhitespace(item);
+        if (normalized.length > 0) {
+            set.add(normalized);
+        }
+    }
+    return [...set];
+};
+const extractDatasets = (sections) => {
+    const matches = [];
+    const datasetPattern = /([A-Z][A-Za-z0-9\-]+\s+(?:dataset|corpus|benchmark))/g;
+    for (const section of sections) {
+        for (const match of section.text.matchAll(datasetPattern)) {
+            if (match[1]) {
+                matches.push(match[1]);
+            }
+        }
+    }
+    return uniqueList(matches).slice(0, 30);
+};
+const extractMetrics = (sections) => {
+    const metricPatterns = [
+        /\bF1(?:-score)?\b/gi,
+        /\baccuracy\b/gi,
+        /\bprecision\b/gi,
+        /\brecall\b/gi,
+        /\bAUC\b/gi,
+        /\bRMSE\b/gi,
+        /\bMAE\b/gi,
+        /\bBLEU\b/gi,
+        /\bROUGE\b/gi,
+        /\bmAP\b/gi
+    ];
+    const found = [];
+    for (const section of sections) {
+        for (const pattern of metricPatterns) {
+            for (const match of section.text.matchAll(pattern)) {
+                if (match[0]) {
+                    found.push(match[0].toUpperCase());
+                }
+            }
+        }
+    }
+    return uniqueList(found);
+};
+export class ExtractionService {
+    extract(document, input) {
+        const selectedSections = this.selectSections(document.sections, input.sections);
+        const claims = collectByPatterns(selectedSections, [
+            /\bwe (?:propose|present|show|demonstrate)\b/i,
+            /\bthis paper\b/i,
+            /\bour (?:results|findings)\b/i,
+            /\bwe find that\b/i
+        ], Math.max(0.45, document.parser.confidence - 0.2));
+        const methods = collectByPatterns(selectedSections, [
+            /\bmethod(?:ology)?\b/i,
+            /\bapproach\b/i,
+            /\bmodel\b/i,
+            /\balgorithm\b/i,
+            /\bexperimental setup\b/i
+        ], Math.max(0.5, document.parser.confidence - 0.15));
+        const limitations = collectByPatterns(selectedSections, [/\blimitation\b/i, /\bhowever\b/i, /\bfuture work\b/i, /\bchallenge\b/i, /\bconstraint\b/i], Math.max(0.4, document.parser.confidence - 0.25));
+        return {
+            documentId: document.documentId,
+            title: document.title,
+            abstract: document.abstract,
+            requestedSections: selectedSections,
+            claims,
+            methods,
+            limitations,
+            datasets: extractDatasets(selectedSections),
+            metrics: extractMetrics(selectedSections),
+            references: input.includeReferences === false ? [] : document.references,
+            parserConfidence: document.parser.confidence,
+            provenance: document.provenance
+        };
+    }
+    selectSections(sections, requested) {
+        if (!requested || requested.length === 0) {
+            return sections;
+        }
+        const normalizedRequested = requested.map((name) => name.trim().toLowerCase());
+        const selected = sections.filter((section) => normalizedRequested.some((target) => section.heading.toLowerCase().includes(target)));
+        return selected.length > 0 ? selected : sections;
+    }
+}

package/dist/research/http-client.js

@@ -0,0 +1,62 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { ResearchProviderError } from './errors.js';
+export class ResearchHttpClient {
+    config;
+    lastRequestAt = 0;
+    constructor(config) {
+        this.config = config;
+    }
+    async fetchJson({ provider, url, headers }) {
+        let attempt = 0;
+        let lastError;
+        while (attempt <= this.config.researchRetryAttempts) {
+            await this.waitBeforeRequest();
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.config.researchTimeoutMs);
+            try {
+                const response = await fetch(url, {
+                    method: 'GET',
+                    headers,
+                    signal: controller.signal
+                });
+                if (!response.ok) {
+                    const body = await response.text();
+                    throw new ResearchProviderError(`Provider ${provider} returned HTTP ${response.status}`, provider, response.status, { url: url.toString(), body: body.slice(0, 1000) });
+                }
+                const json = (await response.json());
+                return json;
+            }
+            catch (error) {
+                lastError = error;
+                const isLastAttempt = attempt >= this.config.researchRetryAttempts;
+                if (isLastAttempt) {
+                    break;
+                }
+                await sleep(this.config.researchRetryDelayMs);
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+            attempt += 1;
+        }
+        if (lastError instanceof Error) {
+            throw lastError;
+        }
+        throw new ResearchProviderError(`Unknown provider error for ${provider}`, provider, undefined, {
+            url: url.toString()
+        });
+    }
+    async waitBeforeRequest() {
+        if (this.config.researchRequestDelayMs <= 0) {
+            this.lastRequestAt = Date.now();
+            return;
+        }
+        const now = Date.now();
+        const elapsed = now - this.lastRequestAt;
+        const waitMs = this.config.researchRequestDelayMs - elapsed;
+        if (waitMs > 0) {
+            await sleep(waitMs);
+        }
+        this.lastRequestAt = Date.now();
+    }
+}

package/dist/research/index.js

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './research-service.js';
+export * from './literature-service.js';
+export * from './ingestion-service.js';
+export * from './extraction-service.js';
+export * from './citation-service.js';