flonat-research 0.1.0

package/packages/mcp-bibliography/_app.py

@@ -0,0 +1,226 @@
+"""
+Biblio MCP Server — shared state
+
+Server instance, client initialization, formatters, and helpers.
+Imported by tool modules in tools/.
+"""
+
+import asyncio
+import os
+import re
+import sys
+import unicodedata
+from pathlib import Path
+
+from mcp.server import Server
+from mcp.types import Tool, TextContent
+
+from biblio_sources import (
+    AltmetricClient,
+    CoreSource,
+    CrossrefSource,
+    DblpSource,
+    OpenCitationsClient,
+    OpenReviewClient,
+    UnpaywallClient,
+    ZenodoClient,
+    OrcidClient,
+    OpenAlexClient,
+    OpenAlexSource,
+    MultiSource,
+    SemanticScholarSource,
+    ScopusSource,
+    WosSource,
+)
+
+# OpenAlex-specific helpers (raw dict API)
+SCRIPTS_DIR = str(Path(__file__).parent.parent.parent / ".scripts" / "openalex")
+sys.path.insert(0, SCRIPTS_DIR)
+
+from query_helpers import (  # noqa: E402
+    find_author_works,
+    analyze_research_output,
+    get_publication_trends,
+)
+
+from formatters import (  # noqa: E402
+    format_works_table,
+    format_author_profile,
+    format_trends,
+    format_work_detail,
+)
+
+from scholarly_formatters import (  # noqa: E402
+    format_papers_table,
+    format_verification_table,
+    format_source_status,
+)
+
+
+def log(msg):
+    print(f"[bibliography-mcp] {msg}", file=sys.stderr, flush=True)
+
+
+# ---------- Client / source initialization ----------
+
+# Shared client instance (polite pool)
+client = OpenAlexClient(email="user@example.com")
+
+_all_sources = []
+_source_info = []
+
+# OpenAlex — always available
+_openalex_source = OpenAlexSource(client)
+_all_sources.append(_openalex_source)
+_source_info.append({"name": "OpenAlex", "key": "openalex", "active": True})
+log("OpenAlex source: active")
+
+# Semantic Scholar — always available, optional API key for higher rate limits
+_s2_key = os.environ.get("S2_API_KEY")
+_s2_source = SemanticScholarSource(api_key=_s2_key)
+_all_sources.append(_s2_source)
+_source_info.append({"name": "Semantic Scholar", "key": "s2", "active": True})
+log(f"Semantic Scholar source: active{' (API key)' if _s2_key else ' (no key, 1 req/sec)'}")
+
+# Crossref — always available (no API key, polite pool via mailto)
+_crossref_source = CrossrefSource(mailto="user@example.com")
+_all_sources.append(_crossref_source)
+_source_info.append({"name": "Crossref", "key": "crossref", "active": True})
+log("Crossref source: active (authoritative DOI registry)")
+
+# Scopus — optional, requires SCOPUS_API_KEY
+_scopus_key = os.environ.get("SCOPUS_API_KEY")
+_scopus_source = None
+if _scopus_key:
+    _scopus_inst_token = os.environ.get("SCOPUS_INST_TOKEN", "")
+    _scopus_source = ScopusSource(_scopus_key, inst_token=_scopus_inst_token)
+    _all_sources.append(_scopus_source)
+    _source_info.append({"name": "Scopus", "key": "scopus", "active": True})
+    log(f"Scopus source: active{' (InstToken)' if _scopus_inst_token else ''}")
+else:
+    _source_info.append({"name": "Scopus", "key": "scopus", "active": False})
+    log("Scopus source: no API key")
+
+# Web of Science — optional, requires WOS_API_KEY
+_wos_key = os.environ.get("WOS_API_KEY")
+_wos_source = None
+_wos_tier = os.environ.get("WOS_API_TIER", "starter").lower()
+if _wos_key:
+    _wos_source = WosSource(_wos_key, tier=_wos_tier)
+    _all_sources.append(_wos_source)
+    _source_info.append({"name": f"Web of Science ({_wos_tier})", "key": "wos", "active": True})
+    log(f"WoS source: active (tier={_wos_tier})")
+else:
+    _source_info.append({"name": "Web of Science", "key": "wos", "active": False})
+    log("WoS source: no API key")
+
+# Composite source for cross-source queries
+_multi_source = MultiSource(_all_sources) if len(_all_sources) > 1 else _openalex_source
+log(f"Multi-source: {len(_all_sources)} source(s) active")
+
+# CORE — open access full text, optional API key
+_core_key = os.environ.get("CORE_API_KEY", "")
+_core_source = None
+if _core_key:
+    _core_source = CoreSource(api_key=_core_key)
+    _all_sources.append(_core_source)
+    _source_info.append({"name": "CORE", "key": "core", "active": True})
+    log("CORE source: active (431M+ records, full-text access)")
+else:
+    _source_info.append({"name": "CORE", "key": "core", "active": False})
+    log("CORE source: no API key (set CORE_API_KEY)")
+
+# ORCID — researcher profiles, always available if credentials set
+_orcid_client_id = os.environ.get("ORCID_CLIENT_ID", "")
+_orcid_client_secret = os.environ.get("ORCID_CLIENT_SECRET", "")
+_orcid_client = None
+if _orcid_client_id and _orcid_client_secret:
+    _orcid_client = OrcidClient(
+        client_id=_orcid_client_id,
+        client_secret=_orcid_client_secret,
+    )
+    log("ORCID client: active")
+else:
+    log("ORCID client: no credentials (set ORCID_CLIENT_ID + ORCID_CLIENT_SECRET)")
+
+# Altmetric Explorer — research attention metrics, optional
+_altmetric_key = os.environ.get("ALTMETRIC_API_KEY", "")
+_altmetric_secret = os.environ.get("ALTMETRIC_API_PASSWORD", "")
+_altmetric_client = None
+if _altmetric_key and _altmetric_secret:
+    _altmetric_client = AltmetricClient(api_key=_altmetric_key, api_secret=_altmetric_secret)
+    log("Altmetric Explorer client: active")
+else:
+    log("Altmetric Explorer client: no credentials (set ALTMETRIC_API_KEY + ALTMETRIC_API_PASSWORD)")
+
+# Zenodo — research data repository, always available (no auth)
+_zenodo_client = ZenodoClient()
+log("Zenodo client: active (no auth required)")
+
+# Unpaywall — OA PDF resolver, always available (no auth, just email)
+_unpaywall_client = UnpaywallClient(email="user@example.com")
+log("Unpaywall client: active (no auth required)")
+
+# OpenCitations — open citation graph, always available (no auth)
+_opencitations_client = OpenCitationsClient()
+log("OpenCitations client: active (no auth required)")
+
+# DBLP — CS publications, always available (no auth)
+_dblp_source = DblpSource()
+log("DBLP source: active (no auth required)")
+
+# OpenReview — conference submissions and reviews, always available (no auth)
+_openreview_client = OpenReviewClient()
+log("OpenReview client: active (no auth required)")
+
+# ---------- Utility: BibTeX key generation ----------
+
+_KEY_STOPWORDS = frozenset({
+    "a", "an", "the", "and", "or", "of", "in", "on", "for", "to", "with", "by",
+    "from", "at", "is", "are", "do", "does", "how", "what", "when", "where",
+})
+
+
+def generate_bibtex_key(authors: list[str], year: int | None, title: str | None) -> str:
+    """Generate a BibTeX key following Google Scholar convention: surnameYearFirstword.
+
+    Examples:
+        ["Albert Einstein"], 1905, "On the Electrodynamics..." -> einstein1905electrodynamics
+        ["María García-López"], 2023, "A Study..." -> garcialopez2023study
+    """
+    # Surname: last token of first author, ASCII-normalized, lowercase
+    surname = ""
+    if authors:
+        name = authors[0].strip()
+        # Handle "Last, First" format
+        if "," in name:
+            surname = name.split(",")[0].strip()
+        else:
+            surname = name.split()[-1] if name.split() else ""
+    surname = unicodedata.normalize("NFKD", surname).encode("ascii", "ignore").decode("ascii")
+    surname = re.sub(r"[^a-zA-Z]", "", surname).lower()
+    if not surname:
+        surname = "unknown"
+
+    # Year
+    year_str = str(year) if year else ""
+
+    # First significant word of title
+    first_word = ""
+    if title:
+        title_ascii = unicodedata.normalize("NFKD", title).encode("ascii", "ignore").decode("ascii")
+        words = re.findall(r"[a-zA-Z]+", title_ascii.lower())
+        for w in words:
+            if w not in _KEY_STOPWORDS and len(w) > 2:
+                first_word = w
+                break
+        if not first_word and words:
+            first_word = words[0]
+
+    return f"{surname}{year_str}{first_word}"
+
+
+# ---------- Server instance ----------
+
+server = Server("bibliography")
+log("Server initialized")

package/packages/mcp-bibliography/formatters.py

@@ -0,0 +1,158 @@
+"""Markdown formatting functions for OpenAlex API results."""
+
+from typing import Any
+
+
+def _get_authors_str(work: dict[str, Any], max_authors: int = 3) -> str:
+    """Extract author names from a work, truncating if needed."""
+    authorships = work.get("authorships", [])
+    names = [a["author"]["display_name"] for a in authorships if a.get("author")]
+    if len(names) > max_authors:
+        return ", ".join(names[:max_authors]) + " et al."
+    return ", ".join(names) if names else "Unknown"
+
+
+def _get_journal(work: dict[str, Any]) -> str:
+    """Extract journal/source name from a work."""
+    loc = work.get("primary_location") or {}
+    source = loc.get("source") or {}
+    return source.get("display_name", "")
+
+
+def _clean_doi(doi: str | None) -> str:
+    """Strip https://doi.org/ prefix from DOI."""
+    if not doi:
+        return ""
+    return doi.replace("https://doi.org/", "")
+
+
+def format_works_table(works: list[dict[str, Any]], title: str = "Results") -> str:
+    """Format a list of works as a markdown table."""
+    if not works:
+        return f"## {title}\n\nNo results found."
+
+    lines = [
+        f"## {title}\n",
+        f"**{len(works)} works**\n",
+        "| # | Title | Authors | Year | Journal | Cites | DOI |",
+        "|---|-------|---------|------|---------|-------|-----|",
+    ]
+
+    for i, w in enumerate(works, 1):
+        title_text = (w.get("title") or "Untitled")[:80]
+        authors = _get_authors_str(w)
+        year = w.get("publication_year", "")
+        journal = _get_journal(w)[:30]
+        cites = w.get("cited_by_count", 0)
+        doi = _clean_doi(w.get("doi"))
+        lines.append(f"| {i} | {title_text} | {authors} | {year} | {journal} | {cites} | {doi} |")
+
+    return "\n".join(lines)
+
+
+def format_author_profile(analysis: dict[str, Any]) -> str:
+    """Format research output analysis as markdown."""
+    if "error" in analysis:
+        return f"**Error:** {analysis['error']}"
+
+    lines = [
+        f"## {analysis['entity_name']}",
+        "",
+        f"- **Total works:** {analysis['total_works']}",
+        f"- **Open access:** {analysis['open_access_works']} ({analysis['open_access_percentage']}%)",
+        "",
+        "### Publications by Year",
+        "",
+        "| Year | Count |",
+        "|------|-------|",
+    ]
+
+    for entry in sorted(analysis.get("publications_by_year", []),
+                        key=lambda x: x.get("key", ""), reverse=True):
+        lines.append(f"| {entry.get('key', '')} | {entry.get('count', 0)} |")
+
+    topics = analysis.get("top_topics", [])
+    if topics:
+        lines.extend(["", "### Top Topics", "", "| Topic | Count |", "|-------|-------|"])
+        for t in topics[:10]:
+            name = t.get("key_display_name", t.get("key", ""))
+            lines.append(f"| {name} | {t.get('count', 0)} |")
+
+    return "\n".join(lines)
+
+
+def format_trends(trends: list[dict[str, Any]], search_term: str = "") -> str:
+    """Format publication trends as markdown."""
+    if not trends:
+        return "No trend data found."
+
+    header = f"## Publication Trends"
+    if search_term:
+        header += f": {search_term}"
+
+    sorted_trends = sorted(trends, key=lambda x: x.get("key", ""), reverse=True)
+
+    lines = [
+        header,
+        "",
+        "| Year | Publications |",
+        "|------|-------------|",
+    ]
+
+    for entry in sorted_trends[:20]:
+        lines.append(f"| {entry.get('key', '')} | {entry.get('count', 0)} |")
+
+    return "\n".join(lines)
+
+
+def format_work_detail(work: dict[str, Any]) -> str:
+    """Format a single work with full metadata."""
+    title = work.get("title") or "Untitled"
+    authors = _get_authors_str(work, max_authors=10)
+    year = work.get("publication_year", "")
+    journal = _get_journal(work)
+    doi = _clean_doi(work.get("doi"))
+    cites = work.get("cited_by_count", 0)
+    oa = work.get("open_access", {})
+    oa_status = oa.get("oa_status", "unknown")
+    oa_url = oa.get("oa_url", "")
+
+    # Reconstruct abstract from inverted index
+    abstract = ""
+    inv_index = work.get("abstract_inverted_index")
+    if inv_index:
+        word_positions: list[tuple[int, str]] = []
+        for word, positions in inv_index.items():
+            for pos in positions:
+                word_positions.append((pos, word))
+        word_positions.sort()
+        abstract = " ".join(w for _, w in word_positions)
+
+    lines = [
+        f"## {title}",
+        "",
+        f"**Authors:** {authors}",
+        f"**Year:** {year}",
+        f"**Journal:** {journal}",
+        f"**DOI:** {doi}",
+        f"**Citations:** {cites}",
+        f"**Open Access:** {oa_status}",
+    ]
+
+    if oa_url:
+        lines.append(f"**OA URL:** {oa_url}")
+
+    work_type = work.get("type", "")
+    if work_type:
+        lines.append(f"**Type:** {work_type}")
+
+    if abstract:
+        lines.extend(["", "### Abstract", "", abstract])
+
+    # Concepts/topics
+    topics = work.get("topics", [])
+    if topics:
+        topic_names = [t.get("display_name", "") for t in topics[:5]]
+        lines.extend(["", f"**Topics:** {', '.join(topic_names)}"])
+
+    return "\n".join(lines)

