flonat-research 0.1.0

package/packages/mcp-bibliography/tools/__init__.py

@@ -0,0 +1,28 @@
+"""
+Tool registry auto-loader.
+
+Importing this package triggers side-effect registration of all tools.
+Conditional tools (ORCID, CORE, Altmetric) register only if their
+API credentials are available — handled inside each module.
+"""
+
+import sys
+from pathlib import Path
+
+# Ensure the parent directory (package root) is on sys.path
+# so tool modules can `from _app import ...`
+_pkg_root = str(Path(__file__).resolve().parent.parent)
+if _pkg_root not in sys.path:
+    sys.path.insert(0, _pkg_root)
+
+# Import all tool modules — each registers its tools as a side effect
+from tools import openalex      # noqa: F401  (8 tools)
+from tools import scholarly     # noqa: F401  (9+ tools)
+from tools import orcid         # noqa: F401  (2 tools, conditional)
+from tools import core          # noqa: F401  (2 tools, conditional)
+from tools import altmetric     # noqa: F401  (2 tools, conditional)
+from tools import openreview    # noqa: F401  (3 tools)
+from tools import dblp          # noqa: F401  (1 tool)
+from tools import opencitations # noqa: F401  (2 tools)
+from tools import unpaywall     # noqa: F401  (1 tool)
+from tools import zenodo        # noqa: F401  (2 tools)

package/packages/mcp-bibliography/tools/_registry.py

@@ -0,0 +1,19 @@
+"""Tool registry — maps tool names to handler functions."""
+
+from __future__ import annotations
+
+from typing import Callable, Awaitable
+
+from mcp.types import Tool, TextContent
+
+# All registered Tool definitions (populated by tool modules at import time)
+TOOL_DEFINITIONS: list[Tool] = []
+
+# name → async handler(args) mapping
+TOOL_REGISTRY: dict[str, Callable[[dict], Awaitable[list[TextContent]]]] = {}
+
+
+def register(tool: Tool, handler: Callable[[dict], Awaitable[list[TextContent]]]) -> None:
+    """Register a tool definition and its handler."""
+    TOOL_DEFINITIONS.append(tool)
+    TOOL_REGISTRY[tool.name] = handler

package/packages/mcp-bibliography/tools/altmetric.py

