elemindex
elemindex is a thin local bridge to the Elements Live
hosted MCP server, a research index that tracks how
much attention each of the 118 chemical elements — and
a wider set of research subjects such as compounds,
materials and topics — is getting in the literature,
and which papers sit behind those numbers.
The bridge holds no data and computes nothing. It
serves the upstream server's tool list locally —
exactly as captured from the live endpoint — and
forwards each tool call upstream, returning the result
untouched. A few upstream tools are free, while others
are described upstream as requiring a paid account
tier; that gating is the upstream's own, stated in the
tool descriptions themselves. This client adds no
gating and no payment machinery: it optionally forwards
one credential, described under Configuration, and
otherwise sends no credential of its own.
Tools
research — the literature entry point. Ask a broad
or specific chemistry, materials or physics question
in plain words (q), or start from a known paper
(paper: a DOI or title). Reading lists come back in
four lenses — relevant, foundational, now and
newest — controlled with lenses, plus page and
page_size for paging. No argument is required by the
schema.get_element_ri — the current Research Intensity
(RIS) for one element, with a citation URL. Required:
symbol — a symbol such as Fe, a name such as
Iron, or an atomic number also work.search_subjects — resolve a free-text query (a
compound, material or research topic) to the
subject_type / subject_id pair the subject tools
need. Required: query.get_subject_ri — RI, RIS, HRI and paper count for
one research topic, keyword or sector. Required:
subject_type (keyword or sector) and
subject_id; resolve both with search_subjects
first.get_subject_history — the full RIS/HRI history for
one subject, at yearly resolution by default or
monthly when asked. Required: subject_type and
subject_id.get_subject_papers — the top papers for one subject:
title, DOI, venue, year and citations. Required:
subject_type and subject_id. Optional: limit
(default 20, capped at 100) and sort (impact,
newest or foundational).get_element_papers — the top papers for one element,
optionally narrowed with keyword to one of that
element's materials or applications. Required:
symbol. Optional: limit and sort, as above.lab_quote — scope a multi-term question with a
boolean filter (query, or markdown carrying the
filter in a fenced block). Returns match counts and a
quote_id; read its warnings before trusting the
filter, since unsupported terms are dropped. No
argument is required by the schema.lab_run — turn a lab_quote result into its ranked
papers. Required: quote_id. Optional: depth
(papers_20 by default, or papers_100).
Configuration
ELEMENTS_LIVE_MCP_URL (optional) — override the
upstream endpoint. Defaults to
https://www.elements-live.com/mcp.
(The override hook is this rebuild's own labelled
reconstruction.)ELEMENTS_LIVE_API_KEY (optional) — when set, its
value is sent as Authorization: Bearer <key> on
every upstream request. When it is not set, no
authorization header is sent at all. (This forwarding
is this rebuild's own labelled reconstruction; the
original capture was taken keyless.)
Forwarding mechanics
On the first tool call the client opens a streamable
HTTP session with the upstream: a JSON-RPC initialize
request (protocolVersion 2025-03-26, clientInfo name
elemindex), then a notifications/initialized
notification, then the tools/call request carrying
the caller's arguments unchanged. When the upstream
answers initialize with an Mcp-Session-Id header,
that value rides on every later request of the
session, which is reused for the life of the process.
Replies may arrive as plain JSON or as
server-sent events; both are read.
Successful upstream results pass through verbatim,
including any isError flag the upstream sets.
Failures — a JSON-RPC error, a non-2xx status, an
unreadable response, or a request that cannot be
completed — come back as an isError result whose
text starts with elemindex error: (this rendering is
this rebuild's own labelled reconstruction).
CLI
Each tool is also a subcommand taking one JSON
argument string (omit it for tools that take none):
Exit codes: 0 on success, 1 on an isError
result, 2 on a usage error.
MCP server
MCP client config:
Docker
The container's default command is mcp, so the first
form is a stdio MCP server; any other arguments reach
the CLI normally.
Development
The test suite runs entirely against a stubbed
JSON-RPC upstream — no live network calls.
License
MIT — see LICENSE.