package/packages/mcp-bibliography/log/2026-03-13-2100.md

@@ -0,0 +1,35 @@
+# Session Log: 2026-03-13 21:00
+
+## Project: .mcp-server-bibliography
+
+> Also logged: Task Management (skills updates) — `../../log/2026-03-13-2100.md`
+
+## What We Did
+- Added Semantic Scholar as 4th source adapter (created in prior session, tested and confirmed working)
+- Rewrote S2 adapter to use `/paper/search/bulk` (recommended by S2) and Recommendations API for `find_similar_works`
+- Added 4 new S2 Graph API methods: `get_paper_citations`, `get_paper_references`, `search_author` + `get_author_papers`, `get_paper_detail`
+- Extended Paper model with `tldr`, `bibtex`, `open_access_url` fields
+- Exposed 4 new MCP tools: `scholarly_citations`, `scholarly_references`, `scholarly_paper_detail`, `scholarly_author_papers`
+- Server now has 17 tools total (7 OpenAlex + 10 scholarly) across 4 sources
+- Fixed S2 field scoping: base fields for bulk endpoints, extended fields (tldr, citationStyles, isOpenAccess, openAccessPdf) only for single paper lookups
+- Fixed citations/references endpoints to use `citingPaper.` / `citedPaper.` field prefixes
+- All 6 test categories passed: bulk search, DOI verify, forward citations, backward references, author search + papers, paper detail with TLDR/BibTeX, recommendations
+
+## Key Decisions
+- S2 Datasets API (bulk download) is NOT suitable for live MCP queries — only Graph + Recommendations are used
+- Extended fields (`tldr`, `citationStyles`) only available on single paper lookup, not bulk/citations/references endpoints — used separate field constants `S2_FIELDS` vs `S2_DETAIL_FIELDS`
+- the user applying for S2 API key for higher rate limits (drafted application answers)
+
+## Problems/Blockers
+- First attempt at extended fields caused 400 errors on bulk search, citations, and references endpoints — resolved by splitting field constants
+- Citations/references endpoints need prefixed nested fields (`citingPaper.title`, `citedPaper.title`) — different from other endpoints
+
+## Next Steps
+- [ ] Add S2_API_KEY to `research/scout/.env` once the user receives it
+- [ ] Consider adding S2 as a source in Scout CLI itself (currently only OpenAlex/Scopus/WoS)
+
+## Files Changed
+- `sources/models.py` — added `tldr`, `bibtex`, `open_access_url` fields to Paper dataclass
+- `sources/semantic_scholar_source.py` — added `S2_DETAIL_FIELDS`, 5 new methods, enriched `_to_paper` with tldr/bibtex/oa_url
+- `server.py` — added 4 new tool definitions and handlers
+- `run.sh` — S2_API_KEY added to env var loading (prior session)