@@ -0,0 +1,107 @@
+"""Altmetric tools (2 tools, conditional on API key)."""
+
+import json
+
+from mcp.types import Tool, TextContent
+
+from _app import _altmetric_client
+from tools._registry import register
+
+
+# ---------- Handlers ----------
+
+
+async def _handle_altmetric_search(args: dict) -> list[TextContent]:
+    if not _altmetric_client:
+        return [TextContent(type="text", text="**Error:** Altmetric not configured (set ALTMETRIC_API_KEY + ALTMETRIC_API_PASSWORD)")]
+
+    query = args["query"]
+    timeframe = args.get("timeframe", "all")
+    limit = min(args.get("limit", 25), 100)
+
+    outputs = await _altmetric_client.search(query, timeframe=timeframe, limit=limit)
+
+    if not outputs:
+        return [TextContent(type="text", text=f"No Altmetric results for: {query}")]
+
+    lines = [f"## Altmetric Search: {query}\n"]
+    lines.append("| Score | Title | Tweets | News | Policy | Blogs | Wikipedia | Readers |")
+    lines.append("|-------|-------|--------|------|--------|-------|-----------|---------|")
+
+    for o in outputs:
+        title = o.title[:50] + ("..." if len(o.title) > 50 else "")
+        m = o.mentions
+        tweets = m.get("tweet", 0)
+        news = m.get("msm", 0)
+        policy = m.get("policy", 0)
+        blogs = m.get("blog", 0)
+        wiki = m.get("wikipedia", 0)
+        readers = o.readers.get("mendeley", 0)
+        score = f"**{o.altmetric_score:.0f}**" if o.altmetric_score else "—"
+        lines.append(f"| {score} | {title} | {tweets} | {news} | {policy} | {blogs} | {wiki} | {readers} |")
+
+    lines.append(f"\n*{len(outputs)} results from Altmetric Explorer (timeframe: {timeframe})*")
+    return [TextContent(type="text", text="\n".join(lines))]
+
+
+async def _handle_altmetric_attention_summary(args: dict) -> list[TextContent]:
+    if not _altmetric_client:
+        return [TextContent(type="text", text="**Error:** Altmetric not configured")]
+
+    query = args["query"]
+    timeframe = args.get("timeframe", "all")
+
+    data = await _altmetric_client.get_attention_summary(query, timeframe=timeframe)
+
+    if not data:
+        return [TextContent(type="text", text=f"No attention data for: {query}")]
+
+    lines = [f"## Attention Summary: {query}\n"]
+    lines.append(f"```json\n{json.dumps(data, indent=2)[:2000]}\n```")
+    lines.append(f"\n*Source: Altmetric Explorer (timeframe: {timeframe})*")
+    return [TextContent(type="text", text="\n".join(lines))]
+
+
+# ---------- Registration (conditional) ----------
+
+if _altmetric_client:
+    register(
+        Tool(
+            name="altmetric_search",
+            description=(
+                "Search for research outputs with altmetric attention data. Returns papers "
+                "with their altmetric score and mention breakdown (tweets, news, blogs, policy docs, "
+                "Wikipedia, Reddit, Bluesky). Use to discover which papers on a topic get the most "
+                "real-world attention beyond citations."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "Search query (topic, keywords)"},
+                    "timeframe": {"type": "string", "description": "Time filter: 'all' (default), '1d', '1w', '1m', '3m', '6m', '1y'"},
+                    "limit": {"type": "integer", "description": "Max results (default 25, max 100)"},
+                },
+                "required": ["query"],
+            },
+        ),
+        _handle_altmetric_search,
+    )
+    register(
+        Tool(
+            name="altmetric_attention_summary",
+            description=(
+                "Get aggregate attention summary for a research topic. Returns total mentions, "
+                "score distribution, and top sources. Use to understand the overall attention "
+                "landscape for a field or topic."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "Topic to analyze"},
+                    "timeframe": {"type": "string", "description": "Time filter: 'all' (default), '1d', '1w', '1m', '3m', '6m', '1y'"},
+                },
+                "required": ["query"],
+            },
+        ),
+        _handle_altmetric_attention_summary,
+    )

package/packages/mcp-bibliography/tools/core.py

@@ -0,0 +1,92 @@
+"""CORE tools (2 tools, conditional on API key)."""
+
+from mcp.types import Tool, TextContent
+
+from _app import _core_source, format_papers_table
+from tools._registry import register
+
+
+# ---------- Handlers ----------
+
+
+async def _handle_core_search(args: dict) -> list[TextContent]:
+    if not _core_source:
+        return [TextContent(type="text", text="**Error:** CORE not configured (set CORE_API_KEY)")]
+
+    query = args["query"]
+    limit = min(args.get("limit", 25), 100)
+    year_from = args.get("year_from")
+    year_to = args.get("year_to")
+
+    papers = await _core_source.search_works(
+        query, year_from=year_from, year_to=year_to, limit=limit
+    )
+
+    if not papers:
+        return [TextContent(type="text", text=f"No CORE results for: {query}")]
+
+    text = format_papers_table(papers, title=f"CORE Search: {query}")
+
+    with_text = sum(1 for p in papers if p.open_access_url)
+    text += f"\n\n*{len(papers)} results from CORE ({with_text} with full text available)*"
+    text += "\n*Use `core_get_fulltext` with the CORE ID to retrieve full paper text.*"
+    return [TextContent(type="text", text=text)]
+
+
+async def _handle_core_get_fulltext(args: dict) -> list[TextContent]:
+    if not _core_source:
+        return [TextContent(type="text", text="**Error:** CORE not configured (set CORE_API_KEY)")]
+
+    core_id = args["core_id"]
+    full_text = await _core_source.get_full_text(core_id)
+
+    if not full_text:
+        return [TextContent(type="text", text=f"No full text available for CORE ID: {core_id}")]
+
+    if len(full_text) > 50000:
+        full_text = full_text[:50000] + f"\n\n... [truncated, {len(full_text)} chars total]"
+
+    return [TextContent(type="text", text=f"## Full Text (CORE ID: {core_id})\n\n{full_text}")]
+
+
+# ---------- Registration (conditional) ----------
+
+if _core_source:
+    register(
+        Tool(
+            name="core_search_fulltext",
+            description=(
+                "Search CORE's 431M+ open access records. Unique: returns papers with "
+                "full-text content available. Use when you need actual paper text, not just metadata. "
+                "Supports year filtering."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "Search query (keywords, title fragment)"},
+                    "year_from": {"type": "integer", "description": "Start year"},
+                    "year_to": {"type": "integer", "description": "End year"},
+                    "limit": {"type": "integer", "description": "Max results (default 25, max 100)"},
+                },
+                "required": ["query"],
+            },
+        ),
+        _handle_core_search,
+    )
+    register(
+        Tool(
+            name="core_get_fulltext",
+            description=(
+                "Get the full text of a paper by CORE ID. Returns the complete paper text. "
+                "Use core_search_fulltext first to find the CORE ID (source_id field, format: core:12345)."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "core_id": {"type": "integer", "description": "CORE work ID (numeric, from source_id field)"},
+                },
+                "required": ["core_id"],
+            },
+        ),
+        _handle_core_get_fulltext,
+    )

