s3-bibliometric
One-line summary: This server runs the S3 (Semantic Similarity Score) bibliometric pipeline on a Scopus-style export — clustering papers into research communities from title+abstract similarity — and lets an assistant inspect, question, label, export and report on the results.
Run the analysis (
run_s3_analysis): point it at a CSV/Excel export with Title and Abstract; options for year range, fixed threshold, embedding model, Leiden vs Louvain, map relations (text only, or text mixed with coupling/co-citation/direct citation), strict citation matching, duplicate removal and significant-ties-only backbone; returns arun_idplus summary.Choose the embedding model (
list_embedding_models): see the available models (mpnet default = published method) with kind, max tokens and description.Exact citations (
enrich_citations): pull full reference lists from the Scopus API to replace approximate title-matched links (needsSCOPUS_API_KEYin the server environment).Inspect the map: threshold scan with silhouette/SII (
get_threshold_scan), community table with size, citations, year span, labels and QI/MI (list_communities), and per-community central papers with abstracts, keywords and TF-IDF terms (get_community).Find outliers and flows: unconnected papers with nearest community (
get_outliers), community×community citation matrix with QI/MI (get_citation_structure), and a knowledge tree of communities across time windows (get_knowledge_tree).Search the corpus semantically (
search_papers).Label themes and store the labels with the run (
save_community_labels).Work through research questions: ranked question list across three levels with data-support flags (
list_questions), and findings + tables for any single question (answer_question).Write the report: one self-contained HTML literature-review report or a question-by-question layout, at level 1–3 (
build_report).Export: CSV outputs of papers, communities, threshold scan and citation matrix (
export_results); one-mode, two-mode and knowledge-graph networks as node/edge CSVs and GraphML for Neo4j/Gephi (export_networks).Manage runs: list previously saved runs with paper counts, best threshold and label status (
list_runs).
Processes Scopus CSV/XLSX exports to run S3 bibliometric analysis, including research community detection, threshold scans, centrality and outlier reporting, citation-flow analysis, semantic paper search, and CSV result export.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@s3-bibliometric Run S3 on ~/Downloads/scopus_innovation.csv and label its communities"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
S3 Bibliometric
S3 project: github.com/AI-Growth-Lab/S3: the method, the paper, the S3 web app and proposals for new analyses. Paper: doi.org/10.1016/j.jbusres.2026.116582. This repository holds the code of the
s3-bibliometricPython library and MCP server.
Semantic Similarity Score (S3): a bibliometric method for mapping intellectual structures, packaged as a free Python library and an MCP server that LLM assistants (Claude, and any other MCP client) can call.
Give it a Scopus export. It finds the research communities of the field, their central papers, outliers, and the citation flows between communities. Your AI assistant can then label the communities and write up the intellectual structure.
No coding needed: see Use it without coding: Claude, ChatGPT or Colab for step-by-step setup with Claude Desktop, Claude Code, Claude.ai, ChatGPT or a Google Colab notebook, or the visual guides: S3 step by step and Scopus export for S3.
How S3 works
The library follows the published method: Bekamiri, Østergaard & Timmermans (2027), Semantic similarity score: A new method for mapping intellectual structures in business research, Journal of Business Research 219, 116582. https://doi.org/10.1016/j.jbusres.2026.116582
Embed each paper's
Title. Abstractwithsentence-transformers/all-mpnet-base-v2S3 matrix = cosine similarity between all papers, time-masked so links run from earlier to later papers (year_i ≤ year_j)
Scan thresholds 0.75–0.85: papers with at least one link S3 ≥ t are retained; Leiden with directed modularity finds the communities
Keep the threshold with the highest SII = mean silhouette of retained papers × number retained
Describe communities with eigenvector and degree centrality and c-TF-IDF terms
With
References+EID: in-corpus citations, QI (within-community citations per paper) and MI (the community's within + inward citations as a share of the field's citation links)
Reproducible. One seed (default 42) fixes every random step: Python, NumPy, PyTorch, Leiden/Louvain, sampling and layouts. Two runs on the same file give identical results.
Clean input. Before the analysis S3 drops records with neither title nor abstract and
removes duplicates: the same EID, the same title + abstract, the same DOI with the same
title (book chapters can share a DOI), and near-identical texts (S3 ≥ 0.98, e.g. reprints).
The most-cited copy is kept; res.removed lists every dropped record and why.
Choose the embedding model (default: mpnet, the model of the published paper):
key | model | use it for |
| sentence-transformers/all-mpnet-base-v2 | default; the published S3 method |
| sentence-transformers/allenai-specter | scientific papers (trained on citations) |
| sentence-transformers/all-MiniLM-L6-v2 | quick looks, about 5× faster |
| paraphrase-multilingual-mpnet-base-v2 | corpora mixing languages |
| Qwen/Qwen3-Embedding-0.6B | long abstracts (no truncation); slower |
| sentence-transformers/clip-ViT-B-32 | multimodal (text + images); reads only 77 tokens of text |
Any other sentence-transformers model name also works. The threshold range 0.75–0.85 was calibrated for mpnet; other models get a wider scan (0.40–0.95) unless you set one.
Exact, complete references (optional). A Scopus CSV export can miss references: some
records have none, and a long reference list can be cut at 32,767 characters, the cell limit
of spreadsheet programs (do not open and re-save the export in Excel). By default S3 finds
citations by matching titles in the References text and builds bibliographic coupling from
the reference strings. With a Scopus API key (SCOPUS_API_KEY, from dev.elsevier.com),
enrich_citations fetches every paper's full reference list as Scopus IDs, using the EID
column of your original export (no new export needed):
in-corpus citations become exact (direct citation, co-citation, QI and MI);
bibliographic coupling counts shared cited Scopus IDs instead of matching reference text, for every paper the API returns references for (the others keep their References text);
if the map uses citation relations, or was chosen with
map_weights="hybrid", the map and communities are rebuilt on the exact data (saved labels are dropped, so label afterwards).
This needs Scopus entitlement: your institution's network or VPN, or an institutional token
(SCOPUS_INST_TOKEN). It makes about one request per paper (one per 200 references); Elsevier
sets a weekly quota per key, shown on the developer portal. Results are cached in
~/s3bib_runs/_scopus, so an interrupted run continues where it stopped.
export SCOPUS_API_KEY="your-key" # in your terminal, never in a chat
s3bib report scopus.csv --scopus -o report.html # text map (default)
s3bib report scopus.csv --scopus --map hybrid -o report.html # or screen the hybrid mapsres = s3bib.run_s3("scopus.csv", s3bib.S3Config(model_name="specter"))
s3bib.enrich_citations(res) # exact citations via the Scopus API
s3bib.S3Config(threshold=0.78) # reproduce a published threshold
s3bib.S3Config(community_method="louvain") # reproduce the S3 web app instead
s3bib.S3Config(dedupe=False) # keep duplicates
s3bib.S3Config(mi_denominator="all") # MI over all in-corpus links
s3bib.S3Config(citation_match="strict") # short titles need year + first author too
s3bib.S3Config(map_weights="text+coupling") # one of four maps (below)
s3bib.S3Config(map_weights="hybrid") # screen the hybrid maps, use the best oneProgress. run_s3, compare_maps, extract_triples and enrich_citations show a progress
bar while they work (a widget in Jupyter and Colab, a text bar in a terminal): loading, embedding
batch by batch, the threshold scan, and so on. Pass progress=False to hide it, or a function
progress(stage, fraction) to handle it yourself.
Strict citation matching. Matching titles inside References text can link a short,
generic title such as "Introduction" to every reference that contains the word. On the
Innovation & Diversity corpus about a quarter of the matched citations came from titles of
25 characters or fewer, and only 11% of those carried the cited paper's year or first
author. citation_match="strict" (CLI --strict-citations) keeps a short-title match only
when the year (±1) and first author also appear in the reference. The default stays
"lenient", as in the S3 web app and the published paper.
Choose the map. By default S3 uses the text map, the published method. Ask for a hybrid
map ("hybrid") and S3 first screens the text map against text plus each citation relation at
5–40% weight, and uses the best hybrid only when it raises both the silhouette and the QI
(see "Which map?" below); otherwise, or without in-corpus citations, it keeps the text map:
| The map is built from |
| text similarity (S3) only, the published method |
| the screening: the best hybrid map, or text if no hybrid raises both silhouette and QI |
| 75% text + 25% bibliographic coupling (shared references) |
| 75% text + 25% co-citation (cited together) |
| 75% text + 25% direct citation |
res = s3bib.run_s3("scopus.csv", s3bib.S3Config(map_weights="text+cocitation"))s3bib report scopus.csv --map text+cocitationEvery result follows the choice: the threshold scan, communities, network map, knowledge
tree, citation flows, bridges, interdisciplinarity and the report header (which names the
map). Coupling and co-citation are Salton cosines (0–1). Because the citation part is 0 for
most pairs, the threshold scan matches link density: each threshold links as many pairs as
one S3 threshold (0.75–0.85) on the same corpus, and SII picks the best, as for S3. Custom
mixes also work, e.g. map_weights={"s3": 0.8, "coupling": 0.2}.
Text floor. A citation relation counts only for pairs whose text similarity is already at
least 0.05 below the lowest S3 threshold (0.70 for mpnet). Citations then re-rank papers that
are close in content and never link two unrelated texts, in line with S3's content-first design.
Set it with S3Config(text_floor=0.72), or text_floor=False to let citations count for
every pair.
Which map? Compare them before the analysis. compare_maps tries the text map and each
citation relation (coupling, co-citation, direct citation) added step by step at 5%, 10%, ...
40% weight, all with the text floor: 25 maps. It builds each candidate map
(threshold scan and Leiden only, so it takes minutes, not a full run per map) and scores it
on measures that do not favour one kind of map:
Measure | What it checks |
Held-out citations | 20% of the in-corpus citation links are hidden while the maps are built. Share of hidden links that fall inside one community, minus the share for random communities of the same sizes. A citation map is not judged on its own input. |
TCI gain over random | Text coherence of the communities (paper Table 5) beyond random communities of the same sizes |
Stability | Adjusted Rand index with the partitions from two other seeds and two 90% samples of the papers |
Coverage | Share of papers placed in a community |
Agreement with text | Adjusted Rand index with the text map: how different the result is (reported, not used) |
A rule fixed in advance recommends a map: keep the text map (the published method) unless a
hybrid raises both the silhouette on the text embeddings (paper Table 6) and the QI on the
held-out citation links (paper Table 7, counted on links the map did not see), keeps the TCI
gain (at most 0.005 lower), loses at most 0.05 stability, and clusters at most 10% fewer papers
than the text map (smaller, tighter communities always score higher, so coverage is guarded). Among the
hybrids that pass, the highest held-out QI wins. The table also gives a 95% bootstrap interval
(over the hidden links) of each map's difference from the text map, so you can see whether a win
is larger than sampling noise. Relations that give a tie to fewer than 5% of the papers are left
out, with the reason. extended=True also tries the whole grid without the text floor, to
show what the floor changes. The report's Q0 draws the held-out gain of each relation against
its weight, next to the text map.
from s3bib.mapchoice import compare_maps
ch = compare_maps("scopus.csv", s3bib.S3Config(cache_dir="~/s3bib_cache"))
ch["table"], ch["recommended"], ch["reasons"]
res = s3bib.run_s3("scopus.csv", s3bib.S3Config(map_weights="hybrid")) # screen, then run on the winner
s3bib.enrich_citations(res) # exact Scopus reference lists, then
res.compare_maps(refresh=True) # compare the maps again on thems3bib compare-maps scopus.csv # the table and the recommendation
s3bib report scopus.csv --map hybrid # screen, then the full report on the recommended mapThe report shows the comparison as Q0 at the top of the methods appendix, and the methods
paragraph says which map was used and why. In Claude, the compare_maps tool runs it before
run_s3_analysis.
On the command line, s3bib report scopus.csv asks which model to use and whether to use the
Scopus API; in Claude, the assistant asks the same two questions before the first run.
Reproducing the paper. On the paper's ‘Innovation and Diversity’ corpus, with
S3Config(threshold=0.78, dedupe=False) the run retains exactly the paper's 1,826 papers,
and the ten largest Leiden communities and their QI, local and global citations closely
match Table 1.
Visuals. The report includes the paper's figures (S3 network map as in Panel 1, SII curve as in Fig. 3, elbow plot as in Fig. 4, citation-flow heatmap as in Table 2), an interactive paper-level network map drawn with force-graph, the library behind the S3 web app's map (hover for the paper, click for its abstract, drag, zoom, play the network year by year, dark/light, click a community to highlight it; a built-in map is used offline), a knowledge tree (communities per 5-year window, linked by citations and S3 similarity from earlier to later periods; switch between citation, similarity or both links, filter weak links, click a community to follow its lineage), a citation-flow diagram, a stacked growth chart, and author × community and country × community maps. Community colours are the same in every chart.
kt = res.knowledge_tree(window_years=5) # {"windows", "nodes", "links"} as DataFramesRelated MCP server: Paper Chaser MCP
The networks behind S3: one-mode, two-mode, knowledge graph
S3 answers its questions from three levels of network. You can export each of them:
Level | Nodes | Ties | Questions |
One-mode | papers | SIMILAR_TO (S3 ≥ threshold) | Q1–Q3, Q5–Q7, Q9, Q12–Q13, Q21–Q23 |
One-mode, multiplex | papers | SIMILAR_TO + CITES (+ coupling, co-citation, co-authorship in Q35–Q37) | Q4, Q8, Q10, Q11, Q24, Q35–Q37 |
Two-mode | papers + authors, keywords, journals, institutions, countries, funders or references | AUTHORED_BY, HAS_KEYWORD, … | Q14–Q16, Q19, Q20; co-citation and bibliographic coupling (Q4) are projections of the paper–reference network |
Knowledge graph | all of the above + communities | all tie types + IN_COMMUNITY, LOCATED_IN | Q17, Q18 |
Communities are not in the data: S3 derives them from the one-mode similarity network. The knowledge graph adds them as nodes so that questions across communities become graph queries.
res.networks() # node and tie types and counts per level
G = res.network("kg") # networkx MultiDiGraph; also "similarity", "citation",
# "one-mode", "paper-author", "paper-keyword", ...
res.export_networks("networks/") # node/edge CSVs (Neo4j, igraph) + GraphML (Gephi)
# add two_mode_kinds=[..., "reference"] for the large
# paper-reference networkKnowledge-graph triples: methods, data, theories and findings
Add what the papers use and find to the knowledge graph as triples, then read them per theme:
Relation | From → to | Example |
| paper → Method | fsQCA, panel regression |
| paper → Dataset | Community Innovation Survey, patent data |
| paper → Theory | resource-based view |
| paper → Construct | absorptive capacity |
| paper → Country, Industry, Level | Germany, manufacturing, firm |
| Construct → Construct | absorptive capacity INCREASES innovation performance |
Upload your own (CSV, Excel, JSON): columns paper_id (EID, DOI or title), subject,
relation, object, optionally evidence. Spelling variants of an entity are merged.
Or let Claude or ChatGPT extract them from the titles and abstracts, batch by batch, with a progress bar and a cache (an interrupted run resumes; a repeated run costs nothing):
Route | Uses | Command |
| your Claude plan, through the Claude Code command line |
|
| your ChatGPT plan, through the Codex command line |
|
| the Claude API ( |
|
| the OpenAI API ( |
|
in a Claude chat | Claude itself, in Claude Desktop or Claude Code | ask: "extract the knowledge-graph triples" (prompt |
The API routes need pip install "s3-bibliometric[llm]". Every extracted triple keeps a quote from
the abstract as evidence, and S3 marks whether that quote is really in the title or abstract
(evidence_found), so you can check the rest before citing them.
res = s3bib.run_s3("scopus.csv")
res.extract_triples("claude-code", max_papers=30) # try on 30 papers first
res.add_triples("my_triples.csv") # or add your own
res.answer("Q39") # methods, data, theories and settings per theme, gaps, rising methods
res.answer("Q40") # findings between constructs: established, contested, single-studys3bib extract-triples scopus.csv --backend claude-code -o triples.csv
s3bib report scopus.csv --triples triples.csvThe triples join the knowledge graph (res.network("kg"), export_networks, Neo4j/Gephi files)
next to themes, authors, journals and funders; the theme cards in the report list each theme's
methods, theories and data.
Three levels of analysis
Level | What it adds | Questions |
1. S3 — the published method | The text-similarity map and what the S3 paper reports from it. Questions marked S3 paper are in the paper; extension questions use the same map. | S3 paper: Q1 threshold (SII) · Q2 structure quality · Q3 outliers · Q38 evaluation against coupling, BERTopic and random clusters (paper Tables 5–7) · Q5 communities · Q6 topics · Q7 core papers · Q8 local vs global foundations · Q10 citation flows, QI, MI (Tables 1–2). Extensions: Q0 which map to use (text alone or text plus citations) · Q9 closeness · Q11 knowledge gaps · Q12 bridges · Q13 growth · Q14 concepts · Q21–Q23 interdisciplinarity |
2. Two-mode networks and knowledge graph (default) | Authors, institutions, countries, journals, funders and references; the map options that mix in citation relations | Q4 agreement with coupling and co-citation · Q15–Q20 actors · Q35 layer overlap and projection check · Q36 homophily · Q37 citation direction |
3. Prediction (off unless asked) | Link prediction and graph neural networks | Q24–Q34 |
Each level includes the ones below it. Choose it for a run or per call:
res = s3bib.run_s3("scopus.csv", s3bib.S3Config(level=1)) # only the published method
res.questions(level=2) # the ranked list, and which ones your data supports
res.answer("Q8") # findings + tables for one question
res.report("report.html", level=1) # the report at one levels3bib report scopus.csv -o report.html --level 1
s3bib questions --level 1Q38 compares the methods as in the paper: the Topic Coherence Index (TCI = 1 − Jensen–Shannon
divergence between each paper's TF-IDF words and its community's), the silhouette on the SBERT
embeddings for every method, and QI. BERTopic is included when installed
(pip install "s3-bibliometric[bertopic]"). Absolute values depend on text cleaning, so compare
the methods within one run rather than with the numbers printed in the paper.
The report: organised for a literature review
res.report("report.html") writes one self-contained HTML page in the order a review is written:
The field at a glance — the numbers, the themes, one paper per theme to read first, the foundations the field builds on, where it is going, the gaps to discuss (and leading authors at level 2).
Scope — records in and out (PRISMA-style counts) and papers that do not belong.
Themes — one card per theme: terms and keywords, papers to read first, foundations, growth, which themes it builds on and is used by, the closest themes in content, and at level 2 its authors, countries, journals and funders. Each card is one subsection of your review.
How themes connect, Evolution, Who does the work (level 2).
Research agenda — knowledge gaps, emerging themes, collaboration gaps (level 2) and forecasts (level 3), for your discussion and future-research sections.
Methods appendix — a methods paragraph to adapt (with the references), a glossary, and the analyses that show the map can be trusted.
Every result carries a For your review note and a tag: L1 · S3 paper, L1 · extension, L2 or L3. When the map mixes in citation relations, the report says that even the level-1 results are no longer the published method. Downloads for writing:
res.export_review("review/") # reading_list.ris (Zotero, EndNote, Mendeley), reading_list.bib,
# themes.csv, prisma.csv, methods.txt
res.report("report.html", layout="questions") # the previous layout: every question in orderPrediction (level 3, stages 7–8) is off by default (S3Config(prediction=False), level=2). Until you
switch it on, Q24–Q34 do not appear in the question list, the report, the CLI or Claude, and
asking for one returns a note that prediction is off. Switch it on for a whole run, or for
one call:
res = s3bib.run_s3("scopus.csv", s3bib.S3Config(prediction=True)) # everything on for this run
res.report("report.html") # then includes Q24–Q34
res.answer("Q30")
res.find_experts("board diversity and green innovation", kind="author") # R-GCN (Q32)
res.report("report.html", prediction=True) # or per call, on a run without it
res.answer("Q30", prediction=True)s3bib report scopus.csv --prediction
s3bib questions --predictionEvery prediction is tested honestly before it is used: the corpus is split in time (the last 5 years are the test window), models see only information from before the split, and each result is compared with simple baselines (popularity, community size, Adamic-Adar, nearest paper) with 95% intervals, so the report says when a model does not beat chance. The GNNs (GraphSAGE, R-GCN, a temporal GCN + GRU, TransE and RotatE) are small and written in plain PyTorch, which sentence-transformers already installs; nothing else is needed.
Multiplex, homophily and direction (Q35–Q37). The same papers are tied in five ways: text (the map's S3 links), bibliographic coupling, co-citation, direct citation and co-authorship.
Question | Measures | What it tells you |
Q35 | Jaccard overlap between layers; lift = how many times more often a tie of one layer is also a tie of another than a random pair | Which relations the text map misses, so which map option ( |
Q36 | Attribute assortativity r (−1 to +1) per attribute and layer, with the within-group share expected by chance | Whether ties stay inside the same community, journal, country or funder, and in which layer |
Q37 | PageRank on in-corpus citations; per community a source score (+1 only cited, −1 only citing); reciprocity of flows between communities against random direction | Which papers and communities are knowledge sources, and whether knowledge moves one way |
A paper can only cite older papers, so reciprocity is measured between communities, not papers.
Projection check (Q35). Coupling, co-citation and co-authorship are one-mode projections of two-mode networks (papers–references, cited–citing papers, papers–authors). Projections inflate ties and clustering: one popular reference links every paper that cites it, and a ten-author paper makes a clique of ten (Jankowski et al. 2026, Commun. Phys. 9:35). Q35 therefore reports, for each projected layer:
Significant ties: two papers share more items than chance predicts from how many items each has and how popular the items are (stochastic degree sequence model with Chung–Lu probabilities, Poisson test, Benjamini–Hochberg FDR 0.05 over all paper pairs). With the ties shuffled and all degrees kept, no tie is significant.
Four-cycle clustering of the two-mode network itself (Robins & Alexander), next to the clustering of the projection, so you can see how much clustering the projection creates.
To build the map and Q35–Q37 from significant ties only:
res = s3bib.run_s3("scopus.csv", s3bib.S3Config(map_weights="text+coupling", backbone=True))s3bib report scopus.csv --map text+coupling --backbonefrom s3bib.layers import layers, overlap, homophily, pagerank, flow_direction
J, lift, summary = overlap(res) # Q35 tables
homophily(res) # Q36: attribute, layer, r
pagerank(res) # Q37: PageRank per paperCharts or tables. Result sections are closed until you click them open. Tables open as bar charts; switch any of them to the table (and pick the column to plot), or switch all of them at once at the top of the report. Q6 shows one word cloud per main community (the top 10, five per row): 30 words each by default, 10 to 50 with one menu.
In Claude, use the s3_guided prompt, or ask: "Walk me through the S3 questions for
my Scopus file."
Use it without coding: Claude, ChatGPT or Colab
S3 runs on your own computer, so your data stays with you, or in a Google Colab notebook in your browser. How you use it depends on your app:
Your app | How | Setup |
Claude Desktop (Mac, Windows) | Chat with S3 directly: Claude runs the analysis and explains it | Once: install uv, paste 6 lines into Claude's settings |
Claude Code | Same, from the terminal | Once: install uv, one command |
Claude.ai (browser, phone) or ChatGPT | Make the report with one command, then upload it to the chat | Once: install uv |
Google Colab (browser) or Jupyter | Paste three cells into a notebook; it runs S3 and downloads the report | Nothing to install in Colab |
Claude.ai in the browser and ChatGPT cannot start programs on your computer, so they cannot run S3 themselves; they can read and explain the report and files S3 makes.
Step 0: export your papers from Scopus
In Scopus, select all results → Export → CSV. Tick every information group (citation, bibliographical, abstract and keywords, funding, and references). Title and abstract are required; the rest (year, citations, authors, affiliations, keywords, references, funding) unlock more of the analysis. Web of Science and OpenAlex exports work if they have Title and Abstract columns.
Step 1: install uv (once)
uv starts S3 for you and installs everything it needs.
Mac: open Terminal and paste:
curl -LsSf https://astral.sh/uv/install.sh | shWindows: open PowerShell and paste:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Close and reopen the Terminal (or PowerShell) window afterwards.
Step 2a: Claude Desktop
In Claude Desktop open Settings → Developer → Edit Config. This opens
claude_desktop_config.json.Paste this and save (if the file already has
"mcpServers", add only the"s3-bibliometric"part inside it):{ "mcpServers": { "s3-bibliometric": { "command": "uvx", "args": ["s3-bibliometric"] } } }Quit Claude Desktop completely and open it again. S3's tools now appear in Claude's tools menu in the chat box.
Ask, for example:
Run S3 on ~/Downloads/scopus.csv. Label the communities, walk me through the level-1 questions, and build the literature-review report.
Claude asks which language model to use (mpnet, the model of the S3 paper, is the default) and whether you have a Scopus API key for exact citations (optional; never paste a key into the chat). To use one, add it to the config above, next to
"args":"env": {"SCOPUS_API_KEY": "your-key"}, and restart Claude Desktop. The first run downloads the model (about 420 MB) and takes a few minutes; later runs are fast.
If the tools do not appear: Claude Desktop may not find uvx. In Terminal run
which uvx (Mac) or where uvx (Windows) and put that full path in "command", e.g.
"command": "/Users/you/.local/bin/uvx".
Step 2b: Claude Code
claude mcp add s3-bibliometric -- uvx s3-bibliometricThen ask the same as above.
Step 2c: Claude.ai in the browser, or ChatGPT
Make the report with one command in Terminal (Mac) or PowerShell (Windows). Replace the file path with yours:
uvx --from s3-bibliometric s3bib report ~/Downloads/scopus.csv -o ~/Desktop/s3_report.htmlIt asks which language model to use (press Enter for the default) and whether you have a Scopus API key (answer n if not). Add
--level 1for only the published S3 method.Open
s3_report.htmlin your browser. At the top, click the downloads: Themes table (CSV), Methods paragraph, and the reading list (RIS) for Zotero, EndNote or Mendeley.Upload the report and the downloaded files to Claude.ai or ChatGPT, and ask, for example:
This is an S3 analysis of my literature. Name each theme in 3-5 words, summarise the field's structure, and draft the structure of my literature review with the gaps to discuss.
Step 2d: a Google Colab notebook (or Jupyter)
Nothing to install: Colab runs Python in your browser, on Google's servers. Skip step 1.
Open colab.research.google.com → New notebook. Optional: Runtime → Change runtime type → T4 GPU makes the embedding faster.
In the first cell, install S3 and press ▶ (or Shift+Enter):
!pip install -q s3-bibliometricIn a new cell, upload your Scopus CSV (pick the file when asked):
from google.colab import files csv = list(files.upload())[0]In a new cell, run S3 and download the report (the text map, the published method):
import s3bib res = s3bib.run_s3(csv) res.report("s3_report.html") # add level=1 for only the published S3 method files.download("s3_report.html")For a hybrid map (text plus citations, screened), use
s3bib.run_s3(csv, s3bib.S3Config(map_weights="hybrid"))andprint(res.answer("Q0"))to see the screening. The first run downloads the language model (about 420 MB). Then open the report and use it as in step 2c, or keep asking in the notebook, e.g.print(res.answer("Q8"))orres.questions()for the list of questions.
Notes:
Colab runs on Google's servers, so your file is uploaded there. A free Colab session ends after a while; download the report before you close it.
Scopus API key in Colab: click the key icon (Secrets), add
SCOPUS_API_KEY, allow the notebook to use it, and run this before the report:import os from google.colab import userdata os.environ["SCOPUS_API_KEY"] = userdata.get("SCOPUS_API_KEY") s3bib.enrich_citations(res)Reference lists need your institution's Scopus access, and Google's servers are not on your campus network, so this usually also needs an institutional token (
SCOPUS_INST_TOKEN, from your library), stored the same way.Jupyter on your own computer: install with
pip install s3-bibliometricin your environment, skip the upload cell, and use the file path, e.g.csv = "/Users/you/Downloads/scopus.csv"; opens3_report.htmlinstead of downloading it.
What you can ask
"Which questions can S3 answer for my data?" — the ranked research questions, in three levels: 1 the published S3 method, 2 authors, countries, journals, funders and citation networks, 3 predictions (only when you ask).
"What are the main themes, and which papers should I read first?"
"Where are the knowledge gaps?" · "Which themes are emerging?"
"Write the methods paragraph for my paper."
"Build the literature-review report at level 1."
The tools Claude uses
Tool | What it does |
| Before the analysis: compare the text map with text+coupling, text+cocitation and text+direct on your corpus and recommend one |
| Run S3 on a CSV/XLSX (year range, map option, strict citation matching); returns a |
| The language models you can choose (default: mpnet, as in the S3 paper) |
| Exact, complete reference lists from the Scopus API: exact citations, and coupling from cited Scopus IDs (needs |
| Saved runs |
| The ranked research questions for a level (1, 2 or 3) and whether your data supports each |
| Findings and tables for one question, e.g. |
| The literature-review report (or every question in order), at a level |
| Silhouette / SII / communities for each threshold |
| Community table incl. QI/MI and saved labels |
| Central papers with abstracts, keywords, TF-IDF terms |
| Store the labels the assistant proposes |
| Unconnected papers + nearest community |
| Community × community citation matrix + QI/MI |
| How communities grow and split over time |
| Semantic search inside the corpus |
| Write CSV outputs |
| One-mode, two-mode and knowledge-graph networks as CSV + GraphML |
| Add a triples file (methods, data, theories, findings) to the knowledge graph |
| Which extraction routes work here: Claude plan, ChatGPT plan, API keys, or the chat |
| Extract triples from the abstracts with Claude Code, Codex or an API, with progress |
| Claude extracts the triples itself in the chat, batch by batch, with progress |
Prompts: s3_guided walks through the questions stage by stage; s3_report writes the
intellectual-structure report. Runs are saved in ~/s3bib_runs (change it with the
S3BIB_HOME environment variable).
Use it from Python
pip install s3-bibliometricimport s3bib
res = s3bib.run_s3("scopus.csv") # or run_s3(df, s3bib.S3Config(start_year=2010))
res.scan # threshold scan
res.communities() # size, citations, years, QI/MI
res.community_papers(0, n=10) # most central papers
res.top_keywords(0); res.top_terms(0)
res.outliers()
res.citation_matrix()
res.search("absorptive capacity")
res.labels = {0: "Open innovation", 1: "M&A"}
res.export("results/") # CSVs
res.save("runs/innovation") # reload with s3bib.S3Result.load(...)Use it from R
The R package s3bibliometric runs this library of the same version, so R and Python give the
same results. Details: r/README.md.
remotes::install_github("AI-Growth-Lab/s3-bibliometric", subdir = "r")
library(s3bibliometric)
res <- s3_run("scopus.csv") # text map; map = "hybrid" screens the hybrids
s3_communities(res)
s3_report(res, "s3_report.html")Python is set up automatically on first use (via reticulate). The R and Python version numbers are always the same: a test fails if they differ, and every release updates both.
Input
Export from Scopus as CSV with at least Title and Abstract. Also used if present: Year, Cited by, Authors, Author Keywords, Source title, DOI, and References + EID (needed for the citation analysis).
Notes
On a CPU, embedding 5,000 abstracts takes a few minutes. The silhouette step uses an N×N matrix (~100 MB at N = 5,000).
A paper counts as citing another if the first 60 characters of the other paper's normalised title appear in its References. This step is O(N²).
Tests
The tests run on real data: 109 OpenAlex records (CC0) on absorptive
capacity and work group diversity, with their real all-mpnet-base-v2 embeddings, in
tests/data/. python tests/data/build_openalex_sample.py rebuilds them.
Authors
Hamid Bekamiri (maintainer), with S3 co-authors Christian Richter Østergaard and Bram Timmermans.
Citation
S3 project: github.com/AI-Growth-Lab/S3. To propose a new analysis, open an issue there; report problems with this library here.
If you use this package, please cite the S3 paper:
Bekamiri, H., Østergaard, C. R., & Timmermans, B. (2027). Semantic similarity score: A new method for mapping intellectual structures in business research. Journal of Business Research, 219, 116582. https://doi.org/10.1016/j.jbusres.2026.116582
License
MIT
Available Tools
23 toolsadd_triplesA
Add knowledge-graph triples from a file (CSV, Excel, JSON or JSON lines) to a run. Columns: paper_id (EID, DOI or title), subject, relation, object (optional: subject_type, object_type, evidence). Paper relations: USES_METHOD, USES_DATA, USES_THEORY, STUDIES, STUDIED_IN, IN_INDUSTRY, AT_LEVEL (subject "PAPER"); findings between constructs: INCREASES, DECREASES, NO_EFFECT_ON, MODERATES, MEDIATES, ASSOCIATED_WITH. The triples join the knowledge graph and answer Q39 (methods, data, theories per theme) and Q40 (findings, contested relations).
Inputs: path (required), run_id (required). Returns: result
answer_questionB
Answer one ranked question, e.g. "Q8" (foundational papers) or "Q21" (interdisciplinarity). Returns findings (plain sentences) and result tables. The prediction questions Q24-Q34 are off unless prediction=True (only when the user asks for prediction).
Inputs: run_id (required), question_id (required), max_rows, prediction. Returns: result
build_reportA
Write one self-contained HTML report. layout="review" (default) is organised for a literature review: a one-page brief, scope (records in and out), one card per theme (what it is about, papers to read first, growth, links to other themes), how themes connect, evolution, research agenda (gaps) and a methods appendix, with RIS/BibTeX reading lists and a methods paragraph to download. layout="questions" lists every question. level: 1 = the published S3 method, 2 = + two-mode and knowledge graph (default), 3 = + prediction (prediction=True is the same; a few minutes more). Default path: the run folder.
Inputs: run_id (required), level, title, layout, +2 more. Returns: result
compare_mapsA
Before the full analysis: which map should S3 use for this corpus? Compares the text map (the published method) with text plus bibliographic coupling, co-citation or direct citation at 5%, 10%, ... 40% weight; citations count only for pairs already close in content (the text floor). extended=True adds the same grid without the floor. 20% of the in-corpus citation links are hidden while the maps are built; each map is scored on the hidden links inside its communities (gain over random communities of the same sizes), on text coherence (TCI gain over random), stability (ARI across seeds and 90% samples) and coverage. A rule fixed in advance recommends a map. Show the user the table and the recommendation, then pass the chosen map to run_s3_analysis as map_relations. Takes a few minutes; embeddings are cached for the run. With run_id instead of csv_path, compares on that run's papers and citation links: use this after enrich_citations, so the comparison uses the exact Scopus reference lists.
Inputs: seed, run_id, csv_path, end_year, +4 more. Returns: result
enrich_citationsA
Exact, complete reference lists from the Scopus Abstract Retrieval API, for every paper of the run (by EID). The in-corpus citation links become exact, and bibliographic coupling uses the cited Scopus IDs instead of the exported References text (which can be truncated or missing). If the run's map uses citation relations (or was chosen with map_relations="hybrid"), the map and communities are rebuilt and saved labels are dropped: label the communities after this step. Reads SCOPUS_API_KEY (and optional SCOPUS_INST_TOKEN) from this server's environment; needs Scopus entitlement (institution network or token). About 0.2 s per paper; cached.
Inputs: run_id (required). Returns: result
export_networksA
Export the networks behind S3 at three levels: one-mode (papers tied by S3 similarity and/or citations), two-mode (papers + authors, keywords, journals, institutions, countries, funders or references) and a knowledge graph (all node and tie types together, with communities as nodes). Writes node/edge CSVs (Neo4j, igraph) and GraphML (Gephi) to output_dir (default: the run folder) and returns the files and a summary of what each network contains.
Inputs: run_id (required), output_dir. Returns: result
export_resultsA
Write CSV outputs (papers with community + label, community table, threshold scan, citation matrix) to output_dir (default: the run folder).
Inputs: run_id (required), output_dir. Returns: result
extract_triplesA
Extract triples (methods, data, theories, constructs, settings, findings) from the titles and abstracts of a run with "claude-code", "codex", "anthropic" or "openai" (see triple_extraction_options), batch by batch, and add them to the run. Reports progress after every batch; answers are cached, so a repeated or interrupted run resumes. Large corpora take a while: tell the user the number of papers first, or test with max_papers=30.
Inputs: run_id (required), model, backend, batch_size, +1 more. Returns: result
get_citation_structureB
In-corpus citation flows between the largest communities (rows cite columns), plus QI (within-community citations / size) and MI (share of field citations). Needs References and EID columns in the export.
Inputs: run_id (required). Returns: result
get_communityA
Details for one community, to interpret or label it: the most central papers (eigenvector centrality, then citations) with abstracts, top author keywords and top TF-IDF terms. Set abstract_chars=0 to return titles only.
Inputs: run_id (required), community_id (required), max_papers, abstract_chars. Returns: result
get_knowledge_treeB
Knowledge tree: papers per community in each time window, and links from earlier to later windows weighted by citations and by S3 similarity links. Use it to describe how communities emerged, which earlier work each one builds on, and where knowledge flowed.
Inputs: run_id (required), min_links, window_years, n_communities. Returns: result
get_outliersB
Papers with no S3 link above the chosen threshold (the "irrelevant" set), most cited first, with their nearest similarity and suggested community.
Inputs: run_id (required), limit. Returns: result
get_threshold_scanC
Threshold scan table: threshold, silhouette, clustered papers, SII, number of communities and edges. The best threshold maximises SII.
Inputs: run_id (required). Returns: result
list_communitiesB
All communities (largest first) with size, citations, year span, saved label, and QI/MI citation metrics when References were available.
Inputs: run_id (required), min_size. Returns: result
list_embedding_modelsA
Embedding models the user can choose for run_s3_analysis (key, model, kind, max tokens, description). Default: mpnet, the model used in the published S3 paper.
Inputs: no named parameters. Returns: result
list_questionsA
The ranked research questions of the S3 method, in three levels: level 1 = the published S3 method (text similarity map; each question says whether it is in the S3 paper or an extension), level 2 (default) = + two-mode networks and knowledge graph (authors, institutions, journals, funders, layer overlap, homophily, citation direction), level 3 = + prediction (link prediction Q24-Q29, GNNs Q30-Q34; only when the user asks; include_prediction=True is the same as level 3). Shows priority and whether this dataset has the columns each question needs.
Inputs: run_id (required), level, include_prediction. Returns: result
list_runsA
List saved S3 runs (run_id, number of papers, best threshold, labels saved?).
Inputs: no named parameters. Returns: result
next_triple_batchA
In-chat extraction, step 1: the next papers without triples (id, title, abstract), the extraction instructions, and the progress so far. Extract the triples yourself, following the instructions, then call save_triples with this batch's paper ids. Repeat until done is true, telling the user the progress after each batch.
Inputs: run_id (required), batch_size. Returns: result
run_s3_analysisA
Run the S3 pipeline on a Scopus CSV/Excel export (needs Title and Abstract; Year, Cited by, Authors, Author Keywords, References and EID are used if present).
Follows the published S3 method: embeds Title+Abstract (all-mpnet-base-v2), builds the time-ordered S3 graph, scans thresholds 0.75-0.85 and keeps the Leiden (directed modularity) partition with the highest SII (silhouette x retained papers). Set threshold (e.g. 0.78) to reproduce a published run, or community_method="louvain" to reproduce the S3 web app. embedding_model is a key from list_embedding_models or any sentence-transformers model name (ask the user first; default mpnet). Records without title and abstract are dropped and duplicates (same DOI/EID/text, or S3 >= 0.98) are removed unless remove_duplicates=False. map_relations chooses the map, and every answer and report follows it: "text" (default; S3 text similarity, the published method), "hybrid" when the user asks for a hybrid map (screens text plus each citation relation at 5-40% weight, as compare_maps does, and uses the best hybrid if it raises both silhouette and QI, else text), or a specific hybrid the user names: "text+coupling", "text+cocitation", "text+direct" (75%/25%) or weights such as "s3=0.8,coupling=0.2". strict_citations=True stops short titles such as "Introduction" from matching unrelated references. significant_ties_only=True keeps only coupling, co-citation and co-authorship ties that are significant under a degree-preserving null model (in the map and Q35-Q37). Can take several minutes for thousands of papers the first time; embeddings are cached afterwards.
Returns a run_id plus a summary: best threshold, communities, outlier count.
Inputs: csv_path (required), seed, rerun, end_year, +8 more. Returns: result
save_community_labelsB
Store short topic labels for communities, e.g. {"0": "Open innovation", "1": "..."}. Labels are saved with the run and included in exports.
Inputs: labels (required), run_id (required). Returns: result
save_triplesA
In-chat extraction, step 2: save the triples you extracted for one batch (each with paper_id, subject, subject_type, relation, object, object_type, evidence) and mark the batch's papers done, including papers with nothing to extract. Returns the progress message to show the user, e.g. "Saved 42 triples. 60 of 800 papers done (8%)".
Inputs: run_id (required), triples (required), paper_ids (required). Returns: result
search_papersC
Semantic search over the run's papers (same embedding model as S3).
Inputs: query (required), run_id (required), top_k. Returns: result
triple_extraction_optionsA
Which ways of extracting triples work on this computer: "claude-code" (the user's Claude plan via the Claude Code command line), "codex" (the user's ChatGPT plan via the Codex command line), "anthropic" / "openai" (API keys in this server's environment), and always "chat" (you extract them yourself with next_triple_batch and save_triples). Ask the user which to use.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Most tools target clearly distinct stages of the S3 workflow: run setup, map comparison, analysis, inspection, labeling, export, and reporting. The only real overlap is among the triple-extraction tools (extract_triples, next_triple_batch, save_triples, add_triples), but their descriptions clarify the automated versus in-chat versus file-import paths.
The set overwhelmingly uses predictable snake_case verb_noun naming, such as list_runs, run_s3_analysis, get_community, save_triples, and export_results. Minor deviations like triple_extraction_options and next_triple_batch are noun-oriented or workflow-step names, but they remain readable and mostly consistent.
With 23 tools, the surface is on the heavy side for a single server and includes many inspection/reporting endpoints. Most tools do earn their place in a complex bibliometric pipeline, but the count sits at the borderline where consolidation could improve usability.
The surface covers the full S3 lifecycle: listing models and runs, running analyses, comparing maps, enriching citations, extracting/importing triples, inspecting thresholds, communities, outliers, citation structure and knowledge trees, searching papers, saving labels, exporting results and networks, answering ranked questions, and building reports. No obvious workflow dead end is apparent.
Maintenance
Related MCP Connectors
Start cited deep-research runs, read reports, search your source vault, and verify citations.
Extract structured data points from research papers and other documents with an LLM.
Knowledge graph ingestion, entity search, ontology analysis, and CoSync scoring.
Search 340M+ academic papers — citation graphs, semantic similarity, and AI literature reviews.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects Scopus to AI assistants for literature discovery. Provides tools for finding papers, experts, citation networks, and analyzing research trends.2GPL 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to conduct academic research workflows such as paper discovery, literature mapping, citation chasing, author pivots, citation repair, and regulatory or species document retrieval.MIT
- FlicenseNot gradedqualityCmaintenanceEnables manuscript researchers to conduct retrieval and scoring searches, inspect human-readable results, record inline reviews, rescore cached corpora, and export reports or ChatGPT-ready research packets.-
- AlicenseBqualityBmaintenanceEnables AI assistants such as Claude to search academic literature, retrieve abstracts and full text, trace citations and multi-generation citation networks, and analyze author profiles, journal quality and bibliometrics from a conversation. It works with Scopus by default and can run the same analyses against OpenAlex without a subscription.3546 PyPI1MIT