package/packages/mcp-bibliography/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "biblio-mcp"
+version = "0.2.0"
+description = "Multi-source scholarly search MCP server: OpenAlex + Scopus + Web of Science"
+requires-python = ">=3.12"
+dependencies = [
+    "mcp>=1.0.0",
+    "requests",
+    "httpx>=0.27",
+    "biblio-sources @ git+https://github.com/user/biblio-sources.git@9cff529",
+]
+
+[tool.uv.sources]
+biblio-sources = { path = "../biblio-sources", editable = true }
+

package/packages/mcp-bibliography/run.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Wrapper to launch the bibliography MCP server with API keys from Scout's .env
+set -euo pipefail
+
+ENV_FILE="$(dirname "$0")/../../research/scout/.env"
+
+if [[ -f "$ENV_FILE" ]]; then
+  while IFS='=' read -r key value; do
+    # Skip comments and blank lines
+    [[ "$key" =~ ^#.*$ || -z "$key" ]] && continue
+    # Only export the keys the server needs
+    case "$key" in
+      WOS_API_KEY|WOS_API_TIER|SCOPUS_API_KEY|SCOPUS_INST_TOKEN|S2_API_KEY|ORCID_CLIENT_ID|ORCID_CLIENT_SECRET|CORE_API_KEY|ALTMETRIC_API_KEY|ALTMETRIC_API_PASSWORD)
+        export "$key"="$value"
+        ;;
+    esac
+  done < "$ENV_FILE"
+fi
+
+exec uv run --directory "$(dirname "$0")" python server.py

package/packages/mcp-bibliography/scholarly_formatters.py

@@ -0,0 +1,83 @@
+"""Markdown formatters for multi-source scholarly results."""
+
+from __future__ import annotations
+
+from biblio_sources.models import Paper
+
+
+def format_papers_table(papers: list[Paper], title: str = "Results") -> str:
+    """Format a list of Papers as a markdown table."""
+    if not papers:
+        return f"## {title}\n\nNo results found."
+
+    lines = [f"## {title}\n"]
+    lines.append("| # | Title | Authors | Year | Cited | Source | DOI |")
+    lines.append("|---|-------|---------|------|-------|--------|-----|")
+
+    for i, p in enumerate(papers, 1):
+        authors = ", ".join(p.authors[:3])
+        if len(p.authors) > 3:
+            authors += " et al."
+        title_short = p.title[:80] + "..." if len(p.title) > 80 else p.title
+        doi_link = f"[link]({p.doi})" if p.doi else "—"
+        source = p.source_name or "—"
+        if len(source) > 30:
+            source = source[:27] + "..."
+
+        lines.append(
+            f"| {i} | {title_short} | {authors} | {p.publication_year} | "
+            f"{p.cited_by_count:,} | {source} | {doi_link} |"
+        )
+
+    return "\n".join(lines)
+
+
+def format_verification_table(results: dict[str, Paper | None]) -> str:
+    """Format DOI verification results as a markdown table."""
+    lines = ["## DOI Verification Results\n"]
+    lines.append("| # | DOI | Title | Year | Cited By | Verified By | Status |")
+    lines.append("|---|-----|-------|------|----------|-------------|--------|")
+
+    verified_count = 0
+    single_count = 0
+    not_found_count = 0
+
+    for i, (doi, paper) in enumerate(results.items(), 1):
+        if paper is None:
+            status = "NOT FOUND"
+            not_found_count += 1
+            lines.append(f"| {i} | `{doi}` | — | — | — | — | ❌ {status} |")
+        else:
+            sources = ", ".join(paper.verified_by)
+            if len(paper.verified_by) >= 2:
+                status = "VERIFIED"
+                verified_count += 1
+            else:
+                status = "SINGLE SOURCE"
+                single_count += 1
+            title_short = paper.title[:60] + "..." if len(paper.title) > 60 else paper.title
+            lines.append(
+                f"| {i} | `{doi}` | {title_short} | {paper.publication_year} | "
+                f"{paper.cited_by_count:,} | {sources} | "
+                f"{'✅' if status == 'VERIFIED' else '⚠️'} {status} |"
+            )
+
+    lines.append("")
+    lines.append(f"**Summary:** {verified_count} verified (2+ sources), "
+                 f"{single_count} single-source, {not_found_count} not found")
+
+    return "\n".join(lines)
+
+
+def format_source_status(sources: list[dict]) -> str:
+    """Format source status as a markdown table."""
+    lines = ["## Scholarly Source Status\n"]
+    lines.append("| Source | Status | Key |")
+    lines.append("|--------|--------|-----|")
+
+    for s in sources:
+        status = "✅ Active" if s["active"] else "❌ Not configured"
+        key = s.get("key", "—")
+        lines.append(f"| {s['name']} | {status} | `{key}` |")
+
+    return "\n".join(lines)