package/packages/mcp-bibliography/tools/dblp.py

@@ -0,0 +1,52 @@
+"""DBLP tools (1 tool, always available)."""
+
+from mcp.types import Tool, TextContent
+
+from _app import _dblp_source, format_papers_table
+from tools._registry import register
+
+
+# ---------- Handler ----------
+
+
+async def _handle_dblp_search(args: dict) -> list[TextContent]:
+    query = args["query"]
+    limit = min(args.get("limit", 25), 1000)
+    year_from = args.get("year_from")
+    year_to = args.get("year_to")
+
+    papers = await _dblp_source.search_works(
+        query, year_from=year_from, year_to=year_to, limit=limit
+    )
+
+    if not papers:
+        return [TextContent(type="text", text=f"No DBLP results for: {query}")]
+
+    text = format_papers_table(papers, title=f"DBLP: {query}")
+    text += f"\n\n*{len(papers)} results from DBLP*"
+    return [TextContent(type="text", text=text)]
+
+
+# ---------- Registration ----------
+
+register(
+    Tool(
+        name="dblp_search",
+        description=(
+            "Search DBLP for computer science publications. Covers conferences, journals, "
+            "books, and theses comprehensively. Free, no auth. Returns title, authors, venue, "
+            "year, DOI. Use for CS venue metadata and author publication lists."
+        ),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Search query (keywords, title, author name)"},
+                "year_from": {"type": "integer", "description": "Start year filter"},
+                "year_to": {"type": "integer", "description": "End year filter"},
+                "limit": {"type": "integer", "description": "Max results (default 25, max 1000)"},
+            },
+            "required": ["query"],
+        },
+    ),
+    _handle_dblp_search,
+)

package/packages/mcp-bibliography/tools/openalex.py

