MatRouter
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.
2 maintainers
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file matrouter-0.10.1.tar.gz.
File metadata
- Download URL: matrouter-0.10.1.tar.gz
- Upload date:
- Size: 659.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
85815cc56a8fdea7a1e37ab3cc4362177704092547a5d9411ae7f1ca550eba51
|
|
| MD5 |
b2527e143f4826508a1f9951d8f67ef0
|
|
| BLAKE2b-256 |
e43954af2941311f4871228a01a5849f060846d3fe74bec0384b27d3c5c144a7
|
Provenance
The following attestation bundles were made for matrouter-0.10.1.tar.gz:
Publisher:
publish.yml on MatRouter/matrouter
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
matrouter-0.10.1.tar.gz -
Subject digest:
85815cc56a8fdea7a1e37ab3cc4362177704092547a5d9411ae7f1ca550eba51 - Sigstore transparency entry: 2441877711
- Sigstore integration time:
-
Permalink:
MatRouter/matrouter@70001cee7faf7dc514f8fb8f1dc403b16e31a4d5 -
Branch / Tag:
refs/tags/v0.10.1 - Owner: https://github.com/MatRouter
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@70001cee7faf7dc514f8fb8f1dc403b16e31a4d5 -
Trigger Event:
release
-
Statement type:
File details
Details for the file matrouter-0.10.1-py3-none-any.whl.
File metadata
- Download URL: matrouter-0.10.1-py3-none-any.whl
- Upload date:
- Size: 275.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0d77e3bdcd99ed9adbd030907be8219b66b609f8df45a3cbfb5ec57b83f05d9e
|
|
| MD5 |
e7486f3eb0bb187a6e0e0bcd1a4b8529
|
|
| BLAKE2b-256 |
a94c220dc637eaa88e231744369b9d049782195822fd0292ab267b68a2ba6753
|
Provenance
The following attestation bundles were made for matrouter-0.10.1-py3-none-any.whl:
Publisher:
publish.yml on MatRouter/matrouter
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
matrouter-0.10.1-py3-none-any.whl -
Subject digest:
0d77e3bdcd99ed9adbd030907be8219b66b609f8df45a3cbfb5ec57b83f05d9e - Sigstore transparency entry: 2441877810
- Sigstore integration time:
-
Permalink:
MatRouter/matrouter@70001cee7faf7dc514f8fb8f1dc403b16e31a4d5 -
Branch / Tag:
refs/tags/v0.10.1 - Owner: https://github.com/MatRouter
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@70001cee7faf7dc514f8fb8f1dc403b16e31a4d5 -
Trigger Event:
release
-
Statement type:
