elemindex

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):

npx @reneturcios/elemindex get_element_ri '{"symbol":"Fe"}'
npx @reneturcios/elemindex search_subjects '{"query":"solid electrolyte"}'
npx @reneturcios/elemindex research
npx @reneturcios/elemindex --version

Exit codes: 0 on success, 1 on an isError result, 2 on a usage error.

MCP server

npx -y @reneturcios/elemindex mcp

MCP client config:

{
  "mcpServers": {
    "elemindex": {
      "command": "npx",
      "args": ["-y", "@reneturcios/elemindex", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/elemindex
docker run --rm ghcr.io/cloudcorprecords/elemindex --version

The container's default command is mcp, so the first form is a stdio MCP server; any other arguments reach the CLI normally.

Development

npm install
npm run build
npm test
npm run dev

The test suite runs entirely against a stubbed JSON-RPC upstream — no live network calls.

License

MIT — see LICENSE.