@@ -0,0 +1,296 @@
+"""OpenAlex + Crossref tools (8 tools, always available)."""
+
+import asyncio
+
+from mcp.types import Tool, TextContent
+
+from _app import (
+    client,
+    _crossref_source,
+    log,
+    find_author_works,
+    analyze_research_output,
+    get_publication_trends,
+    format_works_table,
+    format_author_profile,
+    format_trends,
+    format_work_detail,
+)
+from tools._registry import register
+
+
+# ---------- Handlers ----------
+
+
+async def _handle_search_works(args: dict) -> list[TextContent]:
+    query = args["query"]
+    limit = min(args.get("limit", 25), 50)
+    sort = args.get("sort", "cited_by_count:desc")
+
+    filter_params: dict[str, str] = {}
+    if args.get("year"):
+        filter_params["publication_year"] = args["year"]
+    if args.get("min_citations"):
+        filter_params["cited_by_count"] = f">{args['min_citations']}"
+    if args.get("open_access"):
+        filter_params["is_oa"] = "true"
+
+    def _search():
+        return client.search_works(
+            search=query,
+            filter_params=filter_params if filter_params else None,
+            per_page=limit,
+            sort=sort,
+        )
+
+    response = await asyncio.to_thread(_search)
+    works = response.get("results", [])
+    total = response.get("meta", {}).get("count", 0)
+
+    text = format_works_table(works, title=f"Search: {query}")
+    text += f"\n\n*{total:,} total results in OpenAlex (showing top {len(works)})*"
+    return [TextContent(type="text", text=text)]
+
+
+async def _handle_author_works(args: dict) -> list[TextContent]:
+    author_name = args["author_name"]
+    limit = min(args.get("limit", 50), 100)
+
+    works = await asyncio.to_thread(find_author_works, author_name, client, limit)
+    text = format_works_table(works, title=f"Works by {author_name}")
+    return [TextContent(type="text", text=text)]
+
+
+async def _handle_author_profile(args: dict) -> list[TextContent]:
+    author_name = args["author_name"]
+    years = args.get("years", ">2020")
+
+    analysis = await asyncio.to_thread(
+        analyze_research_output, "author", author_name, client, years
+    )
+    text = format_author_profile(analysis)
+    return [TextContent(type="text", text=text)]
+
+
+async def _handle_institution_output(args: dict) -> list[TextContent]:
+    institution_name = args["institution_name"]
+    years = args.get("years", ">2020")
+
+    analysis = await asyncio.to_thread(
+        analyze_research_output, "institution", institution_name, client, years
+    )
+    text = format_author_profile(analysis)
+    return [TextContent(type="text", text=text)]
+
+
+async def _handle_trends(args: dict) -> list[TextContent]:
+    query = args["query"]
+
+    trends = await asyncio.to_thread(get_publication_trends, query, None, client)
+    text = format_trends(trends, search_term=query)
+    return [TextContent(type="text", text=text)]
+
+
+async def _handle_lookup_doi(args: dict) -> list[TextContent]:
+    doi = args["doi"]
+    if not doi.startswith("https://doi.org/"):
+        doi = f"https://doi.org/{doi}"
+
+    work = await asyncio.to_thread(client.get_entity, "works", doi)
+    text = format_work_detail(work)
+    return [TextContent(type="text", text=text)]
+
+
+async def _handle_citing_works(args: dict) -> list[TextContent]:
+    doi = args["doi"]
+    limit = min(args.get("limit", 25), 50)
+
+    if not doi.startswith("https://doi.org/"):
+        doi = f"https://doi.org/{doi}"
+
+    work = await asyncio.to_thread(client.get_entity, "works", doi)
+    cited_by_url = work.get("cited_by_api_url")
+
+    if not cited_by_url:
+        return [TextContent(type="text", text="No citation data available for this work.")]
+
+    import requests
+
+    def _fetch_citing():
+        resp = requests.get(
+            cited_by_url,
+            params={"mailto": client.email, "per-page": limit},
+            timeout=30,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    data = await asyncio.to_thread(_fetch_citing)
+    citing_works = data.get("results", [])
+    total = data.get("meta", {}).get("count", 0)
+
+    title_text = (work.get("title") or "this work")[:60]
+    text = format_works_table(citing_works, title=f"Papers citing: {title_text}")
+    text += f"\n\n*{total:,} total citing works (showing {len(citing_works)})*"
+    return [TextContent(type="text", text=text)]
+
+
+async def _handle_crossref_lookup_doi(args: dict) -> list[TextContent]:
+    doi = args["doi"]
+    paper = await _crossref_source.verify_doi(doi)
+
+    if not paper:
+        return [TextContent(type="text", text=f"DOI not found in Crossref: {doi}")]
+
+    lines = [f"## {paper.title}\n"]
+    lines.append(f"**Authors:** {', '.join(paper.authors)}")
+    lines.append(f"**Year:** {paper.publication_year}")
+    lines.append(f"**Citations:** {paper.cited_by_count:,}")
+    if paper.source_name:
+        lines.append(f"**Journal:** {paper.source_name}")
+    if paper.doi:
+        lines.append(f"**DOI:** {paper.doi}")
+    if paper.abstract:
+        lines.append(f"\n**Abstract:** {paper.abstract}")
+
+    lines.append(f"\n*Source: Crossref (authoritative DOI registry) | Verified: Yes*")
+    return [TextContent(type="text", text="\n".join(lines))]
+
+
+# ---------- Tool definitions + registration ----------
+
+_TOOLS = [
+    (
+        Tool(
+            name="openalex_search_works",
+            description=(
+                "Search OpenAlex for scholarly papers by topic. Supports filters for "
+                "year range, minimum citations, open access, and sort order. "
+                "Returns a markdown table of results."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "Search query (topic, keywords, title fragment)"},
+                    "year": {"type": "string", "description": "Year filter: e.g. '2023', '>2020', '2020-2024'"},
+                    "min_citations": {"type": "integer", "description": "Minimum citation count"},
+                    "open_access": {"type": "boolean", "description": "Only return open access papers"},
+                    "sort": {"type": "string", "description": "Sort order: 'cited_by_count:desc' (default), 'publication_date:desc', 'relevance_score:desc'"},
+                    "limit": {"type": "integer", "description": "Max results (default 25, max 50)"},
+                },
+                "required": ["query"],
+            },
+        ),
+        _handle_search_works,
+    ),
+    (
+        Tool(
+            name="openalex_author_works",
+            description="Find publications by a specific author. Searches by name, resolves to OpenAlex author ID, returns their works.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "author_name": {"type": "string", "description": "Author name to search for"},
+                    "limit": {"type": "integer", "description": "Max results (default 50, max 100)"},
+                },
+                "required": ["author_name"],
+            },
+        ),
+        _handle_author_works,
+    ),
+    (
+        Tool(
+            name="openalex_author_profile",
+            description="Analyze an author's research output: total works, open access %, publications by year, and top topics.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "author_name": {"type": "string", "description": "Author name to analyze"},
+                    "years": {"type": "string", "description": "Year filter (default: '>2020')"},
+                },
+                "required": ["author_name"],
+            },
+        ),
+        _handle_author_profile,
+    ),
+    (
+        Tool(
+            name="openalex_institution_output",
+            description="Analyze an institution's research output: total works, open access %, publications by year, and top topics.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "institution_name": {"type": "string", "description": "Institution name to analyze"},
+                    "years": {"type": "string", "description": "Year filter (default: '>2020')"},
+                },
+                "required": ["institution_name"],
+            },
+        ),
+        _handle_institution_output,
+    ),
+    (
+        Tool(
+            name="openalex_trends",
+            description="Get publication count trends over time for a search term. Returns yearly publication counts.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "Search term to track trends for"},
+                },
+                "required": ["query"],
+            },
+        ),
+        _handle_trends,
+    ),
+    (
+        Tool(
+            name="openalex_lookup_doi",
+            description="Look up a work by DOI. Returns full metadata including title, authors, abstract, citations, and open access status.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "doi": {"type": "string", "description": "DOI (with or without https://doi.org/ prefix)"},
+                },
+                "required": ["doi"],
+            },
+        ),
+        _handle_lookup_doi,
+    ),
+    (
+        Tool(
+            name="openalex_citing_works",
+            description="Find papers that cite a given work (forward citation tracking). Provide a DOI and get back the citing papers.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "doi": {"type": "string", "description": "DOI of the work to find citations for"},
+                    "limit": {"type": "integer", "description": "Max results (default 25, max 50)"},
+                },
+                "required": ["doi"],
+            },
+        ),
+        _handle_citing_works,
+    ),
+    (
+        Tool(
+            name="crossref_lookup_doi",
+            description=(
+                "Look up a DOI in Crossref, the authoritative DOI registry. Returns "
+                "verified metadata: title, authors, journal, date, abstract, citation count. "
+                "Use this to verify a DOI exists and get canonical metadata. More authoritative "
+                "than OpenAlex for DOI verification."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "doi": {"type": "string", "description": "DOI to look up (with or without https://doi.org/ prefix)"},
+                },
+                "required": ["doi"],
+            },
+        ),
+        _handle_crossref_lookup_doi,
+    ),
+]
+
+for tool, handler in _TOOLS:
+    register(tool, handler)