MatRouter

MatRouter logo

MatRouter is an agent-native routing and aggregation substrate for materials data. It turns an explicit data need into executable routes across heterogeneous sources, then assembles returned records, structures, properties, artifacts, provenance, and execution outcomes into one EvidenceBundle.

The Agent (LLM + MCP + Skill) chooses source and record scope and owns planning, retries, scientific interpretation, and prose. MatRouter owns capability truth, source-qualified execution, normalization, provenance, and bundle integrity. It preserves the context needed for downstream reasoning without turning retrieval into a scientific verdict.

Install

MatRouter requires Python 3.11 or newer.

# Python dependency
uv add --prerelease=allow matrouter

# Standalone MCP command
uv tool install --prerelease=allow matrouter

From a checkout:

git clone https://github.com/MatRouter/matrouter.git
cd matrouter
uv sync
uv run matrouter

Python

from matrouter import create_router

with create_router() as router:
    print(router.get_evidence_capability_document())

EvidenceBundle is the core output and the sole record of what was requested, attempted, returned, or missing. The single MCP surface also exposes explicit methods for exact-input structure matching, frame-safe phase-diagram calculation/plotting, and rendering acquired band-structure or DOS artifacts. Retrieval never renders implicitly. Method results retain their exact inputs, parameters, provenance, and limitations; they are not general scientific verdicts.

Agent plugin

Codex and Claude Code can install the bundled plugin; other MCP hosts can run matrouter as a local stdio server and use the portable Skill when supported. See the user guide for the current installation and configuration procedure.

The sole distributable Skill source is plugins/matrouter/skills/matrouter/.

Scope

MatRouter does not mirror upstream databases, infer missing values, impose a fixed research workflow, embed scientific assessment rules, or decide scientific truth. OPTIMADE remains complementary: OPTIMADE standardizes provider-side common records; MatRouter orchestrates native and OPTIMADE sources on the Agent side and preserves their source-specific context in a common bundle.

Documentation

User guide: installation, configuration, MCP, sources, and usage.
Development guide: architecture, contracts, and maintenance.
Verification report: current tested surface and limits.
Plugin guide: agent-host installation.

Contact

Quansheng Wu quansheng.wu@iphy.ac.cn, wuquansheng@gmail.com
Tiannian Zhu (朱天念) tnzhu@iphy.ac.cn

License

MatRouter is licensed under Apache-2.0; see LICENSE and NOTICE. Retrieved data remains subject to each upstream provider's terms, licenses, attribution requirements, and access restrictions.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

matrouter-0.8.1.tar.gz (679.6 kB view details)

Uploaded Aug 9, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

matrouter-0.8.1-py3-none-any.whl (287.4 kB view details)

Uploaded Aug 9, 2026 Python 3

File details

Details for the file matrouter-0.8.1.tar.gz.

File metadata

Download URL: matrouter-0.8.1.tar.gz
Upload date: Aug 9, 2026
Size: 679.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for matrouter-0.8.1.tar.gz
Algorithm	Hash digest
SHA256	`17128fb1f74b67149987ec6218431c781f81dc94aca8f02052df69e42313989c`
MD5	`94be45bac68f3309a320fa6a02bff4d3`
BLAKE2b-256	`e6d3cb7825701e9fa02bb15d3b7dc65178eb4f09c6573cc815501efecd4804b1`

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrouter-0.8.1.tar.gz:

Publisher: publish.yml on MatRouter/matrouter

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: matrouter-0.8.1.tar.gz
- Subject digest: 17128fb1f74b67149987ec6218431c781f81dc94aca8f02052df69e42313989c
- Sigstore transparency entry: 2395468451
- Sigstore integration time: Aug 9, 2026
Source repository:
- Permalink: MatRouter/matrouter@fe3e30ade91be069c8c3de099cd709f28854b3d3
- Branch / Tag: refs/tags/v0.8.1
- Owner: https://github.com/MatRouter
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@fe3e30ade91be069c8c3de099cd709f28854b3d3
- Trigger Event: release